APTRA™ Advance NDC

Developer’s Guide

B006‐6046‐T000
Issue 1
May 2019

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.
Copyright and Trademark Information

The product described in this book is a licensed product of NCR Corporation.

NCR, APTRA, and Personas are trademarks of NCR Corporation.

Adobe and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States
and/or other countries.
Autodesk and FLIC are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates
in the USA and/or other countries.
Diebold Nixdorf is registered trademark of Diebold Nixdorf International in the United States and/or other countries.
IBM and Operating System/2 are trademarks of International Business Machines Corporation, registered in many
jurisdictions worldwide.
Microsoft, ActiveX, DirectShow, Visual Basic, Visual Studio and Windows are registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries.
Nuance is a trademark and/or registered trademark of Nuance Communications, Inc. and/or its subsidiaries in the
United States and/or other countries.
Parascript is a registered trademark of Parascript LLC in the United States and/or other countries.
Sound Blaster is a trademark or registered trademark of Creative Technology Ltd in the United States and/or other
countries.

Disclaimer:

It is the policy of NCR Corporation to improve products as technology, components, software and firmware become
available. NCR therefore reserves the right to change specifications without prior notice.

All features, functions and operations described herein may not be marketed by NCR in all parts of the world. In some
instances, photographs are of equipment prototypes. Therefore, before using this document, consult with your NCR
representative or NCR office for information that is applicable and current.

To maintain the quality of our publications, we need your comments on the accuracy, clarity, organisation and value of
this book.

Address correspondence to:

NCR Financial Solutions Group Ltd

Product Management Feedback
Discovery Centre
3 Fulton Road
Dundee, Scotland
DD2 4SW

© 2000–2019
By NCR Corporation
Atlanta, Georgia, USA
All Rights Reserved

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.
 Federal Communications Commission (FCC) Radio Frequency Interference Statement

Federal Communications
Commission (FCC) Radio Frequency
Interference Statement

Note: This equipment has been tested and found to comply with
the limits for a Class A digital device, pursuant to Part 15 of the
FCC Rules. These limits are designed to provide reasonable
protection against harmful interference when the equipment is
operated in a commercial environment. This equipment
generates, uses, and can radiate radio frequency energy and, if not
installed and used in accordance with the instruction manual,
may cause harmful interference to radio communications.
Operation of this equipment in a residential area is likely to cause
harmful interference in which case the user will be required to
correct the interference at his own expense.

This digital apparatus does not exceed the Class A limits for radio
Canadian Class A Device noise emissions from digital apparatus set out in the Radio
Declaration Interference Regulations of the Canadian Department of
Communications.
Le présent appareil numérique n’émet pas de bruits
radioélectriques dépassant les limites applicables aux appareils
numériques de la classe A prescrites dans le Réglement sur le
brouillage radioélectrique édicté par le ministère des
Communications du Canada.

This equipment must be installed and used in strict accordance with

Information to User the manufacturer’s instructions. However, there is no guarantee
that interference to radio communications will not occur in a
particular commercial installation. If this equipment does cause
interference, which can be determined by turning the equipment off
and on, the user is encouraged to consult an NCR service
representative immediately.

Caution NCR Corporation is not responsible for any radio or television

interference caused by unauthorised modifications of this
equipment or the substitution or attachment of connecting cables
and equipment other than those specified by NCR. Such
unauthorised modifications, substitutions, or attachments may void
the user’s authority to operate the equipment. The correction of
interference caused by such unauthorised modifications,
substitutions, or attachments will be the responsibility of the user.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide iii

Federal Communications Commission (FCC) Radio Frequency Interference Statement

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

iv APTRA Advance NDC, Developer’s Guide

 Revision Record

Revision Record

Date Page Description of Change

May New revision for Advance NDC 05.01.00

2019

Preface‐li & Added information about the new device,

5‐366 SDM2, a variant of SDM.

Information related to SDM2 device

limitation is added.

1‐15, 5‐50 & Added a note related to dial up

C‐18 communication that describes 64‐bit
systems (Windows 7 or Windows 10)
do not support dial up.

1‐16 & Added information about how to restrict

5‐224 the card entry retires if a card is misread in
the Insert Card state (z008).

1‐17 & 5‐99 Added information about configuring

Advance NDC to provide Uninterruptible
Power Supply (UPS).

1‐17 & Added information about running the

11‐10 application even if the EPP is not detected
or is in an invalid state at the start of day.

1‐18 & Added information about

5‐279 journaling the count of notes that are
attempted to present before a power
failure occurs in a dispense transaction.

1‐21 & 4‐4 Added information related to Local Cash

Dispense State (z010).

1‐26 & 5‐46 Information added about determining and

applying default network connection
based on the operating system of SSTs.

1‐46 & Added information about

5‐358 journaling security trace message for a
cash‐in cassette movement along with the
tamper and sensor status reporting.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA™ Advance NDC, Developer’s Guide v

Revision Record

Date Page Description of Change

1‐35, 5‐62, Added information about configuring

5‐141, 5‐214 device mode to interact with the
to 5‐216, contactless card reader device.
5‐227, 5‐245
to 5‐257 Revised information about the
GASPER‐Compatible SNMP Traps for the
contactless card reader.

Revised the registry path for the

contactless card reader and added
information about the configuration to
change the contactless card reader device
mode.

Revised the table “Contactless Enabler

Schema” with new elements related to the
contactless card reader.

Added information about Device Variants

and Firmware Versions.

1‐37 & Added information about

5‐389 updating the GBXX cassette configuration
sets from the supervisor option.

1‐44 & Added information about journaling

5‐288 location information of notes along with
the serial number in a dispense transaction
on a BRM device.

1‐42 & Added information about reporting

5‐372 cumulative count of notes per operation.

1‐42, 5‐331 Added information about logging the

& 5‐376 serial number of the deposited notes to the
ECB6Log database.

1‐45 & Added information about

5‐344 capturing bunch note image on a BRM
device during a deposit transaction.

1‐46 & Added a section about journaling the

5‐363 count of notes that pass through the bill
validator in case of a deposit transaction
with a hardware error.

4‐3 Added Card Eject State (z026) in the list of

DLLs for authored state types.

4‐4 Added the list of application dlls for

non‐authored state types.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

vi APTRA™ Advance NDC, Developer’s Guide

 Revision Record

Date Page Description of Change

4‐11 Added information about contactless card

reader.

5‐328 Added information about configuring

reject and/or retract bins for depositing
notes during a deposit transaction.

5‐68 & 5‐74 Added information about archiving and

deletion of the SNR image files.

5‐68, 5‐75 & Added information about

5‐289 capturing bunch note image on a BRM
device during a dispense transaction.

5‐115 Revised signature verification service

topic to mention that now all the
deliverables of Advance NDC are digitally
signed.

5‐136 Added information about disabling clear

key in the PIN entry state.

5‐143 Information added about mapping the

entire touch area on the screen to FDK D
for cardless transactions.

5‐164 Revised information related to the

foreground, background,
defaultForeground and
defaultBackground colour in the
“Advance NDC Display XML Elements”
table.

5‐172 Revised information about the elements:

windowMode, defaultOutOf
Service and nestedScreens.

5‐172 Revised runtime installation default value

for the topMost attribute under the
windowMode element.

5‐206 Added a new section to

describe the e‐receipt functionality.

5‐248 & Added a Note to describe

5‐254 that the SST must be rebooted if change is
made to the Beep, widthSwitchTimer
and/or EnableDelayTimer elements in the
ContactlessEnabler.xml when the XFS
mode is enabled.

5‐257 Revised default value of the registry

‘EnableCardDetectEvent’.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA™ Advance NDC, Developer’s Guide vii

Revision Record

Date Page Description of Change

5‐279 Information added regarding last

transaction reply in table “Treatment of
Notes After a Power Failure”.

5‐279 Added information about reporting count

of notes in unknown location in case of a
hardware error in a dispense transaction.

5‐288 Added a registry configuration to

enable/disable the serial number read
functionality in a dispense transaction.

5‐299 Revised the registry entry to update the

path for cUnitIDs & PurgeBinReporting.

5‐302 Added information about reporting

mStatus during prepare dispense
command failure in the Card Read
State/Prepare Dispense State (z024) and
Close State.

5‐304 Added information about journaling the

summary of presented and retracted
notes.

5‐308 Revised the statement of the MDM service

provider limitation.

5‐309 & Added information about handling

C‐31 incorrect denomination and short
dispense.
Also updated the “Note Counters” table
with new CDIs.

5‐323 Added a new section to describe the

configuration detail of retaining
destination for the notes in escrow during
Close State.

5‐331, 5‐337 Revised the Name and Assembly of the

& 5‐341 serial number information.

5‐332 & Table “Serial Number Journal

5‐342 Configuration Properties” is updated with
the information about the SNR image file.

Added information about the captured

SNR image file name format.

5‐333 Added information about journaling

location of notes for a deposit transaction.

5‐336 Reference added to the Supervisor’s

Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

viii APTRA™ Advance NDC, Developer’s Guide

 Revision Record

Date Page Description of Change

5‐368 Added information about logging

signatures of good notes in a deposit
transaction.

5‐389 & Added information about automatic

5‐406 cassette mapping using the
PhysicalPositionMap Property.

5‐407 Added information about the GBXX

Device with non‐configured cassettes.

5‐413 Added a new section to describe about

fixed cassette mapping for a BRM device.

5‐419 Revised default path where cheque

images are stored.

6‐7 & 6‐10 Added a new topic to describe voicing out

last entered key cumulatively.

C‐10 Added CDIs that store information about

note counts that pass through the bill
validator in “BNA MISC table”.

C‐11 & Added information about

5‐348 reporting the reject bin count as
UNKNOWN when an invalid note is
moved to the reject bin.

H‐1 & H‐12 Information added about the CxM

Content Deployer.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA™ Advance NDC, Developer’s Guide ix

Revision Record

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

x APTRA™ Advance NDC, Developer’s Guide

 Table of Contents

Contents

Preface

Conventions Used in This Publication ............................................ l

What Is in This Publication?............................................................lii
Who Should Read This Publication?.............................................liii
What Experience Should I Have? ..................................................liv
Support Information.........................................................................lv

Chapter 1
Introducing Advance NDC

Overview ................................................................................................1‐1
Advance NDC Implementation ..........................................................1‐2
Application Core ...................................................................................1‐4
Managing SST Modes.....................................................................1‐4
Message Handling ..........................................................................1‐4
Activating the Customisation Layer and Supervisor ................1‐5
Enhancing the Application Core ..................................................1‐5
Supervisor...............................................................................................1‐7
Customisation Layer .............................................................................1‐8
State Type Modules ........................................................................1‐8
Upgrading from an Earlier Release of Advance NDC ..............1‐8
Migrating from NDC+ to Advance NDC ....................................1‐8
Synchronisation Between Applications ...........................................1‐10
Common Data Interface .....................................................................1‐11
Common Data Interface...............................................................1‐11
User‐defined Common Data Interface.......................................1‐13
Advance NDC Development.............................................................1‐15
The Advance NDC Application..................................................1‐15
Feature Support.............................................................................1‐15
Internet Protocols..........................................................................1‐36
Troubleshooting Assistance ........................................................1‐36
Cash Acceptors..............................................................................1‐37
Product Class Support .................................................................1‐46

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xi

Table of Contents

Support for CEN‐XFS ...................................................................1‐47

Screen Management......................................................................1‐47
Image and Media Support ...........................................................1‐49
Voice Guidance .............................................................................1‐49
Maximum State Number .............................................................1‐50
Remote Key Management............................................................1‐50
Changing the MAC Encryption Key ..........................................1‐50
Dual‐Mode Journal Printing........................................................1‐50
Format of Journaled Messages....................................................1‐51
APIs for C Exits to Print to Any Printer.....................................1‐51
Night Safe.......................................................................................1‐51
ActiveX Controls ...........................................................................1‐51
Master Expansion State ................................................................1‐51
.NET Assemblies for Advance NDC ..........................................1‐52
Self‐Service Terminal Configuration Component....................1‐53
Configuration of Fixed Drives ....................................................1‐54
PCI DSS Compliance ....................................................................1‐54
Runtime Installation Directories.................................................1‐55
Directories for Customisations....................................................1‐55
Installation Types..........................................................................1‐55
Custom Directory..........................................................................1‐55
Media Entry Indicator (MEI) on Spray Dispensers..................1‐55
Unsupported Features..................................................................1‐56
Differences Between Advance NDC and NDC+.............................1‐57
Aggregate Building.......................................................................1‐58
Cash Dispenser—Beeping ...........................................................1‐58
Cash Dispenser—Cassette Types ...............................................1‐58
Cash Dispenser—Supplies Status...............................................1‐58
TM‐Alert.........................................................................................1‐59
Document Processing Module ....................................................1‐59
Coin Dispenser ..............................................................................1‐62
Digital Audio Service ...................................................................1‐64
State Types .....................................................................................1‐65
Configuration Parameters............................................................1‐66
Customisation Data Commands.................................................1‐67
PIN Entry and Verification ..........................................................1‐67
BAPE Emulation............................................................................1‐68
Electronic Journal and Journal Printer Backup.........................1‐68
Screen Data ....................................................................................1‐70
K Screens ........................................................................................1‐70
Diebold Emulation Mode Status Messages...............................1‐70
Status Messages.............................................................................1‐70

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xii APTRA Advance NDC, Developer’s Guide

 Table of Contents

Alarms and Tamper Indication...................................................1‐71

Option Digits .................................................................................1‐71
Supervisor Mode...........................................................................1‐72
Differences in MACing ................................................................1‐73
Communications Protocols .........................................................1‐73
Basic Operator Panel (BOP).........................................................1‐74
VGA Enhanced Rear Operator Panel (VEROP) .......................1‐74
Graphics .........................................................................................1‐74
Security Camera ............................................................................1‐74
Software Management .................................................................1‐75
Associated Keyboards ..................................................................1‐75
Bunch Note Acceptor (BNA) and Cheque Processing Module
(CPM) ...........................................................................................1‐75
Transaction Request Extension State .........................................1‐76
Font Definition ..............................................................................1‐76
Character Sets ................................................................................1‐76
Localising Advance NDC ............................................................1‐76
Unsolicited Status Messages .......................................................1‐77
Multi‐Media File Support ............................................................1‐77
Number of Screens Supported....................................................1‐77
Support for Screens.......................................................................1‐78
Set Display Mode Control Sequence..........................................1‐78
Passbook Printer Support ............................................................1‐78
Roll Width and Left Margin ........................................................1‐78
Envelope Dispensing....................................................................1‐78
Remote Status Indicators .............................................................1‐79
Aggregate Building .............................................................................1‐80
Advance NDC Aggregate............................................................1‐80
Customising Aggregates..............................................................1‐80
User‐Created Components ..........................................................1‐80

Chapter 2
Installing Advance NDC on a Development PC

Overview ................................................................................................2‐1
System Requirements ...........................................................................2‐2
Supported Operating Systems ......................................................2‐2
Installation Process................................................................................2‐3
Before You Start ..............................................................................2‐3
Installation Types............................................................................2‐3
Installing Advance NDC on a Development PC........................2‐4
After Installation .............................................................................2‐5

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xiii

Table of Contents

De‐installing Advance NDC..........................................................2‐6

Chapter 3
Migrating Existing NDC+ Applications to Advance NDC

Overview ................................................................................................3‐1
Executing an Entire NDC+ Download ...............................................3‐2
Changes Required...........................................................................3‐2
Recreating Graphics ..............................................................................3‐3
Cardholder Graphics ......................................................................3‐3
Logo Control....................................................................................3‐3
Picture Control ................................................................................3‐3
Display Image Files Control ..........................................................3‐4
Load Graphics .................................................................................3‐4
Recreating Audio Files..........................................................................3‐5
Recreating Animation Files..................................................................3‐6
Changing RESRVD.DEF .......................................................................3‐8
Recreating Communications Template Files.....................................3‐9
Proving the Download Works ...........................................................3‐10

Chapter 4
Upgrading from Earlier Releases of Advance NDC

Overview ................................................................................................4‐1
Modularisation and the Single Executable ........................................4‐2
New Authored States .....................................................................4‐2
SSDS DLL Interface Worker ..........................................................4‐3
New Application DLLs ..................................................................4‐3
Feature Support .....................................................................................4‐6
Changes to the Interface since Release 2.6 ..................................4‐6
Communications .............................................................................4‐8
RSA Initial Key Loading ................................................................4‐8
Additional BNA Functionality......................................................4‐8
Enhanced Night Safe ......................................................................4‐8
Enhanced Configuration Parameters Load.................................4‐8
BAPE Emulation..............................................................................4‐9
EMV C Exits.....................................................................................4‐9
Keyboard Data.................................................................................4‐9
Supervisor Menus ...........................................................................4‐9
Fault Display..................................................................................4‐10
User Messages and User Terminal Data Implementation ......4‐10
APTRA Simulator .........................................................................4‐10

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xiv APTRA Advance NDC, Developer’s Guide

 Table of Contents

EMV on Contactless Card Readers ............................................4‐11

Upgrading Your Release of Advance NDC.....................................4‐12
Authored Customisations............................................................4‐12
Worker Class Support ..................................................................4‐13
C Exits.............................................................................................4‐13
Cardholder Screen Display..........................................................4‐14
Device Access ................................................................................4‐14
Supplies Data Sources ..................................................................4‐16
Fitness Data Sources .....................................................................4‐17
Message Handling ........................................................................4‐18
User Messages and User Terminal Data....................................4‐19
Printing...........................................................................................4‐20
STCONT File Updates..................................................................4‐23
Promote Campaigns .....................................................................4‐24

Chapter 5
Configuring Advance NDC and Associated Components

Overview ................................................................................................5‐1
Automatic Configuration at Start‐up .................................................5‐2
Supervisor Option to Auto‐configure Devices ...........................5‐2
SST Configuration Component.....................................................5‐2
ANDCSST.XML Elements ............................................................5‐4
Example ANDCSST.XML Extracts.............................................5‐11
Configuring an Advance NDC Application....................................5‐14
Advance NDC Registry Entries ..................................................5‐14
CEN‐XFS Logical Device Names ................................................5‐17
Active XFS Aliases for Cash and Cheque Acceptors ...............5‐18
Status Handling.............................................................................5‐19
Remote Status Indicators .............................................................5‐19
Unsolicited Status Messages for External System Events.......5‐19
Power‐Up Status Message ...........................................................5‐20
Registry Settings for Device Status Messages...........................5‐20
Enabling Web Exits.......................................................................5‐21
Specifying Local Customisation Data ........................................5‐22
Changing the Next State Number ..............................................5‐25
Security Cameras ..........................................................................5‐26
Configuring Data Masking and Logging ..................................5‐32
Support for DVDs on SSTs ..........................................................5‐35
Unsupported Configuration Options ........................................5‐35
Promote Flow Point Behaviour...................................................5‐35
Configuration Files..............................................................................5‐37

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xv

Table of Contents

XML Configuration Files .............................................................5‐37

.NET Class Configurator Files.....................................................5‐40
Configuring Communications...........................................................5‐44
Service Class ..................................................................................5‐44
Clearing the Communications Buffer ........................................5‐44
Off‐line Timer ................................................................................5‐45
TCP/IP Configuration...................................................................5‐45
Dialup Configuration ...................................................................5‐49
Dialup Timers and Modem Baud Rate ......................................5‐52
Configuring Diagnostics Options .....................................................5‐53
Displaying Additional Diagnostics Menus ...............................5‐53
Show/Hide Diagnostics Shortcut................................................5‐53
Disabling Self‐Test on Diagnostics Exit .....................................5‐54
Configuring Service Providers ..........................................................5‐55
Configuring Service Providers (SPs) for Reboot ......................5‐55
Service Provider Reset Value ......................................................5‐55
Service Provider Tracing..............................................................5‐56
Configuring SP Support for CEN‐XFS Versions ......................5‐56
Configuring SNMP Traps...................................................................5‐58
No Transaction Traps ...................................................................5‐59
Application Heartbeats ................................................................5‐59
Advance NDC Mode Change Traps ..........................................5‐60
Implementation of SNMP Traps.................................................5‐60
Configuring .NET Archive Manager ................................................5‐65
Configuration Properties .............................................................5‐65
General Configuration .................................................................5‐66
Archive Data Configuration Examples......................................5‐68
SST Properties Configuration Examples ...................................5‐77
Additional Configuration ............................................................5‐79
Configuring .NET Retrieve Archive Task........................................5‐82
Example Updates to Settings.......................................................5‐82
Configuring the .NET NDC CRM Service .......................................5‐86
Terminal ID Source .......................................................................5‐87
Configuring SST Recovery .................................................................5‐89
NDC Monitor.................................................................................5‐89
Forced Reboot ................................................................................5‐93
Resetting USB Devices .................................................................5‐94
Uninterruptible Power Supply ...................................................5‐99
Configuring Suspend Timeout ........................................................5‐100
Setting the Service Provider Timeout ......................................5‐100
Setting the Application Timeout...............................................5‐101
Setting the Unusual Object Monitoring Timeout ...................5‐101

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xvi APTRA Advance NDC, Developer’s Guide

 Table of Contents

Configuring Supervisor Functionality ...........................................5‐103

Settlement Screen Customisation .............................................5‐103
Extended Add Cash Option ......................................................5‐103
Rear Settlement ...........................................................................5‐104
Supervisor Alphanumeric Data Entry .....................................5‐105
.NET Supervisor Task ................................................................5‐109
.NET Software Updates..............................................................5‐112
Promote/Copyfile........................................................................5‐116
Relate Supervisor Option...........................................................5‐116
Configuring Multiple Destination Screens to Display Fixed
Drives .........................................................................................5‐116
Configuring the Default Location for Note Signatures .........5‐117
Configuring Extracted Signatures ............................................5‐118
Configuring Denomination and Note ID Validation ............5‐118
Journaling Supervisor Mode Change During a Transaction 5‐119
Configuring Supervisor Entry/Exit Messages ........................5‐119
Configuring Cardholder Functionality ..........................................5‐121
Configuring Input Type, Buffer and Display Format ...........5‐121
Cardholder Alphanumeric Data Entry....................................5‐122
Cardholder Verification State in STCONT..............................5‐126
Confirmation Screens During Cash Deposit...........................5‐126
Disabling Clear Key in PIN Entry State...................................5‐136
Configuring Amount Entry.......................................................5‐136
Validating Buffer Data ...............................................................5‐139
Configuring Beep for Cardholder Transactions.....................5‐140
Cardless Transactions.................................................................5‐142
Configuring Keyboards ....................................................................5‐149
Front Keyboard ...........................................................................5‐149
Operator Keyboard.....................................................................5‐151
Touch‐screen Keyboards for Alphanumeric Data Entry ......5‐152
Configuring Screen Displays ...........................................................5‐155
Secure Key Entry.........................................................................5‐155
Display Manager for HTML Screens .......................................5‐155
Hide Taskbar ...............................................................................5‐155
AVI System Limit........................................................................5‐156
Advance NDC Display Components.......................................5‐156
Advance NDC Display Runtime Settings ...............................5‐176
Enabling Extended Screen Groups...........................................5‐178
Configuring the Electronic Journal .................................................5‐180
EJ Compression ...........................................................................5‐180
EJ Privacy .....................................................................................5‐180
Maximum EJ File Size ................................................................5‐180

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xvii

Table of Contents

EJ Checksum ................................................................................5‐180
Automatic Initialisation Options ..............................................5‐181
Delaying Initialisation During Transactions...........................5‐185
EJ Backup Filenames...................................................................5‐185
Multiple Destinations for EJ Backup........................................5‐186
Enhanced EJ Backup...................................................................5‐187
EJ Level .........................................................................................5‐188
Configuring Printers .........................................................................5‐189
Journal Printer Status .................................................................5‐189
Receipt Printer .............................................................................5‐191
Statement Printer ........................................................................5‐195
USB Statement Printer................................................................5‐196
Forms‐Based Printing .................................................................5‐196
USB Receipt and USB Journal Printers ....................................5‐199
LEAP Receipt Printer..................................................................5‐202
Non‐Thermal Printers ................................................................5‐203
Passbook Printer..........................................................................5‐203
64‐Bit Windows 7: Importing Printer
Registry Files Manually ...........................................................5‐205
Configuring E‐Receipt ......................................................................5‐206
E‐Receipt Service
Component ................................................................................5‐206
Configuring E‐Receipt................................................................5‐206
Configuring Readers .........................................................................5‐209
Accepting Smart Cards in Motorised Card Readers..............5‐209
Additional DASH Reader Fatal/Suspend Handling..............5‐209
Barcode Reader Filter and Extraction Rules ...........................5‐210
Contact and Contactless Card Readers....................................5‐213
Configuring Contactless Card Reader .....................................5‐228
Smart Delay Timer for Smart Dip Card Reader .....................5‐262
Configuring Coin Dispensers ..........................................................5‐264
Registry Keys for the Coin Dispenser ......................................5‐264
Setting the Currency ...................................................................5‐264
Setting the Coin Value................................................................5‐264
Setting the Low Threshold for Coins .......................................5‐265
Supplies and Severity Information...........................................5‐265
Configuring Cash Handlers .............................................................5‐267
Setting the Currency ...................................................................5‐267
Setting the Media Type ..............................................................5‐268
Setting the Denomination ..........................................................5‐268
Setting the Cassette Identifier ...................................................5‐268
Setting the Cash Unit Identifiers for Supervisor ....................5‐268

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xviii APTRA Advance NDC, Developer’s Guide

 Table of Contents

Cash Dispenser Cassette Status ................................................5‐269

Cassette Information Screen......................................................5‐271
Setting Multiple Currencies.......................................................5‐275
Disabling Retract after Suspend ...............................................5‐275
CDM Status When Notes are at Exit Slot ................................5‐276
Reporting Pick Failure Errors....................................................5‐277
Unknown Status of Notes After a Power Failure...................5‐278
Journaling the Count if a Present is Attempted Before a Power
Fail...............................................................................................5‐279
Count of Notes in Unknown Location.....................................5‐279
Cash Handler with a Fifth Physical Cassette..........................5‐280
Enabling Support for Seven Cassette Types ...........................5‐280
Setting Note Thresholds.............................................................5‐281
Configuring the MEI for a Spray Dispenser ...........................5‐282
Supplies and Severity Information...........................................5‐283
Reading and Journaling Serial Numbers.................................5‐288
Capturing Bunch Note Image ...................................................5‐289
Logging Signatures of Dispensed Notes to Database............5‐290
Dual Cash Handler Configuration ...........................................5‐293
S2 Media Dispenser Module .....................................................5‐297
Carriage Sweep ...........................................................................5‐299
Prepare Dispense ........................................................................5‐300
Retract Options............................................................................5‐302
Report Reject and Retract bins Physical Counts.....................5‐307
Tamper Indication on an S2 Dispenser....................................5‐308
Handling Incorrect Denomination and Short Dispense........5‐309
Configuring Cash Acceptors............................................................5‐313
Cash Acceptor Installation Settings .........................................5‐313
Positioning the Reason for Note Refusal.................................5‐320
Defining the Please Wait screen ...............................................5‐320
Setting the Volume .....................................................................5‐320
Combined Cash Handler ...........................................................5‐320
Setting the Insertion Limit for Bunches of Notes ...................5‐320
Setting the Retry Limit for Note Insertion...............................5‐321
Transaction Request Cumulative Counts................................5‐321
Configuring Note Retract to the Escrow .................................5‐322
Configuring the Retain Destination for the
Notes in Escrow ........................................................................5‐323
Enabling Direct Deposit .............................................................5‐324
Setting the Transaction Cash‐In‐Limit.....................................5‐328
Configuring Reject and/or
Retract Bin for Depositing Notes............................................5‐328
Off‐line Cash Deposit Handling ...............................................5‐329

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xix

Table of Contents

Reading, Journaling and

Capturing Serial Numbers of Notes.......................................5‐331
Capturing Bunch Note Image ...................................................5‐344
Reconciliation List Customisation ............................................5‐346
Displaying and Printing BNA Counts .....................................5‐347
Printing BNA Totals, Displaying and
Printing BNA Counts ...............................................................5‐349
Printing BNA Totals ...................................................................5‐350
Reason for Refusing a Deposit ..................................................5‐357
Tamper Indication Journaling...................................................5‐358
Localising Tamper Indication Journaling................................5‐359
Note Type Mapping ...................................................................5‐360
Journaling Note Configuration Failures..................................5‐362
Journaling Note Validation Errors ...........................................5‐362
Journaling the Count of Notes that Pass through the Bill
Validator.....................................................................................5‐363
Device M‐Status Reporting........................................................5‐363
Suspend Handling ......................................................................5‐364
Error Recovery.............................................................................5‐364
ECB 6 Considerations .................................................................5‐367
Media Entry Indicator for a BNA .............................................5‐377
Encash, Print and Set Next State...............................................5‐377
Cash Deposit Exception Reporting...........................................5‐377
Journal Formats ...........................................................................5‐379
GBXX Dynamic Note Sorting ....................................................5‐386
GBXX Cassette Configuration ...................................................5‐388
Automatic Cassette
Mapping for a BRM Device.....................................................5‐407
Deposit Cassette Maximum Threshold ...................................5‐407
BRM Cassette Configuration.....................................................5‐407
Configuring a BRM device as a Deposit only
or a Dispense only ....................................................................5‐414
Configuring BRM to Swap Reject and Retract Bin.................5‐415
Validating the Incorrect Denomination ...................................5‐416
Configuring Cheque Processors......................................................5‐419
Accessing Cheque Data..............................................................5‐419
Cheque Processing Module .......................................................5‐419
Bunch Cheque Acceptor ............................................................5‐422
Cheque Amount Recognition....................................................5‐426
ImageMark Passport ATM Image Agent ................................5‐426
Envelope Dispenser ....................................................................5‐433
Configuring Colored MEEI ..............................................................5‐434
Configuring CRM Flowpoint State .................................................5‐436

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xx APTRA Advance NDC, Developer’s Guide

 Table of Contents

Chapter 6
Configuring Voice Guidance

Overview ................................................................................................6‐1
Introducing Voice Guidance................................................................6‐2
Support for Audio Messages.........................................................6‐2
Enabling Voice Guidance ..............................................................6‐2
Standard Audio Capabilities.........................................................6‐3
Enhanced Audio Capabilities .......................................................6‐4
Voice Guidance During a Transaction.........................................6‐5
Configuring Voice Guidance ...............................................................6‐7
Prompting for a Language.............................................................6‐7
Indicator Volume Control..............................................................6‐8
Automatic Language Selection .....................................................6‐8
Orientation Message.......................................................................6‐8
Configuring the Enter Key to Initiate Cardless Transactions...6‐8
Enabling Voice Guidance Without Host Updates .....................6‐9
Voice Out Entered Key.................................................................6‐10
Configuring the Idle Loop Audio...............................................6‐10
Configuring Third‐Party TTS Software .....................................6‐10
Specifying the Character Encoding ............................................6‐12
Audio Elements Required in the XML Configuration File .....6‐12
Other XML Files Used in Voice Guidance ................................6‐12
Advance NDC Voice Guidance and Other Applications ..............6‐14
Using Voice Guidance with Promote.........................................6‐14
Using Voice Guidance with Display Manager .........................6‐15
XML Schema ........................................................................................6‐16
Schema Elements ..........................................................................6‐24
Voicing the Multi‐Lingual Data Examples................................6‐42
Encoding Formats for Voice Guidance......................................6‐43
Example XML Configuration File .....................................................6‐45
Voice‐Guided Sessions without Host Update.................................6‐50
No Host Update XML Elements .................................................6‐50
Transaction Reply .........................................................................6‐59
Interactive Transaction Response...............................................6‐68
Send Configuration Information ................................................6‐79

Chapter 7
Introducing the Advance NDC Authored Applications

Overview ................................................................................................7‐1

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxi

Table of Contents

The APTRA Author...............................................................................7‐2

Customisation Layer .............................................................................7‐3
Customisation Layer Applications Catalog ................................7‐3
State Types Catalog ........................................................................7‐7
Customisation Layer Catalog........................................................7‐9
Transaction Reply Functions Catalog ..........................................7‐9
CDI ‐ <name> Catalog ....................................................................7‐9
NDC Core Catalog ..........................................................................7‐9
NDC Transactions Catalog ............................................................7‐9
NDC Encryption Keys Catalog .....................................................7‐9
NDC Field Workers Catalog .........................................................7‐9
Application Core..................................................................................7‐10
Application Core Project..............................................................7‐10
Application Core Catalog ............................................................7‐18
User Controls Catalog ..................................................................7‐18
User Stores and Signals Catalog .................................................7‐18
Synchronising with the Customisation Layer ..........................7‐18
Mode Handling .............................................................................7‐19
Message Handling ........................................................................7‐21
Message Handler ..........................................................................7‐24
Supervisor Mode .................................................................................7‐29
Handle Switch Work Group........................................................7‐30
Activating the Supervisor Application ......................................7‐31
Supervisor Project .........................................................................7‐31
Shared Stores .................................................................................7‐34
Testing the Advance NDC Application ...........................................7‐35
Running in the PC Environment ................................................7‐36
Running in the Author Environment.........................................7‐37
Using the XFS Simulator ..............................................................7‐38
Simulating Communications.......................................................7‐45
Simulating a Passbook Printer ....................................................7‐45
Using the Command Line Utility......................................................7‐47
The Customisation Data Database File ......................................7‐47
Using the Custdat.exe Utility ......................................................7‐48
Error Messages ..............................................................................7‐49

Chapter 8
Modifying the Customisation Layer

Overview ................................................................................................8‐1
Modification Options ............................................................................8‐2
Level 1 Customisation ....................................................................8‐2

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxii APTRA Advance NDC, Developer’s Guide

 Table of Contents

Level 2 Extensions and Enhancements........................................8‐3

Methods of Enhancing the Customisation Layer.......................8‐3
Before Modifying the Customisation Layer ......................................8‐4
Customisation Guidelines .............................................................8‐4
Impact of Changing the Customisation Layer............................8‐5
Compatibility Considerations .......................................................8‐5
Documenting Changes...................................................................8‐6
Preparation Guidelines ..................................................................8‐7
Level 1 Modification Example...........................................................8‐10
Journal Level Trigger Value ........................................................8‐10
Journaling Examples ....................................................................8‐11
Level 2 Modification Examples .........................................................8‐13
Replacing State Types with Workers .........................................8‐13
Editing State Types Authored in Advance NDC .....................8‐16
Creating New State Types ...........................................................8‐16
Transaction Request/Reply ................................................................8‐18
Before Modifying the Transaction Request/Reply ...................8‐18
Adding Data Fields to a Transaction Request ..........................8‐18
New Function IDs in a Transaction Reply ................................8‐19
New Printer Flags in a Transaction Reply.................................8‐20
NDC Transaction Handler...........................................................8‐20
Testing the Customisation Layer ......................................................8‐26
Extending the Runtime Application.................................................8‐27

Chapter 9
Enhancing the Application Core or Supervisor

Overview ................................................................................................9‐1
Customising the Application Core .....................................................9‐2
Overview of User Messages/Terminal Data ...............................9‐2
Before Modifying the Application Core.............................................9‐4
Compatibility Considerations .......................................................9‐4
Preparation Guidelines ..................................................................9‐4
Customisation Guidelines .............................................................9‐4
Processing a New Message Class........................................................9‐5
Default User Messages Implementation......................................9‐5
Summary of Procedure ..................................................................9‐7
Example User Messages Implementation ...................................9‐8
Adding Additional Data to Terminal State Messages ...................9‐11
Default User Terminal Data Implementation ...........................9‐11
Procedure for Adding User Terminal Data...............................9‐13
Example User Terminal Data Director ......................................9‐13

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxiii

Table of Contents

Processing new Enhanced Configuration Parameters ...................9‐15

Altering Modes ....................................................................................9‐16
Start of Day and Initialise Tasks .................................................9‐16
In Service Mode.............................................................................9‐17
Out Of Service Mode ....................................................................9‐17
Offline Mode..................................................................................9‐17
Supervisor Mode...........................................................................9‐18
Enhancing the Supervisor Application ............................................9‐19
Customisation without Using APTRA Author ........................9‐19
Customisation Using APTRA Author .......................................9‐19

Chapter 10
Using User‐defined CDI Stores

Overview ..............................................................................................10‐1
UCDI Service ........................................................................................10‐2
UCDI Initialisation File.......................................................................10‐3
Persistence Levels ................................................................................10‐4
Creating a UCDI Store ........................................................................10‐5
Accessing a CDI & UCDI Store .........................................................10‐9

Chapter 11
Delivering an Advance NDC Aggregate to the SST

Overview ..............................................................................................11‐1
Advance NDC on Windows 7
64‐bit and Windows 10 64‐bit Systems ..........................................11‐2
32‐Bit to 64‐Bit Folder Mapping..................................................11‐2
64‐Bit Folder Renaming................................................................11‐2
Registry Entry Redirection ..........................................................11‐3
Interactive Installation of Advance NDC.........................................11‐4
Before You Start.............................................................................11‐4
Installing Advance NDC on an SST ...........................................11‐5
SST Directory Structure................................................................11‐5
Starting the Advance NDC Application....................................11‐7
Including the Runtime Only Component in an Aggregate...........11‐8
Creating a Runtime Only Aggregate .........................................11‐8
Secure Initial Unattended Installation (IUI) ....................................11‐9
Advance NDC and Security for APTRA ...................................11‐9
Advance NDC Customisations and Security for APTRA.......11‐9
Implementing Security for APTRA with Advance NDC........11‐9
NCR Encryptor Configuration ........................................................11‐10

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxiv APTRA Advance NDC, Developer’s Guide

 Table of Contents

Registry Setting for EPP Devices ..............................................11‐10

Registry Setting for BAPE Devices ...........................................11‐11
Setting Basic or Enhanced Mode ..............................................11‐11
Key Names...................................................................................11‐11
Changing the Encryptor—Scenarios........................................11‐12
Retaining Encryption Keys........................................................11‐13
Troubleshooting Key Manager .................................................11‐15
Preparing a Modified Advance NDC Aggregate .........................11‐16
Creating Aggregate Subsets and Supersets ............................11‐16
Tools Component........................................................................11‐16
Extending the Supplied Application........................................11‐17
Installing the Aggregate.............................................................11‐19
De‐installing the Aggregate ......................................................11‐19
Post‐Installation Activities.........................................................11‐19
De‐installing Advance NDC ............................................................11‐21
De‐installing .NET Assemblies........................................................11‐22

Chapter 12
Installing and Configuring Troubleshooting Tools

Overview ..............................................................................................12‐1
Advance NDC Troubleshooting Utilities.........................................12‐2
Selecting a Debugging Utility .....................................................12‐2
Event and Error Logs ..........................................................................12‐4
Advance NDC Trace Information.....................................................12‐5
Tracing from C++ Code ................................................................12‐6
Tracing in the Author ...................................................................12‐6
State Flow Tracing...............................................................................12‐9
Enabling State Flow Tracing .......................................................12‐9
State Flow Trace Journaling ........................................................12‐9
Always On Tracing ...........................................................................12‐11
Installing and Configuring Silent Debug.......................................12‐12
Silent Debug Installation............................................................12‐12
Configuring Silent Debug..........................................................12‐13
Installing and Configuring DebugLog ...........................................12‐16
DebugLog Installation................................................................12‐16
Configuring DebugLog..............................................................12‐16
Using the Troubleshooting Tools....................................................12‐19
Troubleshooting with Problem Determination ......................12‐19
Troubleshooting with Silent Debug .........................................12‐22
Troubleshooting with DebugLog .............................................12‐25

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxv

Table of Contents

Chapter 13
Modifying the Advance NDC Applications

Overview ..............................................................................................13‐1
Ways of Modifying Advance NDC...................................................13‐2
Use an Existing Implementation.................................................13‐2
Modify or Create an Implementation ........................................13‐2
Programming Techniques ..................................................................13‐4
C Exits .............................................................................................13‐4
Using the Author ..........................................................................13‐4
Exposed Functions for PS Customisation..................................13‐6
Further Reading ............................................................................13‐7

Appendix A
Related Documentation

Overview ...............................................................................................A‐1
Advance NDC Documentation ..........................................................A‐2
APTRA Author Documentation.........................................................A‐4
NDC+ Documentation .........................................................................A‐6
Other NCR Documentation ................................................................A‐7
CEN‐XFS Documentation....................................................................A‐9

Appendix B
Advance NDC Workers Supplied

Overview ............................................................................................... B‐1

Customisation Layer Workers ............................................................ B‐2
NDC Core Workers .............................................................................. B‐4
Application Core Workers .................................................................. B‐9
Passbook Printer Workers ................................................................. B‐12
Voice Guidance Workers................................................................... B‐14
Miscellaneous Workers...................................................................... B‐15
Basic Self‐Service.......................................................................... B‐15
Special Self‐Service ...................................................................... B‐16
Self‐Service Core .......................................................................... B‐16
ATM ............................................................................................... B‐17

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxvi APTRA Advance NDC, Developer’s Guide

 Table of Contents

Appendix C
Common Data Interface Stores

Overview ............................................................................................... C‐1

Barcode................................................................................................... C‐3
BNA Accepted Denomination Counts .............................................. C‐4
BNA Active Banknotes ........................................................................ C‐5
BNA Counters....................................................................................... C‐6
BNA Denomination Configuration ................................................... C‐8
BNA Deposited Denomination Counts............................................. C‐9
BNA MISC ........................................................................................... C‐10
Buffers .................................................................................................. C‐12
Coin Counters ..................................................................................... C‐14
CPM ...................................................................................................... C‐15
CPM MISC........................................................................................... C‐16
Dial up.................................................................................................. C‐17
EJ Upload............................................................................................. C‐19
EMV...................................................................................................... C‐20
Encryptor Variant............................................................................... C‐21
Error Processing.................................................................................. C‐22
Exit Migration ..................................................................................... C‐23
FIT Data................................................................................................ C‐25
Key Entry Mode.................................................................................. C‐29
Misc Counters ..................................................................................... C‐30
Note Counters ..................................................................................... C‐31
Option Digit Stores............................................................................. C‐34
Printing ................................................................................................ C‐35
Screen Display..................................................................................... C‐37
Security ................................................................................................ C‐38
State Information ................................................................................ C‐41
Supervisor............................................................................................ C‐44
Terminal Configuration..................................................................... C‐47
Timers................................................................................................... C‐51
Transaction Processing Flags............................................................ C‐53
UCDI Stores......................................................................................... C‐55
Voice Guidance Stores ....................................................................... C‐56
Miscellaneous CDIs............................................................................ C‐57
Accessing CDI Store Values.............................................................. C‐58

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxvii

Table of Contents

Appendix D
Font Definition

Overview ...............................................................................................D‐1
Defining Fonts.......................................................................................D‐2
Creating Fonts ................................................................................D‐2
Font Configuration ........................................................................D‐2
Installing Fonts......................................................................................D‐9
Checking the Fonts .............................................................................D‐10

Appendix E
PCI DSS & PA‐DSS Compliance in Advance NDC

Overview ............................................................................................... E‐1

PA‐DSS and Compliance with PCI DSS............................................ E‐2
PCI DSS Requirements .................................................................. E‐2
Advance NDC and PA‐DSS Requirements................................ E‐3
Other PA‐DSS Requirements ....................................................... E‐4
Advance NDC Modifications for PA‐DSS Compliance.................. E‐5
Debugging....................................................................................... E‐5
Journaling........................................................................................ E‐6
Cash‐In Component....................................................................... E‐7
DAPI Requirements....................................................................... E‐8
Supervisor Authentication............................................................ E‐8
Cheque Processing Solutions............................................................ E‐11
Storing Cheque Images ............................................................... E‐11
Displaying Cheque Images......................................................... E‐11
Printing Cheque Images.............................................................. E‐11
Deleting Cheque Images Securely ............................................. E‐11
Cheque Processing with ImageMark Passport........................ E‐12
External Audits ................................................................................... E‐14
Advance NDC Solutions and Compliance............................... E‐14
Advance NDC Customisations and Compliance.................... E‐14

Appendix F
Example Custom.ini Files

Overview ................................................................................................F‐1
Runtime SST Example...........................................................................F‐2
Development Example .........................................................................F‐4

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxviii APTRA Advance NDC, Developer’s Guide

 Table of Contents

Appendix G
User‐Configurable States

Overview ...............................................................................................G‐1
Web Exit State .......................................................................................G‐2
State Table Parameters ..................................................................G‐2
Tracking URLS ...............................................................................G‐3
Extension to the Web Exit State ...................................................G‐4
Web Exit Configuration.......................................................................G‐6
WebExitURLTable.XML File ...........................................................G‐6
Adding Websites to the Trusted Sites Zone...............................G‐6
Updating STCONT ........................................................................G‐7
Updating the State Flow ...............................................................G‐7
Configuring Web Page Download Timer...................................G‐8
Cardholder Verification State ...........................................................G‐10

Appendix H
Advance NDC and Customer Relationship Management

Overview ...............................................................................................H‐1
Configuring APTRA Promote and APTRA Relate..........................H‐2
Enable/Disable Promote................................................................H‐2
Configuring Consumer ID............................................................H‐3
Multiple Backgrounds Support in Relate ...................................H‐3
Promote Flowpoint Configuration for Continuous Display ...H‐4
Relate Coupon Printing.................................................................H‐7
Reporting Errors in a Relate Transaction ...................................H‐9
Cancelling a Marketing Session.................................................H‐10
Displaying Promote Campaigns................................................H‐10
Input Validation ...........................................................................H‐10
Configuring CxM Content Deployer...............................................H‐12

Glossary
Glossary .................................................................................... Glossary‐1

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxix

Table of Contents

Index
Index ................................................................................................Index‐1

User Feedback Form

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxx APTRA Advance NDC, Developer’s Guide

 List of Figures

List of Figures

Chapter 1
Introducing Advance NDC

Figure 1‐1 Advance NDC Architecture .........................................1‐2

Chapter 4
Upgrading from Earlier Releases of Advance NDC

Figure 4‐1 Double‐Width Printing Example ...............................4‐21

Chapter 5
Configuring Advance NDC and Associated Components

Figure 5‐1 Example SST XML Extract 1 .......................................5‐11

Figure 5‐2 Example SST XML Extract 2 .......................................5‐12
Figure 5‐3 Example SST XML Extract 3 .......................................5‐13
Figure 5‐4 Example SST XML Extract 4 .......................................5‐13
Figure 5‐5 Example Advance NDC Registry Extract.................5‐14
Figure 5‐6 Example Active XFS Aliases.......................................5‐18
Figure 5‐7 Example State Translator XML Extract.....................5‐25
Figure 5‐8 Example Security Camera XML Extract ...................5‐26
Figure 5‐9 Example Camera Service Configuration Extract .....5‐29
Figure 5‐10 Example Adding Flow Points Extract .......................5‐31
Figure 5‐11 XML Envelope Schema ...............................................5‐38
Figure 5‐12 Example Replacement XML .......................................5‐40
Figure 5‐13 Example Connections Settings Extract......................5‐47
Figure 5‐14 Example TCPIP Communications XML Extract......5‐48
Figure 5‐15 APTRA and SNMP ......................................................5‐58
Figure 5‐16 Example STD Achieve Manager Extract...................5‐66
Figure 5‐17 Example STD Achieve Manager Extract...................5‐66
Figure 5‐18 Example 1 Scheduling Archives Extract ...................5‐67
Figure 5‐19 Example 2 Scheduling Archives Extract ...................5‐67

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxxi

List of Figures

Figure 5‐20 Example Archive Manager Array Extract ................5‐68

Figure 5‐21 Example Archive Manager
Array Scheduler Extract ............................................5‐69
Figure 5‐22 Example Archive PD Investigation File Extract ......5‐69
Figure 5‐23 Example Archive Cache Files Extract........................5‐70
Figure 5‐24 Deleting Backed up Cache Files Extract....................5‐71
Figure 5‐25 Example Archive XFS Trace File Extract ..................5‐71
Figure 5‐26 Example Archive Event Log Extract..........................5‐72
Figure 5‐27 Example Archive Manager EJ Data Files Extract ....5‐72
Figure 5‐28 Example Archive Manager ECB 6 Database Files
Extract ..........................................................................5‐73
Figure 5‐29 Example Archive UEH Files Extract..........................5‐74
Figure 5‐30 Example Archive SNR Image Files Extract ..............5‐74
Figure 5‐31 Example SNR Image Files (Group‐wise) Extract.....5‐75
Figure 5‐32 Example Archive Bunch Note Image Files Extract .5‐76
Figure 5‐33 Example Bunch Note Image
Files (Group‐wise) Extract ........................................5‐76
Figure 5‐34 Example SST Properties Extract .................................5‐77
Figure 5‐35 Example Financial Institute Details Extract .............5‐77
Figure 5‐36 Example SST and Network ID Extract ......................5‐78
Figure 5‐37 Example Network ID Array Extract ..........................5‐78
Figure 5‐38 Example Financial Institution Address Extract .......5‐78
Figure 5‐39 Example Financial Institute Address Array Extract5‐79
Figure 5‐40 Example 1 Scheduling Archives Extract ...................5‐80
Figure 5‐41 Example Archive Registry Keys Extract ...................5‐81
Figure 5‐42 Example Change Export Folder Extract....................5‐83
Figure 5‐43 Example Change Date Format Extract ......................5‐84
Figure 5‐44 Example 1 Scheduling Archives Extract ...................5‐85
Figure 5‐45 Example Language Mapping Extract........................5‐86
Figure 5‐46 Example Terminal ID Source Extract ........................5‐87
Figure 5‐47 Example NDC Monitor XML Extract ........................5‐91
Figure 5‐48 Example Device Recovery XML Extract ...................5‐97
Figure 5‐49 Example Supervisor Keyboard XML Extract .........5‐106
Figure 5‐50 Example Start Investigation and Delete Investigation
Extract ........................................................................5‐110
Figure 5‐51 Example Supervisor Task Wrapper Extract ...........5‐111
Figure 5‐52 Example Configuring Installation Script Extract...5‐112
Figure 5‐53 Example Enabling Software Update
Function Extract .......................................................5‐113
Figure 5‐54 Example Configuring Copy File
Directory Extract ......................................................5‐113
Figure 5‐55 Example Enabling File Copy Extract.......................5‐114

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxxii APTRA Advance NDC, Developer’s Guide

 List of Figures

Figure 5‐56 Example Configuring .NET Software Update Service

Extract ........................................................................5‐114
Figure 5‐57 Example Default Location Note
Signature Extract ......................................................5‐117
Figure 5‐58 Example Configuring Extracted
Signature Extract ......................................................5‐118
Figure 5‐59 Example Display Data Format Extract....................5‐121
Figure 5‐60 Example Data Translators Extract ...........................5‐133
Figure 5‐61 Example Screen Formatter Extract ..........................5‐134
Figure 5‐62 Example Screen Data Translator Extract ................5‐134
Figure 5‐63 Example Using Multiple Languages Extract..........5‐135
Figure 5‐64 Example Appendix Buffer XML Extract.................5‐138
Figure 5‐65 Cardless Transaction Flow........................................5‐146
Figure 5‐66 Touch‐screen Keyboard ............................................5‐153
Figure 5‐67 Example Dynamic Button Control Sequence.........5‐173
Figure 5‐68 Example hookConfig Extract..................................5‐174
Figure 5‐69 Maintaining the Aspect Ratio of Displayed Cheque
Images........................................................................5‐175
Figure 5‐70 Example Batch File.....................................................5‐184
Figure 5‐71 Example E‐Receipt Property Extract .......................5‐207
Example E‐Receipt Service Class Extract................5‐208
Figure 5‐72 Example Barcode Filter
Configuration File Extract ......................................5‐212
Figure 5‐73 Example Barcode Extraction Rules Extract ............5‐213
Figure 5‐74 AID Elements for Device Variant
XML File Example....................................................5‐256
Figure 5‐75 Simple XML File Example ........................................5‐259
Figure 5‐76 Example Add Cash Extract.......................................5‐272
Figure 5‐77 Example Standard Cash Extract...............................5‐273
Figure 5‐78 Example Test Cash Extract .......................................5‐274
Figure 5‐79 Example Log Signatures Extract ..............................5‐293
Figure 5‐80 BRM Registry Entry for Handling Incorrect
Denomination and Insufficient Dispense.............5‐311
Figure 5‐81 Direct Deposit Error Screen ......................................5‐327
Figure 5‐82 Capture Serial Number Image and Path Extract ...5‐344
Figure 5‐83 Default Input Rejected Reasons ...............................5‐357
Figure 5‐84 Default Cassette Names ............................................5‐358
Figure 5‐85 Default Cassette Names ............................................5‐360
Figure 5‐86 Note Mapping XML Extract .....................................5‐362
Figure 5‐87 Example Log Signatures (Deposit) Extract.............5‐370
Figure 5‐88 XFS Logical Cash Units to Physical Cassettes........5‐402
Figure 5‐89 NDC Types to XFS Logical Cash Units to Physical
Cassettes ....................................................................5‐403

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxxiii

List of Figures

Figure 5‐90 BRM Configuration Schema .....................................5‐409

Figure 5‐91 BRM Configuration Extract ......................................5‐413
Figure 5‐92 Example Shared Cheque Detailed Extract..............5‐419
Figure 5‐93 Example Code Line Format Extract.........................5‐423
Figure 5‐94 Example Refuse Invalid Cheques Extract...............5‐424
Figure 5‐95 Example Moving Returned Cheque Extract...........5‐424
Figure 5‐96 Example Log Invalid Cheques Extract....................5‐425
Figure 5‐97 Example Retrieving Cheque Image Path Extract ..5‐425
Figure 5‐98 Example Retrieving Scan after Endorsement Setting
Extract ........................................................................5‐426
Figure 5‐99 Example Transaction Data File Extract ...................5‐430
Figure 5‐100 Example Clear Option File Extract ..........................5‐432
Figure 5‐101 CRM Flow Points Schema Extract ...........................5‐436
Figure 5‐102 CRM Flowpoint XML Extract...................................5‐438

Chapter 6
Configuring Voice Guidance

Figure 6‐1 Voice Guidance During a Transaction ........................6‐5

Figure 6‐2 Configuring Multiple Voices ......................................6‐10
Figure 6‐3 Voice Guidance Voices Array.....................................6‐11
Figure 6‐4 Sample Voice Guidance XML Schema ......................6‐16
Figure 6‐5 Key Positions.................................................................6‐41
Figure 6‐6 Example for two audioIDs ..........................................6‐43
Figure 6‐7 Example for one audioID ............................................6‐43
Figure 6‐8 Example Voice Guidance XML File...........................6‐45
Figure 6‐9 Original Transaction Reply.........................................6‐60
Figure 6‐10 Example Voice Guidance XML Extract.....................6‐60
Figure 6‐11 Example Screen Update XML Extract .......................6‐61
Figure 6‐12 Updated Transaction Reply ........................................6‐61
Figure 6‐13 Original Transaction Reply.........................................6‐61
Figure 6‐14 Example Voice Guidance XML Extract.....................6‐62
Figure 6‐15 Example Screen Update XML Extract .......................6‐62
Figure 6‐16 Updated Transaction Reply ........................................6‐62
Figure 6‐17 Original Transaction Reply Display ..........................6‐63
Figure 6‐18 Original Transaction Reply Print ...............................6‐63
Figure 6‐19 Example Voice Guidance XML Extract.....................6‐63
Figure 6‐20 Example Screen Update XML Extract .......................6‐64
Figure 6‐21 Updated Transaction Reply Display .........................6‐65
Figure 6‐22 Updated Transaction Reply Print ..............................6‐65
Figure 6‐23 Original Transaction Reply.........................................6‐66

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxxiv APTRA Advance NDC, Developer’s Guide

 List of Figures

Figure 6‐24 Example Print Data XML Extract...............................6‐67

Figure 6‐25 Updated Transaction Reply........................................6‐68
Figure 6‐26 Original ITR Message ..................................................6‐70
Figure 6‐27 Example XML Extract..................................................6‐70
Figure 6‐28 Updated ITR Message .................................................6‐71
Figure 6‐29 Original ITR Message ..................................................6‐71
Figure 6‐30 Updated ITR Message .................................................6‐72
Figure 6‐31 Original ITR Message ..................................................6‐72
Figure 6‐32 Example XML Extract..................................................6‐73
Figure 6‐33 Updated ITR Message .................................................6‐76
Figure 6‐34 Original ITR Message ..................................................6‐76
Figure 6‐35 Example XML Extract..................................................6‐76
Figure 6‐36 Updated ITR Message .................................................6‐79

Chapter 7
Introducing the Advance NDC Authored Applications

Figure 7‐1 Application Link Build Information............................7‐4

Figure 7‐2 Example of the Advance NDC Director in the
Customisation Layer ...................................................7‐6
Figure 7‐3 Application Core Director...........................................7‐11
Figure 7‐4 AppCore Work Group.................................................7‐11
Figure 7‐5 Start Of Day Work Group ...........................................7‐12
Figure 7‐6 Keymanager Work Group ..........................................7‐13
Figure 7‐7 Initialisation Functions ................................................7‐14
Figure 7‐8 Mode Handler Director ...............................................7‐16
Figure 7‐9 Mode Handling ............................................................7‐20
Figure 7‐10 OOS Mode Change ......................................................7‐20
Figure 7‐11 Message Handling .......................................................7‐22
Figure 7‐12 Process Message ...........................................................7‐23
Figure 7‐13 Application Core Handle Switch ...............................7‐30
Figure 7‐14 Activating the Supervisor Application .....................7‐31
Figure 7‐15 Supervisor Project ........................................................7‐32
Figure 7‐16 Supervisor Mode Start‐Up..........................................7‐33
Figure 7‐17 Advance NDC Test Environment:
Directory Structure ....................................................7‐36
Figure 7‐18 Simulated Passbook Printer Setup.............................7‐46

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxxv

List of Figures

Chapter 8
Modifying the Customisation Layer

Figure 8‐1 Modification Levels........................................................8‐2

Figure 8‐2 NDC State Processing Executor .................................8‐14
Figure 8‐3 Exit List Attribute for the Exit Condition Tester .....8‐15

Chapter 9
Enhancing the Application Core or Supervisor

Figure 9‐1 User Messages Director .................................................9‐6

Figure 9‐2 User Terminal Data Director ......................................9‐12

Chapter 10
Using User‐defined CDI Stores

Figure 10‐1 COM component in VBScript and JScript ..............10‐10

Chapter 12
Installing and Configuring Troubleshooting Tools

Figure 12‐1 Example Tracing Code ................................................12‐6

Figure 12‐2 Tracing in the Author Flow ........................................12‐7
Figure 12‐3 Example Tracing Script for the
Active Script Host Worker........................................12‐7
Figure 12‐4 Tracing with an Active Script Host Worker .............12‐8
Figure 12‐5 Example Transaction State Flow Journal Entry .......12‐9
Figure 12‐6 Example Transaction State Flow Journal Entry .....12‐10
Figure 12‐7 DebugLog Application Properties
Dialog Box .................................................................12‐17
Figure 12‐8 Example Script to Start Silent Debug ......................12‐23
Figure 12‐9 Example MESSAGEIN Log File ...............................12‐24
Figure 12‐10 Example Merged Trace File ......................................12‐25

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxxvi APTRA Advance NDC, Developer’s Guide

 List of Figures

Appendix C
Common Data Interface Stores

Figure C‐1 Example Code to Count Counterfeit Notes ............ C‐58

Appendix E
PCI DSS & PA‐DSS Compliance in Advance NDC

Figure E‐1 Customisation Audit Example.................................. E‐15

Appendix F
Example Custom.ini Files

Figure F‐1 Runtime SST custom.ini example ................................F‐2

Figure F‐2 Development custom.ini example ...............................F‐4

Appendix H
Advance NDC and Customer Relationship Management

Figure H‐1 Example Enable Promote Extract ............................... H‐2

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxxvii

List of Figures

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xxxviii APTRA Advance NDC, Developer’s Guide

 List of Tables

List of Tables

Preface

Table Pref‐1 Navigation Elements .......................................................‐li

Chapter 1
Introducing Advance NDC

Table 1‐1 Use of the General Purpose Buffers...........................1‐12

Table 1‐2 CDI Roles.......................................................................1‐13
Table 1‐3 Cash Acceptor Menu Options ....................................1‐38
Table 1‐4 Migration to CEN‐XFS ................................................1‐47
Table 1‐5 TM Alert ........................................................................1‐59
Table 1‐6 DPM Message Types in Advance NDC....................1‐60
Table 1‐7 DPM State Types in Advance NDC ..........................1‐62
Table 1‐8 Coin Dispenser Differences ........................................1‐62
Table 1‐9 Coin Message Types in Advance NDC.....................1‐63
Table 1‐10 DAS Message Types in Advance NDC.....................1‐65
Table 1‐11 Customisation Data Commands
in Advance NDC........................................................1‐67
Table 1‐12 Status Message..............................................................1‐71
Table 1‐13 Supervisor Functions Not Supported .......................1‐72
Table 1‐14 Security Camera Message Types
in Advance NDC........................................................1‐75

Chapter 3
Migrating Existing NDC+ Applications to Advance NDC

Table 3‐1 Help for Recreating or Migrating Files .......................3‐2

Table 3‐2 Audio File Handling in Advance NDC and NDC+ ..3‐5
Table 3‐3 Video File Handling in Advance NDC and NDC+ ...3‐6

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xxxix

List of Tables

Chapter 4
Upgrading from Earlier Releases of Advance NDC

Table 4‐1 Advance NDC File Locations .......................................4‐7

Table 4‐2 Service Provider Device Access Details ....................4‐14
Table 4‐3 Supplies Data Source Information.............................4‐16
Table 4‐4 Fitness Data Source Information................................4‐17
Table 4‐5 Message Handling Changes Summary.....................4‐19
Table 4‐6 Message Handler Component ID ..............................4‐20
Table 4‐7 Dual Mode Error Message Selection .........................4‐23

Chapter 5
Configuring Advance NDC and Associated Components

Table 5‐1 SST configuration component XML Elements ...........5‐4

Table 5‐2 Examples of Application Links ..................................5‐16
Table 5‐3 Aliases for Device Names ...........................................5‐17
Table 5‐4 ActiveXFS Aliases ........................................................5‐19
Table 5‐5 Enabling Web Exits ......................................................5‐22
Table 5‐6 Tags Used in the Files Referenced in SCXLOC........5‐23
Table 5‐7 Security Camera XML Elements ................................5‐27
Table 5‐8 Camera Flow Points.....................................................5‐30
Table 5‐9 Promote Flow Point Configuration ...........................5‐36
Table 5‐10 Update Mode ................................................................5‐39
Table 5‐11 No Transaction Traps ..................................................5‐59
Table 5‐12 Bit Positions for Modes................................................5‐59
Table 5‐13 NCR SNMP Service Traps ..........................................5‐61
Table 5‐14 NCR SNMP Mode Change Traps ..............................5‐61
Table 5‐15 GASPER‐Compatible SNMP Traps ...........................5‐62
Table 5‐16 GASPER‐Compatible SNMP Traps
for a Contactless Card Reader..................................5‐63
Table 5‐17 Archiving User‐Defined Files Properties..................5‐79
Table 5‐18 Retrieve Archive Task Class IDs ................................5‐82
Table 5‐19 Configure Terminal ID Source ...................................5‐88
Table 5‐20 NDC Monitor XML Elements.....................................5‐90
Table 5‐21 Valid Timer Value Definitions ...................................5‐93
Table 5‐22 USB Device Reset Rules...............................................5‐95
Table 5‐23 Device Recovery Elements..........................................5‐98
Table 5‐24 UPS Power Management when registry is set to 0 .5‐99
Table 5‐25 UPS Power Management when registry is set to 1 .5‐99

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xl APTRA Advance NDC, Developer’s Guide

 List of Tables

Table 5‐26 Registry Entry for Unusual

Object Monitoring Timeout ....................................5‐102
Table 5‐27 Correcting Settlement Screen Customisation
Misalignment............................................................5‐103
Table 5‐28 Supervisor Keyboard: Elements...............................5‐107
Table 5‐29 Registry Entry for Delayed Password Masking ....5‐109
Table 5‐30 SupervisorTaskWrapper Properties ........................5‐111
Table 5‐31 Display Data Format XML Schema .........................5‐122
Table 5‐32 NDC Keyboard XML Schema ..................................5‐123
Table 5‐33 Cash Accept Screens Formatting Properties ..........5‐128
Table 5‐34 Screen Control Character Sequences.......................5‐132
Table 5‐35 Amount Entry XML Schema ....................................5‐138
Table 5‐36 Buffer Validation XML Schema ...............................5‐140
Table 5‐37 Configurable Alert Sounds .......................................5‐141
Table 5‐38 Registry Entry to Configure Beep............................5‐141
Table 5‐39 Cardless Transaction Registry Entries ....................5‐144
Table 5‐40 Key Mask Settings......................................................5‐147
Table 5‐41 Binary to Decimal Conversion Example.................5‐148
Table 5‐42 Front Keyboard Layout .............................................5‐150
Table 5‐43 Offline Keyboard XML Elements.............................5‐157
Table 5‐44 Advance NDC Display XML Elements...................5‐163
Table 5‐45 Offline Screen Properties ..........................................5‐176
Table 5‐46 Reserved Screen Property .........................................5‐177
Table 5‐47 Screen Manager Properties .......................................5‐177
Table 5‐48 Hide Mouse Pointer Property ..................................5‐178
Table 5‐49 CRM Property.............................................................5‐178
Table 5‐50 Journal Printer Registry Value .................................5‐190
Table 5‐51 Cash Count Journal Screens .....................................5‐190
Table 5‐52 Promote Coupon Printing.........................................5‐193
Table 5‐53 Registry Entries for Configuring Forms .................5‐196
Table 5‐54 Registry Entries for Configuring Fonts ..................5‐199
Table 5‐55 Registry Entry for configuring LPI ..........................5‐199
Table 5‐56 Raw data: USB Receipt and
Journal Registry Entries ..........................................5‐200
Table 5‐57 Print Graphic on Next Page Registry Value...........5‐202
Table 5‐58 Passbook Printer Registry Values............................5‐204
Table 5‐59 E‐Receipt Service Class Properties ..........................5‐208
Table 5‐60 Barcode Filter Structure Definition..........................5‐210
Table 5‐61 Barcode Extraction Rules ..........................................5‐212
Table 5‐62 Registry Entry for both Contact and Contactless Card
Readers ......................................................................5‐214
Table 5‐63 Registry Entry for Contact Card Reader as the Primary
Card Reader ..............................................................5‐214

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xli

List of Tables

Table 5‐64 Registry Entry for Contactless Card Reader as the

Primary Card Reader...............................................5‐214
Table 5‐65 Registry Entry for Contactless Card
Reader to Configure Device Mode ........................5‐215
Table 5‐66 Attributes for Voice Guided Sessions .....................5‐217
Table 5‐67 Contact Card Reader..................................................5‐218
Table 5‐68 Contactless Card Reader ...........................................5‐218
Table 5‐69 Contact and Contactless Card Readers ...................5‐220
Table 5‐70 Status Message............................................................5‐222
Table 5‐71 Registry Entry for Controlling
Card Insertion Retries..............................................5‐225
Table 5‐72 Contactless Trace Level Values ................................5‐227
Table 5‐73 M‐Status for Card Reader Failure............................5‐228
Table 5‐74 Contactless Enabler Configuration Data ................5‐230
Table 5‐75 Configuration Values.................................................5‐234
Table 5‐76 General Terminal Data Objects ................................5‐235
Table 5‐77 Transaction Related Data Objects ............................5‐236
Table 5‐78 Visa Specific Terminal Data Objects........................5‐237
Table 5‐79 MasterCard Terminal Data Objects .........................5‐238
Table 5‐80 Interac Specific Terminal Data Objects ...................5‐239
Table 5‐81 IDTech Device Specific Data Objects.......................5‐240
Table 5‐82 IDTech Device Behavioural Data Objects...............5‐241
Table 5‐83 Contactless Enabler Schema .....................................5‐243
Table 5‐84 Examples of Mask Expression..................................5‐255
Table 5‐85 Inadvertent Tap Elements.........................................5‐258
Table 5‐86 Smart Delay Timer Registry Entry for EMV Dip Card
Readers ......................................................................5‐262
Table 5‐87 Default Hopper Values..............................................5‐264
Table 5‐88 Supplies and Severity ................................................5‐265
Table 5‐89 Cash Unit Identifiers in Supervisor Screens...........5‐269
Table 5‐90 Fault DIsplay for the Top Cassette ..........................5‐271
Table 5‐91 Registry Entry for Reporting Good Status When Notes
are at Exit Slot ...........................................................5‐277
Table 5‐92 Treatment of Notes After a Power Failure .............5‐279
Table 5‐93 MEI Spray Dispenser Registry Entries....................5‐283
Table 5‐94 Supplies and Severity ................................................5‐283
Table 5‐95 Overall Supplies Reporting for Reject Bin when
Divert Bin Full Enabled = 1 ..........................5‐285
Table 5‐96 Overall Supplies Reporting for Reject Bin when
Divert Bin Full Enabled = 0 ..........................5‐285
Table 5‐97 Most Severe Status Reporting ..................................5‐285
Table 5‐98 Overall Fitness Reporting for Reject Bin.................5‐287
Table 5‐99 Most Severe Fitness Status Reporting .....................5‐288

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xlii APTRA Advance NDC, Developer’s Guide

 List of Tables

Table 5‐100 Bunch Note Image File Format ................................5‐289

Table 5‐101 Database Structure .....................................................5‐292
Table 5‐102 Dispenser Registry Entries.......................................5‐299
Table 5‐103 Carriage Sweep Registry Entry ................................5‐300
Table 5‐104 Prepare Dispense Registry Entry .............................5‐301
Table 5‐105 Retract Options...........................................................5‐303
Table 5‐106 1, 1.5, 2 and 2.5 Retract on an S2 Dispenser............5‐306
Table 5‐107 SDM Registry Entries ................................................5‐314
Table 5‐108 BRM Registry Entries.................................................5‐315
Table 5‐109 BRM Registry Entry for User Update .....................5‐315
Table 5‐110 Recycling Unit: GBxx Registry Entries Set by Advance
NDC ...........................................................................5‐316
Table 5‐111 Recycling Unit: BRM Registry Entries set by Advance
NDC ...........................................................................5‐316
Table 5‐112 Cash Recycler: Registry Entries for
User Update ..............................................................5‐318
Table 5‐113 Enabling Direct Deposit ............................................5‐325
Table 5‐114 DisplayConfirmationScreenOnError Property......5‐327
Table 5‐115 ReportErrorMessage Property .................................5‐328
Table 5‐116 Examples of Strings for the Off‐Line States Array 5‐330
Table 5‐117 Serial Number Journal Configuration Properties..5‐332
Table 5‐118 Serial Number Receipt Configuration Properties .5‐338
Table 5‐119 Serial Number Image Format...................................5‐342
Table 5‐120 ECB6CashAcceptService Properties ........................5‐343
Table 5‐121 Default Settings for Reconciliation List...................5‐347
Table 5‐122 Forms Used for BNA Note Counts..........................5‐347
Table 5‐123 Cash‐In Supervisor Counters’ Properties ...............5‐349
Table 5‐124 Forms Used for BNA Note Counts..........................5‐350
Table 5‐125 Counts for Note Groups............................................5‐352
Table 5‐126 Counts for Note Totals ..............................................5‐354
Table 5‐127 Enhanced Cash‐In Formatter Properties ................5‐355
Table 5‐128 Print Cash‐in Totals Properties ................................5‐356
Table 5‐129 Note Mapping XML Structure .................................5‐361
Table 5‐130 Example Note Mapping ............................................5‐362
Table 5‐131 Error Recovery Configuration Classes....................5‐365
Table 5‐132 ECB 6 Note Categories ..............................................5‐367
Table 5‐133 Forms Used for Cash Deposit
Exception Reporting ................................................5‐379
Table 5‐134 BNA Journal Format Properties...............................5‐380
Table 5‐135 XML Schema Elements..............................................5‐392
Table 5‐136 Recycling Unit: Registry Entries Set
by Advance NDC .....................................................5‐399
Table 5‐137 Example Mappings ....................................................5‐403

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xliii

List of Tables

Table 5‐138 Registry Entry to ignore Casettes that are not

configured .................................................................5‐407
Table 5‐139 BRM Configuration XML Schema Elements ..........5‐410
Table 5‐140 Cheque Endorsement Form & Media Definitions.5‐421
Table 5‐141 Cheque Deposit Filename Variables .......................5‐428
Table 5‐142 Example Cheque Deposit Files.................................5‐429
Table 5‐143 Transaction Data File: XML Elements.....................5‐430
Table 5‐144 Check Bin Empty XML Tags.....................................5‐433
Table 5‐145 Default MEEI Registry Key Values..........................5‐434
Table 5‐146 CRM Flowpoint XML Schema Elements ................5‐437

Chapter 6
Configuring Voice Guidance

Table 6‐1 Standard Audio SST: Voice Guidance and Cardless

Transactions ..................................................................6‐4
Table 6‐2 Enhanced Audio SST: Voice Guidance with Cardless
Transactions ..................................................................6‐4
Table 6‐3 XML Schema Elements ................................................6‐24
Table 6‐4 Codes for Defined Keys...............................................6‐42
Table 6‐5 No Host Update XML Schema Elements..................6‐50

Chapter 7
Introducing the Advance NDC Authored Applications

Table 7‐1 Application Link and Build Information ....................7‐4

Table 7‐2 Signal Values.................................................................7‐18
Table 7‐3 Customisation Layer Status Values...........................7‐19
Table 7‐4 Application Core Terminal Command Responses..7‐24
Table 7‐5 Application Core Response Definitions....................7‐25
Table 7‐6 Application Core Customisation Data Command
Responses ....................................................................7‐27
Table 7‐7 Application Core Response Definitions....................7‐27
Table 7‐8 Application Core Transaction Reply Command
Response......................................................................7‐28
Table 7‐9 Application Core Response Definitions....................7‐28
Table 7‐10 Shared Stores.................................................................7‐34
Table 7‐11 Coin Dispenser Simulator Settings ............................7‐41
Table 7‐12 Logical Names for Cash Acceptors............................7‐42
Table 7‐13 Cash Acceptor Capability Settings ............................7‐42

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xliv APTRA Advance NDC, Developer’s Guide

 List of Tables

Table 7‐14 Cash Acceptors Output Settings ................................7‐44

Table 7‐15 Custdat.exe Export Command Options....................7‐48

Chapter 8
Modifying the Customisation Layer

Table 8‐1 Data Journaling Control ..............................................8‐11

Table 8‐2 Data Journaling Table Key..........................................8‐11
Table 8‐3 NDC Field Workers and CDI Stores .........................8‐21
Table 8‐4 Extending the Advance NDC Runtime ....................8‐27

Chapter 9
Enhancing the Application Core or Supervisor

Table 9‐1 Customisable Parts of the Application Core ..............9‐2

Chapter 10
Using User‐defined CDI Stores

Table 10‐1 UCDI Initialisation File Format..................................10‐3

Table 10‐2 Persistence of UCDI Stores .........................................10‐4
Table 10‐3 UCDIstring(name) Property.......................................10‐7
Table 10‐4 UCDIinteger(name) Property.....................................10‐7
Table 10‐5 Boolean newUCDIstore(name, initval, thetype)
Method ........................................................................10‐8
Table 10‐6 ResetPersistentStores() Method .................................10‐8
Table 10‐7 CDIs and UCDIs functions .........................................10‐9

Chapter 11
Delivering an Advance NDC Aggregate to the SST

Table 11‐1 Application Installation Locations.............................11‐2

Table 11‐2 SST Directory Structure...............................................11‐6
Table 11‐3 EncMode Values.........................................................11‐12
Table 11‐4 KeyMan Values ..........................................................11‐12
Table 11‐5 Registry Data Type Prefixes .....................................11‐19

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xlv

List of Tables

Chapter 12
Installing and Configuring Troubleshooting Tools

Table 12‐1 Default Trace Stream Types........................................12‐5

Table 12‐2 Silent Debug Installation Paths ................................12‐12
Table 12‐3 Registry Entry for Silent Debug Start‐up................12‐13
Table 12‐4 Silent Debug Configuration Parameters .................12‐14
Table 12‐5 .NET PCD Support Tasks..........................................12‐20
Table 12‐6 Default Problem Determination Trace Settings .....12‐21
Table 12‐7 Silent Debug Commands ..........................................12‐22
Table 12‐8 MESSAGEIN Line Format ........................................12‐23

Chapter 13
Modifying the Advance NDC Applications

Table 13‐1 External Functions exposed for Customisation .......13‐6

Appendix A
Related Documentation

Table A‐1 Advance NDC Documentation ...................................A‐2

Table A‐2 Provided Authoring Documentation .........................A‐4
Table A‐3 Additional Authoring Documentation ......................A‐5
Table A‐4 Additional NDC+ Documentation..............................A‐6
Table A‐5 Other NCR Documentation .........................................A‐8
Table A‐6 CEN‐XFS Documentation ............................................A‐9

Appendix C
Common Data Interface Stores

Table C‐1 Barcode ........................................................................... C‐3

Table C‐2 BNA Accepted Denomination Counts ....................... C‐4
Table C‐3 BNA Active Banknotes ................................................. C‐5
Table C‐4 BNA Counters................................................................ C‐6
Table C‐5 BNA Denomination Configuration ............................ C‐8
Table C‐6 BNA Deposited Denomination Counts ..................... C‐9

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xlvi APTRA Advance NDC, Developer’s Guide

 List of Tables

Table C‐7 BNA Misc ..................................................................... C‐10

Table C‐8 Buffers ........................................................................... C‐12
Table C‐9 Coin Counters.............................................................. C‐14
Table C‐10 CPM............................................................................... C‐15
Table C‐11 CPM Misc ..................................................................... C‐16
Table C‐12 Dial up CDI Store Workers........................................ C‐17
Table C‐13 EJ Upload...................................................................... C‐19
Table C‐14 EMV............................................................................... C‐20
Table C‐15 Encryptor Variant........................................................ C‐21
Table C‐16 Error Processing .......................................................... C‐22
Table C‐17 Exit Migration .............................................................. C‐23
Table C‐18 FIT Data ........................................................................ C‐25
Table C‐19 Key Entry Mode .......................................................... C‐29
Table C‐20 Misc Counters .............................................................. C‐30
Table C‐21 Note Counters.............................................................. C‐31
Table C‐22 Option Digit Stores ..................................................... C‐34
Table C‐23 Printing ......................................................................... C‐35
Table C‐24 Screen Display ............................................................. C‐37
Table C‐25 Security ......................................................................... C‐38
Table C‐26 State Information......................................................... C‐41
Table C‐27 Supervisor .................................................................... C‐44
Table C‐28 Terminal Configuration ............................................. C‐47
Table C‐29 Timers ........................................................................... C‐51
Table C‐30 Transaction Processing Flags..................................... C‐53
Table C‐31 UCDI Stores ................................................................. C‐55
Table C‐32 Voice Guidance Stores................................................ C‐56
Table C‐33 CDIs Outside Catalogs ............................................... C‐57

Appendix D
Font Definition

Table D‐1 Font Selection Escape Sequences ................................D‐3

Table D‐2 Font Designators ...........................................................D‐4
Table D‐3 Character Set Names and Values................................D‐5
Table D‐4 Field to Attribute Mappings ........................................D‐6

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xlvii

List of Tables

Appendix E
PCI DSS & PA‐DSS Compliance in Advance NDC

Table E‐1 PCI DSS Requirements ................................................. E‐2

Table E‐2 Changes to Advance NDC for PA‐DSS...................... E‐3
Table E‐3 ImageMark Passport Requirements and PA‐DSS
Compliance ................................................................ E‐12

Appendix G
User‐Configurable States

Table G‐1 Web Exit State ................................................................G‐2

Table G‐2 Web Exit Tracking URLs ..............................................G‐3
Table G‐3 Extension to the Web Exit State...................................G‐4
Table G‐4 Cardholder Verification State....................................G‐11

Appendix H
Advance NDC and Customer Relationship Management

Table H‐1 Relate Coupon Printing................................................ H‐9

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

xlviii APTRA Advance NDC, Developer’s Guide

 Preface
About This Publication

About This Publication

This publication describes the following:

 Installing and configuring APTRA Advance NDC
 Upgrading existing APTRA Advance NDC applications
 Enhancing the APTRA Advance NDC cardholder session,
transaction requests/replies and message handling
 Migrating existing NCR Direct Connect Plus (NDC+) Native
Mode applications to the APTRA Advance NDC product.
For differences in functionality and operation that apply on other
vendors’ SSTs, refer to the APTRA Advance NDC, Multi‐Vendor
Support Reference Manual.
For methods of extending, enhancing or modifying Advance NDC,
refer to the APTRA Advance NDC, Extending the Product IP.

Using this Publication

This publication can be viewed electronically or printed.
The electronic publication provides:
 Hyperlinked page references
 A hyperlinked content tree in the Bookmarks pane.
The following navigation and commenting elements are used in this
publication:

Note: Most of the following table items are clickable.

Table Pref-1 Item Description

Navigation Elements
Revision Record Lists updates for current release in page order with
page references. The page references are
hyperlinked.

Table of Contents List the first two heading levels in page order with
page references.

Table of Contents Lists the first three heading levels in page order
for chapter or with page references.
appendix

Cross‐References Within the text, cross‐references are provided to

other relevant information. This may be a table,
figure or section, or a particular field or element
within a table or a reference to an external web site.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide xlix

Preface
About This Publication

Item Description

Glossary Provides an alphabetical list of terms, acronyms,

and abbreviations with their meaning.

Index Provides an alphabetical list of topics, keywords,

concepts, and data references with page references.

User Feedback Allows you to comment on the publication by:

Form — Completing and posting the feedback form
— Sending email
— Completing the web form, if you have
access to the NCR intranet.

New information provided in the text for the features and functions
Conventions Used in This added to this release of Advance NDC is highlighted with a
Publication pale‐green background.
The following abbreviations are used in this publication.

Full Form Abbreviation

APTRA Author Author

Microsoft Windows Windows 7 32‐bit or 64‐bit, or

Windows 10 64‐bit

CEN‐XFS 3.xx or later CEN‐XFS 3

HKEY_LOCAL_MACHINE HKLM

In XML examples, bold text is used to highlight the elements

referred to in the example description.

Terms for Cash Acceptors

There are different types of cash acceptors as follows:
 Devices that allow only single notes to be deposited
 Devices that allow bunches of notes to be deposited
 Devices that allow bunches of notes and/or cheques to be
deposited
 Devices that allow bunches of notes to be deposited and can also
allow notes to be dispensed from separate cassettes (cash in/cash
out)
 Devices that allow bunches of notes to be deposited and can also
allow notes to be dispensed from the same cassette (recycling).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

l APTRA Advance NDC, Developer’s Guide

 Preface
About This Publication

The following table describes the terms used in this publication

when referring to cash acceptors and their variants:

Term Refers to...

Cash acceptor Generic term for any device that accepts note
deposits
See Note 1:

Recycling Generic terms for any device that can accept note
unit/Recycler deposits, dispense notes and recycle deposited notes
(that is, dispense the deposited notes)

SNA Single note acceptor

An NCR term for a device that accepts deposits of
single notes
See Note 2:

BNA Bunch note acceptor

An NCR term for a device that accepts deposits of
bunches of notes
See Note 2:, Note 3: and Note 4:

SDM Scalable deposit module

An NCR device that can accept deposits of notes or
cheques in a single transaction.
See Note 1:, Note 2: and Note 6::

GBNA Global bank note acceptor

An NCR term for a device with configurable
cassettes that can accept note deposits and can
dispense notes from separate cassettes

GBRU Global bill recycling unit

An NCR term for a device that accepts note deposits
and can dispense notes using the same cassettes

BRM Bunch recycling module

An NCR term for a device that accepts and dispenses
notes as configured using the same cassettes or
separate cassettes

GBXX An NCR term used when referring to both the GBNA

and GBRU devices
See Note 3: and Note 5:

Note 1: Some cash acceptors can also accept cheques.

Note 2: Whenever a BNA is mentioned, the information also

applies to the SNA, SDM and SDM2 unless explicitly stated.

Note 3: Occasionally BNA and GBXX are used to refer to all

vendors’ devices, such as in some Supervisor menu options. When a
term is used generically, this is explained in the associated text.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide li

Preface
About This Publication

Note 4: BNA1, BNA2 and BNA3 are the variants of BNA.

Note 5: GBXX2 is a variant of GBXX.

Note 6: SDM2 is a variant of SDM. SDM2 has two variants: SDM2

CBM configuration 0 and SDM2 CBM configuration 1.

This publication consists of the following chapters and appendices.

What Is in This
Publication? Read ... For...

Chapter 1, “Introducing Information about Advance NDC and

Advance NDC” what documentation can be localised.

Chapter 2, “Installing Installing Advance NDC on your

Advance NDC on a development PC.
Development PC”

Chapter 3, “Migrating Migrating an existing NDC+ application

Existing NDC+ Applications to Advance NDC.
to Advance NDC”

Chapter 4, “Upgrading from Migrating an existing Advance NDC

Earlier Releases of Advance application and which registry settings
NDC” you can modify for communications.

Chapter 5, “Configuring Information about the Advance NDC

Advance NDC and Customisation Layer and Application
Associated Components” Core.

Chapter 6, “Introducing Information about voice guidance in

Voice Guidance” Advance NDC.

Chapter 7, “Introducing the For information about the Advance

Advance NDC Authored NDC applications in the Author (the
Applications” Customisation Layer, Application Core
and Supervisor) and how to test the
applications on a development system.

Chapter 8, “Modifying the For the customisation options available

Customisation Layer” in the Advance NDC Customisation
Layer and how to modify or enhance its
functionality.

Chapter 9, “Enhancing the For the customisation options available

Application Core or in the Advance NDC Application Core
Supervisor” and how to modify or enhance it.

Chapter 10, “Using For how to create and use User‐defined

User‐defined CDI Stores” Common Data Interface (UCDI) stores
in the APTRA Author.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

lii APTRA Advance NDC, Developer’s Guide

 Preface
About This Publication

Read ... For...

Chapter 11, “Delivering an Installing runtime Advance NDC

Advance NDC Aggregate to application on an SST.
the SST”

Chapter 12, “Installing and The Advance NDC trace logs and how
Configuring to use the “Silent Debug” and
Troubleshooting Tools” “DebugLog” utilities to troubleshoot
trace information.

Chapter 13, “Modifying the For methods of modifying the Advance

Advance NDC NDC Applications in the APTRA
Applications” Author.

Appendix A, “Related Information about the documentation

Documentation” available to help you modify/enhance
an Advance NDC application or
migrate from NDC+.

Appendix B, “Advance NDC For descriptions of the workers

Workers Supplied” provided with Advance NDC.

Appendix C, “Common For details of the Common Data

Data Interface Stores” Interface (CDI) stores and UCDI stores
provided with Advance NDC.

Appendix D, “Font For defining and using fonts.

Definition”

Appendix E, “PCI DSS & The changes introduced for compliance

PA‐DSS Compliance in with the Payment Application Data
Advance NDC” Security Standard (PA‐DSS) of the
Payment Card Industry Data Security
Standard (PCI DSS).

Appendix F, “Example For custom.ini files for both runtime SST

Custom.ini Files” and development environments.

Appendix G, The main parts in implementing a Web

“User‐Configurable States” Exit state.

Appendix I, “Advance NDC Configuring Advance NDC for APTRA

and Customer Relationship Connections
Management”

Appendix I, “Advance NDC Configuring Advance NDC with

and Customer Relationship APTRA Relate and Promote
Management”

This publication is intended for you if you belong to one of the

Who Should Read This following categories:
Publication?  Users who want to run Advance NDC in a multi‐vendor
environment

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide liii

Preface
About This Publication

 Advance NDC users who want to use the new functionality

offered in this release
 Advance NDC users who want to move to an SST environment
that is compliant with the interface specification for CEN‐XFS 3
 Current NDC+ Native Mode users who:
— Want more flexibility than the NDC+ product offers
— Intend to migrate from OS/2 to a Windows environment.
 Users who want the benefits of NDC’s message interface, using
Self‐Service Support. This includes current PAS/NIC and
Composer users who wish to utilise the NDC message interface.

You are expected to be familiar with using the Windows operating

What Experience Should I systems, and with either NDC+ or Advance NDC. In addition, if
Have? you are going to develop your own states, supervisor features,
virtual controllers or hooks (Exits), you will need programming
experience in C, C++ or C#
For any Advance NDC customisation that requires programming to
the XFS interface, such as C Exits or Authored workers, you must be
familiar with the CEN‐XFS standard and be experienced in
programming to the XFS interface.
If considering initial unattended installation (IUI), you require
knowledge of the following:
 APTRA XFS
 Security for APTRA
 APTRA IUI
 APTRA Aggregate Installer/Builder Tool.

Training
NCR recommends that NCR employees, partners and customers
complete appropriate training as follows:
 NCR associates supporting APTRA Advance NDC: complete
the curriculum: “Supporting APTRA Advance NDC for a
Technical Audience”.
 NCR partners: contact your NCR Partner manager or
APTRAXpress partner team for suitable certification courses.
 NCR customers: contact your local NCR office to arrange a
suitable training programme.
A full list of courses, including other useful courses such as those for
BNA devices, voice guidance and Display Manager for HTML
screens, is available on the NCR University web site (registered
users only).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

liv APTRA Advance NDC, Developer’s Guide

 Preface
About This Publication

If you have a problem using Advance NDC, try the following to

Support Information solve it:
1 Refer to the APTRA Author User’s Guide, Appendix A,
“Troubleshooting”, to see if you can resolve the problem
yourself.

Note: If an Advance NDC exception occurs on an SST where

Problem Determination Collection is running, details are written
to the Windows event log to assist in the resolution of the
problem.

The APTRA Author User’s Guide describes how to make use of

the information. For example, a domain number is provided,
which identifies the offending component. The domain numbers
associated with the Advance NDC product are 115
(Customisation Layer) and 116 (Application Core).

2 Contact your internal support person for help.

Note: For .NET components, such as the .NET Assemblies for

Advance NDC component, you must provide Problem
Determination trace files.

3 Contact your local NCR representative.

NCR provides a wide range of support programmes. For more
information, contact your local Account Team.
If you have any problems using this guide, there is a “User
Feedback Form” at the back of this guide, where you will find the
email and postal addresses for NCR. Please take the time to reply;
your comments will be appreciated.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide lv

Preface
About This Publication

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

lvi APTRA Advance NDC, Developer’s Guide

 Table of Contents
Introducing Advance NDC

Chapter 1
Introducing Advance NDC

Overview 1‐1

Advance NDC Implementation 1‐2

Application Core 1‐4

Managing SST Modes 1‐4
Message Handling 1‐4
Activating the Customisation Layer and Supervisor 1‐5
Enhancing the Application Core 1‐5

Supervisor 1‐7

Customisation Layer 1‐8

State Type Modules 1‐8
Upgrading from an Earlier Release of Advance NDC 1‐8
Migrating from NDC+ to Advance NDC 1‐8
Enhancing the Customisation Layer 1‐9

Synchronisation Between Applications 1‐10

Common Data Interface 1‐11

Common Data Interface 1‐11
General Purpose Buffers 1‐11
Migrating from NDC+ 1‐12
Enhancing the Customisation Layer 1‐13
User‐defined Common Data Interface 1‐13

Advance NDC Development 1‐15

The Advance NDC Application 1‐15
Feature Support 1‐15
Dialup communications 1‐15
Automatic Device Reset Functionality 1‐15

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Introducing Advance NDC

Smart Dip Card Readers 1‐16

Controlling the Card Entry Retries 1‐16
Card Read PIN Entry Initiation State 1‐16
Reporting Card Data 1‐16
Encrypting PIN Pad (EPP) 1‐17
Secure Key Entry 1‐17
Uninterruptible Power Supply (UPS) 1‐17
Treatment of Notes After a Power Failure 1‐17
Journaling the Count of Notes When a
Present is Attempted Before Power Failure 1‐18
Security Cameras 1‐18
Configuring Denominations for NDC Cassette Types 1‐18
Reporting Pick Failures 1‐18
Support for Five Physical Cassettes 1‐19
Dual Cash Handlers 1‐19
Note Mix Selection 1‐19
Cash Handler Retract Counts 1‐20
Automatic Error Recovery 1‐20
Replenishment Status of Cash Dispenser Cassettes 1‐20
Foreign Currency Exchange Transactions 1‐20
Local Cash Dispense State 1‐21
Cheque Processing Module (CPM) 1‐21
Return of Invalid Cheques 1‐22
Magnetic Ink Character Recognition 1‐23
Display of Cheque Images 1‐23
Amount Buffer Display in Bunch Cheque Transactions 1‐23
Cardless Transactions 1‐24
Alphanumeric Dialup 1‐24
Enhanced EJ Features 1‐24
Display and Print TCP/IP Configuration 1‐25
Default Network Connection 1‐26
Promote Coupon Printing During Transaction Reply 1‐26
Promote Flow Points 1‐26
Configure Statement Length 1‐26
Long Receipt Handling 1‐27
Configuration of Forms‐Based Printing 1‐27
Configuration of Amount Entry Length 1‐27
Enable Web Exits 1‐27
Local Customisation Data 1‐28
Passbook Printer Worker Classes 1‐28
Associated Keyboards for FDKs 1‐29
Beep Configuration 1‐29
Alphanumeric Data Entry 1‐29
Validation of Host Responses to Transaction Requests 1‐30
Supervisor Menus 1‐30

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Table of Contents
Introducing Advance NDC

Configuration of Cardless Transactions 1‐30

Machine Number Entry 1‐30
Supervisor Entry/Exit Message 1‐30
SNMP 1‐30
NDC Monitor 1‐31
Archive Manager 1‐31
Voice‐Guided Sessions 1‐31
Intelligent Fraud Device (IFD) 1‐32
Receipt Capture Bin 1‐33
Top Margin for Receipts 1‐33
Displays 1‐33
Fault Displays 1‐33
Cardholder Display Status 1‐33
Information Entry State 1‐34
Data Copy and Compare State 1‐34
Hide Taskbar 1‐34
Transactions Based on Device Availability 1‐34
Scalable Deposit Module 1‐34
Remote Status Indicators (RSIs) 1‐34
Customer Relationship Management (CRM) 1‐35
Cash Recyclers 1‐35
Avoid Inadvertent Tap on Contactless Card Reader 1‐35
Interaction with Contactless Cad Reader 1‐35
Journaling the Cassette Information 1‐36
Internet Protocols 1‐36
Troubleshooting Assistance 1‐36
Problem Determination 1‐36
Silent Debug 1‐36
DebugLog 1‐36
Message Reflection 1‐36
Cash Acceptors 1‐37
Supervisor Options 1‐37
Direct Deposits 1‐40
Off‐line Cash Deposit Handling 1‐40
Dynamic Note Sorting 1‐40
Fixed Cassette Mapping 1‐41
ECB 6 Regulations 1‐41
Serial Number Information 1‐42
Error Recovery 1‐42
Journaling 1‐43
Capturing Bunch Note Image 1‐45
Printing Note Counts for Bunch Note Acceptors 1‐45
Confirmation Screens 1‐45
Configuration Files 1‐45
Promote Flow Points 1‐46

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Introducing Advance NDC

Tamper and Sensor Status Reporting 1‐46

Journaling Security Trace Message 1‐46
Journaling the Count of Notes that Pass
through the Bill Validator 1‐46
Product Class Support 1‐46
Support for CEN‐XFS 1‐47
Screen Management 1‐47
Screen Support 1‐47
Display Management 1‐48
Image and Media Support 1‐49
Voice Guidance 1‐49
Invalid XML File Handling 1‐49
Maximum State Number 1‐50
Remote Key Management 1‐50
Certificates 1‐50
Changing the MAC Encryption Key 1‐50
Dual‐Mode Journal Printing 1‐50
Format of Journaled Messages 1‐51
APIs for C Exits to Print to Any Printer 1‐51
Night Safe 1‐51
ActiveX Controls 1‐51
Master Expansion State 1‐51
.NET Assemblies for Advance NDC 1‐52
Local Printing Functions 1‐52
.NET Supervisor Tasks 1‐52
Software Update 1‐53
Self‐Service Terminal Configuration Component 1‐53
Configuration of Fixed Drives 1‐54
PCI DSS Compliance 1‐54
Masking of Sensitive Data 1‐54
Runtime Installation Directories 1‐55
Directories for Customisations 1‐55
Installation Types 1‐55
Custom Directory 1‐55
Media Entry Indicator (MEI) on Spray Dispensers 1‐55
Unsupported Features 1‐56

Differences Between Advance NDC and NDC+ 1‐57

Aggregate Building 1‐58
Cash Dispenser—Beeping 1‐58
Cash Dispenser—Cassette Types 1‐58
Cash Dispenser—Supplies Status 1‐58
TM‐Alert 1‐59
Document Processing Module 1‐59

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Table of Contents
Introducing Advance NDC

Coin Dispenser 1‐62

Digital Audio Service 1‐64
State Types 1‐65
Configuration Parameters 1‐66
Report Card Data in Status Message 1‐66
Customisation Data Commands 1‐67
PIN Entry and Verification 1‐67
PIN Entry States 1‐67
PIN Block ‐ No Encryption 1‐67
BAPE Emulation 1‐68
Electronic Journal and Journal Printer Backup 1‐68
Electronic Journal Log File Checksum 1‐68
EJ Log File Inspection (In Service Supervisor) 1‐68
Tampered Journal Records 1‐68
EJ File Format 1‐69
Screen Data 1‐70
K Screens 1‐70
Diebold Emulation Mode Status Messages 1‐70
Status Messages 1‐70
Alarms and Tamper Indication 1‐71
Option Digits 1‐71
Supervisor Mode 1‐72
Communications 1‐72
Diagnostics 1‐72
Miscellaneous Functions 1‐73
Differences in MACing 1‐73
Communications Protocols 1‐73
Basic Operator Panel (BOP) 1‐74
VGA Enhanced Rear Operator Panel (VEROP) 1‐74
Graphics 1‐74
Security Camera 1‐74
Software Management 1‐75
Associated Keyboards 1‐75
Bunch Note Acceptor (BNA) and Cheque Processing Module
(CPM) 1‐75
Transaction Request Extension State 1‐76
Font Definition 1‐76
Character Sets 1‐76
Localising Advance NDC 1‐76
Unsolicited Status Messages 1‐77
Multi‐Media File Support 1‐77
Number of Screens Supported 1‐77
Support for Screens 1‐78
Set Display Mode Control Sequence 1‐78
Passbook Printer Support 1‐78

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Introducing Advance NDC

Roll Width and Left Margin 1‐78

Envelope Dispensing 1‐78
Remote Status Indicators 1‐79

Aggregate Building 1‐80

Advance NDC Aggregate 1‐80
Customising Aggregates 1‐80
User‐Created Components 1‐80

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
A

Overview

Overview 1

This release of Advance NDC offers the following:

 A multi‐vendor environment supporting the same functionality
as a single‐vendor environment, except for tally and error
reporting, which are not supported.
 A migration path from NCR Direct Connect Plus (NDC+) Native
Mode to the NCR APTRA Author Environment (Author)

Note: The NDC+ Diebold Emulation product cannot be

migrated to Advance NDC. For more information, refer to the
APTRA Advance NDC, Overview.

This chapter discusses the following:

 The Advance NDC applications
 Advance NDC development
 Differences between Advance NDC and NDC+
 The Aggregate Builder Tool (ABT) and Advance NDC.
For information about running Advance NDC on other vendors’
SSTs, refer to the APTRA Advance NDC, Multi‐Vendor Support
Reference Manual.
For information about new features in Advance NDC, refer to the
APTRA Advance NDC, Overview.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-1

Introducing Advance NDC
Advance NDC Implementation

Advance NDC Implementation 1

Advance NDC provides a single application executable, the

Application Core, which activates the Customisation Layer and
Supervisor application DLLs as required. Having a single
executable simplifies the synchronisation between the Application
Core, Customisation Layer and Supervisor. There are still three
authored projects in the Author, maintaining the division of
functionality, and they are ApplicationCore.mpj, Supervisor.mpj, and
CustomisationLayer.mpj.
The Application Core executable activates the two DLLs and
interacts with the Central application as shown in the following
diagram:

Figure 1-1 Advance NDC

Advance NDC Architecture

Customisation Supervisor
Layer

Application
Core

Host
Application

The host application (also known as the Central application) resides

on a host or switch and interacts with Advance NDC on the SST to
perform self‐service transactions and maintain the SST in operation.
As well as activating the Customisation Layer and Supervisor, the
Application Core performs the background processing activities
previously performed by the executable part of NDC+.
The Supervisor performs the ‘Out Of Service’ activities associated
with routine maintenance and replenishment. The Customisation
Layer performs the ‘In Service’ activities associated with the
cardholder.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-2 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Implementation

Shared data is used by the Application Core, Supervisor and

Customisation Layer. The repository that holds this data is called
the Common Data Interface (CDI).
The following sections describe each of these applications.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-3

Introducing Advance NDC
Application Core

Application Core 1

The Application Core is an authored application built as an

executable. It performs the following tasks:
 Managing the different modes the Self‐Service Terminal (SST)
can operate in
 Handling messages to and from the host.

The Application Core is responsible for moving from one mode to

Managing SST Modes another, based on certain conditions of the Self‐Service Terminal
1

(SST), as well as performing the functionality of each mode. The

Application Core activates the Customisation Layer or Supervisor
depending on the mode:
The modes are:
 Out of Service
 Supervisor—see Note:
 In Service—the Customisation Layer executing states and
screens
 Offline.

Note: Supervisor mode is entered only when the terminal is idle

and after the mode switch is moved to the ‘Supervisor’ position.
Supervisor mode functionality is provided by the Supervisor
application. For details, see “Supervisor” on page 1‐7.

In addition to mode changes, there are other tasks that are

performed by the Application Core:
 Power‐up
 Start of Day
 Initialise
 Suspend.

The Application Core either accepts or rejects the incoming

Message Handling messages depending on the content of the message and the current
1

mode of the SST. This shields the Customisation Layer from any
message handling and retains the integrity of the NDC message
interface compatibility. Any messages received which are not valid
for a particular mode are rejected.
Central can send the following types of messages to the SST:
 Terminal Commands
 Customisation Data Commands

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-4 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Application Core

 Transaction Reply
 Host to Exit. That is, the message used by the host to
communicate with states, supervisor features, virtual controllers
or hooks developed by the user.
For details of these messages, refer to the APTRA Advance NDC,
Reference Manual and the APTRA Advance NDC, Extending the
Product publication for host to Exit messages.

The Application Core determines when to enter In‐Service or

Activating the Supervisor mode. For In‐Service mode, the Application Core
Customisation Layer and activates a cardholder session and passes control to the
Supervisor 1 Customisation Layer. When the transaction is complete, control is
returned to the Application Core. Any processing performed by the
Customisation Layer can only be done while the SST is In Service.
The Application Core controls the Customisation Layer by
communicating mode changes to and from In Service. However, if
the SST is in the middle of a cardholder session, the Customisation
Layer completes the current session before passing control back to
the Application Core.
For Supervisor mode, the Application Core activates a Supervisor
session and passes control to Supervisor. When the session is
complete, control is returned to the Application Core.
For more information, see “Synchronisation Between Applications”
on page 1‐10.

The Application Core executes the fixed part of Advance NDC that
Enhancing the Application is not typically customised. Most developers will only wish to make
Core 1
changes to the Customisation Layer but the Application Core can be
customised using the following:
 Screen downloads
 Configuration and/or Enhanced Configuration Parameter
downloads
 Native Mode option digits
 Reserved Screens.
The Application Core cannot be modified to the same extent as the
Customisation Layer. Any modifications to the Application Core
must be made by observing the customisation guidelines given in
Chapter 8, “Customisation Guidelines”. Conformance to the
guidelines will ensure the core NDC+ functionality (mode handling
and existing messages) remains intact and that minimal
redevelopment is required for subsequent releases of Advance
NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-5

Introducing Advance NDC
Application Core

Any Application Core customisations you make using the Author

will have to be re‐applied to future releases of Advance NDC
Service Packs or updates. For this reason, NCR recommends you
avoid using the Author to customise the Application Core.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-6 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Supervisor

Supervisor 1

Supervisor is an authored application DLL activated by the

Application Core to perform Supervisor‐related tasks.
You can customise or extend Supervisor functionality in the
following ways:
 Modifying the text displayed in menus and messages
 Modifying the text used for printing Security Trace Messages
 Including your own Supervisor Exits
 Adding Activate .NET Supervisor Tasks.
It is also possible to add new menus, functions and Activate .NET
Supervisor tasks using the APTRA Author, and then building the
application DLL. However, any Supervisor changes you make using
the Author will have to be re‐applied to future releases of Advance
NDC or service pack updates.
For more information on how the Supervisor application handles
Supervisor Mode, see “Supervisor Mode” on page 7‐17.
The Supervisor application uses the Common Data Interface (CDI)
to read and set configuration options and counters. For details of the
CDI, see the “Common Data Interface” on page 1‐11.
To enable data to be shared between the Application Core and the
Supervisor application, some CDI stores are shared stores. These
stores are listed in “Shared Stores” on page 7‐34.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-7

Introducing Advance NDC
Customisation Layer

Customisation Layer 1

The Customisation Layer is an authored application DLL that is

activated by the Application Core to handle all aspects of a
cardholder session (for example, Card Entry, Card Read, PIN Entry,
Transaction Request/Reply, Cash Dispense). In other words, it
performs the ‘In Service’ activities associated with the cardholder.
The Customisation Layer allows you to customise the behaviour of
the SST by modifying the behaviour of the cardholder session
without affecting the Application Core or the NDC message
interface. State type modularisation reduces the impact on your
customisations of any future Advance NDC release or update.

The modularisation of state types and Transaction Reply functions

State Type Modules 1

simplifies the Customisation Layer application DLL by separating

the state flow from state type implementation. Each authored state
type, including NDC states, has its own application DLL and each
state is executed by the NDC Processing State Executor worker.

Upgrading from an earlier release of Advance NDC may require

Upgrading from an Earlier some additional configuration as all devices are now accessed
Release of Advance NDC 1
through an interface that is compliant with the CEN‐XFS 3
specification.
State type modularisation means that any customisations to the
following may have to be re‐applied:
 State types
 Transaction Reply functions.
However, for customisations to be performed or migrated, the state
flow can still be exited through the normal method of the ʹExit
Condition Testerʹ worker.
For details of the changes affecting customisation and configuration
in Advance NDC, see Chapter 4, “Upgrading from Earlier Releases
of Advance NDC”.
If you are upgrading to move to a multi‐vendor environment, the
APTRA Advance NDC, Multi Vendor Support Reference Manual gives
details of the operational and other differences that apply on other
vendors’ SSTs.

In Advance NDC, NCR provides a Customisation Layer, which

Migrating from NDC+ to executes your existing NDC+ download. There is generally no need
Advance NDC 1
to modify the download in any way.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-8 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Customisation Layer

The equivalent functionality of the Customisation Layer in NDC+ is

when NDC+ enters In Service mode and executes the downloaded
State flow, starting at State 0 (the Card Read or Card Read PIN
Entry Initiation state).
Chapter 3, “Migrating Existing NDC+ Applications to Advance
NDC”, describes how you can use Advance NDC to execute your
existing NDC+ download. However, NCR recommends you first
read this chapter and Chapter 2, “Installing Advance NDC on a
Development PC”.

Enhancing the Customisation Layer 1

After migrating to Advance NDC, you may want to offer, during In

Service mode, functionality that cannot be achieved using NDC+
state types. In NDC+ you were able to customise the behaviour of
the SST using data download messages. Advance NDC supports
this method of customisation and offers additional means of
enhancing Advance NDC using the Author.
You can enhance the Customisation Layer provided using the
APTRA Author and Authoring components (workers).
By modifying the Customisation Layer using the Author, you can
author new cardholder services and transactions, and incorporate
them as applications DLLs with no impact to the rest of the
application. Modifying the Customisation Layer is discussed in
“Modification Options” on page 8‐2
Any modifications you make to the Customisation Layer using the
Author will have to be re‐applied to future releases of Advance
NDC or service pack updates. However, only the affected state type
or Transaction Reply DLL will have to be rebuilt.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-9

Introducing Advance NDC
Synchronisation Between Applications

Synchronisation Between
Applications 1

The Application Core controls the activity of the Customisation

Layer and Supervisor applications and is responsible for managing
the different modes of the SST. The implementation of state types as
application DLLs has allowed all three authored applications to be
merged into one executable. This simplifies inter‐process
communications and XFS session management.
The role of the Customisation Layer is to initiate a cardholder
session for cardholder transactions. For this processing to occur, the
SST must be in the In Service mode and ready to initiate a
cardholder session. The Application Core activates the
Customisation Layer to allow a cardholder session to be initiated
and the Card Read state is encountered first. At the end of a
transaction, the Session Complete condition is met and the flow
returns to the Application Core.
While the SST is In Service, the Application Core can query the
status of the Customisation Layer using a shared store provided by
the Customisation Layer. This is used to determine whether further
message processing or mode changes can take place at various
stages in the application execution (such as processing messages
while the SST is idle, waiting for a card to be entered).
How the Application Core controls the activities of the
Customisation Layer and Supervisor is described in “Synchronising
with the Customisation Layer” on page 7‐18.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-10 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Common Data Interface

Common Data Interface 1

The Application Core, Customisation Layer and Supervisor share

data at runtime. The repositories that hold this data are called the
Common Data Interface (CDI) and the User‐defined Common Data
Interface (UCDI).

The CDI consists of stores representing all of the data used

Common Data Interface 1

throughout an Advance NDC application. There are several

hundred CDI store workers, one for each piece of data.
The CDI stores are provided in “CDI ‐ <name>” catalogs. For details
of the CDI stores provided and their use, see Appendix C,
“Common Data Interface Stores”.
Each piece of CDI data has a specific purpose and is used in
different parts of the Advance NDC application. For example, the
Operation Code Buffer is read by the Transaction Handler and
included in the Transaction Request Message. It is written to by
various state types, and may be written to by your Customisation
Layer.
The workers are grouped in catalogs according to their use.
Examples of CDI data are as follows:
 Configuration options
 FIT data
 Transaction related buffers, such as the Operation Code Buffer,
Buffer A and Card Track 3 Data.
The CDI stores you are most likely to access are those in the “CDI ‐
Buffers” catalog.

General Purpose Buffers 1

Many of the buffers used in Advance NDC store a particular data

item, such as the Card Track 1 Data buffer for the Card Read state,
or the Amount buffer for the Amount Entry State. There are also
two general purpose buffers, Buffer B and Buffer C, which can be
used to store a variety of numeric data collected from the
cardholder. The functionality of the buffers is determined by the
download from Central, or a local customisation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-11

Introducing Advance NDC
Common Data Interface

Different state types can populate these buffers or be used to check

the values stored in them, as follows:

Table 1-1
Use of the General Purpose Buffers

State Type Description

H ‐ Information Entry State Used for data of up to 32 digits. Examples of the data that could be stored are: an
account number for a money transfer; or a mobile phone number when buying
more call time.

G ‐ Amount Check State Used to check the value of the buffers against specified limits.

R ‐ Enhanced Amount Entry Used when multi‐language screens are required; the specified buffer stores the
State amount entered by the cardholder. The maximum number of digits that can be
entered is determined by the size of the Amount buffer, 8 or 12 digits.

X ‐ FDK Information Entry The specified buffer stores a predefined number corresponding to the FDK
State selected by the cardholder. For example, this could be used to offer fixed
amounts of cash to the cardholder.

z017 ‐ Note Mix Selection One or two buffers can be specified to store the following:
State  Amount entered by the cardholder. The maximum number of digits that can
be entered is determined by the size of the Amount buffer, 8 or 12 digits
 Note mix requested by the cardholder.
If the same buffer is specified in both parameters, only the amount entered by
the cardholder is stored.

The locally stored data can be passed to Central, which must specify
transmission of the buffers, using a Transaction Request state if
required. Central also specifies which buffer to use.
In addition, Buffer B is used in an Interactive Transaction Response,
when a message is sent to the SST with screen data and specific keys
enabled. The key data entered by the cardholder at this screen is
stored in Buffer B and reported to the host in a second transaction
request message. If the cardholder presses the Cancel key, or does not
press a key before a time‐out occurs, then the value C or T is
returned in the buffer to indicate the cardholder’s action.
For details of the state types, Transaction Requests and Interactive
Transaction Responses, refer to the Advance NDC Reference Manual.

Migrating from NDC+ 1

If you are simply using Advance NDC to execute your existing

NDC+ download, you do not need to concern yourself with the
Common Data Interface as access to the CDI stores has been
implemented for you.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-12 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Common Data Interface

All of the data in Advance NDC will be accessed at the correct time
and place, whether it is from one of the NDC+ state types or from a
Transaction Request/Reply.

Enhancing the Customisation Layer 1

Whether you choose to enhance the Customisation Layer or extend

it by adding your own state types, you need to be aware of the
relevance of the Common Data Interface (CDI) and the use of the
CDI workers provided with Advance NDC. The CDI data has the
following roles:

Table 1-2 Type of CDI Data Role

CDI Roles
Data used by the Advance Enables data sharing between state
NDC application types, the Transaction Request/Reply
mechanism and workers.

Data made available in NDC+ Enables the migration of the Exit code
to allow you to develop Exits you have developed to Advance NDC.
(Shared Data)

The data that you need to access is dependent on what you want to
do. If you are extending the Customisation Layer, you have to write
to the correct CDI workers before using the Transaction
Request/Reply mechanism. For example, you need to explicitly put
a value in the Operation Code Buffer, which is included in the
Transaction Request message. To do this, you write to the Operation
Code Buffer worker in the “CDI ‐ Buffers” catalog, using a
Setter/Assigner worker.
For details of the Setter and Assigner workers, refer to the worker
class on‐line help provided with the APTRA Author.
For details of the CDI stores you need to write to for each of the
Transaction Request Fields, see “Transaction Request/Reply” on
page 8‐18.
For more details of NDC+ shared data, refer to the APTRA Advance
NDC, Extending the Product publication.

The APTRAUSERCDI local service runs at start‐up. It is identical to

User‐defined Common the CDI in functionality, but also allows for the creation of new CDI
Data Interface 1
stores (called UCDI stores) without the need to modify the CDI C++
source code.
Like CDI stores, UCDI stores provide a means of sharing data
between applications. They hold string or integer data and may be
persistent (persistent data is preserved across terminal shutdowns
or power failures).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-13

Introducing Advance NDC
Common Data Interface

UCDI stores can be created to share data between the Customisation

Layer and Application Core and in different programming
environments such as C, C++, Script, COM, Author and VB. For
example, you may use UCDI stores when supporting a third‐party
device or when configuring new options or timers.
All UCDI stores must be cleared, initialised and set by your
application, as required.
An example of a UCDI store implementation is the CPM Cheque
Accept state (‘w’). The state uses a UCDI store named CPM cheque
present which checks if a cheque is present in the CPM device. The
store is used in the state and by Supervisor.
For details of the UCDI stores provided and their use, see
Appendix C, “Common Data Interface Stores”.
For more information on using UCDI stores, see Chapter 10, “Using
User‐defined CDI Stores”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-14 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Advance NDC Development 1

This section summarises the changes and additions made during

the development of releases of Advance NDC.

Prior to Advance NDC 2.05, the Supervisor functionality was

The Advance NDC contained in the Application Core. In Advance NDC 2.05, the
Application 1
Supervisor functionality was moved from the Application Core into
a separate Supervisor application. This change meant that Advance
NDC comprised three applications developed using the APTRA
Author, NCR’s graphical development tool.
From Advance NDC 3.03, a single application executable is
provided, the Application Core, which activates the Customisation
Layer and Supervisor application DLLs as required. The separation
of the state flow from the state type implementation simplified the
Customisation Layer application DLL.

The following sections describe the support offered by various

Feature Support 1

releases of Advance NDC.

Dialup communications 1

Advance NDC uses CCM VISA2 for dialup communications. For

details of the supported modems, refer to the CCM VISA2 release
bulletin.

Note: Support of dial up in 64‐bit systems (Windows 7 or Windows

10) is not available. For more information, please contact NCR FSE
Product Management.

There is an additional menu in Supervisor to configure most of the

dialup parameters. In the APTRA Author, there is a worker class,
NDC Dialup, and a CDI store, Dialup Flag, to handle dialup
communications in the Supervisor project.
From Advance NDC 3.04, TCP/IP configuration uses .NET CCM
TCP/IP support. For information on the development of
communications from release 3.04, see “.NET Assemblies for
Advance NDC” on page 1‐52.

Automatic Device Reset Functionality 1

Prior to Advance NDC 4.02, the CEN‐XFS reset was only invoked
following errors reporting WFS_SYSE_HARDWARE_ERROR and
WFS_ERR_ACT_RESET system events. A 24‐volt reset would also

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-15

Introducing Advance NDC
Advance NDC Development

occur if the device remained in a fatal condition following the

CEN‐XFS reset.
From Advance NDC 4.02, the following improvements have been
made to the reset functionality on NCR SSTs with a USB
Miscellaneous Interface:
 A 24‐volt reset can be triggered if a communications failure is
reported with WFS_ERR_ACT_RESET or WFS_ERR_HW_MAINT
errors
 The 24‐volt reset can be configured to reset all USB devices
following a communications failure, so the SST does not need to
be restarted following the reset
 A CEN‐XFS reset does not need to be performed before a 24‐volt
reset.

Note: The 24‐volt reset is not supported for cash acceptors.

Smart Dip Card Readers 1

From Advance NDC 3.00, in the APTRA Author, a worker class,

Card ATR Reader, is available and a work group has been added to
the Card Acceptor worker class to provide smart card support.

Controlling the Card Entry Retries 1

From Advance NDC 5.01, the number of card entry retries can be
restricted in the Insert Card State (z008) through a registry
configuration when a card is misread due to an invalid card or a
mechanism error.

Card Read PIN Entry Initiation State 1

From Advance NDC 4.02, the display of a PIN entry screen in the T
state (Card Read PIN Entry Initiation) while the card is being read is
optional.

Note: This optional configuration does not change the behaviour of

the Card Read PIN Entry Initiation state with a smart dip reader
when the chip on the card being read is successfully powered on. In
this case, the PIN entry screen is never displayed as part of the
processing for this state.

Reporting Card Data 1

Prior to Advance NDC 3.00.01, it was not possible to configure the

reporting of card data either to the journal or in status messages.
From Advance NDC 3.00.01, Enhanced Configuration option 37
(Print Track 2 to Journal) is supported. This option enables the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-16 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

journaling of track 2 data, masked if required for PA‐DSS

compliance.
From Advance NDC 4.02, Enhanced Configuration option 41 (Send
Track Details on Card Retract) is supported. This option enables the
reporting of all card data in a Card Reader/Writer status message
following a card retract operation.

Encrypting PIN Pad (EPP) 1

From advance NDC 05.01, at the start of day, if the EPP is not
detected, the application loads successfully.
If the EPP is not detected or goes fatal, the application either stops
or allows further transactions through a registry setting.

Secure Key Entry 1

From Advance NDC 3.00, manual entry of secure keys is supported

with a worker class, Secure Encryption Key Collector.

Note: Secure key entry offers standards compliance rather than

enhanced security. The decision to use secure key entry rather than
entering keys through the EOP is the responsibility of the financial
institution.

Uninterruptible Power Supply (UPS) 1

From Advance NDC 3.00, support for UPS devices enables the SST
to complete a transaction if a power failure occurs, and then go out
of service, or perform a controlled shutdown if the battery power
runs low.
From Advance NDC 05.01, a new registry configuration is provided
to keep SSTs either in service or out of service when the mains
power is active and the UPS battery level is below the low
threshold.

Treatment of Notes After a Power Failure 1

Prior to Advance NDC 4.02, if the status of notes was unknown

following a power failure during a transaction, the notes were
treated as presented.
From Advance NDC 4.02, a configuration setting allows notes with
an unknown status following a power failure during a transaction
to be treated as not presented.
From Advance NDC 4.03, notes with an unknown status following a
power failure during a transaction are treated as not presented on
GBRU SSTs by default.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-17

Introducing Advance NDC
Advance NDC Development

Note: This configuration is intended for use on GBRU and Diebold

SSTs only. It is not compliant with CEN XFS and must be used with
caution.

For details of the configuration, see “Unknown Status of Notes After

a Power Failure” on page 5‐278.

Journaling the Count of Notes When a

Present is Attempted Before Power Failure 1

From Advance NDC 05.01, in a dispense transaction, when a

present is attempted and a power‐fail occurs before notes are
presented, then after restart, the application journals the count of
notes that are requested from each cassette type.

Security Cameras 1

From Advance NDC 4.00, support for cash deposit camera flow
points was withdrawn due to the change of implementation to
.NET.
From Advance NDC 4.01, two camera flow points are supported at
Cash Present and Cash Taken. Two cameras can be configured to
take pictures at both flow points using an XML‐based configuration
file.
From Advance NDC 4.02, support for .NET is introduced, allowing
the cash deposit flow points to be re‐introduced and extended.

Configuring Denominations for NDC Cassette Types 1

Prior to Advance NDC 4.02, only one NDC cassette type could be
configured for each denomination.
From Advance NDC 4.02, a cassette unit identifier can be used to
configure the same denomination for multiple NDC cassette types.

Reporting Pick Failures 1

Advance NDC recognises consecutive pick failures occurring

during a single transaction or over several transactions. On NCR
SSTs with single cash handlers and four cassette types, consecutive
pick failures are reported as follows:
 From Advance NDC 3.03, the first and second pick failures are
not reported as errors. The third pick failure is reported as a fatal
error.
 From Advance NDC 4.02, this default reporting of pick failures
can be configured to report a routine error on the first pick
failure and a warning on the second pick failure. The third pick
failure is still reported as a fatal error.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-18 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Support for Five Physical Cassettes 1

From Advance NDC 4.01, the reporting of a physical fifth cassette is

supported on the Fault Display and in the Test Cash option in
Supervisor. Only the journaling of tamper indications for the fifth
cassette is supported.
From Advance NDC 4.04.01, for the fifth cassette, the tamper
indication message is reported to the host and is traced to the
journal when the Enhanced TI/Sensor Status unsolicited message is
enabled.

Dual Cash Handlers 1

From Advance NDC 3.01, cash handler capacity can be increased

without host impact.
A second cash handler can be added with the two cash handlers
reported as a single logical cash unit, therefore emulating a single
cash handler.
Dual cash handlers, if present, are supported as follows:
 Increased cash handler capacity without host impact
 The ability to use each cash handler for a different currency type
 Two cash handlers are reported as a single logical cash unit
 The option of using up to seven cassette types, depending on the
setting of Enhanced Configuration Parameter option 76
 Separate and/or combined status reporting for hardware
configuration, supplies and fitness data.
From release 3.03, the combination of supported cash handlers can
include a recycling unit (GBRU).
From Advance NDC 4.02, a specific cash handler can, if configured,
be selected in the Clear Cash and Standard Cash functions on the
Supervisor Replenish menu. This means that reconciliation and
count clearing can be done separately for each cash handler in a
dual cash handler.

Note Mix Selection 1

From Advance NDC 4.02, the Note Mix Selection state allows
consumers to select their preferred note mix in cash dispense
operations using the FDKs.

Note: This state is not supported when dual cash handlers are
present.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-19

Introducing Advance NDC
Advance NDC Development

Cash Handler Retract Counts 1

Prior to Advance NDC 4.01, the retract counts for dispense

operations were not maintained although the counts for notes
retracted during deposit operations were maintained. From
Advance NDC 4.01, the reporting of retract counts for dispense
operations can be configured if the SST contains a cash recycler and
recycling is enabled.
Cash Recycler Reject and Retracted Total Counts
From Advance NDC 4.04, the total number of retracted notes and
rejected notes are also reported, if reporting of retract counts is
enabled on a cash recycler and if recycling is enabled.

Automatic Error Recovery 1

Prior to Advance NDC 04.01.01, automatic error recovery (AER)

was performed whenever the following hardware errors were
received from the Service Provider:
 ACT_HWMAINT
 ACT_RESET
From Advance NDC 04.01.01, AER was performed only when an
ACT_RESET error is received from the Service Provider.
From Advance NDC 4.02, AER is superceded by the reset
functionality described in “Automatic Device Reset Functionality”
on page 1‐15.

Replenishment Status of Cash Dispenser Cassettes 1

In Advance NDC 3.04, the replenishment status of cassettes was

reported only for those cassettes that had been accessed during a
dispense operation.
From Advance NDC 4.00, the actual replenishment status of all
cassettes can be reported, not just those that have been accessed
during a dispense operation.

Foreign Currency Exchange Transactions 1

From Advance NDC 4.02, two new transaction reply functions

(function IDs ‘b’ and ‘f’) are provided for foreign currency exchange
transactions. They allow deposit and dispense operations to be
processed as a single function. Function ID ‘b’ allows cash to be
dispensed before notes are deposited and can be used only on SSTs
where the deposit device is physically different from the cash
dispenser. Function ID ‘f’ allows notes to be deposited before cash is
dispensed and can be used on any SST that supports cash
dispensing and depositing. ECB 6 functionality is supported for

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-20 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

both. Only notes can be deposited, but both notes and coins can be
dispensed.

Local Cash Dispense State 1

From Advance NDC 4.02, a new state is available to support local

transactions dispensing notes, coins or a combination of notes and
coins that can be completed without host interaction. This state can
be used, for example, in foreign currency transactions where the
consumer deposits notes in a foreign currency and receives cash,
which can be notes, coins or both, in the local currency.
From Advance NDC 05.01, support of Local Cash Dispense State is
not available by default. If you need to use this functionality, please
contact NCR FSE Product Management.

Cheque Processing Module (CPM) 1

From Advance NDC 3.02, the Cheque Processing Module (CPM), if

present, is supported in Advance NDC as follows:
 Additional information in various Terminal State messages
 New Device Fault Status messages
 New Configuration Parameters
 New State Type ‐ Cheque Accept State
 Additional fields in Transaction Request and Transaction Reply
messages
 New printer flags in field ‘q’ of the Transaction Reply allowing
cheque endorsement and/or rubber stamping
 Changes to the Close state
 Changes to various Supervisor replenishment functions
 Two Supervisor functions
 Returns cheques not authorised by Central
 Endorses and pockets authorised cheques
 Takes a front and/or rear image of the cheque
 Images can be rotated and resized and the codeline can be
masked for printing on the receipt printer
 Changes to Start of Day
 New CDI Stores.
For details of configuring cheque processors, see “Configuring
Cheque Processors” on page 5‐419. For details of using the CPM,
refer to the following publications:
 APTRA Advance NDC, Supervisor’s Guide
 APTRA Advance NDC, Reference Manual.
Bunch Cheque Accept State In Advance NDC 3.04, the Bunch 1

Cheque Accept State implementation was the same as NDC+: when

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-21

Introducing Advance NDC
Advance NDC Development

the cardholder declined more time, the Timeout Next State number
was taken. From Advance NDC 4.00 onwards, the Cancel Next State
number is taken, which matches the CIC implementation.
Accepting Single Cheques on a Bunch Cheque Acceptor In 1

Advance NDC 03.02 and 03.03, access to the bunch cheque acceptor
was provided by the PTR SP. To use the PTR SP for single cheque
acceptance, the platform components had to be configured as
follows:
1 Set the USB SCPM component to the PTR class, as described in
the USB SCPM component release bulletin

2 Point to the Advance NDC defined forms and media definition

folders using the following registry entries:

HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
SCPMPTR\GENERAL_CONFIGS\FormsDir

HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
SCPMPTR\GENERAL_CONFIGS\MediaDir

In Advance NDC 03.02.xx, the definition folders were specified

as follows:
— FormsDir
C:\XFS\Data\CPM\Forms
— MediaDir
C:\XFS\Data\CPM\Media

In Advance NDC 03.03.xx, the definition folders were specified

as follows:

— For forms
C:\Program Files\NCR APTRA\Printing\CPM\Forms
— For media definitions
C:\Program Files\NCR APTRA\Printing\CPM\Media

From Advance NDC 3.04.xx, the bunch cheque acceptor was

supported through the .NET Assemblies for Advance NDC. For
details of this development, see “.NET Assemblies for Advance
NDC” on page 1‐52.
From Advance NDC 4.02, a cheque returned by the host can be
endorsed during the Process Cheque Transaction Reply function
where the bunch cheque acceptor is configured as a single cheque
processor. This is also supported on single cheque processors that
support the endorsement of returned cheques.

Return of Invalid Cheques 1

Prior to Advance NDC 4.00, cheques detected as invalid by the

validation service were by default returned to the customer during

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-22 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

the Bunch Cheque Acceptance state. This happened at the

beginning of a transaction.
From Advance NDC 4.00, invalid cheques, as detected by the
validation service, can be marked for return and returned later in
the transaction. For off‐line transactions, the cheques are returned
during the Bunch Cheque Handling state. For transactions
controlled by the host, the cheques are either returned or moved to
the deposit bin.

Magnetic Ink Character Recognition 1

From Advance NDC 4.00, Magnetic Ink Character Recognition

(MICR) reading for cheque processing can be disabled or enabled
through the registry.
Codeline Configuration In Advance NDC 3.02 and earlier 1

versions XFS returned codeline characters in cheque truncation

system (CTS) format. The following registry entry was set to 0:

HKLM\SOFTWARE\NCR\Advance NDC\CPM\MICRFormat

From Advance NDC 3.03, this registry entry is set to 1 and XFS
returns codeline characters in NCR format.
Information is provided on configuring the codeline for alternative
MICR fonts.

Display of Cheque Images 1

Prior to Advance NDC 4.02, cheque images could be displayed

scaled according to the scanned image size.
From Advance NDC 4.02, additional local configuration provides
two further options, re‐interpreting the Lift Cheque Image control,
as follows:
 Scaling the cheque image according to the display size instead of
the scanned image size.
 Scaling the cheque image to fit the screen display area and
maintain its aspect ratio. This prevents distortion of the
displayed image.
This configuration also applies to the Bunch Cheque Display Image
control.

Amount Buffer Display in Bunch Cheque Transactions 1

Prior to Advance NDC 4.02, the display of the Amount buffer using
the Bunch Cheque Value Display control was always aligned to the
right of the display area on the screen.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-23

Introducing Advance NDC
Advance NDC Development

From Advance NDC 4.02, the alignment and format of the Amount
buffer during bunch cheque transactions depends on the Value
Format Screen field specified in the Bunch Cheque Value Display
control.

Cardless Transactions 1

From Advance NDC 3.01, a non‐cash transaction can be started

without a card using FDKs, FDK emulation, or a numeric key
defined in the registry. This provides an alternative to using a card.
From Advance NDC 4.01, support for customer relationship
management (CRM) applications is provided for cardless
transactions where a FIT search is not performed.
From Advance NDC 4.02, a Supervisor option is available for
configuring cardless transactions. For further information see
“Configuration of Cardless Transactions” on page 1‐30.

Alphanumeric Dialup 1

From Advance NDC 3.01, alphanumeric characters can now be

included in the following dial up fields:
 BIN
 TID
 MODEM INI STR
 PRIMARY NO
 SECONDARY NO
 N/A STRING

Enhanced EJ Features 1

Various electronic journal (EJ) options have been added since

release 3.01.
EJ Backup Mode In previous releases of Advance NDC, only the 1

latest copy of the EJ could be retained. From release 3.01, up to 1000

previous backups can be retained, depending on disk space. The
option is enabled through the Enhanced Configuration Parameters
download, or using the Supervisor Config menu. The format of the
EJ remains unchanged.
Host Control of BackUp Mode From release 3.02, the Enhanced 1

Configuration Parameters download method of updating the EJ

backup mode can be blocked. This option is enabled through the
Supervisor Config menu.
Multiple Destinations for EJ Backup In addition to retaining 1

multiple copies of the EJ, the destination for the EJ backup file can
be selected from available network and removable drives such as

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-24 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

CDRW, diskette or USB (Universal Serial Bus) drives. This option is

enabled through the Supervisor Config menu.
Maximum File Size From release 3.02, a maximum size can be set 1

for the EJ file. This can be a minimum of 1KB; the maximum

depends on available disk space. This option is enabled through the
Supervisor Config menu.
Automatic INIT From release 3.02, several options are available to 1

allow EJ initialisation (EJ INIT) to be run automatically, as follows:

 Cutover
 Scheduled
 Agent
There is also an option to take a copy of the initialisation file after
completion of the initialisation operation. All these options are
enabled through the Supervisor Config menu.
From release 4.0, the EJ can be initialised after a settlement
transaction using a Supervisor option.
Direct EJ Backup From release 3.02, an emergency backup can be 1

made of the EJ file if, for example, there is insufficient disk space for
an initialisation operation. This is selected through the Supervisor
Replenish menu.
Compression of the EJ File From release 3.02, the EJ file can be 1

compressed as part of the initialisation operation.

Privacy for the EJ File From release 3.02, the EJ file can be 1

compressed and password protected as part of the initialisation

operation.
Delay EJ Initialisation during Transactions From Advance NDC 1

4.02, scheduled EJ initialisation can be configured to wait until an

in‐progress transaction completes. This avoids splitting the
journaling from one transaction over multiple EJ files.

Display and Print TCP/IP Configuration 1

From release 3.01, options are available through Supervisor to

display or print the current TCP/IP configuration information. If the
print option is selected, the default printer for the operator interface
is used (receipt printer for the facia interface and journal printer for
the operator interface).
From Advance NDC 4.01, the TTU form supplied is the standard
form provided with the CCM TCPIP component. Consequently,
some of the messages for the Message Format, PING, SSL and DNS
SUFFIX options in Supervisor have changed.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-25

Introducing Advance NDC
Advance NDC Development

Default Network Connection 1

From Advance NDC 05.01, the application automatically

determines and applies the default network connection based on the
operating system of the SST i.e. Ethernet for Windows 10 and Local
Area Network for Windows 7.

Promote Coupon Printing During Transaction Reply 1

From release 4.01, you can choose to print Promote coupons only
when a receipt is successfully printed. This can be configured using
a registry key. The coupon can be printed during Transaction Reply
functions.

Promote Flow Points 1

From Advance NDC 4.00, a new Promote flow point for Next State
and Print has been added to the existing flow.
From Advance NDC 4.01, two new Promote flow points have been
added to the cash deposit flow. Two new Promote flow points have
also been added to the cheque deposit flow.
PIN Acquired Flow Point Prior to Advance NDC 4.02, the PIN 1

Acquired flow point was displayed in the following situations:

 PIN entry whether valid or invalid
 PIN Cancel
 Time‐out during the PIN Entry state.
From Advance NDC 4.02, this flow point is displayed only after a
valid PIN entry. This flow point is configured by default for the
following states:
 Card Read ‐ PIN Entry Initiation (state T)
 PIN Entry (state B)
 Enhanced PIN Entry (state M)
 PIN and Language Select (state m).
For further information on Promote flow points supported by
Advance NDC, see “Promote Flow Point Behaviour” on page 5‐35 and
the APTRA Promote User’s Guide.

Configure Statement Length 1

From release 3.01 a maximum statement length for the statement

printer can be specified using a registry key. This allows the setting
of the maximum number of lines to be printed before a cut. This can
be used, for example, where black mark paper is not used and no
form feed is included in the Transaction Reply print data.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-26 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Long Receipt Handling 1

Prior to Advance NDC 4.02, long receipts (49 lines) were not
retracted if left at the exit slot or in the transport after a transaction.
From Advance NDC 4.02, a configurable registry entry is available
to define whether long receipts are to be retracted or not.

Configuration of Forms‐Based Printing 1

The following updates have been made to the configuration of

forms‐based printing.
Automatic Configuration of Receipt Media Size Prior to 1

Advance NDC 4.02, an empty string was sent to the service provider
if no media definition was provided and this caused the printing to
fail. A media definition was required to configure the media size for
receipt printing.
From Advance NDC 4.02, a null pointer is sent when no media
definition is provided. This means that, if the printer service
provider does not require a media definition file, printing does not
fail and different media sizes can be used during receipt printing.
Scaling Printed Graphics Prior to Advance NDC 4.02, graphics 1

were printed within the boundaries of the graphic field, but the
aspect ratio might not have been maintained.
From Advance NDC 4.02, whether a graphic is scaled to fit the
graphic field boundaries and whether the aspect ratio is maintained
can be configured.

Configuration of Amount Entry Length 1

From Advance NDC 4.00, the length of an amount entry can be

configured up to a maximum of 12 digits. Once the number of digits
reaches the maximum value, no more input is permitted.

Enable Web Exits 1

From Advance NDC 3.01, support is provided for enabling web

Exits. Using web Exits provides a means to interact with the
consumer outside of the Advance NDC application.
From Advance NDC 3.03, support is provided for up to eight web
Exit state URLs.
From Advance NDC 4.02, table entry 7 of the Web Exit state can be
used to prevent the display of a web page. By default, the web page
is displayed. Hiding the web page means that script‐only web pages
can be used to load web content, carry out processing and then
move to another page or state.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-27

Introducing Advance NDC
Advance NDC Development

Local Customisation Data 1

From Advance NDC 3.01, local customisation data can be used to

replace or modify the data provided in host downloads.
The local data is provided by files placed directly on the SST.
From Advance NDC 4.0, you can also use a local file to specify the
Next State Number following a Transaction Reply.

From Advance NDC 04.01, local customisation download files are

loaded at the following points in the application:
 At Start of Day.
 After the host sends one or more download messages followed
by a go‐in‐service (GIS) message.
From Advance NDC 04.02, local customisation files are loaded
when a GIS message is received. Therefore, software management
can change local customisation files on the SST allowing Advance
NDC to read new customisation files after receiving the GIS
message.

Passbook Printer Worker Classes 1

In Advance NDC 2.5 and earlier, support for the passbook printer
was provided by the APTRA Advance Passbook component, an
optional component of APTRA Advance ADE, providing SST
runtime software and authoring components.
From Advance NDC 3.03, support is provided for the passbook
printer worker classes using the CEN‐XFS interface, enabling you to
develop an authored flow for passbook transactions. The
functionality and usage of the worker classes are the same as in the
APTRA Advance Passbook component, except for the following:
 When a runtime error occurs, an merror is not raised, but an
equivalent signal is generated by a worker
 The Passbook Definition and Passbook Definer workers can
create media definitions and form definitions dynamically to
read and write data using the CEN‐XFS interface; but it is better
to prepare the definitions manually for specific passbook
printers
 Registry settings are used for the default location of the form
and media definitions, and control of page mark reading and
line number scanning
For more information, see “Passbook Printer” on page 5‐203, and
refer to the Passbook Printer worker class help.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-28 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Associated Keyboards for FDKs 1

In Advance NDC 2.05, a physical keyboard could be defined by

associating a key position and a key code. The key position
identified the physical location of the key, and the key code defined
the value returned to the terminal when the key is pressed.
In the CEN‐XFS environment, the physical keyboard is not defined
at the application level. Consequently, Advance NDC can only
allow mapping between logical CEN‐XFS keys.
In Advance NDC 2.06, the following restrictions applied:
 Nested keyboards were not supported
 Screen and keyboard associations were ignored, as they
cannot be defined at application‐level.
 The Clear and Cancel key positions could not be swapped.
From Advance NDC 3.03, associated keyboards are supported for
physical and emulated FDKs only.
Associations between screens and keyboards for FDKs can be
created using the Screen And/Or Keyboard Data Load command.
Not all the Advance NDC state types support associated keyboards.
For more information, refer to “Chapter 4, Keyboard Data and
Layouts” in the APTRA Advance NDC, Reference Manual.

Beep Configuration 1

Beeps can be configured to sound at various points during

cardholder transactions.
Beep on Emulated FDK Selection From Advance NDC 4.00, a 1

beep can be configured to sound when an FDK is selected.

Beep on Card Eject and Cash Present From Advance NDC 4.00, 1

the beep sounded on card ejection or cash presentation can be

configured to use one of the sounds provided by the SIU SP.
PC Beep From Advance NDC 4.01, the beep can be configured to 1

use either the PC beep or SIU SP beep.

Alphanumeric Data Entry 1

From Advance NDC 3.03, SMS‐style alphanumeric key entry using

numeric keys is supported as an optional key entry mode in the
Information Entry ‘H’ state, table entry 9.
From Advance NDC 3.04, PC keyboard alphanumeric data entry is
also supported in the Information Entry (‘H’) state.
From Advance NDC 4.01, touch‐screen keyboards can be
configured for consumer data input in the Information Entry state.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-29

Introducing Advance NDC
Advance NDC Development

Validation of Host Responses to Transaction Requests 1

From Advance NDC 4.02, the Message Coordination Number can

be used in a Interactive Transaction Response to check that it
corresponds to the Transaction Request sent by the SST.
Enhanced Configuration Parameter 34 From Advance NDC 4.02, 1

Option 34 — MCN range, also defines how Transaction Replies and

Interactive Transaction Responses with incorrect MCNs are
processed.

Supervisor Menus 1

From Advance NDC 4.00, reserved screen M03 (Supervisor Access

menu) is no longer used. It has been replaced by screen m03 as it
includes an option for APTRA Promote, which is supplied with
Advance NDC.

Configuration of Cardless Transactions 1

From Advance NDC 4.02, an option is available on the Configure

menu in Supervisor to enable or disable cardless transactions and to
set or change the next state number. The cardless transactions status
and next state number are displayed and journaled along with other
configuration data. There is no host interaction associated with this
option.

Machine Number Entry 1

From Advance NDC 4.00, there is a Supervisor option to enter an

alphanumeric machine number at the SST.
From Advance NDC 4.01, fewer than six digits or characters can be
entered for a machine number, which is automatically padded with
leading zeros to make it the correct length of 6 digits.

Supervisor Entry/Exit Message 1

From Advance NDC 4.01, an extra field can be added in Supervisor

entry and exit messages that will distinguish whether the message is
sent due to Supervisor mode change or simulated Supervisor entry
and exit. The field can be added using the registry. A message to set
the mode switch to normal is displayed on front interface and rear
interface. The message can be edited in reservd.def.

SNMP 1

From Advance NDC 4.02, SNMP Out of Service and In Service

mode change traps are issued when Advance NDC relinquishes or
regains control of the SST respectively although the mode does not
actually change.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-30 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

From Advance NDC 4.02, the SNMP Agent is no longer supplied as

an optional component on the Advance NDC CD. The Unified
Agent SNMP Product replaces the SNMP Agent. For further details,
refer to the APTRA Advance NDC, Overview.

NDC Monitor 1

Prior to Advance NDC 4.02, there was no way to detect that the SST
had stopped responding. If the SST stopped responding it became
unavailable for transactions but no indication could be given to the
host.
From Advance NDC 4.02, NDC Monitor can be used to detect a
freeze and take a defined recovery action. NDC Monitor does the
following:
 Monitors application heartbeats
 Polls the SST to check that it is responding
 Checks the CPU usage.
If the application is unresponsive or no CPU usage is reported, NDC
Monitor can be configured to take either of the following actions:
 Log an error
 Reset the SST and log an error.

Archive Manager 1

From Advance NDC 4.00, the .NET Archive Manager component is

used to archive and manage data on the SST.
From Advance NDC 4.01, the ECB 6 database file can be archived
using the .NET Archive Manager. The .NET Archive Manager is
controlled from the Troubleshooting option on the Supervisor
Configure menu.
From Advance NDC 4.02, the .NET Archive Manager is configured
by default to remove PD investigation files after they have been
archived during a scheduled collection. PD investigations that are
active or paused are not deleted until the next scheduled archive
time arrives, providing these investigations have since completed.

Voice‐Guided Sessions 1

In Advance NDC 3.03, voice‐guided cardholder sessions were

introduced to provide configurable audio guidance during
transactions for visually impaired consumers using headphones or
speakers on the SST.
From Advance NDC 4.01, the Interactive Transaction Response
(ITR) message can be used to define screen data to display while
playing the audio guidance.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-31

Introducing Advance NDC
Advance NDC Development

Prior to Advance NDC 4.02, the voice associated with a language

was defined in the VoiceDict.xml file.
From Advance NDC 4.02, the VoiceDict.xml file is no longer used.
Configuration of voices is optional. The association of voice and
language is configured in the AdvanceNDC.accfg file.
From Advance NDC 4.03, the association of voice and language is
configured in the AdvanceNDCCustom.accfg file.
From Advance NDC 4.02, languages with accented or special
characters are supported using the character encoding specified in
the XML. For legacy configurations, the encoding of Spanish is
automatically converted to the correct ISO character code.
From Advance NDC 4.02, if only a single language is available for
voice‐guided sessions, whether the consumer is prompted for a
language selection is configurable.
From Advance NDC 4.02, a language selected for the voice‐guided
session can be applied automatically to the language selection
states. For backward compatibility, this can be disabled, meaning
that the consumer will have to select a languages more than once
during a session.
Voice‐Guided Session Without Host Update From Advance 1

NDC 4.00, voice data can be provided locally rather than supplied
by the host in Interactive Transaction Response and Transaction
Reply messages.

Intelligent Fraud Device (IFD) 1

From Advance NDC 4.00, to support NCR’s Intelligent Fraud

Device, an IFD Alarm worker was provided.
The IFD Alarm sensors that could be monitored, depending on the
installed hardware sensors and IFD configuration, were as follows:
 Media In Sensor
 Media Out Sensor
 Cardholder Sensor
 Service Sensor
 Environment Sensor

Note: Advance NDC did not support the custom configuration of

the IFD sensors. If any of the sensors monitored by Advance NDC
were reconfigured, the alarms event monitoring may have stopped
working, or may have sent incorrect reports.

From Advance NDC 4.02, the IFD is not supported. Therefore, the
IFD Alarm worker class and IFD Alarm help have been removed
from the APTRA Author.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-32 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Receipt Capture Bin 1

From Advance NDC 4.00, the Error severity and Supplies status
fields of the unsolicited message for the Receipt printer will report
the receipt capture bin status.
From Advance NDC 4.02, there is a registry setting to configure
whether receipt capture fitness and supplies are reported in status
messages to the host.

Top Margin for Receipts 1

Prior to Advance NDC 4.02, the top margin of receipts for raw‐data
printing could only be configured through screen ‘K01’. When
forms‐based printing was introduced in Advance NDC 3.03, the top
margin could be configured through the registry for forms‐based
printers only.
From Advance NDC 4.02, in addition to these two methods, a
Supervisor option on the Configure menu can be used to set the
receipt top margin for both raw‐data and forms‐based printing. The
registry is updated with any valid value entered using this option.

Displays 1

The Settlements supervisor transaction screens can be configured.

From Advance NDC 4.00, a single consolidated display interface for
the cardholder screen is provided. It is used to display the state flow
screens and customer relationship management (CRM) content
provided by APTRA Promote or APTRA Relate during a
transaction. For more information, see “Display Management” on
page 1‐48.
Replacing MPEG Animation Prior to Advance NDC 4.00, MPEG 1

animation files could not be replaced with a different animation

unless the file name and screen definition were also changed.
From Advance NDC 4.00, the changes to display management
removed this restriction.

Fault Displays 1

From Advance NDC 4.02, customisations can display messages on

the Fault Display. For example, a customisation can display
messages related to devices that are not managed by Advance NDC.
The author of the customisation is responsible for the accuracy of
the messages, which are defined using local customisation.

Cardholder Display Status 1

From Advance NDC 4.02, a registry setting can be used to include

or suppress cardholder display data in the Get Fitness response.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-33

Introducing Advance NDC
Advance NDC Development

Information Entry State 1

From Advance NDC 3.03, this entry includes support for SMS and
PC keyboard data entry.
From Advance NDC 4.02 the buffer and display parameters used to
display consumer input in the Information Entry state (‘H’) can be
controlled using table entry 9. The parameters defined in the state
table can be overridden using an XML file.

Data Copy and Compare State 1

From Advance NDC 4.02, the Data Copy and Compare state can be
used to process buffer data locally instead of by the host. Valid
buffers are Buffer B, Buffer C and the Amount buffer. Data in two
buffers can be compared for validation or data can be copied from
one buffer to another.

Hide Taskbar 1

Previously in Advance NDC, the hidetb.exe program was used to

hide the Microsoft Start menu and the taskbar on the SST.
From Advance NDC 4.01, hidetb.exe is no longer used as hiding the
taskbar is controlled through the registry.

Transactions Based on Device Availability 1

From Advance NDC 4.00, the following allow screen content and
FDKs to be updated based on the availability of devices, to direct
the transactions offered:
 Device Fitness Flow Select state
 Dynamic display of text and buttons
 Dynamic enabling of FDKs.

Scalable Deposit Module 1

From Advance NDC 4.00, support is extended to allow an NCR

scalable deposit module (SDM) to be configured as a cheque
processor that can accept cash or cheques.
Cash/Cheque Deposit Module From Advance NDC 4.02, the SST 1

is automatically configured for the Cash/Cheque Deposit Module

from Wincor if present on the SST.

Remote Status Indicators (RSIs) 1

In previous versions of Advance NDC, the red and yellow RSIs

were controlled by the platform and a registry configuration.
From Advance NDC 4.00, support for RSIs is extended to the red
and yellow RSIs through CEN XFS. No configuration is required.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-34 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Customer Relationship Management (CRM) 1

Advance NDC supports two CRM products: APTRA Promote for

customer‐targeted marketing and advertising campaigns and
APTRA Relate for building relationships with customers.
APTRA Promote In previous releases, APTRA Promote was 1

disabled by default.
From Advance NDC 4.02, APTRA Promote is enabled by default.
NDC CRM Interface Worker Class In previous releases, at the 1

Author flow level, Advance NDC invoked Promote flow points and
informed Promote of application events using an Active Script Host
worker and the Promote Dialogs COM interface.
From Advance NDC 4.00, to provide the same level of functionality
for CRM through the new .NET CRM service, flow points and
events can now be invoked at the Author flow level and at .NET
state flow level for cash or bunch cheque deposits using an NDC
CRM Interface worker.
The NDC CRM Interface worker also allows new flow points to be
added to the existing Author flow if required.
NDC CRM Service From Advance NDC 4.00, the NDC CRM 1

Service provides support for the addition of new flow points in C

Exits and the existing Author flow and the configuration of a
campaign language and coupon printing.

Cash Recyclers 1

From Advance NDC 4.04, a new recycling device, Bunch Recycling

Module (BRM) is supported, which supports five physical cassette
types i.e. four deposit/recycling cassettes and one deposit cassette,
and a retract, a reject and a counterfeit.

Avoid Inadvertent Tap on Contactless Card Reader 1

From Advance NDC 5.00, when a dual interface card is inserted in a

contact card reader and a contactless card reader is in close
proximity, the contactless card reader is triggered unintentionally.
In this scenario, the application interprets the card tap as an
inadvertent tap and proceeds with the transaction flow of a contact
card reader.

Interaction with Contactless Cad Reader 1

From Advance NDC 5.01, the application supports interaction with

the contactless card reader device through the XFS session or the
wrapper session. By default, the application interacts with the
device through the XFS session.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-35

Introducing Advance NDC
Advance NDC Development

Interaction with the device through the XFS session supports the
contactless card reader on the other vendors’ SST.

Journaling the Cassette Information 1

From Advance NDC 5.00, the logging of the cassette information to

the journal is configurable.

From release 4.02, Advance NDC supports TCP/IP communications

Internet Protocols 1

protocol IPv6 as well as IPv4.

Advance NDC uses a variety of utilities to help in the identification

Troubleshooting of errors when they occur.
Assistance 1

Problem Determination 1

From Advance NDC 4.00, Problem Determination investigations

can be fully controlled through options on the Supervisor Configure
menu under Troubleshooting.
Always On Tracing From Advance NDC 4.02, Always On tracing 1

is used to store troubleshooting information for all .NET code. The

Always On traces are logged to Problem Determination even when
Problem Determination is disabled.
The Always On traces are collected by .NET Archive Manager. For
more information about .NET Archive Manager, see “Configuring
.NET Archive Manager” on page 5‐65.

Silent Debug 1

From Advance NDC 3.02, support is provided for a utility called

Silent Debug that will perform trace capture on live SSTs.
From Advance NDC 4.02, there is a configurable registry setting to
run Silent Debug at start of day. This provides a level of
troubleshooting information for the APTRA Author and C++ code.
Archive Manager collects the Silent Debug logs.

DebugLog 1

From Advance NDC 3.02, support is provided for the DebugLog

utility.
Note: The DebugLog utility was available in previous releases of
Advance NDC but was not supported.

Message Reflection 1

From Advance NDC 3.02, support is provided for the reflection of

terminal to host messages using the virtual controller interface.
Previously, only host to terminal message reflection was supported.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-36 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Reflected messages are recorded in the MESSAGEOUT and MESSAGEIN

trace streams. Reflected messages in these trace streams can be
viewed using the Silent Debug or DebugLog utilities.
For information on viewing trace streams using Silent Debug or
DebugLog, see “Using the Troubleshooting Tools” on page 12‐19.

Cash acceptors are supported through ActiveXFS, making use of the

Cash Acceptors 1

Cash Accept Service component.

From Advance NDC 3.03, fault display and serial number reading
and logging (only to the EJ) are supported.
From Advance NDC 3.04, updates to the Cash Accept state for
returned notes are supported.
From Advance NDC 4.00, the following changes have been made:
 Multi‐vendor environments are supported, including support
for VDM mode
 The number of acceptable note types has increased with no host
impact
 Support for cash deposit has been re‐implemented using .NET
technology
 Bunch Note Acceptor 1 (BNA 1) devices are not supported.
From Advance NDC 4.02, the following changes apply:
 The number of attempts made by a consumer to re‐insert
bunches of rejected notes is configurable
 The number of bunches that a consumer can insert during a
single transaction can be configured
 The destination of notes retracted when the consumer does not
remove refunded notes is configurable. If configured to retract
notes to the escrow, the cash acceptor remains in a fatal
condition until either the INIT BNA or Clear BNA Supervisor
options are performed. This allows first‐line maintenance to
access notes retracted to the escrow
 A flag for customisations if a host time‐out occurs during a
transaction is provided by a new CDI store. This trigger can be
used, for example, to print a receipt.
From Advance NDC 4.04, for BNA variants (BNA1, BNA2 and
BNA3 devices), automatic reset is performed as part of the Advance
NDC Start of Day configuration.

Supervisor Options 1

In Advance NDC 3.04, the following changes were made to the

Supervisor Replenish menu:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-37

Introducing Advance NDC
Advance NDC Development

 Improvements to the reporting of counts and cleared notes in

the INIT BNA Supervisor option
 New Supervisor options to display reconciliation (DSP BNA
RCNL) and print a reconciliation (PRN BNA RCNL) list for cash
acceptors.
In Advance NDC 4.00, option 82, GBNA.INI CONFIG, was
removed from the Configure menu as the associated .ini file was no
longer used.
From Advance NDC 4.02, option 82, BNA CASS CFG on the
Configure menu is used to configure cassettes in cash acceptors and
recycling units using the Cash In Module (CIM) XFS interface.
Option 82 displays the physical and logical configuration of each
cassette and can also be used to print this configuration. This option
can be used on all vendors’ SSTs but cannot be used to configure
NCR GBXX‐specific settings, which continue to be configured using
option 39 GBXX CONFIG and the XML configuration file.
From Advance NDC 5.01, option 39 GBXX CONFIG can be used to
view and apply the GBXX cassette configuration sets present in the
XML file.
Advance NDC has the following Supervisor menu options for cash
acceptors if present:

Table 1-3 Menu Option Function

Cash Acceptor Menu Options
Configure 39 GBXX CONFIG Configures the GBXX device

80 DISP CSH/ACC Displays the cash acceptor

CONFIG configuration

81 PRNT CSH/ACC Prints the cash acceptor

CONFIG configuration

82 BNA CASS CFG Configures the XFS settings for

cassettes on cash acceptors and
recycling units
Any settings required
specifically for NCR GBXX
devices must be set using option
39 GBXX CONFIG

83 BRM CASS CFG Configures the BRM device

Replenish 3 DISP CNTRS Displays counters including cash

acceptor counters

4 PRNT CNTRS Prints counters, including cash

acceptor counters

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-38 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Menu Option Function

48 DSP BNA RCNL Displays the cash acceptor

reconciliation list
See “Reconciliation Lists” on
page 1‐39

49 PRN BNA RCNL Prints the cash acceptor

reconciliation list
See “Reconciliation Lists” on
page 1‐39

53 CLR BNA Clears the counters used to track

note movement within any cash
acceptor

54 INIT BNA Initialises the cash acceptor

55 CREATE SIGS Creates signatures.

In a cash acceptor creates
signatures for counterfeit notes
as identified by ECB 6 regulation

56 EXTRACT SIGS Extracts signatures.

In a cash acceptor the extract
signature writes a selected range
of records from the ECB 6
transaction

58 DSP BNA CNTS Displays the cash acceptor

counts

59 PRN BNA CNTS Prints the cash acceptor counts

60 PRN BNA TTLS Prints totals of the cash acceptor

counts
The counters that are included in
the printout can be configured

For details of the Replenish and Configure options for cash

acceptors, refer to the APTRA Advance NDC, Supervisor’s Guide.
Reconciliation Lists Prior to Advance NDC 4.02, the 1

reconciliation lists provided by the Supervisor Replenish menu had

the following issues:
 When multiple currencies or multiple note revisions were
deposited, the counts may not have been correctly updated
 When counts were full, the last row was overwritten in the
displayed reconciliation list
 The date and time was displayed and printed
 Only four fields were used in the displayed reconciliation list,
which means that there may have been unused space in the
screen

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-39

Introducing Advance NDC
Advance NDC Development

 When multiple note revisions were defined for a single

denomination, the counts for each note revision were displayed
separately.
From Advance NDC 4.02, a new screen is displayed for each
currency and the reconciliation lists are improved as follows:
 Counts are correctly updated, even if multiple currencies or
multiple note revisions are deposited
 When counts are full, the last row of the displayed reconciliation
list is not overwritten
 The date and time is printed but not displayed
 The screen space is efficiently used
 All note revisions for a single denomination are reported
together.

Direct Deposits 1

From Advance NDC 4.01, if direct deposit is supported by the

hardware and if it is configured, cash will be deposited directly to
the cassettes without first being stored in the escrow. This provides
support for devices with no escrow and for depositing large
amounts using only one note validation. Only vaulted counts are
updated in status messages and journaled.
Single Note Acceptors From Advance NDC 4.01, single note 1

acceptors are supported. This allows consumers to pay bills using

direct deposit on financial kiosks.

Off‐line Cash Deposit Handling 1

From Advance NDC 4.02, a new state, Cash Deposit Handling, is

available as an off‐line alternative to the Media and Refund Media
transaction reply functions. Both deposit and refund functions can
be used for refundable notes and the deposit function can be used
for direct deposit transactions.

Dynamic Note Sorting 1

In Advance NDC 3.01, support for dynamic note sorting was

introduced. This allowed the device to continue accepting notes and
to store them in sequenced cassettes. This functionality was
optional, and could be configured using registry settings.
In Advance NDC 4.00, support for dynamic note sorting was
removed.
From Advance NDC 4.01, dynamic note sorting is supported,
allowing a device to continue accepting notes after the cassette
originally configured for the note type becomes nearly full.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-40 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Dynamic note sorting is configured using the CashInCustom.accfg file

instead of the registry.

Fixed Cassette Mapping 1

Previous to Advance NDC 4.02, cash‐in NDC cassette types were

automatically mapped to XFS logical cash units based on the
position of the cassette.
From Advance NDC 4.02, a mapping array in the
CashInCustom.accfg file allows a fixed mapping to be defined. If
defined, the fixed mapping overrides the automatic mapping.

ECB 6 Regulations 1

In Advance NDC 3.03, support for ECB 6 regulations was

introduced.
In Advance NDC 3.04, support for the ECB 6 regulations was
extended as follows:
 New status codes were added to report counterfeit and
suspect notes
 For PA‐DSS compliance, customer information was masked
in the ECB 6 database.
In Advance NDC 4.00 support for ECB 6 regulations was removed.
From Advance NDC 4.01 ECB 6 regulations are supported again, as
follows:
 Status codes to report counterfeit and suspect notes
 For PA‐DSS compliance, masking of customer data in the
ECB 6 database
 The signatures (serial numbers) of good notes, if read
successfully, are journaled only to the EJ. The number of
unsuccessful reads of serial numbers in a bunch of good
notes is also journaled only to the EJ. The parser used to read
the signature is configurable for supported hardware
variants.
 The .NET Class Configurator files can be used to configure
whether unsolicited messages are sent when counterfeit or
suspect notes are identified.
 The Write Signatures option on the Supervisor Replenish
menu has been removed. The operation is now part of the
Extract Signatures option.
 In status messages and the journal, the escrow counts field
reports the count of notes that have been inserted, regardless
of physical location.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-41

Introducing Advance NDC
Advance NDC Development

 Reporting counterfeit and suspect counts in ECB 6 messages

is now cumulative for each transaction, not for each bunch of
notes inserted. If direct deposit is used, only the vaulted
counts are updated.
From Advance NDC 05.01, counterfeit and suspect counts in ECB 6
messages is configurable to report cumulative counts for each
transaction or for each operation.

Serial Number Information 1

From Advance NDC 4.04, the serial number information of good,

counterfeit and suspect notes, if read successfully is logged to EJ
and receipt. The number of unsuccessful reads of serial numbers of
good, counterfeit and suspect notes is also logged on the EJ and for
receipt, the logging is optional and based on the configuration.
From Advance NDC 5.01, on a BRM device, in a deposit transaction,
the serial number information of the deposited notes is logged to the
ECB6Log database file.
Reporting of Counterfeit or Suspect Notes From Advance NDC 1

4.02, notes identified as counterfeit or suspect under the ECB 6

regulations can be reported in the Transaction Request message.
The Transaction Request state (‘I’) defines whether these optional
fields are included.
Signatures in the ECB 6 Database In Advance NDC 3.04, 1

signatures of counterfeit or suspect notes were not logged to the

ECB 6 database unless ECB 6 was enabled.
From Advance NDC 4.01, signatures retrieved for counterfeit or
suspect notes are always logged to the ECB 6 database, regardless of
the ECB 6 settings.

Error Recovery 1

In Advance NDC 4.00, error recovery was enhanced to support

additional journaling, consolidation of error recovery behaviour at
different times and the ability to configure automatic error recovery.
From Advance NDC 4.01, recovery from a Suspend state is
supported without the need to treat the cash acceptor as if it were in
a fatal condition.
From Advance NDC 4.02, an XML file can be used to log exceptions,
retract operations, and host time‐outs occurring during deposit
transactions. The file logs all status messages for note acceptors,
with the exception of a successful operation (‘w0’), a time‐out or the
consumer requesting a refund or cancelling the transaction during
the Cash Accept state (‘w1’). The log file can be printed, archived

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-42 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

and cleared using options on the Supervisor Replenish and

Configure menus.
Automatic Error Recovery From Advance NDC 3.03, automatic 1

error recovery (AER) is supported.

In Advance NDC 3.04, the encash counts (the bank’s money) were
updated whenever notes were retained.
From Advance NDC 4.00, if the money belongs to the consumer, the
retract counts are updated.
From Advance NDC 4.01, there is a configurable option to move the
notes to the appropriate recovery destination, according to
ownership of the money as follows:
 Retract bin for the consumer’s money
 Cassettes for the bank’s money.
This option is configured by default to retain notes left in the device
in the recovery destination, which can be automatically selected.

Journaling 1

The following sections describe the improvements and

enhancements to journaling in Advance NDC.
Journaling the Cassette Status From Advance NDC 3.01, cassette 1

status can be optionally reported in the host message when

Enhanced Configuration option 45 is set to enable the extended
message format.
Journaling Reject Counts In Advance NDC 3.04 and earlier, the 1

returned count in the journal consisted of the total number of

recognised note types refunded to the cardholder plus the total
number of invalid notes that were rejected. The invalid notes were
also journaled in the reject count.
From Advance NDC 4.00, the returned count in the journal is
replaced by the refunded count. The refunded count includes only
the total number of recognised note types refunded to the
cardholder. The total number of invalid notes is now journaled only
in the reject count.
Journaling the Count of Failed Serial Number Reads From 1

Advance NDC 4.04, the count of the failed serial number reads of
Category 2, Category 3 and Category 4 notes is journaled for a
deposit transaction.
Journaling the Escrow Status In Advance NDC 3.04, when the 1

number of notes inserted exceeded the escrow capacity, the message

REJECT COUNTS NOT UPDATED - ESCROW FULL was journaled.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-43

Introducing Advance NDC
Advance NDC Development

From Advance NDC 4.01, if the inserted notes exceed the escrow
capacity, the message ESCROW FULL (reserved screen t19) is
journaled.

Note: On SSTs with GBXX devices, this message can also indicate
that a large number, for example 50, invalid notes have been
inserted.

Journaling Note Counts In Advance NDC 3.04, if automatic error 1

recovery was enabled and a power failure occurred with notes in

the escrow, then, after power up, an unsolicited message was sent to
the host correctly reporting the vaulted counts.
From Advance NDC 4,01, if the vaulted counts are not accurately
reported due to platform limitations, the message COUNTS MAY BE
INACCURATE (reserved screen U0151) is journaled.

From Advance NDC 4.01, if notes are detected at the exit slot during
AER, the message NOTES DETECTED AT EXIT SLOT (reserved
screen U0135) is journaled.
From Advance NDC 4.02, if notes are detected in the escrow during
AER, the message NOTES DETECTED IN THE STACKER (reserved
screen U0171) is journaled. If a retract operation is performed,
RETRACT TO <RetractArea%> (reserved screen U0172) is journaled.
In this screen, the <RetractArea%> variable identifies the
destination of the retracted notes.
Journaling Serial Number Information of Notes From Advance 1

NDC 4.04, the serial number information of Category 4 (Good),

Category 3 (Suspect) and Category 2 (Counterfeit) notes is journaled
for deposit and dispense transactions.
From Advance NDC 5.01, in a deposit transaction, the file name of
the captured serial number image is formatted with details like
operation type and machine number. The file name is also journaled
to the EJ along with the existing serial number information.
From Advance NDC 5.01, the application journals location
information of notes along with the serial number in both deposit
and dispense (only in a BRM device) transactions.
Configuring Journaling From Advance NDC 4.00, journaling is 1

configured using the Journal Level option on the Configure menu in

Supervisor mode. Improvements are also extended to journaling
and its configuration when the device status is reported to the host.
In Advance NDC 4.00, the registry entries defining the format of
journal entries were replaced by configuration settings in the
AdvanceNDC.accfg file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-44 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

From Advance NDC 4.01, the formatting of journal entries is

defined in the CashInCustom.accfg file.
From Advance NDC 4.02, cash counts are included by default when
the maximum journal level is configured. The journaling of the cash
counts can be disabled by editing reserved screens.
For details of the levels and their configuration, see “Journal
Formats” on page 5‐379.

Capturing Bunch Note Image 1

From Advance NDC 5.01, on a BRM device, the application

supports capturing the image of bunch of notes through a camera at
the entry or exit slot for both deposit and dispense transactions.

Printing Note Counts for Bunch Note Acceptors 1

From Advance NDC 4.02, there is an option, Print BNA Totals, on

the Supervisor Replenish menu to print the number of notes in
different groups such as deposited, rejected, retracted and refunded
by denomination, and print the total counts. The journal printer, the
receipt printer or both can be selected to print the counts through
the Set Printer option on the Configure menu in Supervisor.

Confirmation Screens 1

From Advance NDC 4.00 dynamic confirmation screens used in the

Cash Accept state are supported. These replace the basic
confirmation screens, M10, M11, M13 and M14.
From Advance NDC 4.01, the dynamic content of the Confirmation
screens used in the Cash Accept state is configured using the
CashInCustom.accfg file instead of using the registry. New
configuration options have also been added.

Configuration Files 1

Prior to Advance NDC 4.00, if a GBXX device was detected, a

GBNA.ini file was created.
From Advance NDC 4.00, the GBNA.ini file is no longer used. It is
replaced by the note type mapping XML file.
From Advance NDC 4.01, NDC note types are mapped
automatically on a one‐to‐one basis to XFS note types by default. It
is also possible to either group note types by currency and
denomination or to use an XML configuration file to define the
mapping and grouping. For details of the note type mapping XML
file, see “Note Type Mapping” on page 5‐360.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-45

Introducing Advance NDC
Advance NDC Development

From Advance NDC 4.01, the cash‐in entries in the

AdvanceNDC.accfg file are in new files, CashInCore.accfg and
CashInCustom.accfg to help simplify maintenance and configuration.

Promote Flow Points 1

Support for Promote flow points in cash deposits, which was

available in Advance NDC 3.04 but not in 4.00, is available from
Advance NDC 4.01.01.

Tamper and Sensor Status Reporting 1

From Advance NDC 4.01, tamper and sensor status reporting is

supported for cash‐in cassettes with sensors. If a cassette is inserted
or removed, this is reported to the host and journaled, except if the
cassette is manipulated during Vendor Dependent Mode (VDM).

Journaling Security Trace Message 1

From Advance NDC 5.01, when a cash‐in cassette is inserted or

removed, along with the tamper and sensor status, a security trace
message is also journaled.

Journaling the Count of Notes that Pass

through the Bill Validator 1

From Advance NDC 5.01, on a BRM device, in a deposit transaction,

when a hardware error occurs, the count of notes that pass through
the bill validator is journaled irrespective of whether the notes are
moved to escrow/cassettes.

From release 4.00, Advance NDC supports the reporting of the

Product Class Support 1

SelfServ 22e product class in hardware configuration messages.

From release 4.01, Advance NDC supports the reporting of the
following SelfServ product classes in hardware configuration
messages:
 SelfServ 4
 SelfServ 8
 SelfServ 16
 SelfServ 42.
From release 4.02, Advance NDC supports the reporting of the
SelfServ 14 product class (2014) in hardware configuration
messages.
From release 4.04, Advance NDC supports the reporting of the
following SelfServ product classes in hardware configuration
messages:
 SelfServ 6623

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-46 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

 SelfServ 6627
 SelfServ 6683
 SelfServ 6687
From release 4.04.01, Advance NDC supports the reporting of the
following SelfServ product classes in hardware configuration
messages:
 SelfServ 6681
 SelfServ 6682
 SelfServ 6684
 SelfServ 6688

NCR has migrated the Advance NDC product from a proprietary

Support for CEN‐XFS 1

implementation based on ADI2 to a vendor‐independent

implementation that is compliant with CEN‐XFS 3. This allows
Advance NDC to run in a multi‐vendor environment. CEN‐XFS
support was introduced in phases as described in the following
table:

Table 1-4 Advance NDC Version Interface

Migration to CEN-XFS
2.05 ADI2

2.06 ADI2 and CEN‐XFS 2.00

3.00‐3.01 ADI2 and CEN‐XFS 3.00

3.02‐4.02 CEN‐XFS 3.00 to 3.03 and

CEN‐XFS 3.10

Service providers compliant with CEN‐XFS 3.10 are as follows:

 Bunch Cheque Deposit (Advance NDC 3.04)
For details of the specific devices accessed through ADI2 or
CEN‐XFS and for information describing of how this affects
customised applications, see Chapter 4, “Upgrading from Earlier
Releases of Advance NDC”.

Advance NDC provides support for and management of screens as

Screen Management 1

described in the following sections.

Screen Support 1

Prior to Advance 2.06, Advance NDC supported up to 999 screens.

From Advance NDC 2.06, up to 9999 screens are supported.
From Advance NDC 4.02, the screen numbers defined in state tables
are extended from 000‐999 to 000‐Z99. The alphanumeric character
is mapped to a numeric value to allow the direct specification of

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-47

Introducing Advance NDC
Advance NDC Development

3599 screens. Applying language offsets allows all 9999 screens to be

referenced from the state tables if necessary.
A configuration option allows screen base and group sizes to be
extended to increase the available number of multi‐language
screens.

Display Management 1

From Advance NDC 4.00, the integrated consumer interface

displays screen data from the host or stored as local customisation
data. The screen data is converted to a supported screen definition
format before being displayed.
Media Formats Advance NDC supports a wide range of media 1

formats, as described in “Image and Media Support” on page 1‐49.

Dynamic Screens Dynamic screen content, such as text and 1

buttons, can be used to implement dynamic menus. The dynamic

menu can accurately reflect the availability of various transactions
without the need for updates from the host.
Advance NDC 4.00 includes new escape sequences that enable
buttons and the provide dynamic text for screen display.
CRM Content The integrated consumer interface delivers any 1

configured CRM content to the screen at the correct time. The

content must be provided by the APTRA Promote and APTRA
Relate products and flow points in the Advance NDC state flow
control requests for CRM content.
Font Definition Prior to release 4.0, the font definition file 1

(fontdefs.txt) was used to define the fonts used by Advance NDC for
screen display.
From Advance NDC 4.0, fonts are defined using the integrated
consumer interface XML configuration file.
Other Vendors’ SSTs Prior to Advance NDC 4.02, the labels 1

displayed on‐screen for FDKs did not always align with the physical
key locations on some other vendors’ SSTs.
From Advance NDC 4.02, the screen display can be automatically
scaled on other vendors’ SSTs to align FDK labels to physical
positions if necessary. Further configuration settings can also be
defined to improve the display. For deployment in mixed networks,
XML configuration files can be defined to allow the correct
re‐scaling to be performed.
For further information on the configuration and deployment of the
scaled screen displays, refer to the APTRA Advance NDC,
Multi‐Vendor Support Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-48 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

From Advance NDC 4.00, an integrated consumer display interface

Image and Media Support 1

is provided, with support for image and animation file formats as

well as NDC screens and off‐line screen files.
Formats such as GIF, JPEG and PNG are supported. In addition,
media formats such as animated and transparent GIF, and
transparent PNG are supported.
From Advance NDC 4.01, the PCX format is no longer supported. If
a host download contains a reference to a PCX file in a screen
definition, Advance NDC discards the PCX extension and searches
for a match on the filename in a supported format. For example, if
the download contains graphic1.pcx, a match would be found with a
file called graphic1.png.
From Advance NDC 4.04.01, the SWF format is no longer supported
as Adobe’s Flash is not suitable for 24/7 environments.
Microsoft DirectShow is used to render video files to the screen.
This allows support for a wide range of video formats, such as
WMV, AVIs, MPEGs and animated GIFs. Free support for common
formats, such as DIVX and QuickTime (.mov), is available through
third‐party DirectShow codecs. DirectShow codecs also provide
support for audio file formats, such as MP3 and AAC.
For more information about image and multi‐media file formats,
refer to the following:
 For image and animation file formats, the “Picture and
Animation Formats” topic in the APTRA Author help
 For multi‐media video, chapter 3, “Screen Data” in the APTRA
Advance NDC Reference Manual.

Advance NDC uses voice guidance to allow any prompts on the

Voice Guidance 1

screen in the consumer transaction flow to be spoken.

Invalid XML File Handling 1

In Advance NDC 3.04, if an invalid AudioGuidanceData.xml file was

copied manually to the SST, it was deleted.
If an AudioGuidanceDataLocal.xml file that contained invalid data
was manually copied to the SST, it was not deleted, however,
AudioGuidanceData.xml was deleted whether valid or invalid.
In both cases, a message in the NoAudio.xml file was played to
indicate that voice guidance was temporarily unavailable on the
SST.
In Advance NDC 4.02, if an invalid AudioGuidanceData.xml or
AudioGuidanceDataLocal.xml file is manually copied to the SST, no

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-49

Introducing Advance NDC
Advance NDC Development

files are deleted. A message in the NoAudio.xml file is played to

indicate that voice guidance is temporarily unavailable on the SST.

In Advance NDC 2.05, the maximum number of valid states was

Maximum State Number 1

increased from 750 to 999. Each ‘Next State Number’ entry in the
APTRA Advance NDC, Reference Manual, Chapter 2 “State Tables”
had a possible range of 000‐254 or 256‐999.
From Advance NDC 3.02, the maximum number of valid states is
increased from 999 to 46655. This is achieved by introducing
support for alphanumeric state numbers in state tables. Depending
on the number system specified in Enhanced Configuration
Parameter option 80, each ‘Next State Number’ entry in the APTRA
Advance NDC, Reference Manual, Chapter 2 “State Tables” has a
possible range as follows:
 000‐254 or 256‐999 using the decimal (base 10) system
 000‐254 or 256‐ZZZ using the alphanumeric (base 36) system.

From Advance NDC 2.06, for SSTs fitted with an Encrypting PIN
Remote Key Management 1

Pad (EPP), the loading of the initial encryption keys (A key, B key
and V key) using RSA encryption is supported as an alternative to
local entry in Supervisor mode.
In Advance NDC 3.02, worker classes were added to support
enhanced remote key management.
From Advance NDC 4.00, a modifier is available as part of remote
key management. This provides information to the host in
identifying whether the EPP is PCI DSS compliant or not.

Certificates 1

From Advance NDC 4.01.01, remote key management using

certificates is supported on other vendors’ SSTs where supported by
the XFS platform. NCR SSTs continue to use signatures.

In previous releases, the MAC encryption key could not be updated

Changing the MAC while the SST was In‐Service. From Advance NDC 3.03, the MAC
Encryption Key 1
encryption key can be updated using the Extended Encryption Key
Change message at any point after it is initially entered, except
when a transaction is in process, the terminal is in Suspend mode, or
when the operator is executing a Supervisor settlement transaction.

From Advance NDC 2.06, additional functionality on the Supervisor

Dual‐Mode Journal Configure menu supports dual‐mode journaling, which allows both
Printing 1
a paper journal to be printed and an electronic journal (EJ) to be
created.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-50 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

In previous releases, group separators were not included when a

Format of Journaled message was journaled. From Advance NDC 4.02, group separators
Messages 1
are represented by asterisks on both the EJ and hardcopy journal.
This improves the readability of the journaled message.

From Advance NDC 4.00, in addition to the PrintToJournal API, the

APIs for C Exits to Print to following APIs are provided for C Exits:
Any Printer 1

 PrintToReceipt
 PrintToStatement
For further details, refer to the APTRA Advance NDC, Extending the
Product publication.

Up to Advance NDC 2.06, the night safe was supported for both
Night Safe 1

basic and enhanced variants. In Advance NDC 3.00, only the basic
night safe was supported. From Advance NDC 3.03, both the basic
and enhanced night safes are supported.

In Advance NDC 2.x, ActiveX Controls were used in a

ActiveX Controls 1

single‐vendor environment and used ADI. These controls contained

a complete worker hierarchy. Three files were delivered as part of
the ActiveX Control. Controls were registered using the regsvr32.exe
application provided with Windows.
From Advance NDC 3.03, ActiveX Controls are XFS‐based. These
controls wrap the application DLL file and provide an interface to
use the application DLL file in different environments. Four files are
delivered as part of the ActiveX Control. Controls are registered
using the Assembly Registration tool (regasm.exe) provided with the
.NET 2.0 runtime installation.

Note: Any Globally Unique Identifiers assigned to ActiveX

Controls built using Advance NDC 2.x cannot be maintained in
Advance NDC 3.x. This is due to a difference in registering C++
COM Controls and .NET ActiveX enabled controls.

In previous versions of Advance NDC, the available characters used

Master Expansion State 1

to indicate which state type is referenced in the State Type field

were almost exhausted.
From Advance NDC 3.03, the available state types have been
extended by defining a Master Expansion State, State ‘z’. The first
entry in the Master Expansion State defines the new state type.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-51

Introducing Advance NDC
Advance NDC Development

From version 3.04, a new component is included to provide the

.NET Assemblies for following features:
Advance NDC 1

 Bunch cheque acceptors are supported as CPM devices, with

additional support as follows:
— New states to support bunch cheque acceptance
— New control sequences to support bunch cheque acceptance
— Support for offline bunch cheque solutions, including
transaction receipt printing
— Support for dynamic screen content for bunch cheque
acceptance through Display Manager
— Configuration at start of day through a configuration file
 Extended Supervisor options for TCP/IP communications.
From Advance NDC 4.00, the following apply to the .NET
Assemblies for Advance NDC component:
 Cash‐in functionality is implemented through the .NET
Assemblies for Advance NDC.
 Cardholders can unmark cheques they have incorrectly marked
for return, instead of having to perform another cheque deposit
transaction. This facility to toggle between marking and
unmarking cheques is controlled through the Cheque Detail
Display state. For details of this state, refer to Chapter 2, “State
Tables” in the APTRA Advance NDC, Reference Manual.
From Advance NDC 4.01, TCP/IP configuration in Supervisor
allows you to add, delete or edit the four optional parameters to
configure security certificates, as follows:
 4 Received Certificate Issuer
 5 Received Certificate Subject
 9 Supplied Certificate Identifier
 10 Supplied Certificate Subject

Local Printing Functions 1

From Advance NDC 4.02, places known as print points are available
in the transaction flow to allow printing to be initiated by Advance
NDC rather than by the host. This functionality can be used, for
example, in local states and customisations. For details of using
these print points refer to Chapter 10, “Developing Hooks” in
APTRA Advance NDC, Extending the Product.

.NET Supervisor Tasks 1

From Advance NDC 4.00, there is support for including Activate

.NET Supervisor Tasks (Supervisor tasks) through either of the
following:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-52 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

 The existing Supervisor Exit Executor worker, which does not

require any authoring updates, but limits the inclusion of
Supervisor tasks to the first two levels of the Supervisor menus
 The new Supervisor Task Executor worker, which requires
authoring updates, but allows the inclusion of a Supervisor task
anywhere in the Supervisor application flow.
APTRA Promote From Advance NDC 4.00, the APTRA Promote 1

CRM product is supported using .NET Supervisor Tasks on the

Access menu.
The following changes are made to the Supervisor Access menu to
support Promote:
 The Copyfile option is replaced by the Promote/Copyfile option,
which offers the following:
— The same functionality offered by the previous Copyfile
function
— A Promote sub‐menu that allows you to enable or disable
Promote, copy campaigns, delete campaigns and export logs
containing details of Promote screens and coupons.
 The Promote option is removed.
APTRA Relate From Advance NDC 4.00, the APTRA Relate CRM 1

product is supported using .NET Supervisor Tasks on the Access

menu. Option 21, Relate menu, is provided to enable or disable
Relate.
Troubleshooting From Advance NDC 4.00, Problem 1

Determination investigations and the retrieval of archives are

supported using .NET Supervisor Tasks. Option 44,
Troubleshooting on the Configure menu provides access to both of
these options.

Software Update 1

From Advance NDC 4.02, there is an option on the Misc Funcs

menu in Supervisor to install or update software and configuration
files from removable media and without using a PC keyboard. The
option uses the .NET Software Update Tasks component to copy or
execute files.

From Advance NDC 4.00, the Self‐Service Terminal Configuration

Self‐Service Terminal component (SST configuration component) runs automatically
Configuration Component 1
following installation to configure the SST. The devices present on
the SST are identified using an XML‐based configuration file, which
also defines the configuration settings.
The configuration component can be used on SSTs from NCR and
other vendors.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-53

Introducing Advance NDC
Advance NDC Development

The SST configuration component replaces any cash‐in,

printer‐specific and vendor‐specific registry files. The
AdvanceNDC.reg and NDC_SP.reg files are retained, with the SST
configuration component providing additional settings.
From Advance NDC, 4.01, the SST configuration component can be
used on all NCR SSTs.

From Advance NDC 4.01, a preconfigured location on a fixed drive

Configuration of Fixed is provided as the default location for the storage of note signatures.
Drives 1
This can be changed by editing the CreateSignaturesPath
property in the Class Configurator file, AdvanceNDC.accfg.
From Advance NDC 4.03, the CreateSignaturesPath property can
be changed in the class configurator file, CashInCustom.accfg.

Advance NDC 3.04 obtained PA‐DSS compliance certification from

PCI DSS Compliance 1

the PCI Securities Standards Council (PCI SSC), following

assessment and submission of an audit report by a PCI DSS
Qualified Security Assessor. The updates made are described in
Appendix E, “PCI DSS & PA‐DSS Compliance in Advance NDC”.

Masking of Sensitive Data 1

From Advance NDC 4.00, additional registry keys are provided to

mask the sensitive customer data in trace data when
troubleshooting. Data sent in an Interactive Transaction Reply or a
Transaction Reply to the Message In window, or printer data sent to
the OOXFS window in DebugLog and Silent Debug, can now be
masked.
Interactive Transaction Reply The Screen Data field (field j) and 1

the Trailer field (field k) can be masked when an Interactive

Transaction Reply is written to the Message In window. The
masked characters will be replaced by asterisks.
Transaction Reply From Advance NDC 3.04, the following fields 1

of the Transaction Reply message are masked before being logged

in the ʺMessage Inʺ window of Debug Log or Silent Debug:
 Track 1 data
 Track 2 data
 Track 3 data
 Exit data buffers M, N , O, P, Q and R.
From Advance NDC 4.00, it is possible to enable or disable masking
of the Screen Display Update and Printer Data fields through the
registry. The masked characters will be replaced by asterisks.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-54 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Advance NDC Development

Printer Data Logging From Advance NDC 4.00, it is possible to 1

configure whether printer data sent to the journal, receipt and

statement printers is also logged to the OOXFS window of Debug
Log or Silent Debug.
Note Acceptor Unsolicited Messages From Advance NDC 4.01, 1

cardholder data is masked with asterisks.

From Advance NDC 3.04, during a runtime installation, the

Runtime Installation C:\SSDS path is no longer used for files, although it is still available
Directories 1
for backward compatibility with customer Exits.
Any files previously installed to C:\SSDS\DLL or C:\SSDS\APPS
are now installed to C:\Program Files\NCR APTRA\Advance NDC
and its subdirectories. This includes application files, DLL files,
media files, and configuration files.

Prior to Advance NDC 4.00, customisations, such as customer Exits,

Directories for were installed to C:\SSDS\DLL.
Customisations 1

From Advance NDC 4.00, customisations must be installed as

follows:
 On an SST, C:\Program Files\NCR APTRA\Advance NDC
 On a development PC, C:\NTGlobal\AANDCAPPS.

From Advance NDC 3.01, all installation options are available for
Installation Types 1

selection from a single Advance NDC aggregate.

From Advance NDC 4.00, a smaller Runtime‐only installer is also
provided as an alternative to the Combined installer for use on
SSTs.

From release 3.01, a directory containing all modified files and

Custom Directory 1

registry settings, called the custom directory, replaces the Advance

NDC Support component containing the supportfiles subdirectory.

Prior to Advance NDC 4.02, the MEI on spray dispensers was never
Media Entry Indicator turned on.
(MEI) on Spray Dispensers 1

From APTRA Advance NDC 4.02, there is a configuration option to

enable the MEI and to specify the length of time it flashes during a
dispense operation on a spray dispenser. Using registry entries, the
MEI can be configured to delay flashing until just before notes are
presented and also to continue flashing for a few seconds after the
last note has been dispensed.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-55

Introducing Advance NDC
Advance NDC Development

From release 3.00, the EPP in BAPE emulation mode is no longer

Unsupported Features 1

supported in Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-56 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

Differences Between Advance NDC

and NDC+ 1

To compare the overall features offered by NDC+ with those offered

by Advance NDC, refer to the APTRA Advance NDC, Overview.
The Customisation Layer allows you to customise the behaviour of
the SST to a greater extent than was available in NDC+.
This section discusses specific operational differences between
Advance NDC and NDC+. It focuses on the features in NDC+ that
are either not available in Advance NDC or operate differently.
These operational differences include:
 Aggregate Building
 Cash dispenser beeper
 Cash dispenser cassette types
 TM‐Alert
 Document Processing Module (DPM)
 Coin Dispenser
 Digital Audio Service (DAS)
 State Types
 Configuration Parameters
 Customisation Data Commands
 PIN Entry and Verification
 BAPE emulation
 Electronic Journal and Journal Printer Backup
 Screen Data
 K Screens
 Diebold Emulation Mode Status Messages
 Status Messages
 Alarms and Tamper Indication
 Option Digits
 Supervisor Mode
 Differences in MACing
 Communications Protocols
 Basic Operator Panel (BOP)
 VGA Enhanced Rear Operator Panel (VEROP)
 Security Camera
 Software Management
 Associated Keyboards

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-57

Introducing Advance NDC
Differences Between Advance NDC and NDC+

 Transaction Request Extension State

 Font Definition
 Character Sets
 Localising Advance NDC
 Unsolicited Status Messages
 MPEG and PCX File Support
 Number of Screens Supported
 Support for Screens
 Set Display Mode Control Sequence
 Passbook Printer Support
 Roll Width and Left Margin
 Envelope Dispensing
 Remote Status Indicators.
For information on the BNA and CPM devices, see “Advance NDC
Development” on page 1‐15.

From Advance NDC 2.05, the Aggregate Builder Tool has been used
Aggregate Building 1

to define component aggregates.

For an introduction to building aggregates with Advance NDC, see
“Aggregate Building” on page 1‐80.

In NDC+, when option A was set to Action (do not retract notes),
Cash Dispenser—Beeping 1

option B was ignored; so the beeper did not sound. In Advance

NDC, the behaviour of option B, when set to Action, depends on the
setting of option A. For details, refer to the APTRA Advance NDC,
Supervisor’s Guide.

In NDC+, up to four cassette types were supported.

Cash Dispenser—Cassette
Types 1
In Advance NDC, Enhanced Configuration option 76 controls the
number of supported cassette types. By default, this option is set to
support up to four cassette types. For further details of option 76,
refer to the APTRA Advance NDC, Reference Manual.

In NDC+, the current supply status was reported for repeated

Cash Dispenser—Supplies transactions, even where the supply status remained the same.
Status 1

In previous releases of Advance NDC, the supply status was

reported as 0 ‐ ‘no new state’ for repeated transactions if the supply
status remained the same.
From Advance NDC 3.03, the supply status reported is that of the
cassette referenced by the transaction. If the status remains the same

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-58 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

as the previous transaction, it does not change to 0 ‐ ‘no new state’.

The purge bin never reports 0.
Following a retract operation in NDC+, only the supplies status of
the dispensing cassette type was reported.
In Advance NDC, the supplies status of all cassettes are reported
following a retract operation.

TM‐Alert is not supported by Advance NDC.

TM‐Alert 1

The following table details which message types associated with

TM‐Alert are handled differently by Advance NDC.

Table 1-5
TM Alert

Message Message
Message Destination Differences
Class Sub-Class

5 ‐ TM‐Alert Terminal This message from the Central application is not supported. If
it is sent, Advance NDC responds with a Command Reject or
Specific Command Reject (E01).

3 ‐ TM‐Alert Central As a result of the above, Advance NDC does not send this
message to the Central application.

The Document Processing Module (DPM) is not supported in

Document Processing Advance NDC.
Module 1

Advance NDC behaves in the same way as NDC+ when running on

an SST where a DPM device is not present.
The following table details the message types associated with this
device which are handled differently by Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-59

Introducing Advance NDC
Differences Between Advance NDC and NDC+

Table 1-6
DPM Message Types in Advance NDC

Message Message
Message Destination Differences
Class Sub-Class

1 1 Transaction Request Central If the DPM fields are requested for inclusion in
this message, they will be included. Although all
DPM data (such as Read Zones) is initialised, it is
never written to by Advance NDC.

NCR recommends you do not request inclusion of

the DPM related fields.

1 2 Device Fault Status Central Advance NDC will not send any Unsolicited or
2 2 Information Solicited Device Fault Status messages for the
DPM.

1 2 Sensors Device Fault Central For the Sensors device, byte 19 of the Device Status
Status Information is not reported as it relates to the DPM.

2 2 Send Configuration Central DPM, and DPM Tamper Indicator (TI) and Coin TI
Information Terminal fields are included in this message, if specified, but
State Message will always indicate that the device is not
configured.

2 2 Send Supply Counters Central DPM fields are not included in this message.
Terminal State

2 2 Send Tally Information Central Not supported in Advance NDC.

Terminal State A default message is always returned in which
zeros are reported for the DPM.

2 2 Send Error Log Central Not supported in Advance NDC.

Information Terminal DPM fields are not included in the SST Device
State Error Logs.

2 2 Hardware Central There will be no Device Identifier/Configuration

Configuration Data for the DPM in this message (Device Identifier ‘]’).
Terminal State
If a Depository is present, Device Identifier ‘F’ will
have a Hardware Configuration of ‘02’ for PPD
(Programmable Printing Depository) reported
rather than ‘04’ for DP‐ATM Depository.

If a Statement printer is present, Device Identifier

‘V’ will have a Hardware Configuration of ‘01’ for
standard Statement printer reported rather than
‘05’ for 5665 Statement printer.

If an Envelope Dispenser is present, Device

Identifier ‘\’ will have a Hardware Configuration
of ‘01’ reported rather than ‘02’ for DP‐ATM
Envelope Dispenser.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-60 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

Message Message
Message Destination Differences
Class Sub-Class

There will be no Device Identifier/Configuration

for DPM TI (‘_’).

2 2 Supplies Data Terminal Central There will be no Device Identifier/Supplies for

State DPM.

DPM TI is never reported.

2 2 Fitness Data Terminal Central There will be no Device Identifier/ Fitness for the
State DPM.

DPM TI is never reported.

2 2 Tamper and Sensor Central In field g2, the value of the sensor status is derived
Status Data Terminal from the XFS HRESULT.
State In field g3 (Tamper Indicator Identifier ‘B’) the
status of each Tamper Indicator is reported.
This field is always 13 bytes in length. Bytes 1‐7
are derived from XFS.
Bytes 8‐12 deal with the coin dispenser.
Byte 13 is always ‘0’, indicating DPM TI is not
present.
In field g4 (Extended Tamper Indicator Identifier
‘C’) the status of each extended Tamper Indicator
is reported.

4 ‐ Transaction Reply Terminal Functions ‘S’ and ‘T’ are not supported by
Advance NDC. If they are specified, a Command
Reject or Specific Command Reject (E02) is
reported. These functions are rejected at the
earliest stage, with no validation or use of the
DPM data in the Transaction Reply.

Printer Flags ‘;’ and ‘<’ are ignored by Advance

NDC.

3 1 Override Reserved Terminal This Customisation Data Command (Message

Screens Command Identifier ‘G’) is accepted, but the ‘Type D’
reserved screens are not used by Advance NDC. A
Ready 9 message is returned.

3 1 Configuration/ Terminal These Customisation Data Commands (Message

Enhanced Identifiers ‘3’ and ‘A’) are accepted. See
Configuration “Configuration Parameters” on page 1‐66.
Parameters Load

The following table details which state types associated with the
DPM device are handled differently by Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-61

Introducing Advance NDC
Differences Between Advance NDC and NDC+

Table 1-7 State Type Description

DPM State Types in Advance NDC
Close The extension to this State related to DPM
error handling and screens is ignored.

Courtesy Amount This State does nothing other than take the
Verification exit specified by Table Entry 4 (CAV
Unavailable Next State Exit).

DPM Document Accept This State does nothing other than take the
exit specified by Table Entry 6 in Extension
3 (Exception Type 3 Next State Exit).

Enhanced Amount Entry The “Start CAV” extension to this State is

ignored by Advance NDC.

The differences between using a coin dispenser with NDC+ and

Coin Dispenser 1

using a coin dispenser with Advance NDC are detailed in Table 1‐8.

Table 1-8
Coin Dispenser Differences

NDC+ Advance NDC

Supported a coin dispenser with four hopper types By default, Advance NDC is NDC+ compatible and
configured to support only four hopper types.
However, support for up to eight hopper types can be
set using Enhanced Configuration option 79

Supported a coin dispenser with a maximum dispense Supports the dispense of coins up to the maximum
of 25 coins reported by the hardware SP

Coins can be dispensed using the Display and Print Coins cannot be dispensed using the Display and Print
function function

Coins cannot be dispensed without notes Coins can be dispensed without notes; a cash
dispenser does not have to be present for a coin
dispense

A low condition is reported immediately, then the A low condition is reported at the end of the
transaction continues transaction

The STD COIN Supervisor option prints all counters The STD COIN Supervisor option prints the coin
before performing the CLR COIN, ADD COIN and counters before performing the CLR COIN, ADD
CHECK CDM Supervisor options COIN, and CHECK COIN Supervisor options

If no coin dispenser is configured, Advance NDC returns the same

message as NDC+ when running on an SST where a coin dispenser
is not present.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-62 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

The following table details which message types associated with

this device are handled differently by Advance NDC.

Table 1-9
Coin Message Types in Advance NDC

Message Message
Message Destination Differences
Class Sub-Class

1 1 Transaction Request Central If option 79 is set to 000, the message has the same
format as in NDC+ with field ‘r’ containing the
number of coins dispensed in the last transaction.

If option 79 is set to 001, the number of coins

dispensed is reported in the ‘ce1’ to ‘ce<n+1>’
fields (derived from buffer f) and field ‘r’ is set to
zero.

1 2 Device Fault Status Central If option 79 is set to 000, device fault status
2 2 Information information is sent for four hopper types.

If option 79 is set to 001, device fault status

information is sent for the number of hopper types
reported in the Hardware Configuration message.
A minimum of four hopper types are reported.

The Advance NDC message also reports hopper

type severities and the actual coins dispensed.

2 2 Send Configuration Central If specified, a Tamper and Sensor Status Data

Information Terminal message is returned for the coin dispenser. The
State Message information is extended, as shown in Tamper and
Sensor Status Data Terminal State below.

2 2 Send Supply Counters Central Using the command modifiers for Command
Terminal State Code ‘4’, it is possible to select the basic or
extended message format.

The basic message format is as NDC+ (command

modifier 1).

The extended message format differs from NDC+.

It allows the reporting of more than four hopper
types (command modifier 2).

2 2 Send Tally Information Central This is not supported in Advance NDC. For
Terminal State further information, refer to the Advance NDC,
Reference Manual.
2 2 Send Error Log Central This is not supported in Advance NDC. For
Information Terminal further information, refer to the Advance NDC,
State Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-63

Introducing Advance NDC
Differences Between Advance NDC and NDC+

Message Message
Message Destination Differences
Class Sub-Class

2 2 Hardware Central If enhanced configuration option 79 is set to 001,

Configuration Data the coin dispenser configuration data is extended
Terminal State from 2 to 7 bytes.
This provides additional information on the
number of hopper types and the maximum coins
per dispense.

2 2 Supplies Data Terminal Central Extended to allow the reporting of more than four
State hopper types.

2 2 Fitness Data Terminal Central Extended to allow the reporting of more than four
State hopper types.

2 2 Tamper and Sensor Central In field g2, the value of the sensor status is derived
Status Data Terminal from the XFS HRESULT.
State In field g3 (Tamper Indicator Identifier ‘B’) the
status of each Tamper Indicator is reported.
This field is always 13 bytes in length. Bytes 1‐7
are derived from XFS.
Bytes 8‐12 deal with the coin dispenser.
Byte 13 is always ‘0’, indicating DPM TI is not
present.
In field g4 (Extended Tamper Indicator Identifier
‘C’) the status of each extended Tamper Indicator
is reported.

4 ‐ Transaction Reply Terminal Extra fields for more than four hopper types are
used if option 79 is set to 001.

Printer Flags ‘;’ and ‘<’ are ignored by Advance

NDC.

3 1 Override Reserved Terminal This Customisation Data Command (Message

Screens Command Identifier ‘G’) is accepted, but the ‘Type D’
reserved screens are not used by Advance NDC. A
Ready 9 message is returned.

3 1 Configuration/ Terminal These Customisation Data Commands (Message

Enhanced Identifiers ‘3’ and ‘A’) are accepted. See the
Configuration “Configuration Parameters” section.
Parameters Load

From Advance NDC 3.03, voice guidance is supported, but differs

Digital Audio Service 1

significantly from the Digital Audio Service (DAS) added to NDC+

release 6.
The DAS provided a limited set of messages which could be sent in
transaction replies for account balances and general transaction
data. In Advance NDC, a full solution is offered, called Voice
Guidance, to assist visually impaired cardholders throughout

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-64 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

transactions. Support is provided for use of a text‐to‐speech engine

or recorded voice data.
The Audio Control State is not supported by Advance NDC.
An XML configuration file is used in Advance NDC to define the
audible echo of the keyboard instead of the Enable Audible Echo of
Keyboard configuration parameter.
Antex audio files cannot be played in Advance NDC, but
industry‐standard audio files that are supported by the Windows
Media Player can be used. For details, see “Recreating Audio Files”
on page 3‐5. Advance NDC also supports the use of third‐party
Text‐to‐Speech (TTS) software to render the audio messages.
The following table details which message types associated with the
DAS are handled differently by Advance NDC.

Table 1-10
DAS Message Types in Advance NDC

Message Message
Message Destination Differences
Class Sub-Class

4 ‐ Transaction Reply Terminal Two Printer Flags are supported for voice guidance. In
addition to Printer Flag ‘>’, supported in NDC+ as
“Annunciated Voice”, Printer Flag ‘w’ can also be used
to identify audio data for voice guidance.

3 1 Enhanced Terminal This Customisation Data Command (Message Identifier

Configuration ‘A’) is accepted, but the Enable Audible Echo of
Parameters Load Keyboard parameter is ignored. See “Configuration
Parameters” on page 1‐66.

Advance NDC handles the following state types differently from

State Types 1

NDC+:
 Close ‐ see “Document Processing Module” on page 1‐59
 Courtesy Amount Verification ‐ see “Document Processing
Module”
 DPM Document Accept ‐ see “Document Processing Module”
 Enhanced Amount Entry ‐ see “Document Processing Module”
 Audio Control State ‐ see “Digital Audio Service” on page 1‐64
 PIN Entry ‐ see “PIN Entry States” on page 1‐67
 Enhanced PIN Entry ‐ see “PIN Entry States”
 Card Read ‐ PIN Entry Initiation ‐ see “PIN Entry States”
 Smart FIT check ‐ refer to the APTRA Advance NDC, Reference
Manual, Chapter 12, ‘Smart Card Handling’

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-65

Introducing Advance NDC
Differences Between Advance NDC and NDC+

The following Configuration and/or Enhanced Configuration

Configuration Parameters 1

Parameters may be downloaded, but are ignored by Advance NDC:

 Card Read Error Threshold
 Card Write Error Threshold
 Timers:
— 70 (DASH ‘Remove Card’ Screen Delay Timeout is not
supported)
— 91 (In Service Inspection Timeout is not supported)
— 97 (Door Access Open Timeout is not supported)
 Diebold Status Reporting for Vandal Guard (Diebold is not
supported)
 Tamper Indication Control Option
 Extended Status Control Option
 Optical Sensor Option (CIM86 is not supported)
 Journal Printer Backup Log Tamper Option
 Touch Screen Error Reporting Option (Touch Screen errors are
not reported because, unlike S4, Self‐Service Support does not
support a proprietary Touch Screen device)
 Remote Status Indicators (RSI) and the Remote Relay option
(RSIs are enabled as described in “Remote Status Indicators” on
page 5‐19 and Remote Relay is not supported)
 TPA Informed of SM Activity Option (not applicable with
Self‐Service Support)
 Enable Audible Echo of Keyboard
 Non‐Magnetic Card Accept.

Report Card Data in Status Message 1

The following Enhanced Configuration Parameter options allow

card data to be included in status messages:
 Print Track 2 to Journal (option 37). As in NDC+, this option
allows the track 2 data to be printed. In Advance NDC, the
format of the printed information is defined using reserved
screen t15
 Send Track Details on Card Retract (option 41). In NDC+, this
option allowed all the data read from the card to be included in
the status message when a card jam occurred. In Advance NDC,
this option allows all the data read from the card to be included
in the status message when a card is retracted.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-66 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

Advance NDC handles Customisation Data Commands differently

Customisation Data from NDC+, as listed in the following table:
Commands 1

Table 1-11
Customisation Data Commands
in Advance NDC

Message Message
Message Destination Differences
Class Sub-Class

3 1 Diebold PIN Terminal This Customisation Data Command (Message Identifier

Information Load ‘4’) is accepted, however the downloaded data is not
stored because it is never used in Advance NDC. A
Ready 9 message is returned.

3 1 Override Terminal This Customisation Data Command (Message Identifier

Reserved Screens ‘G’) is accepted; the ‘Type D’ reserved screens are used
Command by Advance NDC for EMV Exits.

3 1 Configuration/ Terminal These Customisation Data Commands (Message

Enhanced Identifiers ‘3’ and ‘A’) are accepted. For details of
Configuration unsupported options, see the “Configuration
Parameters Load Parameters” on page 1‐66.

The following PIN Verification methods are not supported by

PIN Entry and Verification 1

Advance NDC:
 Local Diebold PIN Verification
 Local GBP PIN Verification
 Atalla PIN Verification
 Remote BANKSYS PIN Verification.

PIN Entry States 1

In Advance NDC, the numeric keypad must be used for PIN entry.
As a result of this, the following state types do not support the use
of the Touch Screen in Advance NDC:
 PIN Entry
 Enhanced PIN Entry
 Card Read ‐ PIN Entry Initiation.

PIN Block ‐ No Encryption 1

A value of 4 for the FIT field PINPD means no Encryption of the PIN
Block. This value is not supported in Advance NDC as it breaches
the use of Secure PIN Entry and results in the PIN being sent to the
Central application in clear text.
In Advance NDC, use of Secure PIN Entry means the PIN the
cardholder enters is not available to the application.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-67

Introducing Advance NDC
Differences Between Advance NDC and NDC+

Specifying a value of 4 for PINPD will result in the Cancel Next

State being taken in PIN Entry states.

The EPP in BAPE emulation mode is not supported in Advance

BAPE Emulation 1

NDC.

The following journal‐related features are not supported, or are

Electronic Journal and supported differently in Advance NDC.
Journal Printer Backup 1

Electronic Journal Log File Checksum 1

This feature is supported differently in Advance NDC.

In NDC+, when the Electronic Journal (EJ) was initialised (using the
INIT EJRNL Supervisor function) with an eight‐byte ASCII numeric
string (which acted as a checksum) added to the end of both the file
copied to diskette (ejxxxxxx.nnn) and the backup log file (ejrcpy.log).
This checksum was also logged at the start of the new journal log
file (ejdata.log).
In Advance NDC, this checksum feature has also been implemented
as part of the Electronic Journal functionality. However, the
checksum can be turned off using a registry setting. For details of
turning off the checksum, see “EJ Checksum” on page 5‐180.

Note: Adding a checksum results in a longer initialisation process

that increases with larger EJ files. For details of the INIT EJRNL
option, refer to the APTRA Advance NDC, Supervisor’s Guide.

EJ Log File Inspection (In Service Supervisor) 1

This feature is not supported in Advance NDC.

If the EJ was configured and the SST had a rear operator panel,
NDC+ supported inspection of the EJ log file and the copying of
sections of the log file to diskette (as DOS text) while the SST was in
any Mode. Additionally, copying sections of the log file to a printer
was supported while the SST was in Supervisor Mode.

Tampered Journal Records 1

This feature is not supported in Advance NDC.

If Journal Printer Backup was configured, NDC+ applied an
integrity check to all records passing through the Journal Printer
Backup disk buffer. If an integrity error occurred on a reprint
record, NDC+ supported several different courses of action (all
configured by the Journal Printer Backup Log Tamper Enhanced
Configuration Parameter) as follows:
a No action

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-68 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

b Printed the defective (‘tampered’) record, bracketed by >> and

<< characters
c Sent an unsolicited status message, including the last Security
Trace Number, its date and time stamp, and the record offset, to
the Central application
d In addition to option c, wrote the defective journal record to a
file on the system disk (up to ten defective records).
In the case of option d, subsequent access to these files used the
FREE JDATA Supervisor function, enabled or disabled by a
Terminal Command from Central.
This ‘tamper’ feature has not been implemented as part of the
Journal Printer Backup functionality in Advance NDC, as follows:
 No checks are made for ‘tampered’ reprint records
 No unsolicited status messages relating to this feature are sent to
the Central application
 The FREE JDATA Supervisor function has not been
implemented. However, if the Enable Free JData Terminal
Command is received from the Central application, it will be
handled by Advance NDC in the same manner as by NDC+.
Setting the associated Enhanced Configuration Parameter (22)
will have no effect on the system, as it will be ignored by
Advance NDC.

EJ File Format 1

This feature is supported differently in Advance NDC.

The EJ file contains the same printable characters as were logged
using NDC+. However, there may be additional Advance NDC
specific printer control codes present in the file.
In NDC+, the EJ file size was fixed at 1.44 MB. Advance NDC,
allows a file size to be set for the EJ of at least 1K. The maximum that
can be set is calculated using the available disk space. For details,
see “Maximum EJ File Size” on page 5‐180.
Advance NDC also does the following to the EJ log file:
 Adds an end date stamp
 Allows password protection and compression
 Allows compression without password protection.
If you have developed a tool to view the Electronic Journal file,
ensure that it ignores irrelevant control characters.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-69

Introducing Advance NDC
Differences Between Advance NDC and NDC+

The following Screen Data features are not supported by Advance

Screen Data 1

NDC:
 Set display mode control ‐ ignored, because the screen
resolution cannot be changed at runtime
 Voice ‐ Antex Audio files are not supported. Instead
industry‐standard Sound Blaster WAVE (.wav) and MIDI (.mid)
audio files can be used. For details, see “Recreating Audio Files”
on page 3‐5.
 Animation ‐ VGM.ani files and Autodesk FLIC (.fli or .flc)
animation files are not supported. Instead, Microsoft AVI (.avi)
movies and industry standard MPEG (.mpg) video/audio files
can be used. For details, see “Recreating Animation Files” on
page 3‐6.
The following screen resolutions are not supported:
 640 x 350 x 16
 320 x 200 x 256.
Advance NDC supports resolutions of 640 x 480 and above. For
details, see “Recreating Graphics” on page 3‐3.

In NDC+, screens K04, K05, and K06 were sent to the printers on exit
K Screens 1

from NDC+ to prepare for diagnostics.

In Advance NDC, these screens are not used. For details, refer to the
APTRA Advance NDC, Reference Manual.

No Diebold Emulation Mode Status messages are sent to the Central

Diebold Emulation Mode application because Advance NDC only supports NCR Native
Status Messages 1
Mode.

Advance NDC does not send Unsolicited/Solicited Device Fault

Status Messages 1

Status information messages for the following devices:

 Touch Screen Keyboard ‐ unlike S4, Self‐Service Support does
not support a proprietary Touch Screen device
 Document Processing Module ‐ device not supported. See
“Document Processing Module” on page 1‐59
 Door Access ‐ device not supported

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-70 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

Table 1-12
Status Message

Message Message
Message Destination Differences
Class Sub-Class

1 2 Card Reader/Writer Central The Transaction/Device Status values of ‘6’ to ‘9’ are
2 2 Device Fault Status not reported, because the CIM86 Card Reader is not
Information supported.
Similarly, the Error Severity is always one byte.
The Transaction/Device Status values of ‘1’ to ‘9’ and
also Supplies Status values ‘0’ and ‘4’ are not reported
if a contactless card reader is the primary card reader.

1 2 Secondary Card Central The Transaction/Device Status values of ‘1’ to ‘9’ and
Reader Supplies Status values ‘0’ and ‘4’ are not reported if a
2 2 Device Fault Status contactless card reader is the secondary card reader.
Information Advance NDC supports only a contactless card reader
as the secondary card reader.

1 2 Sensors Device Fault Central See “Document Processing Module” on page 1‐59.
Status Information

In NDC+, alarms and tamper indications were reported while in

Alarms and Tamper diagnostics.
Indication 1

Advance NDC does not report alarms and tamper indications while
in Vendor Dependent Mode (VDM). However, on NCR hardware,
Advance NDC does report alarms and tamper indications for cash
and coin dispensers on exit from VDM.
For the Cardholder Display Alarm, reporting of unsolicited
messages is controlled by option 32 of the Enhanced Configuration
Parameters Load message.
The sending of cardholder display status in Get Fitness responses
can be controlled by a registry setting.

The following Option Digits (specified in Supervisor mode) can be

Option Digits 1

entered but are ignored:

 Option Digit 3, Part B
 Option Digit 7, Part B.
Option Digit 7, Part C ‐ SOH reporting is handled differently by
Self‐Service Support compared to NDC+.
For details of Option Digits, refer to the APTRA Advance NDC,
Supervisor’s Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-71

Introducing Advance NDC
Differences Between Advance NDC and NDC+

Advance NDC does not use reserved screens M10, M11 and M13 to
Supervisor Mode 1

define key positions on the cardholder keyboard. Instead, Advance

NDC Supervisor mode uses the default keyboard layouts provided
in NDC+.
Instead of reserved screen M03, Advance NDC uses reserved screen
m03.
If you wish to change the key positions and return code, you can do
so using the TTU SP configuration for rear operator access or the
PIN SP configuration for front operator access.
The following Supervisor functions are not supported by Advance
NDC:

Table 1-13 Present in the Advance

Menu Options
Supervisor Functions Not Supported NDC Supervisor Menu?

Select Menu SET SW0 ‐ SET SW3 NO

CSOH 2
CSOH 3
TM‐ALERT

Replenish Menu DUMP IMAGES YES

Configure Menu VOLUME SST YES

VOLUME JACK

Access Menu INIT SUP SOH NO

INIT INS SOH
FREE JDATA

For details of the behaviour in Advance NDC of the unsupported

functions, refer to the APTRA Advance NDC, Supervisor’s Guide.

Communications 1

Advance NDC provides Supervisor menus for configuring CCM

VISA2 dialup or TCP/IP communications with Central. These
menus are accessed by selecting the required menu function on the
Configure menu.
If you wish to use CCM VISA2 dialup, or TCP/IP to communicate
with the host, refer to the APTRA Advance NDC, Supervisor’s Guide
for details of the TCP/IP and dialup configuration menus. For
additional communications configuration, see “Configuring
Communications” on page 5‐44.

Diagnostics 1

If you move the mode switch to Normal, then exit Diagnostics in

Advance NDC, the SST returns to In Service or Out of Service mode.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-72 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

In NDC+, this returned you to Supervisor mode.

Miscellaneous Functions 1

Advance NDC provides a Select menu item for Miscellaneous

Functions (‘MISC FUNCS’). The MISC FUNCS menu contains
options for journaling the EMV smart card application component
versions (‘PRNT CMPNT VERS’) and smart card hardware version
(‘PRNT SCRW VERS’), if present.

If the security flags are such that flag 1 is FALSE and flag 2 is TRUE,
Differences in MACing 1

a Message Authentication Code (MAC) value is expected at the end

of the following messages, but it is not checked:
 Transaction Reply
 Customisation Data State Tables Load Command
 Customisation Data FIT Data Load Command
 Customisation Data MAC Field Selection Load Command
 Dispenser Currency Cassette Mapping.
When security flag 1 is set to FALSE (do not check MAC in
incoming messages), no attempt is made to determine whether or
not a MAC exists in the message. When security flag 2 is set to
TRUE, this indicates that a MAC is expected. Do not use this
combination of security flags because the consequences are as
follows:
 Some invalid messages may be rejected with a different reject
status from before. This is not seen as an issue, as invalid
messages should not be sent to a live SST.
 Messages that are valid, but do not have a MAC attached when
one is expected, will be accepted. Previously such messages
would have been rejected.
In the Message Authentication Field Selection Load message, EMV
field offsets differ in that NDC+ used offset 35 and Advance NDC
uses offset 36. This means that you cannot use the same Message
Authentication Field Selection Load message if you wish to use
selective MACing on EMV ICC data with Advance NDC and NDC+
based terminals.

APTRA Communications Connection Manager (CCM) is used in

Communications Protocols 1

Advance NDC to support the following protocols for

communications:
 TCP/IP
 VISAII
 All protocols supported by the PCCM service except for IBM
3600 Loop communications.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-73

Introducing Advance NDC
Differences Between Advance NDC and NDC+

The Basic Operator Panel (BOP) is not supported by Advance NDC.

Basic Operator Panel Although the Supervisor interface has the same look and feel as in
(BOP) 1
NDC+, menus can only be displayed on the front interface or the
Enhanced Operator Panel (EOP).

In NDC+, the VGA Enhanced Operator Panel (VEROP) could be

VGA Enhanced Rear used in EOP emulation mode. However, Self‐Service Support does
Operator Panel (VEROP) 1
not support the VEROP in EOP emulation mode. Advance NDC
supports Enhanced Operator Panel (EOP), a Graphical Operator
Panel (GOP) or a Compact Operator Panel (COP).

In NDC+, the config.con file was needed to successfully display logos

Graphics 1

and pictures. The files used were the Gxx.pcx files

In Advance NDC, the config.con file is no longer required. The
names of the files required to successfully display logos and
pictures in Advance NDC are described in “Recreating Graphics”
on page 3‐3.
From Advance NDC 4.01, the .pcx format is no longer supported.
For compatibility, the pictures can still be defined as
<picture>.pcx in the screen definitions, but a supported file
format must be used for all graphic files on the SST.
From Advance NDC 4.01, the graphics files are Gxx.png files.

In NDC+, a single integrated security camera was supported with

Security Camera 1

two timers. Advance NDC can support up to 3 cameras at different

positions: person, exit slot and room. An XML file is used to
configure the flow points at which pictures can be taken. Each flow
point can obtain multiple images.
On the Replenish menu in Supervisor, the fill camera option is
renamed SECURITY CAMERA and provides the following options
for cameras:
 TEST CAMERA (NDC+ had the Fill Camera function for this)
 COPY SNAPSHOTS
 DELETE SNAPSHOTS.
The following table details which message types associated with the
security camera are handled differently by Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-74 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

Table 1-14
Security Camera Message Types
in Advance NDC

Message Message
Message Destination Differences
Class Sub-Class

2 2 Send Tally Information Central Tally information is not supported.

Terminal State

2 2 Send Error Log Information Central Error Log information is not supported.
Terminal State

In NDC+, a message was sent to the Central application (Message

Software Management 1

Class 4, Sub‐Class 1) giving information on the status of any

Software Management installation.
In Advance NDC, there is no interaction between Advance NDC
and the Software Management components running in the SST.
Therefore, Advance NDC will never send Message Class 4 to
Central and the Enhanced Configuration Parameter ‘TPA Informed
of SM Activity Option’ is not used.

In NDC+, a screen displayed during a State Type could optionally

Associated Keyboards 1

have had an associated keyboard definition, to let you define which

keys to enable and the return code for each key.
In Advance NDC, these associated keyboards are supported with
the following release restrictions due to service provider limitations:
 For Advance NDC 3.00 to 3.02, these associated keyboards were
ignored.
 From Advance NDC 3.03, associated keyboards are supported
for FDKs only. For further details, see “Associated Keyboards
for FDKs” on page 1‐29.

For information on the development histories of the Bunch Note

Bunch Note Acceptor Acceptor (BNA) and the Cheque Processing Module (CPM), see
(BNA) and Cheque “Advance NDC Development” on page 1‐15.
Processing Module (CPM) 1

The Bunch Note Acceptor (BNA), if present, is supported in

Advance NDC as follows:
 Additional information in various Terminal State Messages
 Terminal Command ‐ Retrieve Note Definitions
 Device Fault Status messages
 Configuration Parameters
 State Type ‐ Cash Accept State
 Additional fields in Transaction Request and Reply messages

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-75

Introducing Advance NDC
Differences Between Advance NDC and NDC+

 Three transactions ‐ two Encash functions and a Refund

transaction
 Changes to various Supervisor replenishment functions
 Specific Supervisor functions
 Changes to Start of Day
 CDI Stores.

Note: Refund functionality is not supported on SNA.

For details of using the BNA, refer to the following publications:
 APTRA Advance NDC, Supervisor’s Guide
 APTRA Advance NDC, Reference Manual.

In NDC+, you could not add new data fields to the Transaction
Transaction Request Request message.
Extension State 1

In Advance NDC, the Transaction Request Extension State has been

modified to allow you to add new data fields to the Transaction
Request message. For more details, see “Adding Data Fields to a
Transaction Request” on page 8‐18.

In NDC+, you could not define alternative fonts to those provided.

Font Definition 1

In Advance NDC, you can define alternative fonts to those provided

with Advance NDC. These alternative fonts can be third‐party
fonts, or fonts you have developed.
For more information, see Appendix D, “Font Definition”.

The following NDC+ designated character sets are not supported in

Character Sets 1

Advance NDC:
 ‘6’ (Customer Graphics 1)
 ‘8’ (Customer Graphics 3)
 ‘9’ (Customer Graphics 4)
 ‘<’ (Chinese 3)
 ‘=’ (Chinese 4)
 ‘@’ (Chinese 7)
 ‘A’ (Chinese 8).

To aid your understanding of the Advance NDC Customisation

Localising Advance NDC 1

Layer and Application Core, and the NDC‐specific workers

provided with Advance NDC, on‐line information in UK English is
available in the form of On‐line Help and Component Descriptions.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-76 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

You can translate the on‐line information if required. To learn how

to do this, refer to the APTRA Advance ADE, Local Language
Customisation Guide.
For details of the files which contain the on‐line information to be
translated, refer to the text files
<global>\Custom\CustomisationLayer\rt115_cust.txt and
<global>\Custom\ApplicationCore\rt116_cust.txt.

NDC+ sent unsolicited status messages immediately when the SST

Unsolicited Status was in In Service mode. With Advance NDC, unsolicited status
Messages 1
messages may also be sent at different times. In Advance NDC,
unsolicited messages are not always sent immediately, but at
defined points in the application. This difference does not cause
incompatibility issues for hosts.
You may find that some unsolicited status messages, which were
not sent in NDC+, are sent to Central in Advance NDC. For
example, if the currency dispenser shutter is jammed closed when a
present is attempted, Advance NDC sends a Suspend unsolicited
status message to Central. With NDC+, this Suspend message was
not sent.
In Advance NDC, unsolicited status messages are used to report
any change of condition at the terminal, as follows:
 Recognition of an external event
 Supplies problems
 Device errors.

Note: Unsolicited messages are not generally used to report

device errors at Start of Day. If required at this time, Central
must use Terminal Commands to query the current SST device
status.

NDC+ supported MPEG files through the hardware, but Advance

Multi‐Media File Support 1

NDC uses a proprietary implementation together with the

appropriate codecs installed on the SST to render multi‐media video
files such as AVIs, and MPEGs. On Windows, Windows Media
Player uses the DirectX interface for video rendering. For details of
formats supported on Windows, refer to the Microsoft article
“Windows Media Player Multimedia File Formats” (article ID
316992) at http://support.microsoft.com.

NDC+ supported up to 999 screens. From Advance NDC 2.06, up to

Number of Screens 9999 screens are supported.
Supported 1

From Advance NDC 4.02, the screen numbers defined in state tables
are extended from 000‐999 to 000‐Z99. The alphanumeric character

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-77

Introducing Advance NDC
Differences Between Advance NDC and NDC+

is mapped to a numeric value to allow the direct specification of

3599 screens. Applying language offsets allows all 9999 screens to be
referenced from the state tables if necessary. A configuration option
allows screen base and group sizes to be extended to increase the
available number of multi‐language screens.

The following differences exist between NDC+ screens and

Support for Screens 1

Advance NDC screens:

 Z screens — In NDC+, Z screens were used to display state of
health screens on the BOP. Advance NDC does not support the
BOP, so Z screens are not used
 X screens — In NDC+, X screens were used to display state of
health information on the EOP or front screen. In Advance
NDC, X screens are used for audio messages
 C05 screen — In NDC+, if a card jam occurred resulting in a
suspend condition, screen C05 and another ‘card could not be
read’ screen were displayed. In Advance NDC, only screen C05
is displayed in this situation.

In NDC+, the Set Display Mode control sequence could be used.

Set Display Mode Control
Sequence 1
Advance NDC does not support this control sequence.

In NDC+, passbook transactions were handled by the DPM.

Passbook Printer Support 1

Advance NDC does not support the DPM and does not provide a
runtime implementation for the passbook printer. Instead, passbook
printer worker classes are provided to enable the development of an
authored flow in the APTRA Author to support passbook
transactions.

In NDC+, you could set the Roll width and Left margin for journal
Roll Width and Left and receipt printers. In Advance NDC, these options are applied to
Margin 1
receipt printers only.

In NDC+, an envelope could only be dispensed using NDC State C

Envelope Dispensing 1

(Envelope Dispenser State).

In Advance NDC, if the NDC Envelope Dispenser state (state C) is
used, an envelope is dispensed.
In addition, the application uses registry settings to determine the
following envelope dispensing behaviour:
 Dispense an envelope during the Deposit and Print function if
NDC State C (Envelope Dispenser State) has not been used
(default Advance NDC behaviour).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-78 APTRA Advance NDC, Developer’s Guide

 Introducing Advance NDC
Differences Between Advance NDC and NDC+

 Do not dispense an envelope during the Deposit and Print

function. (NDC+ behaviour).

In NDC+, Remote Status Indicators were set using the envelope

Remote Status Indicators 1

dispenser status configuration option.

From Advance NDC 4.00 Remote Status Indicators handling
matches the Fault Display. For details, see the APTRA Advance NDC,
Supervisor’s Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 1-79

Introducing Advance NDC
Aggregate Building

Aggregate Building 1

Using the Aggregate Builder Tool (ABT), you have control over the
components to be installed on the development PC or the SST. For
information about the ABT, refer to the on‐line help provided with
the tool.

There is only one Advance NDC installable aggregate. The

Advance NDC Aggregate 1

aggregate provides the following installation options:

 Development
 Development and Simulation
 Runtime SST
 Documentation Only.
For details of the components in the Advance NDC Package, refer to
the APTRA Advance NDC, Overview.

You can customise the provided aggregate installation by using the

Customising Aggregates 1

Aggregate Builder Tool (ABT) on the development PC. For details,

see “Preparing a Modified Advance NDC Aggregate” on
page 11‐16.
You can also use the ABT to control the installation of components
on a development PC, using a similar process.

Using the Component Builder, you can build your own components
User‐Created Components 1

(for example, a custom presentation client) to add to an aggregate.

For guidance, refer to the Component Builder on‐line help.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1-80 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Installing Advance NDC on a Development PC

Chapter 2
Installing Advance NDC on a
Development PC

Overview 2‐1

System Requirements 2‐2

Supported Operating Systems 2‐2

Installation Process 2‐3

Before You Start 2‐3
Default Installation Folder 2‐3
Author User IDs 2‐3
Author On‐line Help 2‐3
Installation Types 2‐3
Combined Installer 2‐3
Runtime Only Installer 2‐4
Installing Advance NDC on a Development PC 2‐4
After Installation 2‐5
Custom Directory 2‐5
Working Directory for the APTRA Author 2‐5
Creating a Modified Aggregate for the SST 2‐6
De‐installing Advance NDC 2‐6

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Installing Advance NDC on a Development PC

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Installing Advance NDC on a Development PC
B

Overview

Overview 2

The Advance NDC package includes the Advance NDC product

together with other associated products.
This chapter provides additional information about installing
Advance NDC on your development PC and what to do after
installation.
For details of installing Advance NDC on an SST, see Chapter 11,
“Delivering an Advance NDC Aggregate to the SST”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 2-1

Installing Advance NDC on a Development PC
System Requirements

System Requirements 2

For details of the hardware required and prerequisite software for

your development PC, refer to the APTRA Advance NDC Overview
(PDF) which is available in the APTRA online documentation after
Advance NDC has been installed.
For last‐minute information refer to the appropriate release bulletin.

Windows operating systems are supported as follows:

Supported Operating
 Windows 7 32‐bit or 64‐bit, and Windows 10 64‐bit in both
Systems 2

development and runtime environments.

 POSReady 7 in runtime environments only.
For details of operating system support, refer to the APTRA Advance
NDC, Overview.
For more information about Advance NDC in a Windows 7 64‐bit
environment, see “Advance NDC on Windows 7 64‐bit and
Windows 10 64‐bit Systems” on page 11‐2.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

2-2 APTRA Advance NDC, Developer’s Guide

 Installing Advance NDC on a Development PC
Installation Process

Installation Process 2

Before installing the Advance NDC software, ensure you have

gathered all the information that you will require, as described in
the following sections.

If the development PC has Advance NDC 3.01 or earlier installed,

Before You Start 2

you must follow the instructions described in “De‐installing

Advance NDC” on page 11‐21.

Default Installation Folder 2

By default, the C:\NTGlobal folder will be used as the Advance

NDC global directory. You can change this location during
installation.

Author User IDs 2

If you want to add User IDs during installation, ensure that you
have the details ready before you begin the installation and use the
recommended format.
Before using the Author for the first time, you must set up at least
one User ID. This can be completed as the last step of installation, or
at a later time.
User ID Utility The User ID utility is used to create User IDs. For 2

details of this utility and reserved User IDs, refer to the APTRA
Author User’s Guide.

Author On‐line Help 2

On Windows 7, you must install the Windows Help program

(WinHlp32.exe) as described at
http://www.microsoft.com/en‐us/download/details.aspx?id=91 to
view the on‐line help.
On Windows 10, the Windows Help program is not supported. So,
the Author On‐line Help is not available for Windows 10.

Two installers are provided with Advance NDC, the Combined

Installation Types 2

installer, which contains all installation types, and the Runtime

Only installer for SSTs, which is a smaller alternative to the
Combined installer.

Combined Installer 2

The combined installer offers the following installation methods in

the Target Environment window:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 2-3

Installing Advance NDC on a Development PC
Installation Process

 Runtime SST
 Development and Simulation

Note: The following options are also listed:

— Development. This is the same as the Development and

Simulation option
— Simulation. NCR recommends that the Simulation option is
not used.
 Documentation Only.
For information about the components that are installed on the
development PC or SST, refer to the APTRA Advance NDC Overview
(PDF), which is available in the APTRA online documentation or in
the root directory of the CD‐ROM.
Runtime SST For the SST, select the Runtime SST option. 2

Development and Simulation For the development PC, the 2

Development and Simulation option provides the same

functionality as the Development option, and also allows you to run
simulations of your developments.
Documentation Only To see the documentation before installing 2

the Advance NDC software, select the Documentation Only option.

This will install all the documentation for Advance NDC and other
components in the Advance NDC aggregate. You do not need to
de‐install the documentation before installing the software.

Runtime Only Installer 2

The Runtime Only installer provides an alternative method of

installing on an SST. It installs the runtime version of Advance NDC
without offering a choice of installation types. For details of using
the Runtime Only installer, see Chapter 11, “Delivering an Advance
NDC Aggregate to the SST”.

Installing Advance NDC on a development PC for the first time is

Installing Advance NDC like installing any software package on Windows operating system.
on a Development PC 2

Caution: If you have an installation of Advance NDC 3.01 or earlier, this must
be removed first. For details, refer to “De‐installing Advance NDC”
on page 11‐21.

To install Advance NDC, perform the following steps:

1 Insert the APTRA Advance NDC Package CD‐ROM into the
CD‐ROM drive of the development PC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

2-4 APTRA Advance NDC, Developer’s Guide

 Installing Advance NDC on a Development PC
Installation Process

2 Run the setup.exe file located in the root directory and follow the
on‐screen instructions for the installation type you require.

The other choices on this screen allow you to do the following:

 Read the APTRA Advance NDC Overview (PDF)

 Read the release bulletins.

3 After installation is complete, read and follow the instructions in

“After Installation” on page 2‐5.
The Silent Debug utility and the DebugLog tool are installed with
Advance NDC. For further information on troubleshooting utilities,
see Chapter 12, “Installing and Configuring Troubleshooting
Tools”.

After you have successfully installed Advance NDC on your

After Installation 2

development PC, you need to set up required files and folders to

use the Aggregate Builder Tool and/or the APTRA Author for any
modifications you intend making to the Advance NDC application
supplied in the Advance NDC Package.

Custom Directory 2

The custom directory contains your DLLs and any other modified
files and can be created anywhere within an APTRA component
directory.
Any folder containing _comp.ini is recognised by the ABT as an
APTRA component directory.
You must create the custom.ini file, which is used to locate new files
or registry settings to update the supplied application. All registry
entries and source and target file names are held in the custom.ini
file.
For details, see “Preparing a Modified Advance NDC Aggregate”
on page 11‐16.

Working Directory for the APTRA Author 2

To use the APTRA Author, you need to create a working directory

to store your projects and generate a final build. For details, refer to
the APTRA Author, User’s Guide.
For information on the Advance NDC application flow and testing
the applications in the Author, see Chapter 7, “Introducing the
Advance NDC Authored Applications”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 2-5

Installing Advance NDC on a Development PC
Installation Process

Creating a Modified Aggregate for the SST 2

You can modify the software to create an aggregate using the

Aggregate Builder Tool. For more information, see Chapter 11,
“Delivering an Advance NDC Aggregate to the SST”.

If you want to re‐install Advance NDC, you must first remove the
De‐installing Advance existing Advance NDC installation and any associated software that
NDC 2
has been installed separately.
If you re‐install Advance NDC to the same location, it overwrites
most of the contents of the Advance NDC directories, so you need to
take copies of any files you wish to keep. Complete the following
steps:
1 If you have carried out any development under the root
directory of Advance NDC (default name is <drive>:\ntglobal), or
have changed any files under it, back up the development or
changed files.

2 In the Windows Control Panel, use Add or Remove Programs to

first remove any Advance NDC service pack, then the Advance
NDC components. Files created after the installation of Advance
NDC, such as custom.dat, user ID files and CDI data files, will
not be deleted. It is up to you to keep or delete them.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

2-6 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Migrating Existing NDC+ Applications to Advance NDC

Chapter 3
Migrating Existing NDC+
Applications to Advance NDC

Overview 3‐1

Executing an Entire NDC+ Download 3‐2

Changes Required 3‐2

Recreating Graphics 3‐3

Cardholder Graphics 3‐3
Logo Control 3‐3
Picture Control 3‐3
Display Image Files Control 3‐4
Load Graphics 3‐4

Recreating Audio Files 3‐5

Recreating Animation Files 3‐6

Changing RESRVD.DEF 3‐8

Recreating Communications Template Files 3‐9

Proving the Download Works 3‐10

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Migrating Existing NDC+ Applications to Advance NDC

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Migrating Existing NDC+ Applications to Advance NDCC

Overview

Overview 3

This chapter guides you through the migration of an existing NDC+

application to Advance NDC.
This chapter provides information on:
 How to migrate an NDC+ download, including the creation of:
— Graphics files
— Audio files
— Animation files
— Reserved screens
— Communications Template files
 Proving the download works.

Note: Advance NDC supports Display Manager, which provides

support for HTML screens, including images and video, and
Advance NDC display for a variety of multi‐media formats on the
cardholder display.
For information on migrating existing NDC+ Exits, refer to the
APTRA Advance NDC, Extending the Product publication.
For information on screen formatting in Advance NDC, refer to
Chapter 3, “Screen Data” in the APTRA Advance NDC, Reference
Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 3-1

Migrating Existing NDC+ Applications to Advance NDC
Executing an Entire NDC+ Download

Executing an Entire NDC+

Download 3

Migrating an existing NDC+ application to Advance NDC may

require some changes, which are summarised in this section.
The Customisation Layer handles the download and execution of
NDC+ customisation data (States Types, Screen Data, Printer Data,
Configuration Parameters and Financial Institution Tables). There
is no need for you to make any authoring changes using the
APTRA Author.

Note: If you want to familiarise yourself with the application flow,

you can do so using the Author. See Chapter 7, “Introducing the
Advance NDC Authored Applications”. If you intend enhancing
the Customisation Layer, see Chapter 8, “Modifying the
Customisation Layer”. To enhance the Application Core, see
Chapter 9, “Enhancing the Application Core or Supervisor”.

To successfully run your Customisation Layer application, you may

Changes Required 3

need to recreate or migrate certain files, as described in the

following table, which contains links to the relevant sections in this
chapter:

Table 3-1 To... See...

Help for Recreating or Migrating Files
Recreate graphics files “Recreating Graphics” on page 3‐3

Recreate audio files using new “Recreating Audio Files” on

tools page 3‐5

Recreate animation files using “Recreating Animation Files” on

new tools page 3‐6

Recreate communications “Recreating Communications

template files Template Files” on page 3‐9

Edit resrvd.def if you have made “Changing RESRVD.DEF” on

changes to it page 3‐8

Migrate Exits used in your NDC+ APTRA Advance NDC, Extending

application the Product

After carrying out the relevant changes, you can proceed to

“Proving the Download Works” on page 3‐10.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

3-2 APTRA Advance NDC, Developer’s Guide

 Migrating Existing NDC+ Applications to Advance NDC
Recreating Graphics

Recreating Graphics 3

Advance NDC does not support the 640 x 350 and 320 x 200 screen
resolutions used in NDC+. Advance NDC only supports screen
resolutions of 640 x 480 and above.
If you have created your own graphics for display in NDC+, you
may need to recreate them. If you try to display one of your current
NDC+ graphics using Advance NDC, the vertical dimension of the
graphic, as displayed on the screen, will be reduced by
approximately 28%.
After recreating your own graphics, copy them to your custom
directory. This includes them in the aggregate when you export it
from the Aggregate Builder Tool. For further information on the
custom directory and building a new aggregate, see “Preparing a
Modified Advance NDC Aggregate” on page 11‐16.
Although you need to recreate your graphics, download screens do
not usually require any changes, as the same screen controls as in
NDC+ are supported (or ignored if not supported; for example, the
‘Set Display Mode Control’ is ignored if sent).

To take account of the different screen resolutions supported, the

Cardholder Graphics 3

Screen Type ‘G’ cardholder graphics (G00, G01 and G03‐G06)

supplied with NDC+ have been recreated. For more information,
refer to the APTRA Advance NDC, Reference Manual.
The provided graphics are located in the <global>\final\xfs\dll
directory.
Copy the required graphics to your custom directory. This includes
them in the aggregate when you export it from the Aggregate
Builder Tool for installation on an SST.

Logos must have a file name of the format logoxx.yyy, where xx is

Logo Control 3

the two digit number representing the logo (for example, 00) and
yyy is its file extension.
For details of the supported file formats, search for “Picture and
Animation File Formats” in the APTRA Author online help.

Pictures must have a file name of the format picxxx.yyy or

Picture Control 3

picxxxx.yyy, where xxx/xxxx is either a three or four‐digit number

representing the picture and yyy is its file extension (for example,
pic001.yyy or pic0001.yyy).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 3-3

Migrating Existing NDC+ Applications to Advance NDC
Recreating Graphics

Although in NDC+ pictures could be referenced by a number of

between one and three or four digits, Advance NDC requires that
the file name has three or four digits, with leading zeros if
necessary, and displays the picture if found. For example,
pic020.yyy. You do not need to modify the screen definitions. A
screen definition of ESC ‘P’ 2 20 ESC ‘\’ will display the file
pic020.yyy. However, if the file name with three digits is not found,
Advance NDC searches the file name that has four digits, with
leading zeros if necessary, and displays when found. For example,
pic0020.yyy.
When the picture referenced is a four digit number, Advance NDC
searches for the file name that has four digits and displays the
picture if found. For example, pic1120.yyy. A screen definition of
ESC ‘P’ 2 1120 ESC ‘\’ will display the file pic1120.yyy.

For details of the supported graphics file formats, search for

“Picture and Animation File Formats” in the APTRA Author online
help.

An AVI file‐name prefix must not exceed eight characters, that is,
Display Image Files the name must conform to the 8.3 format (<filename>.avi).
Control 3

The default path for an image file is C:\Program Files\NCR

APTRA\Advance NDC\Media.
To display image files, the path of the image in the screen definition
command is:
3 FS FS FS 11 FS 010 FF ESC PEC:\G01.png ESC \
In runtime mode (default), if the image name is provided in the
command, then it is picked from the path C:\Program Files\NCR
APTRA\Advance NDC\Media and in a Development and Simulation
mode, the path is C:\NTGlobal\Final\XFS\Dll.

Advance NDC supports the display of new graphics without

Load Graphics 3

restarting the application. So, if any media file is changed, the

updated media file is displayed immediately without restarting the
application or sending the download again.
If a file is copied with the same name but with a different extension,
the display will be based on the alphabetical order of the file
extension. For example, if XXX.jpeg is available and XXX.png is
copied, the XXX.jpeg file is displayed as the file with JPEG extension
takes precedence over the PNG extension.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

3-4 APTRA Advance NDC, Developer’s Guide

 Migrating Existing NDC+ Applications to Advance NDC
Recreating Audio Files

Recreating Audio Files 3

Advance NDC does not support NCR’s proprietary Antex audio

board. Therefore, Antex audio files cannot be played in Advance
NDC.
Instead audio files with the appropriate codec installed on the SST,
and any installed text‐to‐speech software, are supported.
The same host (Central) interface for playing audio is supported. As
in NDC+, a screen control results in an audio file being played.
The following table identifies how Advance NDC handles playing
audio files compared with NDC+.

Table 3-2 NDC+ Advance NDC

Audio File Handling in Advance NDC and
NDC+ Number of standard 10 Antex audio files 10 WAVE/MIDI
messages provided audio files (same
messages as in
NDC+)

Screen control plays a ‘xx’ or ‘xxx’ ‘xx’ or ‘xxx’

message identified by
a number

Audio file format daudioxx.msg or daudioxx.yyy or

(where ‘xx’ or ‘xxx’ daudixxx.msg daudixxx.yyy
maps the file to a (see step 1)
message number)

To play message number ‘xx’ or ‘xxx’, you need to do the following:

1 Re‐record or save the audio file as a .wav or .mid file.

Note: The file must follow the same fixed naming convention
used in NDC+. That is, daudioxx.yyy or daudixxx.yyy, where xx
or xxx is the message number and yyy is wav/mid.

2 Copy the file to your custom directory.

By following the file format, file name convention and directory
location specified, the audio files will be included in the aggregate
when you export it from the Aggregate Builder Tool. For
information about using the Aggregate Builder Tool with Advance
NDC, see “Aggregate Building” on page 1‐80.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 3-5

Migrating Existing NDC+ Applications to Advance NDC
Recreating Animation Files

Recreating Animation Files 3

Advance NDC does not support proprietary VGM .ani animation

files, or Autodesk FLIC (.fli or .flc) animations.
File formats such as Microsoft AVI (.avi) movies and
industry‐standard MPEG (.mpg) video/audio files are supported.
Other file formats such as animated GIFs are supported only if they
use the codecs that are supplied with Windows and which are
enabled by default on the SST. For more information about the
various supported file formats, refer to the following:
 Chapter 3, “Screen Data” in the APTRA Advance NDC Reference
Manual
 “Picture and Animation File Formats” in the APTRA Author
online help.
Supported Codecs The codecs which are supplied with Windows 3

and enabled by default are only supported. If you wish to use a

third party codec or enable a codec, which is supplied with
Windows but not enabled by default, please contact NCR FSE
Product Management.

Note: There is a system‐imposed limit on the number of AVI files

that can be used. For further information, see “AVI System Limit”
on page 5‐156.

The same host (Central) interface for playing animations is

supported. As in NDC+, a Picture control or Display Image Files
control can be used to display an animation file.
The following table identifies how Advance NDC handles
displaying animation and video files compared with NDC+.

Table 3-3 NDC+ Advance NDC

Video File Handling in Advance NDC and
NDC+ Control displays a ‘x’ ‘x’
picture (animation)
identified by a
number

Mapping between config.con A fixed mapping

picture (animation/ convention is used
video) file and picxxx.yyy
number is specified (see step 1)
by (Picture control
only)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

3-6 APTRA Advance NDC, Developer’s Guide

 Migrating Existing NDC+ Applications to Advance NDC
Recreating Animation Files

To display an animation or video file with number ‘xxx’, complete

the following:
1 Create the animation or video in a supported file format.

Note: 1. To display an animation or video file using a Picture

Control sequence, Advance NDC requires that the file name has
three digits, with leading zeros if necessary, for example,
pic020.avi.

Note: 2. If the animation is played using the Display Image Files

control, no mapping is required.

2 Copy the file to your custom directory.

By following the file format, file‐name convention and directory
location specified, the animation or video file will be included in the
aggregate when you export it from the Aggregate Builder Tool.
For information about using the Aggregate Builder Tool with
Advance NDC, see “Aggregate Building” on page 1‐80.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 3-7

Migrating Existing NDC+ Applications to Advance NDC
Changing RESRVD.DEF

Changing RESRVD.DEF 3

If you have made any changes to the RESRVD file in NDC+, you
will need to re‐apply these changes to the resrvd.def file in Advance
NDC.

Note: The resrvd.def file must not contain any TAB characters. Use
the SPACE character instead.

To apply changes without editing the supplied resrvd.def file, do the

following:
1 Create a file that uses the same format as the resrvd.def file, but
which contains your changes

2 Create the following registry entry with the name of your file as
the data:
HKLM\SOFTWARE\NCR\Advance NDC\supervisor\
UseAdditionalReservedScreenFile

Valid values are blank for no additional reserved screen file, or the
name of the file, for example resrvd.4012.
The supplied resrvd.def file will be loaded, and then any additional
file is loaded. If any screens are duplicated in the additional file, the
original version is overwritten.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

3-8 APTRA Advance NDC, Developer’s Guide

 Migrating Existing NDC+ Applications to Advance NDC
Recreating Communications Template Files

Recreating Communications
Template Files 3

When an SST running NDC+ software was installed in a network,

its communications had to be configured before it could
communicate with Central.
The communications service was configured by creating a
communications template file (CTF) using the NCR
Communications Template Generator. The communications
template file contained protocol‐dependent configuration
parameters.
One of the parameters you defined in the CTF was the name of the
connection to use when sending messages to and receiving
messages from Central. Although NDC+ did not know the name of
the connection specified in the CTF, it was able to communicate
with the Central application using an alias name of
‘COMMUNICATIONS’.
Owing to the differences in the way Self‐Service Support handles
communications compared with S4, the alias name
‘COMMUNICATIONS’ cannot be used in Advance NDC. Instead,
the Application Core uses the connection name ‘TPA
CONNECTION’. This means when you create your CTF, you must
define the name of the comms connection as ‘TPA CONNECTION’.
For details of creating a CTF for use by an SST running Advance
NDC, refer to the APTRA Communications Feature, User’s Guide.

Note 1: If the name you specify in the CTF for the connection is not
‘TPA CONNECTION’, a communications link will not be
established.

Note 2: If you are using TCP/IP communications, you will not need
to recreate your CTF as TCP/IP communications configuration is
performed using the TCP/IP Configuration menus in Supervisor
mode. For details, refer to the APTRA Advance NDC, Supervisor’s
Guide.

For information about registry and other settings that can be

modified for communications, see “Configuring an Advance NDC
Application” on page 5‐14.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 3-9

Migrating Existing NDC+ Applications to Advance NDC
Proving the Download Works

Proving the Download Works 3

After you have made the necessary changes to migrate graphics,

audio and animation files and NDC+ Exits, you may want to install
Advance NDC on an SST to confirm that it works correctly with
your NDC+ download.
For details of how to install an Advance NDC application on an SST,
see Chapter 11, “Delivering an Advance NDC Aggregate to the
SST”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

3-10 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Upgrading from Earlier Releases of Advance NDC

Chapter 4
Upgrading from Earlier Releases of
Advance NDC

Overview 4‐1

Modularisation and the Single Executable 4‐2

New Authored States 4‐2
SSDS DLL Interface Worker 4‐3
New Application DLLs 4‐3
DLLs for Authored State Types 4‐3
DLLs for Non‐authored State Types 4‐4
DLLs for Transaction Reply Functions 4‐4
DLLs for the Cash‐In Component 4‐4

Feature Support 4‐6

Changes to the Interface since Release 2.6 4‐6
ADI2 to CEN‐XFS 4‐6
Advance NDC and Updates for Security for APTRA 4‐7
Communications 4‐8
RSA Initial Key Loading 4‐8
Additional BNA Functionality 4‐8
Enhanced Night Safe 4‐8
Enhanced Configuration Parameters Load 4‐8
BAPE Emulation 4‐9
EMV C Exits 4‐9
Keyboard Data 4‐9
Supervisor Menus 4‐9
Fault Display 4‐10
User Messages and User Terminal Data Implementation 4‐10
APTRA Simulator 4‐10
EMV on Contactless Card Readers 4‐11

Upgrading Your Release of Advance NDC 4‐12

Authored Customisations 4‐12
Customisations in the Customisation Layer 4‐12
Worker Class Support 4‐13
C Exits 4‐13

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Upgrading from Earlier Releases of Advance NDC

EMV/CAM2 Exits for APTRA Advance NDC 4‐13

Cardholder Screen Display 4‐14
Device Access 4‐14
Supplies Data Sources 4‐16
Fitness Data Sources 4‐17
Message Handling 4‐18
User Messages and User Terminal Data 4‐19
Printing 4‐20
Printer Variants 4‐20
Receipt Printer 4‐21
Journal Printer 4‐22
STCONT File Updates 4‐23
Promote Campaigns 4‐24

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC D

Overview

Overview 4

Prior to Advance NDC 2.05, the Supervisor functionality was

contained in the Application Core, and two separate authored
executables were provided that formed the Advance NDC runtime.
From Advance NDC 2.05, Advance NDC consisted of three
authored applications: the Customisation Layer, the Application
Core, and a separate Supervisor application containing all the
Supervisor functionality from the Application Core.
With the move to the CEN‐XFS interface, the structure of the
Advance NDC application did not change and wherever possible,
existing functionality remained unchanged.
From Advance NDC 3.03, the applications have been further
simplified, particularly the Customisation Layer, through the
following:
 Modularisation of state types
 Modularisation of reply functions for the Transaction Request
state type
 The introduction of a single executable replacing the three
executables previously supplied.

Note: The three authored projects are still supplied with

Advance NDC.

The objectives are to reduce the work required to re‐implement or

re‐apply customisations, and help simplify maintenance.
This chapter describes the differences you need to be aware of when
upgrading your Advance NDC installation from an earlier version,
as follows:
 Modularisation
 Feature support
 Device access and data sources
 Message handling and printing
 Configuration
For more information about the structure of Advance NDC, see
Chapter 1, “Introducing Advance NDC”.
For information about configuration of Advance NDC see
Chapter 5, “Configuring Advance NDC and Associated
Components”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-1

Upgrading from Earlier Releases of Advance NDC
Modularisation and the Single Executable

Modularisation and the Single

Executable 4

If you have customised previous versions of Advance NDC using

the APTRA Author, the move to a single executable and
modularisation of state types will affect you. However, the benefits
will be clear in future Advance NDC releases and updates, as they
will be simpler to incorporate into your application.
Prior to Advance NDC 3.03, three application executables were
released: ApplicationCore.exe, CustomisationLayer.exe and
Supervisor.exe. When a product update or new version was released,
the impact to users of the product varied depending on the level of
customisation they had already performed on the various authored
projects, with customisations being re‐applied to the updated or
new version to ensure nothing was lost.
Any product update to the Customisation Layer meant users had to
rebuild the whole of the application to pick up any change, unlike a
C++ code change, which was, and is, provided as an updated DLL in
a service pack. An updated DLL has minimal impact on customised
versions of Advance NDC as the only integration required is
configuration to ensure the appropriate versions of DLLs are
present in the system.
With the adoption of the modularised approach a single executable
is provided, ApplicationCore.exe. The other two are now application
DLLs. As the state types have also been separated from the
Customisation Layer into application DLLs, a small author project
containing the updated state type can be delivered. A decision can
then be made if the authored update affects any existing
customisation. If no change is required, the DLL can be delivered to
the SST like a C++ update.
If an authored update is required, the affected state type is updated
(or customisations are re‐applied to it), re‐built and delivered to the
SST. Any changes are local to the area of customisation, and
therefore have a smaller re‐implementation impact. Only changes to
the Author worker class interface, such as new workers or changes
to attributes, require all application DLLs to be built again.

Prior to Advance NDC 3.03, when a new authored state was added,
New Authored States 4

the Customisation Layer project had to be updated to directly

reference the Authored state type. Now the NDC Processing State
Executor is used to execute a state type through the SSDS DLL
Interface worker.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-2 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Modularisation and the Single Executable

The SSDS DLL Interface worker has always been used to split up
SSDS DLL Interface large authored applications, by adding a Director as the Top Worker
Worker 4
in an application and building a Final application.
The application DLL can then be referenced in the original
application by the SSDS DLL Interface worker, which loads and
executes the DLL as if it were still part of the application.
This principle provides the basis of the state type modularisation
with a modification to the SSDS DLL Interface worker, and the
addition of an attribute called Application Link. This allows each
application‐related state type in the Customisation Layer to be an
application DLL, loaded and executed by the SSDS DLL Interface
worker.

Separate application DLLs have been created for the following:

New Application DLLs 4

 Suspend mode, which has functionality shared between the

authored states
 Cardholder session
 Supervisor session
 Each of the authored state types and transaction reply functions
(listed below)
 The cash‐in component (listed below).

DLLs for Authored State Types 4

The top‐level director of each of the authored state types is now the
top worker of an application. Each application has been built to
produce the DLL, FRF, and STR files required to be referenced by
the SSDS DLL Interface worker. The following, state‐type
application DLLs are provided:
 Card Read states (state types A and T)
 Card Insert (z008)
 PIN Entry states (B and M)
 Customer Selectable PIN (b)
 PIN And Language Select (m)
 Close (J)
 Transaction Request (I)
 Cheque Accept (w)
 Smart FIT Check (k)
 Envelope Dispense (C)
 Card Write (L)
 Camera Control (N)
 Cardholder Authorised Verification (O)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-3

Upgrading from Earlier Releases of Advance NDC
Modularisation and the Single Executable

 Barcode Read (&)

 Web Exit (user‐defined)
 Prepare Dispense (z024)
 Card Eject State (z026)
 Local Cash Dispense State (z010)
State type DLLs are initiated from the STCONT file and executed
using the NDC Processing State Executor worker, For details of the
changes to STCONT, see “STCONT File Updates” on page 4‐23 and
refer to the APTRA Advance NDC, Extending the Product publication.

DLLs for Non‐authored State Types 4

The below application DLLS are not implemented in the author:

 Data Copy and Compare state (z013)
 Cash Deposit Handling state (z014)
 Note Mix Selection state (z017)

DLLs for Transaction Reply Functions 4

The Transaction Request state type has had all its reply functions
modified to reference a DLL for each reply function containing the
implementation, as follows:
 Deposit And Print
 Dispense And Print
 Display And Print
 Print Immediate
 Next State and Print
 Night Safe Deposit
 Parallel Eject/Dispense and Print (Fast Cash)
 Card Before Cash
 Card Before Dispense and Print
 Print Statement and Wait
 Print Statement and Next State
 Process Cheque

DLLs for the Cash‐In Component 4

The cash‐in component also has a set of application DLLs, as

follows:
 BNA Start of Day
 BNA Event Monitor
 BNA Close State
 BNA Reconfigure Cassettes

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-4 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Modularisation and the Single Executable

 BNA Tamper Indication

For details of the registry settings for the transaction reply
functions, cash‐in component, cardholder session and supervisor
session, see “Registry Entry for Application Links” on page 5‐14.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-5

Upgrading from Earlier Releases of Advance NDC
Feature Support

Feature Support 4

This section describes changes in the implementation, functionality

or operations of features compared to earlier versions of Advance
NDC. For details of differences that apply only on other vendor’s
SSTs, refer to the APTRA Advance NDC, Multi‐Vendor Support
Reference Manual.

Devices that were previously accessed through ADI2 or CEN‐XFS 2

Changes to the Interface are now accessed through the CEN‐XFS 3 interface.
since Release 2.6 4

The content of messages is derived from the XFS data and mapped
to the equivalent NDC message. In cases where an exact match is
not possible, the closest compatible message is generated.
Access to the BNA device was through ActiveX, but now the
ActiveXFS interface is used. Access to the CPM device was through
ActiveX, but now the CEN‐XFS interface is used. Access to the
drives and cardholder display is still through the operating system.

ADI2 to CEN‐XFS 4

In Advance NDC 2.06, the following devices were accessed through

ADI2:
 Swipe Reader
 3 Track Write Reader
 Spray Dispenser
 Alarms
 Night Safe Depository
 Statement Printer
 Encryptor.
In Advance NDC 2.06, the following devices were accessed through
CEN‐XFS 2. Prior to Advance NDC 2.06, they were supported
through ADI2:
 MCRW Tk123
 Smart MCRW
 Dip
 Smart/DIP Card Readers (without smart functionality)
 Cardholder and Operator Keyboards
 Cash Dispenser
 Envelope Dispenser and Depository
 Receipt Printer

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-6 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Feature Support

 Journal Printer
 TI Bins (Alarms)
 System Display
 Media Entry Indicators.
In Advance NDC 3.00, the device access changed to CEN‐XFS 3.
For details of access to all devices in Advance NDC, see “Device
Access” on page 4‐14.

Advance NDC and Updates for Security for APTRA 4

From APTRA Advance NDC 2.6, all files created at runtime,

including the EJ and hardcopy backup files, are located in
C:\Program Files\NCR APTRA\Advance NDC\Data to allow
read/write access under Security for APTRA. The c:\ssds folder has
been maintained for backward compatibility, but is not used by
Advance NDC.
The following table gives details of the files that have been moved to
C:\Program Files\NCR APTRA\Advance NDC\Data.

Table 4-1 Previous Path and Filename Description

Advance NDC File Locations
C:\pmdata\pmpageentry Persistent memory file

C:\windows\system32\custom.dat NDC download backup

file

C:\keystore.txt Security related files

C:\keystore.tmp

C:\FONTDEFS.INI Font related files

C:\FONTDEFS.TXT

C:\windows\system32\NDCDATAA.DAT System settings backup

C:\windows\system32\NDCDATAD.DAT files

C:\ssds\apps\ERJCPY.LOG Journal related files

C:\ssds\apps\ERJCPY.IDX
C:\ssds\apps\EJDATA.LOG
C:\ssds\apps\EJDATA.IDX
C:\ssds\apps\HBDATA.LOG
C:\ssds\apps\HBDATA.IDX

C:\windows\system32\ucdiini.txt User defined storage

C:\windows\system32\ucdipers.dat files

C:\ndcrcpt resrvd.def K07 screen

See Note 1:

C:\frontimg.bmp resrvd.def C07 screen

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-7

Upgrading from Earlier Releases of Advance NDC
Feature Support

Note 1: This is the path for printer graphic file images. It is not
defined in resrvd.def for Advance NDC so that printer driver
defaults are used.

In Advance NDC, the default setup for communications is TCP/IP,

Communications 4

which is configured through the Supervisor Access menu. For

PCCM, or CCM VISA2 dialup communications, the registry must be
edited. For details of all registry keys for communications, see
“Configuring Communications” on page 5‐44.

In Advance NDC 2.06, support for RSA encryption was introduced.

RSA Initial Key Loading 4

On SSTs with an EPP, the initial encryption keys (A key, B key and
V key) can be downloaded from Central using RSA encryption
instead of being entered locally in Supervisor mode.
Before using RSA encryption, the Host Security Module (HSM) on
the host and the EPP on the SST must perform an authentication
process that meets the requirements described in the APTRA
Advance NDC, Reference Manual in Chapter 11, “Security Features”.

From Advance NDC 3.00, as well as including transaction counts in

Additional BNA the Transaction Request message, option 45 of the Enhanced
Functionality 4
Configuration Parameters Load is used to configure the following:
 Reporting of retract operations
 Number of notes to accept (up to 90 or more than 90)
The reporting of individual cassette status through an extended
message format is included from Advance NDC 3.01.
From Advance NDC 4.01, you can choose whether to handle a
Suspend condition as a Fatal condition or a Suspend condition. If
you require compatibility with earlier releases, you must handle a
Suspend condition as a Fatal condition

In Advance NDC 2.06, the enhanced night safe was supported.

Enhanced Night Safe 4

In versions 3.0 to 3.02, the enhanced night safe was not supported,
as the variant information was unavailable.
From Advance NDC 3.03 support for the enhanced night safe is
included.

Enhanced Configuration Parameters Load messages are handled as

Enhanced Configuration previously, except for MCRW Enhanced Card Drive (ECD) Security
Parameters Load 4
Jitter. Option number 46, which is used to set the registry key for
MCRW Enhanced Card Drive (ECD) Security Jitter, takes effect only
when the SST is reset.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-8 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Feature Support

Note: If this option is set, any card reader security options set
outside Advance NDC, such as through the Card Reader Property
pages, are lost.

From Advance NDC 3.00, the EPP in BAPE emulation mode is not
BAPE Emulation 4

supported; therefore the full EPP functionality must now be used.

As in Advance NDC 2.06, the Advance NDC application will

EMV C Exits 4

operate with existing EMV C Exits that are EMV Level 2 compliant.
For details of the EMV release to use, see “EMV/CAM2 Exits for
APTRA Advance NDC” on page 4‐13.
For voice guidance, when an EMV C Exit builds a screen, you must
include an audio escape sequence in the Exit that corresponds to
placeholders in the voice guidance XML configuration file. All fixed
audio messages are stored in the XML file, but dynamic audio data
can also be referenced. For details of the audio escape sequence to
use with EMV C Exits, refer to the APTRA Advance NDC, Reference
Manual. For details of the XML configuration file for voice guidance,
see Chapter 6, “Configuring Voice Guidance”.

From Advance NDC 2.06, the following configuration parameters

Keyboard Data 4

are not supported:

 Downloadable keyboard definitions. If different keyboard
layouts are required, they must be specified through the PIN
service provider.

Note: From Advance NDC 3.03, downloadable keyboard

definitions are supported for physical and emulated FDKs.

 Cancel/Clear swap option.

Note: The FDK swap option is supported as it applies only to

the front keyboard and to some state types that require dynamic
swapping at application runtime.

From Advance NDC 3.00, Supervisor has option 38 on the

Supervisor Menus 4

Configure menu leading to submenus for dialup communications

functions. For full details of the dialup menu functions, refer to the
APTRA Advance NDC, Supervisor’s Guide.
From Advance NDC 3.01, alphanumeric entry can be used for
certain functions.

For more information about configuring dialup communications,

see “Configuring Communications” on page 5‐44.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-9

Upgrading from Earlier Releases of Advance NDC
Feature Support

While an SST is in service, messages about device faults are

Fault Display 4

displayed cyclically on the rear operator panel. These messages give

information about devices requiring attention soon, such as Receipt
Low, and devices in a fatal condition, such as Cash Handler Fatal.
The messages also give details of the corrective measures necessary
to maintain an operational SST.
When the SST is in Supervisor mode, the fault display can be
displayed on request using one of the Supervisor functions. This
applies to both front and rear interfaces.

Note: Fault display is not supported for DASH devices.

Prior to Advance NDC 2.06, the FDK H key was used to invoke fault
display. From Advance NDC 2.06, the SELECT menu option 26 ‐
FAULT DISPLAY is used. The CANCEL key is used to exit the Fault
Display and return to the SELECT menu.
As all the device status information is provided through XFS, fault
display messages indicate the device or type of device and, where
possible, give extra details such as “CASH HANDLER FATAL,
SHUTTER JAMMED” to enable the operator to identify the failure.

The Fault Display shows all faults on one screen if possible, using
additional screens if necessary. The operator is given enough time to
read them as the value of Timer 92 is extended based on the number
of text lines displayed at a time. If there are no faults, the fault
display shows reserved screen E1903 NUMBER OF FAULTS = 0.
The text strings for fault messages can be localised by editing
resrvd.def. They are contained in the screen group Ennnn.

Prior to Advance NDC 2.06, User Messages and User Terminal Data
User Messages and User were implemented as ActiveX controls. From Advance NDC 2.06,
Terminal Data they are implemented in the Application Core, with unchanged
Implementation 4 functionality. For information about these changes and their impact
on customised applications, see “User Messages and User Terminal
Data” on page 4‐19.

From Advance NDC 3.03, the APTRA Simulator is a separate

APTRA Simulator 4

product and is available through NCR. The APTRA Simulator

product includes several component parts, including the XFS
Simulator and its documentation.
For information about using the simulator, see “Testing the
Advance NDC Application” on page 7‐35 and refer to the release
bulletin.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-10 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Feature Support

From Advance NDC 4.04, EMV on contactless card readers is

EMV on Contactless Card supported. To use EMV on contactless card readers, the
Readers 4
‘EMV/CAM2 Exits for APTRA Advance NDC’ product must be
installed.
From Advance NDC 5.01, EMV on contactless card readers is CEN
XFS compliant and supported on other vendorʹs SSTs. There is an
updated version of the Contactless Enabler component which has
new Windows Registry locations and new elements in the
ContactlessEnabler.xml file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-11

Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

Upgrading Your Release of Advance

NDC 4

If you use the Advance NDC application as provided by NCR, you

will be able to upgrade with only a few configuration changes,
described in “Configuring an Advance NDC Application” on page 5‐14.
As devices are now accessed through the XFS interface instead of
ADI2, changes will be required if you have done any or all of the
following:
 Added any new ADI2 device‐handling functionality
 Applied customisations to Author applications that include
workers which are now unsupported or changed
 Created your own User Messages or added your own data to
Terminal State messages.
The device status information is maintained for compatibility with
previous versions of Advance NDC.
If you have applied authored customisations to state types or
transaction reply functions, or authored your own, you will need to
consider the impact of modularisation and how you want to
proceed.

Instead of building three executables from the three projects in the

Authored Customisations 4

Author, only one executable is built, ApplicationCore.exe. The

Customisation Layer and Supervisor projects are built as
application DLLs for the cardholder and supervisor sessions.
There is no change to the way customisations are re‐applied to the
Supervisor or Application Core projects but state type
modularisation has changed how customisations are re‐applied in
the Customisation Layer.

Customisations in the Customisation Layer 4

Two new catalogs are provided in the Author, as follows:

 State Types, for the application DLLs relating to state types
 Transaction Reply Functions for the application DLLs relating to
transaction reply functions

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-12 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

For each state type customisation or transaction reply function,

complete the following:
1 In the Author, open the Customisation Layer project and
associated catalogs, including the State Types and Transaction
Reply Functions catalogs, which are nested within the
Customisation Layer Applications catalog.

2 Select the appropriate state type from the catalog and apply
your customisations to it.

3 Test and build.

When testing a large authored application, each application DLL
must be tested individually. You must test and then build lower‐
level DLLs before testing and building the DLLs and EXEs that
use them. NCR recommends that you avoid overwriting
existing DLLs by building to a DLL of a different name. For
more information, see “Testing the Advance NDC Application”
on page 7‐35. While testing an authored application DLL, other
authored application DLLs can be used, but they will exhibit the
functionality of a Build Final DLL, not a Test DLL.

4 Repeat for each customisation and finally build the

Customisation Layer.

5 If necessary, update the Application Links registry key to point

to the customised version. For details, see “Registry Entry for
Application Links” on page 5‐14.

If your application uses workers that either function differently or

Worker Class Support 4

are not supported in multi‐vendor Advance NDC, you will need to

assess the extent of the changes required before you migrate your
application. An alternative to using an unsupported worker is to
use an authored Exit state.
For more information about worker class support in Advance NDC,
building an application and the locations for customised files, refer
to the APTRA Author, User’s Guide.

C Exits are supported in a multi‐vendor environment, though C

C Exits 4

Exits written for an earlier release of Advance NDC will need

modification if they access devices.

EMV/CAM2 Exits for APTRA Advance NDC 4

For EMV Exits support, you must use a version that is certified with
the current version of Advance NDC. For details of certified

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-13

Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

versions, refer to the APTRA Advance NDC Package Release

Bulletin.

As Advance NDC now uses integrated displays for cardholder

Cardholder Screen Display 4

screen display, if an application has previously hosted Advance

NDC in a child window you must now develop an Exit to
communicate using the DisplayScreen and DisplayString
application programming interfaces provided by ndccust.lib. For
further information on using these APIs, refer to Chapter 4,
“Sharing Data with Advance NDC” in the APTRA Advance NDC,
Extending the Product publication.

The following table gives details of the service providers used for
Device Access 4

device access. Device identifiers are present in terminal

configuration Terminal State messages. They indicate the device to
which the data in the message applies. For some supported variants,
it is not always possible to identify each unique variant, for
example, the DIP readers.
For details of the hardware configuration data associated with each
device, refer to the APTRA Advance NDC, Reference Manual,
Appendix E, “Device Identifiers”.

Table 4-2
Service Provider Device Access Details

Device ID Device Name Device Variant Device Access Comment

D Magnetic Card Track 2 IDC SP Read only

Reader/Writer DIG ‘D’ is reported for
the primary card reader

Track 1/2/3 MCRW IDC SP Write on track 3 only

PC Dip Reader IDC SP —

3 Track Write MCRW IDC SP —

Track 2 Smart Card Reader IDC SP —

Track 1/2/3 Smart Card Reader IDC SP —

3 Track Write Smart Card Reader IDC SP —

Track 2/3 Dip MSR IDC SP Variant returned as

Track 2/3 Reader

Track 1/2 Dip MSR IDC SP —

Track 1/2 Swipe Reader IDC SP —

Dip and Smart Hardware () Card IDC SP —

Reader

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-14 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

Device ID Device Name Device Variant Device Access Comment

Contactless Card Reader Contactless —

Enabler

E Cash Handler Standard cash handler CDM SP —

Spray dispenser CDM SP —

Dual cash handler CDM SP —

F Envelope Depository DEP SP —

G Receipt Printer Dot matrix PTR SP —

Thermal PTR SP —

H Journal Printer Dot matrix PTR SP —

Thermal PTR SP —

K Night Safe DEP SP —

Depository

L Encryptor NBS encryptor PIN SP This is reported for

BAPE/HI‐BAPE

EPP encryptor PIN SP —

M Camera All variants CAM SP —

O Off‐Line Flex Disk 1.44 Mb Flex Disk Drive O/S Access to the diskette
drive is through the
2.88 Mb Flex Disk Drive O/S operating system and is
vendor‐independent

P TI Bins (Alarms) All variants SIU SP —

Q Cardholder Standard (BAPE) keyboard PIN SP —

Keyboard

EPP keyboard PIN SP —

R Operator Keyboard Keyboard plus FDKs (enhanced) TTU SP This is reported for the
Enhanced Operator
Panel

S Cardholder Display O/S Access to display, touch

screen, and voice
functions is through the
operating system and is
vendor‐independent

V Statement Printer All variants PTR SP —

Y Coin Dispenser All variants CDM SP —

Z System Display Enhanced display TTU SP —

(16 x 32)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-15

Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

Device ID Device Name Device Variant Device Access Comment

[ Media Entry SIU SP —

Indicators

\ Envelope Dispenser DEP SP —

q Cheque Processing All variants PTR SP —

Module (CPM) Bunch cheque acceptor IPM SP

w Bunch Note Acceptor All variants (including GBXX) ActiveXFS —

(BNA)

y Secondary Card Contactless Card Reader Contactless —

Reader Enabler

The following table gives details of the information source for

Supplies Data Sources 4

device supplies data.

For details of the supplies data associated with each device, refer to
the APTRA Advance NDC, Reference Manual, Appendix E, “Device
Identifiers”.

Table 4-3 Device ID Device Name Supplies Data Data source

Supplies Data Source Information
D Magnetic Card Card capture bin XFS IDC
Reader/Writer

E Cash Handler Cash handler reject bin XFS CDM

Cash handler cassette types XFS CDM

1 to 7

F Envelope Envelope deposit bin XFS DEP

Depository

G Receipt Printer Receipt printer paper XFS PTR

Receipt printer ribbon XFS PTR

Receipt printer print‐head DSM

01 (Good State) always
returned

Receipt printer knife DSM

01 (Good State) always
returned

Capture bin XFS PTR

0 Capture bin not present
1 Good
4 Overfill

H Journal Printer Journal printer paper XFS PTR

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-16 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

Device ID Device Name Supplies Data Data source

Journal printer ribbon XFS PTR

Journal printer print‐head DSM

K Night Safe Night safe bin XFS DEP

Depository

V Statement All supplies data XFS PTR

Printer
all variants

Y Coin Dispenser Coin dispenser module and XFS CDM

all hopper types

\ Envelope Envelope dispenser hopper XFS DEP

Dispenser

w Bunch Note All BNA cassettes ActiveXFS

Acceptor (BNA)
all variants

The following table gives details of the information source for

Fitness Data Sources 4

fitness data.
For details of the fitness data associated with each device, refer to
the APTRA Advance NDC, Reference Manual, Appendix E, “Device
Identifiers”.

Table 4-4 Device ID Device Name Fitness Data Data source

Fitness Data Source Information
D Magnetic Card Magnetic Card XFS IDC
Reader/Writer

Contactless Card Reader

E Cash Handler Cash handler reject bin XFS CDM

Cash handler cassette types

1 to 7

F Envelope Depository XFS DEP

Depository

G Receipt Printer Receipt Printer XFS PTR

Capture bin
0 No error or not supported
4 Fatal
For details, see the note on
4‐18.

H Journal Printer Journal Printer XFS PTR

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-17

Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

Device ID Device Name Fitness Data Data source

K Night Safe Night Safe XFS DEP

Depository

L Encryptor Encryptor XFS PIN

Q Cardholder Cardholder Keyboard XFS PIN

Keyboard

V Statement Statement Printer XFS PTR

Printer

Y Coin Dispenser Coin dispenser module and XFS CDM

all hopper types

\ Envelope Envelope Dispenser XFS DEP

Dispenser

q Cheque CPM XFS PTR

Processing
Module (CPM)

w Bunch Note BNA ActiveXFS

Acceptor (BNA)

y Secondary Card Contactless Card Reader Contactless

Reader Enabler

Note: The Supplies and Fitness data sources for the Receipt printer
capture bin will always be reported as zero if the printer does not
have a capture bin.

For devices accessed through XFS, the message format is unchanged

Message Handling 4

but the content of both solicited and unsolicited status messages is

derived differently.
The following table summarises the changes that apply to the
devices listed earlier in this chapter under “Changes to the Interface
since Release 2.6” on page 4‐6. For further details of messages, refer
to the APTRA Advance NDC, Reference Manual, Chapter 9, “Terminal
to Central Messages.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-18 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

Table 4-5
Message Handling Changes Summary

Status Descriptor Field Description Comment

‘Cʹ ‐ Specific Command Reject g1 = ‘C’ The message is not This is returned when the
g2 = 02 accepted while diagnostics, application has passed control to
or clear SOH level 2 or Vendor Dependent Mode (VDM).
level 3 is in progress.

‘Fʹ ‐ Terminal State

1 ‐ Send Configuration g3 Device Severity The value is derived from

Information g5 Supplies Status information provided by the SP.
g6 Sensor Status

‘H’ ‐ Hardware g4 Hardware Configuration The device configuration is derived

Configuration Data from the XFS capabilities.

‘I’ ‐ Supplies Data g2 Supplies Status Supplies data is derived from XFS.

‘J’‐ Fitness Data g2 Fitness Device fitness is derived from XFS.

‘K’ ‐ Tamper and Sensor g2 Sensor Status The value is derived from XFS.
Status data g3 Tamper Status As the DPM is not supported,
character 13 is always set to 0.

‘L’ ‐ Software ID and g2 Release Number Identifier For example, the value is 040000 for
Release Number data Advance NDC 4.00.

ʹ8ʹ ‐ Device Fault g3 Error Severity The value is derived from XFS
g4 Diagnostic Status information.
g5 Supplies Status

For full details of the status message format and fields, refer to the
APTRA Advance NDC, Reference Manual.

If you have created new Message Classes or included additional

User Messages and User data in Terminal State messages, you will have to import your code
Terminal Data 4
into the Application Core, where the functionality that used to be
provided in separate ActiveX controls is now supported directly by
the Message Handler for each mode.
You import your User Messages director or User Terminal Data
director for each mode as required. The following table gives the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-19

Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

component ID of the Message Handler director where you insert

your code.

Table 4-6 Mode Message Handler Component ID

Message Handler Component ID
Out‐of‐Service 11L286B7

Supervisor 15L302B7

In‐Service 69L302B7

Complete the following steps:

1 Make a copy of the Advance NDC application and open the
Application Core project.

2 Import your User Messages director or User Terminal Data

director from the old catalog into the Application Core.

3 Insert your User Messages or Terminal Data director under the

Message Handler director for the required mode, replacing the
default implementation of the User Messages director or the
User Terminal Data director.

In Advance NDC 2.06, access to the receipt, journal and envelope

Printing 4

printers was changed to the CEN‐XFS interface. From Advance

NDC 3.00, access to the statement printer is also through the
CEN‐XFS 3 interface. From Advance NDC 3.02, support for USB
receipt and journal printers is supported using the PrintRawData
command, and in release 3.03 dynamic XFS form generation is
supported for SelfServ Receipt, Journal and Statement printers.
The NDC printer control sequences are still supported under the
NDC message format and the existing workers. A conversion DLL
is called, which uses entries in the registry to do one of the
following:
 Convert the NDC print control codes to vendor‐specific codes
 Generate a series of XFS forms. For these, the conversion DLL
returns the names of the XFS forms to be printed.
For further information on printing, refer to the APTRA Advance
NDC, Reference Manual, Chapter 5 “Printer Data” and Appendix B
“Character Sets”.

Printer Variants 4

If text‐only support is offered by the SP, the default printer

configuration is for thermal printers. Where a non‐thermal printer is
configured, the registry can be set so that all unsupported
commands are stripped before the data is sent to the printer.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-20 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

Graphics and barcode sequences are most likely to be unsupported

by dot matrix printers.

Receipt Printer 4

The receipt printer can support double‐width printing, the euro

symbol and printing a footer, as follows.
Double‐Width Printing Using the Normal Receipt Page worker, 4

double‐width text can be printed on a receipt printer by selecting

the appropriate character set in the Paragraph Text attribute of the
Print Paragraph worker. This is illustrated in Figure 4‐1 below.

Figure 4-1
Double-Width Printing Example
4

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-21

Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

Double‐width text is specified by putting the control character ESC,

followed by ‘(‘ and the ‘>’ designator, before the text you want to
make double width, as shown in the Multi Line String Editor. For
example, 1BH 2BH ‘>’ ‘text’ prints the text double‐width. At the
end of the text, the default character set must be set back with
‘ESC(1’.

Euro Symbol Printing The euro symbol is specified by using the 4

control character ESC, followed by ‘(’, the ‘R’ designator and the
dollar sign ‘$’. For example, 1BH 28H ‘R’ ‘$’ selects the
international character set Alpha 6, and prints the euro symbol.
After the euro symbol, the default character set must be restored
with ‘ESC(1’.
NDC Print Footer Worker To facilitate the printing of receipts, a 4

new worker class was introduced in Advance NDC 2.06. This

worker prints to a receipt any remaining preprint information not
printed by Print Buffer, and ejects the receipt. For details, refer to the
Advance NDC Worker Class help in the Author.

Journal Printer 4

When hardcopy backup is set from the host (enhanced

configuration option 16 or 17), status messages for the physical
printer and hardcopy backup are reported to the host. When the EJ
is selected by the user at the SST (option 1 from 30 SET JRNL in the
Supervisor Configure menu), messages are reported for the EJ.
To improve the readability of journaled messages, group separators
are represented as asterisks in both the EJ and hardcopy journal.
If either the EJ or hardcopy backup log (ejdata.log or hbdata.log)
reaches its size limit, and automatic initialisation by cutover is not
enabled, a fatal error message is sent and the printer enters a fatal
state. A warning message is also sent when the EJ log is 90% full. For
information on automatic initialisation by cutover, see “Cutover” on
page 5‐181.
From release 3.01, the following EJ options are available:
 Enhanced EJ backup, providing the following choices:
— A single backup file using Standard EJ backup
— Up to 1000 backup files depending on disk space using
Multiple EJ backup.

For details, see “Enhanced EJ Backup” on page 5‐187.

 Multiple destinations, allowing the choice of available

destinations for the backup file. For details, see “Multiple
Destinations for EJ Backup” on page 5‐186.
From release 3.02, the following EJ options are available:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-22 APTRA Advance NDC, Developer’s Guide

 Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

 The host control of the EJ backup mode can be disabled. For

details, see “Disable Host Control of Enhanced EJ Backup” on
page 5‐188.
 The initialisation operation can be run automatically in a
number of ways. An optional copy of the EJ file can also be
made following the automatic initialisation. For details, see
“Automatic Initialisation Options” on page 5‐181.
 The EJ file can be compressed. For details, see “EJ Compression”
on page 5‐180.
 A maximum size for the EJ file can be set. For details, see
“Maximum EJ File Size” on page 5‐180.
For information on using all EJ options, refer to the APTRA Advance
NDC, Supervisor’s Guide.
Dual Mode Operation From Advance NDC 2.06 onwards, dual 4

mode operation is supported. When dual mode is selected (option 2

from 30 SET JRNL in the Supervisor Configure menu), only
messages for the physical printer are sent to the host. No status
messages for the EJ or hardcopy backup are sent unless enhanced
configuration option 35 is set as follows:

Table 4-7 Value Effect in Dual Mode

Dual Mode Error Message Selection
000 Send unsolicited error messages for the physical journal
printer only (the default value)

001 Send unsolicited error messages for the physical journal

printer and EJ only

002 Send unsolicited error messages for both EJ and hardcopy

backup

Note: When the journal printer is set to dual mode, hardcopy

backup is automatically enabled. If option 16 or 17 is sent from the
host, it will be ignored.

The STCONT file supports alphanumeric state entries for up to

STCONT File Updates 4

46655 state numbers.

In the STCONT file, all state parameters referring to state numbers
have their limit set to ZZZ (base 36). For any new states, the limits of
state parameters that represent state numbers must be set to ZZZ.
Nested extension states are also supported, as described in the
APTRA Advance NDC, Extending the Product publication.
The STCONT file is used to configure the calling of authored state
types, using the keyword ʹApplication Linkʹ as the C Exit function
name. This indicates to the state execution system that the DLL is

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 4-23

Upgrading from Earlier Releases of Advance NDC
Upgrading Your Release of Advance NDC

loaded and executed through the SSDS DLL Interface worker. For
details, refer to the APTRA Advance NDC, Extending the Product
publication.

All Promote campaigns must be created using the appropriate

Promote Campaigns 4

version of APTRA Promote Manager. If you have existing

campaigns, you may need to recreate them.
For further information on Promote campaigns, refer to the APTRA
Promote User’s Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

4-24 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Configuring Advance NDC and Associated Components

Chapter 5
Configuring Advance NDC and
Associated Components

Overview 5‐1

Automatic Configuration at Start‐up 5‐2

Supervisor Option to Auto‐configure Devices 5‐2
SST Configuration Component 5‐2
Advance NDC Startup 5‐3
ANDCSST.XML Elements 5‐4
Example ANDCSST.XML Extracts 5‐11
Receipt Printer XML 5‐11
Defining Class Sub‐Types 5‐13

Configuring an Advance NDC Application 5‐14

Advance NDC Registry Entries 5‐14
Registry Entry for Application Links 5‐14
Examples of Application Links 5‐16
Performance and Memory Considerations 5‐16
CEN‐XFS Logical Device Names 5‐17
Active XFS Aliases for Cash and Cheque Acceptors 5‐18
Status Handling 5‐19
Remote Status Indicators 5‐19
Unsolicited Status Messages for External System Events 5‐19
Unsolicited Status Messages for Cash Handlers 5‐20
Power‐Up Status Message 5‐20
Registry Settings for Device Status Messages 5‐20
Cardholder Display 5‐20
Receipt Capture Bin 5‐21
Enabling Web Exits 5‐21
Configuring the Web Exit State 5‐21
Specifying Local Customisation Data 5‐22
SCXLOC File 5‐23
LOCAL File 5‐24
Changing the Next State Number 5‐25
Example of StateTranslator.xml 5‐25
Security Cameras 5‐26
Using the XML File 5‐26

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

Table of Contents
Configuring Advance NDC and Associated Components

Using the NDC Camera Service 5‐29

Flow Points Defined for the Security Cameras 5‐30
Example of Adding Flow Points 5‐31
Configuring Data Masking and Logging 5‐32
Interactive Transaction Response 5‐32
Masking of Buffer B and Buffer C 5‐32
Transaction Reply 5‐33
Printer Data Logging to the OOXFS Trace Stream 5‐34
Masking of Track 2 Data 5‐34
Masking of PAN 5‐34
Support for DVDs on SSTs 5‐35
Re‐writable and Dual‐layer DVDs 5‐35
Unsupported Configuration Options 5‐35
Promote Flow Point Behaviour 5‐35

Configuration Files 5‐37

XML Configuration Files 5‐37
Configuration Update Control 5‐37
.NET Class Configurator Files 5‐40
AdvanceNDC.accfg 5‐41
AdvanceNDCCore.accfg 5‐41
AdvanceNDCCustom.accfg 5‐41
CashinCore.accfg 5‐41
CashinCustom.accfg 5‐42
SupervisorReceiptConfig.accfg 5‐42
NDCLocalTxReceiptConfig.accfg 5‐42
NDCCRMReceiptConfig.accfg 5‐42
TcpipSupportTaskReceiptConfig.accfg 5‐42
Conventions For Multiple Files 5‐42
Creating Classes 5‐43
Class Configurator Files 5‐43

Configuring Communications 5‐44

Service Class 5‐44
TCP/IP Setting 5‐44
CCM PCCM Setting 5‐44
CCM VISA2 Setting 5‐44
Clearing the Communications Buffer 5‐44
Off‐line Timer 5‐45
TCP/IP Configuration 5‐45
Configuring TCP/IP 5‐45
Configuring Network Connections
and Communications Links 5‐46

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

 Table of Contents
Configuring Advance NDC and Associated Components

Internet Protocols 5‐48

Dialup Configuration 5‐49
Status Message Suppression 5‐50
Alphanumeric Entry 5‐50
Preconfiguration 5‐51
Connect Life Time 5‐51
Copy On/Off 5‐51
XML Restrictions 5‐51
Diagnostics 5‐51
Dialup Timers and Modem Baud Rate 5‐52
Activity Timer 5‐52
Error Redial Timer 5‐52
Timer 3 5‐52
Modem Connect Timer 5‐52
Dial on Send Timer 5‐52

Configuring Diagnostics Options 5‐53

Displaying Additional Diagnostics Menus 5‐53
Show/Hide Diagnostics Shortcut 5‐53
Disabling Self‐Test on Diagnostics Exit 5‐54

Configuring Service Providers 5‐55

Configuring Service Providers (SPs) for Reboot 5‐55
Service Provider Reset Value 5‐55
Service Provider Tracing 5‐56
Configuring SP Support for CEN‐XFS Versions 5‐56

Configuring SNMP Traps 5‐58

No Transaction Traps 5‐59
Application Heartbeats 5‐59
Advance NDC Mode Change Traps 5‐60
Service State Changes 5‐60
Implementation of SNMP Traps 5‐60
NCR SNMP Implementation 5‐60
GASPER‐Compatible Implementation 5‐62
GASPER‐Compatible SNMP Traps for a
Contactless Card Reader 5‐62

Configuring .NET Archive Manager 5‐65

Configuration Properties 5‐65
General Configuration 5‐66
Scheduling Archives 5‐66

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

Table of Contents
Configuring Advance NDC and Associated Components

Setting the Default Collection Directory 5‐67

Deleting Old Archives 5‐67
Archive Data Configuration Examples 5‐68
Archive Files Using the Supervisor Task 5‐68
Archive Files Using the Scheduler 5‐68
Archiving PD Investigation Files 5‐69
Archiving Cache Files 5‐70
Archiving XFS Trace Files 5‐71
Archiving Event Logs 5‐71
Archiving EJ Data Files 5‐72
Archiving ECB 6 Database File 5‐73
Archiving Unhandled Exception Handler (UEH) Files 5‐73
Archiving SNR Image Files 5‐74
Archiving Bunch Note Image Files 5‐75
SST Properties Configuration Examples 5‐77
Owner Details 5‐77
SST and Network ID 5‐77
Postal Address 5‐78
Additional Configuration 5‐79
Archiving User‐Defined Files 5‐79
Archiving Registry Keys 5‐81

Configuring .NET Retrieve Archive Task 5‐82

Example Updates to Settings 5‐82
Changing the Export Folder 5‐83
Changing the User Response Timeout 5‐83
Changing the Date Format 5‐84
Using Only Removable Drives 5‐84
Excluding CD and DVD Drives 5‐84
Changing the Number of Days to Search 5‐85

Configuring the .NET NDC CRM Service 5‐86

Terminal ID Source 5‐87

Configuring SST Recovery 5‐89

NDC Monitor 5‐89
Enabling NDC Monitor 5‐89
NDC Monitor XML Elements 5‐90
Defining the States to Monitor 5‐92
Forced Reboot 5‐93
Resetting USB Devices 5‐94
Device Recovery XML File 5‐96

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

 Table of Contents
Configuring Advance NDC and Associated Components

Device Recovery Schema 5‐98

Uninterruptible Power Supply 5‐99

Configuring Suspend Timeout 5‐100

Setting the Service Provider Timeout 5‐100
Setting the Application Timeout 5‐101
Setting the Unusual Object Monitoring Timeout 5‐101

Configuring Supervisor Functionality 5‐103

Settlement Screen Customisation 5‐103
Extended Add Cash Option 5‐103
Rear Settlement 5‐104
PIN Entry 5‐104
Dummy PIN Block 5‐104
Supervisor Alphanumeric Data Entry 5‐105
Supervisor Keyboard XML Configuration File 5‐106
Delayed Password Masking 5‐109
.NET Supervisor Task 5‐109
Developing a New .NET Supervisor Task 5‐109
Integrating New or Existing .NET Supervisor Tasks 5‐110
.NET Software Updates 5‐112
Configuring the Installation Script 5‐112
Configuring the Copy File Directory 5‐113
.NET Software Update Service 5‐114
Security Considerations 5‐115
Promote/Copyfile 5‐116
Configuring the Export File Path 5‐116
Relate Supervisor Option 5‐116
Configuring Multiple Destination Screens to Display Fixed
Drives 5‐116
Configuring the Default Location for Note Signatures 5‐117
Configuring Extracted Signatures 5‐118
Configuring Denomination and Note ID Validation 5‐118
Journaling Supervisor Mode Change During a Transaction 5‐119
Configuring Supervisor Entry/Exit Messages 5‐119
Simulated Supervisor Entry/Exit Messages 5‐120

Configuring Cardholder Functionality 5‐121

Configuring Input Type, Buffer and Display Format 5‐121
Cardholder Alphanumeric Data Entry 5‐122
Configuring SMS‐style Data Entry or PC Keyboard 5‐123
Cardholder Verification State in STCONT 5‐126

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

Table of Contents
Configuring Advance NDC and Associated Components

Confirmation Screens During Cash Deposit 5‐126

Direct Deposit Confirmation Screen on Error 5‐126
Cash Accept Screen Formatter Classes 5‐127
ECB 6 Dialog Class 5‐135
Disabling Clear Key in PIN Entry State 5‐136
Configuring Amount Entry 5‐136
Configuring Amount Entry Length 5‐136
Configuring Whole Amount Entry 5‐136
Validating Buffer Data 5‐139
Configuring Beep for Cardholder Transactions 5‐140
PC Beep 5‐141
Contactless Card Reader Beep 5‐141
Cardless Transactions 5‐142
Supervisor Configuration of Cardless Transactions 5‐142
Registry Configuration of Cardless Transactions 5‐142
Key Mask Definition 5‐147

Configuring Keyboards 5‐149

Front Keyboard 5‐149
Audible Alert on Emulated FDK Selection 5‐150
Mapping the Enter Key to an FDK 5‐150
Operator Keyboard 5‐151
Touch‐screen Keyboards for Alphanumeric Data Entry 5‐152
Keyboard Definitions 5‐152
Defining the Screen 5‐153
Customising a Keyboard Definition 5‐153
Touch‐screen Keyboard Display 5‐154

Configuring Screen Displays 5‐155

Secure Key Entry 5‐155
Display Manager for HTML Screens 5‐155
Hide Taskbar 5‐155
AVI System Limit 5‐156
Advance NDC Display Components 5‐156
Offline Keyboard Layouts 5‐156
Advance NDC Display Configuration File 5‐162
Advance NDC Display Runtime Settings 5‐176
Offline Screens 5‐176
Reserved Screens 5‐176
Screen Manager Class 5‐177
Display Manager Class 5‐177
Hide Mouse Pointer 5‐178
Customer Relationship Management 5‐178

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

 Table of Contents
Configuring Advance NDC and Associated Components

Enabling Extended Screen Groups 5‐178

Configuring the Electronic Journal 5‐180

EJ Compression 5‐180
EJ Privacy 5‐180
Maximum EJ File Size 5‐180
EJ Checksum 5‐180
Automatic Initialisation Options 5‐181
Cutover 5‐181
Scheduled 5‐181
Agent 5‐183
Automatic Initialisation Copy Drive 5‐184
Initialisation After Settlement 5‐185
Delaying Initialisation During Transactions 5‐185
EJ Backup Filenames 5‐185
EJFileDateFormat 5‐185
EJShortFilename 5‐186
Multiple Destinations for EJ Backup 5‐186
Enhanced EJ Backup 5‐187
Maximum Number of Backups 5‐187
Disable Host Control of Enhanced EJ Backup 5‐188
EJ Level 5‐188
Journal Page Workers 5‐188

Configuring Printers 5‐189

Journal Printer Status 5‐189
Journal Printer Level 5‐190
Receipt Printer 5‐191
Receipt Handling 5‐191
Promote Coupons 5‐192
Top Margin of Receipts 5‐194
Statement Printer 5‐195
USB Statement Printer 5‐196
Forms‐Based Printing 5‐196
Registry Entries for Configuring Forms 5‐196
Registry Entries for Configuring Fonts 5‐198
Registry Entry for Configuring LPI 5‐199
USB Receipt and USB Journal Printers 5‐199
Registry Entry for Receipt Retract 5‐200
Creating Graphics Files 5‐200
Registry Entry for Printing Graphics on the Next Page 5‐202
LEAP Receipt Printer 5‐202
Non‐Thermal Printers 5‐203

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

Table of Contents
Configuring Advance NDC and Associated Components

Passbook Printer 5‐203

Implementation 5‐204
64‐Bit Windows 7: Importing Printer
Registry Files Manually 5‐205

Configuring E‐Receipt 5‐206

E‐Receipt Service
Component 5‐206
Configuring E‐Receipt 5‐206

Configuring Readers 5‐209

Accepting Smart Cards in Motorised Card Readers 5‐209
Additional DASH Reader Fatal/Suspend Handling 5‐209
Barcode Reader Filter and Extraction Rules 5‐210
Example Barcode Filter Configuration File 5‐212
Example Barcode Extraction Rules 5‐213
Contact and Contactless Card Readers 5‐213
Primary and Secondary Card Readers 5‐213
Contact Card Reader as the Primary Card Reader 5‐214
Contactless Card Reader as the Primary Card Reader 5‐214
Configuring Contactless Card Reader Device Mode 5‐215
Transaction Activation 5‐216
Read Conditions 5‐217
Automatic Language Selection 5‐217
Voice Guided Sessions 5‐217
Device Faults 5‐218
Status Messages 5‐222
Reset Contactless Reader 5‐222
24‐Volt Reset for Contactless Reader 5‐223
Card Misreads 5‐224
Controlling the Card Entry Retries 5‐224
Journaling Card Entry Retries 5‐225
Media Entry/Exit Indicator (MEI) for Contact and Contactless
Card Readers 5‐225
Journaling Card Reader Events 5‐226
Tracing for Contactless Transactions 5‐226
Error Reporting for Contactless Card Readers 5‐228
Configuring Contactless Card Reader 5‐228
Configuration Data 5‐229
XML File Format 5‐241
Mask Expression 5‐254
Device Variants and Firmware Versions 5‐255
Avoid Inadvertent Tap 5‐257
Simple XML File Example 5‐258

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

 Table of Contents
Configuring Advance NDC and Associated Components

Smart Delay Timer for Smart Dip Card Reader 5‐262

USB and RS232 DASH Card Readers 5‐263

Configuring Coin Dispensers 5‐264

Registry Keys for the Coin Dispenser 5‐264
Setting the Currency 5‐264
Setting the Coin Value 5‐264
Setting the Low Threshold for Coins 5‐265
Supplies and Severity Information 5‐265

Configuring Cash Handlers 5‐267

Setting the Currency 5‐267
Setting the Media Type 5‐268
Setting the Denomination 5‐268
Setting the Cassette Identifier 5‐268
Setting the Cash Unit Identifiers for Supervisor 5‐268
Cash Dispenser Cassette Status 5‐269
Automatic XFS Exchange 5‐270
Manual XFS Exchange 5‐270
XFS Exchange and Cassette Information 5‐271
Cassette Information Screen 5‐271
Add Cash 5‐272
Standard Cash 5‐272
Test Cash 5‐273
Reporting the MANIP Status of CDM Cassettes 5‐274
Setting Multiple Currencies 5‐275
Disabling Retract after Suspend 5‐275
CDM Status When Notes are at Exit Slot 5‐276
Reporting Pick Failure Errors 5‐277
Unknown Status of Notes After a Power Failure 5‐278
Journaling the Count if a Present is Attempted Before a Power
Fail 5‐279
Count of Notes in Unknown Location 5‐279
Cash Handler with a Fifth Physical Cassette 5‐280
Enabling Support for Seven Cassette Types 5‐280
Setting Note Thresholds 5‐281
Maximum Notes to be Dispensed 5‐281
Low Threshold for Notes in Cassettes 5‐281
Reject Bin Maximum Threshold 5‐282
Configuring the MEI for a Spray Dispenser 5‐282
Supplies and Severity Information 5‐283
Replenishment Status of Cassettes 5‐284
Supplies Reporting for S2 Media Dispenser Module 5‐284

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

Table of Contents
Configuring Advance NDC and Associated Components

Fitness Reporting for S2 Media Dispenser Module 5‐286

Reading and Journaling Serial Numbers 5‐288
Journaling Serial Number Information 5‐288
Capturing Bunch Note Image 5‐289
Logging Signatures of Dispensed Notes to Database 5‐290
Dual Cash Handler Configuration 5‐293
Registry Entries for Dual Cash Handlers 5‐294
Setting the Cash Handler Priority 5‐294
Setting the Counter Entry Mode 5‐294
Setting the Counter Clearing Mode 5‐295
Status Reporting 5‐295
Cash Handler Status Message 5‐296
Interlock Handling 5‐297
Tamper Indication 5‐297
S2 Media Dispenser Module 5‐297
Carriage Sweep 5‐299
Serial Carriage Sweep 5‐300
Parallel Carriage Sweep 5‐300
Prepare Dispense 5‐300
Card Read State A and Card Read ‐ PIN Entry Initiation
state T 5‐302
Prepare Dispense State z024 5‐302
Close State 5‐302
Retract Options 5‐302
1 Retract 5‐303
1.5 Retract 5‐303
2.5 Retract 5‐303
Two Stage Retract 5‐304
Clearing the device 5‐306
Report Reject and Retract bins Physical Counts 5‐307
Tamper Indication on an S2 Dispenser 5‐308
Journaling 5‐308
Handling Incorrect Denomination and Short Dispense 5‐309
Journaling Moved Notes 5‐312

Configuring Cash Acceptors 5‐313

Cash Acceptor Installation Settings 5‐313
Scalable Deposit Module 5‐314
Bunch Recycling Module 5‐315
Miscellaneous Configuration 5‐316
Positioning the Reason for Note Refusal 5‐320
Defining the Please Wait screen 5‐320
Setting the Volume 5‐320
Combined Cash Handler 5‐320

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

 Table of Contents
Configuring Advance NDC and Associated Components

Setting the Insertion Limit for Bunches of Notes 5‐320

Setting the Retry Limit for Note Insertion 5‐321
Transaction Request Cumulative Counts 5‐321
Configuring Note Retract to the Escrow 5‐322
Enabling Retract to the Escrow 5‐322
Automatic Error Recovery 5‐323
Journaling 5‐323
Configuring the Retain Destination for the
Notes in Escrow 5‐323
Enabling Direct Deposit 5‐324
Automatically Enabling Direct Deposits 5‐325
Setting the Direct Deposit Limit 5‐325
Reporting Direct Deposit Capability 5‐326
Displaying Direct Deposit Error Messages 5‐326
Setting the Transaction Cash‐In‐Limit 5‐328
Configuration 5‐328
Configuring Reject and/or
Retract Bin for Depositing Notes 5‐328
Off‐line Cash Deposit Handling 5‐329
Suppressing Messages 5‐329
Receipt Service Provider 5‐330
Off‐line States Array 5‐330
Reading, Journaling and
Capturing Serial Numbers of Notes 5‐331
Reading the Serial Numbers 5‐331
Configuration for Journaling Serial Number
Information 5‐331
Capturing Serial Number Image 5‐341
Capturing Bunch Note Image 5‐344
Scenario 1: Deposit 5‐345
Scenario 2: Reject 5‐345
Scenario 3: Refund 5‐345
Scenario 4: Retract 5‐346
Scenario 5: Error Recovery 5‐346
Reconciliation List Customisation 5‐346
Displaying and Printing BNA Counts 5‐347
Supervisor Counters Cassette Names Array 5‐347
Cash‐in Supervisor Counters Configuration 5‐348
Printing BNA Totals, Displaying and
Printing BNA Counts 5‐349
Currency Names Mapping Array 5‐349
Printing BNA Totals 5‐350
Counts Configuration Array 5‐350
Available Counts 5‐351
Enhanced Cash‐in Formatter 5‐355
Print Cash‐in Totals 5‐356

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

Table of Contents
Configuring Advance NDC and Associated Components

Reason for Refusing a Deposit 5‐357

Tamper Indication Journaling 5‐358
Localising Tamper Indication Journaling 5‐359
Note Type Mapping 5‐360
Using the Note Type Mapping XML File 5‐361
Journaling Note Configuration Failures 5‐362
Journaling Note Validation Errors 5‐362
Journaling the Count of Notes that Pass through the Bill
Validator 5‐363
Device M‐Status Reporting 5‐363
Suspend Handling 5‐364
Error Recovery 5‐364
Error Recovery Modes 5‐365
Recovery Destination 5‐365
Reason for Failed Recovery 5‐366
Report Error Message 5‐367
ECB 6 Considerations 5‐367
ECB 6 Note Categories 5‐367
Counterfeit, Suspect and Good Notes 5‐368
ECB 6 Modes 5‐374
ECB 6 Database Support Utility 5‐376
Media Entry Indicator for a BNA 5‐377
Encash, Print and Set Next State 5‐377
Cash Deposit Exception Reporting 5‐377
Enabling Exception Reporting for Cash Acceptors 5‐377
Configuring the Report Format 5‐378
Configuring the Statement Service 5‐378
Configuring the Receipt Service 5‐378
Printing Exception Reports 5‐379
Journal Formats 5‐379
Class Configurator Configuration 5‐380
Serial Number Information 5‐381
Reserved Screen Configuration 5‐383
Journaling Retract Counts 5‐386
GBXX Dynamic Note Sorting 5‐386
Scenario 1: No All‐in Cassette Configured 5‐388
Scenario 2: All‐in Cassette Configured 5‐388
GBXX Cassette Configuration 5‐388
Cassette Configuration Using Supervisor 5‐389
XML Schema 5‐391
GBXX Configuration File 5‐397
Registry Entries for Recycling Units 5‐399
Reporting the MANIP Status of GBRU Cassettes 5‐401
CDM and CIM NDC Cassette Types 5‐401
Fixed Cassette Mapping for Recycling 5‐404

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

 Table of Contents
Configuring Advance NDC and Associated Components

Maximum Accepted Notes 5‐405

Journaling Note Counts 5‐405
Automatic Cassette Mapping using
PhysicalPositionMap Property 5‐406
GBXX Device with Cassettes Not Configured 5‐407
Automatic Cassette
Mapping for a BRM Device 5‐407
Deposit Cassette Maximum Threshold 5‐407
BRM Cassette Configuration 5‐407
BRM Configuration XML File 5‐408
BRM Configuration File Example 5‐412
Fixed Cassette Mapping for BRM 5‐413
Configuring a BRM device as a Deposit only
or a Dispense only 5‐414
Configuring BRM to Swap Reject and Retract Bin 5‐415
Validating the Incorrect Denomination 5‐416

Configuring Cheque Processors 5‐419

Accessing Cheque Data 5‐419
Cheque Processing Module 5‐419
Cheque Images on Two‐Sided Thermal Printers 5‐420
Resizing the Image 5‐420
Form and Media Definitions 5‐421
Magnetic Ink Character Recognition (MICR) Option 5‐422
Bunch Cheque Acceptor 5‐422
Configuring the Codeline 5‐422
Suppressing Status Messages 5‐423
Accepting Cheques in a Single Orientation 5‐423
Moving Returned Cheques to Retract Bin 5‐424
Supporting a Cheque Validation Service 5‐425
Retrieving the Cheque Image Path 5‐425
Retrieving the Scan After Endorsement Setting 5‐426
Endorsing Cheques Returned by the Host 5‐426
Cheque Amount Recognition 5‐426
ImageMark Passport ATM Image Agent 5‐426
Envelope Dispenser 5‐433

Configuring Colored MEEI 5‐434

Configuring CRM Flowpoint State 5‐436

CRM Flowpoint XML 5‐438

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

Table of Contents
Configuring Advance NDC and Associated Components

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
E

Overview

Overview 5

This chapter describes how to configure Advance NDC and any

associated components, including the following:
 Automatic configuration carried out by the Self‐Service
Terminal Configuration component
 Communications and service providers
 Diagnostics and SST management
 Cardholder and Supervisor functionality
 Devices.
For information about using touch screens in a development
environment, see “Running in the PC Environment” on page 7‐36.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-1

Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

Automatic Configuration at Start‐up 5

The Self‐Service Terminal Configuration component (SST

configuration component) runs automatically before Advance NDC
starts. A default configuration file is provided in Advance NDC,
complete with settings for all vendors’ SSTs. This file does not need
to be updated unless you are using different or additional hardware
to that included in the default file. Example configuration settings
are given in ++. The SS15T configuration component will not
perform any further configuration unless new devices are detected
or the ANDCConfig.NDC file is not found, as described in the section
below.
The SST configuration component uses a configuration file
(ANDCSST.xml) to identify the XFS devices present on the SST and
configure the devices for the vendor platform. The SST
configuration component schema, ANDCSST.xsd, defines the
structure of the configuration file as described in Table 5‐1, “SST
configuration component XML Elements” on page 5‐4.
The device settings given in this chapter are set using the SST
configuration component. If the settings are to be updated you must
edit the ANDCSST.xml file accordingly. If you edit the registry
entries directly, the settings will be overwritten next time the SST
configuration component runs.

There is also a Supervisor option, option 94, Auto‐Configure

Supervisor Option to Devices, available on the Configure menu. This option deletes the
Auto‐configure Devices 5
existing ANDCConfig.NDC file and restarts the SST to run the SST
configuration component and create ANDCConfig.NDC, as
described in the next section. For details of the Auto‐Configure
Devices option, refer to chapter 4, “Configure Menu” of the APTRA
Advance NDC Supervisor’s Guide.

After the initial installation, the SST configuration component is run

SST Configuration to apply the configuration settings defined for devices found on the
Component 5
SST and create the ANDCConfig.NDC file. The SST configuration
component also starts the platform before Advance NDC starts. For
subsequent startups, any new devices will be configured, but full
re‐configuration is performed only if the file does not exist.

Note: Various registry keys can be automatically configured by

running the AppLoader.exe after installing the application. The
AppLoader.exe must be first run in the administrator mode before
running the secure mode.
The location of the file is as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-2 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

C:\Program Files\NCR APTRA\Advance NDC\Config

If the ANDCConfig.NDC file is not found in this location, a full

re‐configuration is performed before Advance NDC starts.

Note: To reconfigure the alias names specific to Advance NDC,

ensure to delete the ANDCConfig.NDC file whenever a new Active
XFS component is installed on a machine with Advance NDC.

Advance NDC Startup 5

If the ANDCConfig.NDC file is not found, full configuration is

required and the following steps are completed:
1 AppLoader.exe calls startapps.cmd, which calls startapps.vbs

2 The VBscript, startapps.vbs, calls

NCR.APTRA.NDC.SST.Configuration.exe and waits for
NCR.APTRA.NDC.SST.Configuration.exe to complete

3 NCR.APTRA.NDC.SST.Configuration.exe loads the SST

configuration component (ANDCSST.xml)

4 The SST configuration component identifies the available XFS

services by checking the registry

5 The SST configuration component tries to open each service and

records the status, capability and vendor name for each
successfully opened service. If a service is available, it is
recorded in the Persistent Services List (PSL), as described in
“Persistent Service List” on page 5‐4. If a service is not available,
the Advance NDC alias is set to " " and the Active XFS alias is
set to "Not Used"

6 The SST configuration component identifies the configuration

actions in the ANDCSST.xml file that match the identified
services

7 The SST configuration component completes the required

actions

8 The SST configuration component creates the ANDCConfig.NDC

file

9 The SST configuration component may restart the SST to

complete the configuration

10 The VB script, startapps.vbs, calls Applicationcore.exe to start

Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-3

Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

On subsequent start‐ups, the following occurs:

 If the ANDCConfig.NDC file is found and new devices are
detected, the SST configuration component completes the
configuration actions defined for the new devices.
 If the ANDCConfig.NDC file is found and no new devices are
detected, no configuration is performed.
Persistent Service List The PSL includes all services that have 5

been identified as available. This ensures that they are not

configured again unless the ANDCConfig.NDC file is deleted.
If a service is not available, it is not included in the list and is
reopened each time the SST configuration component runs to check
whether it has become available. This allows devices that are
physically present, but temporarily unavailable to be configured
when they become available.
The PSL contains the SP name and the alias mapping information.

Table 5‐1 describes the elements used in the ANDCSST.xml file. The
ANDCSST.XML Elements 5

default file installed with Advance NDC is located in the following

folder:

C:\Program Files\NCR APTRA\Advance NDC\Config

Table 5-1
SST configuration component XML
Elements

Element Description

ANDCSSTConfiguration Mandatory.

This is the root element.

The whole file is enclosed within ANDCSSTConfiguration tags.

Nested elements:
 AppConfig
 Platform
 ANDCDevice
 ANDCActions

AppConfig Mandatory.

Allows for fine‐tuning of the configuration process.

The Timeout attribute defines the length of the time‐out applied when opening
XFS services.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-4 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

Element Description

Platform Optional.

Identifies the platform by the PIN Service vendor. If no PIN Service vendor is
provided, the vendor name is taken from the last service listed in the
HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES registry key.

The Vendor attribute identifies the name of the vendor. The string must match
the name given in the entries under the
HKLM\SOFTWARE\XFS\SERVICE_PROVIDERS key.

The WaitTime attribute specifies the time in milliseconds to wait between

stopping and attempting to restart the platform.

Nested elements:
 StartAndWait
 Stop

StartAndWait Mandatory.

Defines the Microsoft batch processing commands used to start the platform and
wait for the start process to complete.

Stop Mandatory.

Defines the Microsoft batch processing commands used to stop the platform.

If this command fails and the Unhandled Exception Handler (UEH) is installed
and configured to reboot the SST, the SST is rebooted.

ANDCDevice Mandatory.

Identifies the XFS device. This is used to associate the instance of the device with
the XFS service and describes the configuration for the device.

The alias attribute contains the Advance NDC alias for the device and is used to
populate the Aliases registry entries. There must be one ANDCDevice element for
each entry under the HKLM\SOFTWARE\Advance NDC\Aliases registry key.

The Active XFS alias registry entries under the HKLM\SOFTWARE\ActiveXFS

key are also populated by the SST configuration component.

Nested elements:
 Identification
 Configuration

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-5

Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

Element Description

Identification Mandatory.

Identifies the XFS service.

This is achieved by matching the following attributes to data retrieved from the
XFS service:
 xfsclass. The name of the CEN XFS class
 xfsclasstype. The CEN fwType Capability used to determine the use of
the class
 compound. Whether the class is a compound class. This can have a value of
True, False or N/A. A value of N/A indicates that this attribute is not used
for identification
 xfsclasssubtype. Differentiates devices of the same subtype. This is used
only to differentiate different types of scanners of the printer class.

Note: Compound devices are identified by their class, for example cash‐recycling
devices have two Identification elements, one for CIM and one for CDM.

Configuration Mandatory.

Describes how to configure the device identified in the Identification

element.

Nested elements:
 Configure
 Vendor

Configure Mandatory.

Describes the actions taken to configure the device. The actions apply to all
instances of the device identified in the ANDCDevice element regardless of
vendor.

The Actionlist attribute identifies the ActionList element containing the

configuration instructions. The Actionlist attribute must match the name
attribute of the ActionList element for the configuration. If no match is found,
an error is written to the PD log but processing continues.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-6 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

Element Description

Vendor Optional.

Describes how to configure the device identified in the Identification

element for a specific vendor.

The SST configuration component searches the Vendor elements until it matches
the vendor name retrieved from the XFS registry area.

The name attribute contains the name of the vendor as entered in the
HKLM\SOFTWARE\XFS\SERVICE_PROVIDERS registry key.

Nested elements:
 Configure

Note: When the Configure element is placed below the Vendor element, the
configuration instructions apply only to the specified vendor.

 Provider

Provider Optional.

Identifies the service provider when specific settings need to be based on the
presence of that service provider.

The name attribute contains the name of the service provider as entered in the
HKEY_USERS\.DEFAULT\XFS\LOGICAL_SERVICES registry key.

Nested elements:
 Configure
 HardwareName

Note: When the Configure element is placed below the Provider element,
the configuration instructions apply only to the specified service provider.

HardwareName Optional.

Identifies the hardware installed on the SST where this cannot be determined
from the provider name.

The NameID attribute contains an identifier string for the hardware that can
appear in the extra detail in the XFS capabilities command. The string used must
uniquely identify the required hardware device from those supported by the
provider.

Nested elements:
 Configure

Note: When the Configure element is placed below the HardwareName

element, the configuration instructions apply only to the specified hardware.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-7

Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

Element Description

ANDCActions Mandatory.

Identifies the configuration actions performed on any supported SST. The actions
are identified by name and linked with the identified devices.

Nested elements:
 ActionList

ActionList Mandatory.

Contains the steps used in applying the named configuration.

The name attribute matches the Actionlist attribute of the Configure

element for the configuration.

The description attribute provides an optional free‐text description of the

configuration and is used for tracing to Problem Determination.

Nested elements:
 Action
 ClassConfiguration
 FileOperation

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-8 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

Element Description

Action Mandatory.

Describes the settings to apply to the Windows registry or file system for the
identified configuration.

The implements attribute identifies the action to be applied to the registry or a

file as follows:

registry Contains a registry setting in the format of Microsoft

.rgs files. For details of these files, refer to
http://support.microsoft.com/kb/310516

Note: The RegistryEditorVersion part of the .rgs

file syntax is not required as this is added by the
component.

reservedregistry Contains a registry setting that is only applied where a

condition defined in the description attribute occurs
in the related component

file Contains a file copy operation in the following format:

<full source path>||<full destination
path>
The source file is copied to the path specified as the
destination. If the destination file already exists, it is
deleted before the copy is performed
Alternatively, you can use the FileOperation
element

reservedfile Contains a file copy operation that is only applied

where a condition defined in the description attribute
occurs in the related component

If the implements attribute is set to reservedregistry or reservedfile,

the description attribute can define the following conditions:
 CDMHWSensorsPresent. The action is applied only if there are hardware
sensors on the CDM cassettes
 CDMHWSensorsNotPresent. The action is applied only if no hardware
sensors are present on the CDM cassettes

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-9

Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

Element Description

ClassConfiguration Describes the settings to apply to the .NET Class Configurator files for the
identified configuration. For further information on the .NET Class Configurator
files, see “.NET Class Configurator Files” on page 5‐40.

The classID attribute identifies the class to update using the class ID used in the
.NET Class Configurator file

The property attribute identifies the property to update within the specified
class ID

The setvalue attribute identifies the new default value to apply to the specified
property

The file attribute specifies the .NET Class Configurator file containing the
specified class ID. This attribute is not required if this is the AdvanceNDC.accfg file

The description attribute provides an optional free‐text description of the

configuration and is used for tracing to Problem Determination.

FileOperation Provides an alternative to using the file value in the Action element

The source attribute defines the source file to copy

The destination attribute defines the target file. If the target file is already
present, it is deleted before the copy is performed. If the path does not exist, it is
created

The operation attribute is always copy

The description attribute provides an optional free‐text description of the

configuration and is used for tracing to Problem Determination

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-10 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

The following sections provide examples of configuration settings

Example ANDCSST.XML defined in the ANDCSST.xml file.
Extracts 5

The following example is an extract from the ANDCSST.xml file. A

fuller default XML file is supplied with the APTRA Advance NDC.

Figure 5-1
Example SST XML Extract 1
<ANDCSSTConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="ANDCSST.xsd">
<!-- Application Configuration -->
<!-- 5 minutes timeout. Do not change this value -->
<AppConfig Timeout="49400"/>
<Platform Vendor="NCR Corporation">
<StartAndWait>ulwait.exe /w 1800 /e</StartAndWait>
<Stop/>
</Platform>
----
----
----
----
</ANDCSSTConfiguration>
<!--
Configurations not applied as default in AdvanceNDC.reg file

Receipt Printer XML 5

The following extracts set up a receipt printer for use by Advance

NDC.
Defining the Alias The alias for the device in the registry is set as 5

follows:
<ANDCDevice Alias="Receipt Printer">

If an XFS receipt printer service is found, the following registry

setting is populated with the logical service name:
HKLM\SOFTWARE\NCR\Advance NDC\Aliases

For further information on aliases, see “CEN‐XFS Logical Device

Names” on page 5‐17.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-11

Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

Receipt Printers on NCR SSTs The following extract shows the 5

device section of the ANDCSST.xml file for receipt printers on an

NCR SST:

Figure 5-2
Example SST XML Extract 2
<ANDCDevice Alias="Receipt Printer">
<Identification xfsclass="WFS_SERVICE_CLASS_PTR" xfsclasstype="WFS_PTR_TYPERECEIPT"
compound="False"/>
<Configuration>
<Configure actionlist="General Receipt Forms Parameters"/>
<Configure actionlist="BMP Conversion"/>
<Configure actionlist="Receipt Forms debug off"/>
<Configure actionlist="General Receipt Forms Controls"/>
<Configure actionlist="General Receipt Forms LPI"/>
<Configure actionlist="General Receipt Fonts"/>
< Vendor name="NCR Corporation">
<Configure actionlist="NCR Receipt Forms Parameters"/>
<provider name="ReceiptPrinter1">
<!-- SDC printers -->
<HardwareName NameId="RPNT-01-PcThermal">
<Configure actionlist="NCR SDC Receipt Rawdata"/>
<Configure actionlist="Set Receipt printer Dynamic forms off"/>
<Configure actionlist="Promote Coupon Receipt Low Res"/>
</HardwareName>
<!-- Universal Printers -->
<HardwareName NameId="RPNT-01-UsbThermal">
<Configure actionlist="Set Receipt printer Dynamic forms on"/>
<Configure actionlist="NCR Universal Receipt Raw Data"/>
<Configure actionlist="Promote Coupon Receipt High Res"/>
</HardwareName>
<!-- Leap Printer -->
<HardwareName NameId="RPNT-01-UsbThermal,DEVVAR=8">
<Configure actionlist="Leap Printer"/>
<Configure actionlist="Set Receipt printer Dynamic forms on"/>
</HardwareName>
</provider>
</Vendor>
</Configuration>
</ANDCDevice>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-12 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Automatic Configuration at Start-up

BMP Conversion Action The following extract shows the 5

definition of the actions to take to covert graphics files to BMP files

for forms printing:

Figure 5-3
Example SST XML Extract 3
<ANDCActions>
<ActionList name="BMP Conversion">
<Action description="graphic file extensions to replace with .BMP for forms printing."
Implements="registry">
[HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\PRINTING]
/FORMS_GRAPHICS_EXT="PRN,GPH,LGO"
</Action>
</ActionList>
</ANDCActions>

This configuration is applied to every receipt printer as the

configuration is defined at device level rather than vendor or
provider level.

Defining Class Sub‐Types 5

The following extract differentiates a barcode reader and a CPM

from other types of scanner and printer classes:

Figure 5-4
Example SST XML Extract 4
<ANDCDevice Alias="Barcode Reader">
<Identification xfsclass="WFS_SERVICE_CLASS_PTR" xfsclasstype="WFS_PTR_TYPESCANNER"
xfsclasssubtype="WFS_PTR_READBARCODE"/>
</ANDCDevice>

<ANDCDevice Alias="Cheque Processor">

<Identification xfsclass="WFS_SERVICE_CLASS_PTR"
xfsclasstype="WFS_PTR_TYPESCANNER"/>
</ANDCDevice>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-13

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Configuring an Advance NDC

Application 5

This section describes the configuration settings used by Advance

NDC.
For details of configuring troubleshooting utilities, see Chapter 12,
“Installing and Configuring Troubleshooting Tools”.

The root registry key for Advance NDC is as follows:

Advance NDC Registry HKLM\SOFTWARE\NCR\Advance NDC
Entries 5

All registry settings for Advance NDC are in subkeys of this entry.

Registry Entry for Application Links 5

The registry includes the DLL location for authored state types, the
cardholder session, the Supervisor session and the transaction reply
functions as string values under the following key:
HKLM\SOFTWARE\NCR\Advance NDC\Application Links

Transaction reply functions and states are executed using the SSDS
DLL Interface worker and the load methods available (either load at
start of day or on activation of the worker) apply only to them. State
types are initiated from the STCONT file and executed using the
NDC Processing State Executor worker.
The string value must specify the name of the APTRA Author
Application DLL to be loaded, with or without a fully qualified
path. The format for a string value added to a *.reg file is as follows:
<Application Link>=<DLLNAME>

The default values, which are provided in AdvanceNDC.reg, are as

follows:

Figure 5-5
Example Advance NDC Registry Extract
"Reply Function Deposit And Print"="ReplyDepositAndPrint"
"Reply Function Dispense And Print"="ReplyDispenseAndPrint"
"Reply Function Display And Print"="ReplyDisplayAndPrint"
"Reply Function Print Immediate"="ReplyPrintImmediate"
"Reply Function Next State And Print"= "ReplySetNextStateAndPrint"
"Reply Function Night Safe Deposit"= "ReplyNightSafeDepositAndPrint"
"Reply Function Fast Cash"= "ReplyParallelEjectDispenseAndPrint"

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-14 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

"Reply Function Card Before Cash"="ReplyCardBeforeCash"

"Reply Function Card Before Dispense And Print"= "ReplyCardBeforeParallelDispenseAndPrint"
"Reply Function Print Statement And Wait"= "ReplyPrintStatementAndWait"
"Reply Function Print Statement And Next State"= "ReplyPrintStatementAndSetNextState"
"Reply Function BNA Refund"="ReplyBNARefundAndSetNextState"
"Reply Function BNA Encash"="ReplyBNAEncashAndSetNextState"
"Reply Function BNA Encash And Wait"="ReplyBNAEncashAndWait"
"Reply Function Process Cheque"="ReplyProcessCheque"
"Reply Function Process Multiple Cheques"= "ReplyProcessMultipleCheques"
"Reply Function Deposit Then Dispense"= "ReplyCashDepositThenDispense"
"Reply Function Dispense Then Deposit"= "ReplyCashDispenseThenDeposit"
"Cardholder Session"="CustomisationLayer"
"Supervisor Session"="Supervisor"
"Suspend Mode"="SuspendMode"
"BNA Start Of Day"="BNAStartOfDay"
"BNA Event Monitor"="BNAEventMonitor"
"BNA Close State"="BNACloseState"
"BNA Reconfigure Cassettes"="BNAReconfigureCassettes"
"BNA Tamper Indication"="BNATamperIndication"
"State Card Read"="StateCardRead"
"State Insert Card"="StateInsertCard"
"State PIN Entry"="StatePINEntry"
"State Transaction Request"="StateTransactionRequest"
"State Close"="StateClose"
"State Card Write"="StateCardWrite"
"State PIN Entry"="StatePINEntry"
"State Customer Selectable PIN"="StateCustomerSelectablePIN"
"State Cash Accept"="StateCashAccept"
"State Cheque Accept"="StateChequeAccept"
"State Smart FIT Check"="StateSmartFITCheck"
"State PIN And Language Select"="StatePINAndLanguageSelect"
"State Web Exit"="StateWebExit"
"State Cardholder Authorised Verification"= "StateCardholderAuthorisedVerification"
"State Barcode Read"="StateBarcodeRead"
"State Camera Control"="StateCameraControl"
"State FIT Search"="StateFITSearch"
"State Prepare Dispense"="StatePrepareDispense"

The name is fixed (for example, State Close) but you can change
the data value (for example, StateClose) to point to your own DLL.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-15

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

The default registry settings do not specify a path and assume the
DLLs will be loaded at start of day. The format of the string data is
as follows:
DLLNAME[;LoadMethod]

The DLLNAME value is the name of the authored DLL and can include
a fully qualified path. If the path is not specified, the standard
search strategy is used to find the DLL.
The LoadMethod parameter is optional. If it is not specified, the
semi‐colon (;) may also be omitted and the default value is assumed.
If specified, it must be preceded by the semi‐colon. Values for
LoadMethod are case sensitive as follows:
 PRELOAD — DLL to be loaded at start of day (the default)
 ONSTART — DLL to be loaded the first time the worker is started

Examples of Application Links 5

The following table shows the format of the optional elements of the
registry settings:

Table 5-2
Examples of Application Links

Registry Entry Data Value Description

C:\Program Files\NCR APTRA\Advance NDC\DLL\APP1.DLL ; Loads the DLL in the specified

PRELOAD location at start of day.

APP1.DLL ; ONSTART Searches for APP1.DLL and loads

the DLL when the worker is started

APP1.DLL Searches for APP1.DLL and loads

the DLL at start of day

Performance and Memory Considerations 5

Performance and memory requirements dictate which load method

to use for each DLL, as follows:
 PRELOAD causes the delay for loading the DLL to occur at start of
day. There will therefore be no delay when the SSDS DLL
Interface worker is started. Memory will always be allocated for
the DLL resulting in an increased memory footprint for the
application. Use this load method when the worker is likely to
be started during the execution of the application.
 ONSTART causes the delay for loading the DLL to occur when the
worker is started for the first time only. There will be a delay
during the execution of the application, but if the worker is
never started, no memory will be allocated resulting in a smaller

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-16 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

memory footprint for the application. Use this load method

when the worker is unlikely to be started during the execution
of the application.

When a CEN‐XFS session is opened, WFSOpen(), a logical device

CEN‐XFS Logical Device name is supplied, for example, PinPad1 on NCR SSTs. As this
Names 5
name is vendor‐dependent, Advance NDC defines configurable
device‐name aliases in the registry to handle it, as described in
Chapter 5, “Setting up the Terminal” of the Multi‐Vendor Support
Reference Manual. The values defined by these configurable aliases
should be used to open a CEN‐XFS session. The registry key is the
following:
HKLM\SOFTWARE\Advance NDC\Aliases

Note: A single SST can be configured for either an envelope

depository or a cheque processor, but not both. If both devices are
attached, the device alias for the unused device must be removed
from the registry. For example, remove the device alias for the
Envelope Depository to use only a bunch cheque acceptor.

On NCR SSTs, the settings are as follows:

Table 5-3
Aliases for Device Names

Device Name Alias NCR SP Device Name

Card Reader IDCardUnit1

Card Reader Second Contactless1

Cash Dispenser CurrencyDispenser1

BillDispenser1

Cash Dispenser Second CurrencyDispenser2

CurrencyDispenser1 (if Cash Dispenser is set to
BillDispenser1)
BillDispenser1 (if Cash Dispenser is set to
CurrencyDispenser1)

Coin Dispenser CoinDispenser1

Cash Acceptor See “Active XFS Aliases for Cash and Cheque
Acceptors” on page 5‐18

Night Safe NightSafe1

Journal Printer JournalPrinter1

Document Printer StatementPrinter1

Receipt Printer ReceiptPrinter1

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-17

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Device Name Alias NCR SP Device Name

Passbook Printer PassbookPrinter1

PIN Pad PinPad1

Sensors, Doors and Indicators SIU

Envelope Depository Envelope1

Text Terminal Unit TextTerminalUnit1

Vendor Dependent Mode VendorDependentMode1

Cheque Processor ChequeProcessor1

IPM ItemProcessing1

Barcode Reader BarcodeReader1

Security Camera Camera1

These aliases contain different values for every vendor. The

configuration of these values is part of the vendor‐specific setup.

Note: Not all these aliases are currently being used in Advance
NDC.

Active XFS Aliases are set to point to the appropriate service

Active XFS Aliases for provider for the cash or cheque acceptor hardware variant in use
Cash and Cheque under the following registry entry:
Acceptors 5

HKLM\SOFTWARE\ActiveXFS\Aliases\

The following extract is an example for Active XFS Aliases:

Figure 5-6
Example Active XFS Aliases
HKLM\SOFTWARE\ActiveXFS]"CashInModule1"="CashInModule1"
"CurrencyDispenser1"="CurrencyDispenser1"
"PinPad1"="Pinpad1"
"ReceiptPrinter1"="ReceiptPrinter1"
"SIU"="SIU"
"StatementPrinter1"="StatementPrinter1"
"VendorDependentMode1"="VendorDependentMode1"

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-18 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Table 5‐4 lists the Active XFS aliases, the service provider device
name values and the hardware variants.

Table 5-4 ActiveXFS Alias SP Device Name NCR Hardware Variant

ActiveXFS Aliases
CashInModule1 CashInModule1 BNA, SNA, SDM
BillAcceptor1 GBRU, GBNA, BRM
BRMAcceptor1

ItemProcessing1 BunchCheque1 Bunch cheque acceptor

For further information on the service providers, refer to the

APTRA on‐line documentation under ActiveXFS Controls.

As devices are accessed through the CEN‐XFS interface, the status

Status Handling 5

information from XFS is mapped to the corresponding Advance

NDC status.

No configuration is required as Advance NDC fully controls the

Remote Status Indicators 5

Remote Status Indicators (RSIs). The operation of the RSIs

corresponds to the information given in the Fault Display option of
the Supervisor Select menu. For details of RSIs, refer to Chapter 7,
“Error and Exception Reporting and Recovery” in the APTRA
Advance NDC, Supervisor’s Guide.

Advance NDC can send unsolicited status messages to the host for a
Unsolicited Status system event (WFS_SYSTEM_EVENT) that occurs on a device in
Messages for External response to a command issued in another process, even though
System Events 5 there is no outstanding WFS command in Advance NDC (no
execute command is issued in Advance NDC).
This feature can be used for Exits, web Exits and external
applications that access SST devices but cannot handle the system
events caused by device errors. The Exits and external applications
must be CEN‐compliant and supported by NCR.
This feature applies to all devices. It is enabled through the
following DWORD registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\Extensions\
External System Events\ProcessSystemEventsForAllDevices

Valid values are as follows:

 0 = disabled (the default)
 1 = enabled
If the value is invalid or does not exist, the feature is disabled.
If the feature is enabled, Advance NDC sends an unsolicited status
message to the host whenever a system event occurs for a device. In

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-19

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

certain situations, this can result in duplicate unsolicited status

messages being sent to the host, for example, when an execute
complete message is followed by a system event message.

Unsolicited Status Messages for Cash Handlers 5

A suspend unsolicited status message can be sent at any time to the

host when a cash handler enters Suspend mode and Enhanced
Present Sequence 2 (EPS 2) / Dispenser Security Enhancement
hardware is present. The EP allows the dispenser severity to be set
to suspend when tampering is suspected.
The sending of suspend unsolicited status messages is enabled
using the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\Extensions\
External System Events\EPEnabled

Valid values (DWORD) are as follows:

 0 = disabled (the default)
 1 = enabled
If the value is invalid or does not exist, the cash handler severity is
not forced into Suspend mode and no suspend unsolicited status
message is reported to the host.

A power‐up message can be sent to the host when communications

Power‐Up Status Message 5

are restored. This is configured using the following DWORD

registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\PowerUpOnCommsRestore

Valid values are as follows:

 0 = Do not send (default)
 1 = Send

By default, some data is suppressed in certain device status

Registry Settings for messages sent to the host, for example, cardholder display fitness
Device Status Messages 5
status. The data can be included in the status messages by editing
the registry.

Cardholder Display 5

The following DWORD registry value configures whether the

fitness status for the cardholder display is included in fitness status
messages sent to the host:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\Network
SupressCardholderDisplayFitness

Valid values are as follows:

 1 = Do not send the fitness status (default)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-20 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

 0 = Send the fitness status.

Receipt Capture Bin 5

The following DWORD registry value configures whether the

supplies status and fitness status for the receipt capture bin are
included in status messages to the host:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\Network
SupressReceiptRetractBinSupplies

Valid values are as follows:

 1 = Do not send supplies/fitness status (default)
 0 = Send supplies/fitness status.

Advance NDC can use a web Exit to display screens and interact
Enabling Web Exits 5

with the consumer outside of Advance NDC. The Advance NDC

state flow is exited and full control passed to a web browser with no
need for a host change to the existing state flow.

Note: The web Exit maintains the web browser session using
Display Manager instead of the web Exit state control process. For
details of Display Manager, refer to the APTRA Advance NDC, User
Guide for Display Manager.
Enabling web Exits involves the following:
1 Altering the state flow to introduce the new state

2 Activating the web Exit state

3 On exiting the web Exit state on completion of the web Exit,

passing control back to Advance NDC.
The web Exit state can be executed anywhere within the state flow
where an Exit state can be executed.

Configuring the Web Exit State 5

To configure the web Exit state, complete the following steps:

1 Assign any available state type letter. This is used to represent
the state.

2 Associate state type parameters containing the state type and

state information for each web Exit state that can be executed.

3 Populate the state table parameters with the updated web state
parameters using local customisation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-21

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

4 Configure Internet Explorer so that the web pages used within

the web Exit state are added to the list of trusted web sites.
For more information on states see “Overview” on page G‐1. For
information on standard state table types supported in Advance
NDC, refer to chapter 2 “State Tables” of the APTRA Advance NDC,
Reference Manual.
Appendix G, “User‐Configurable States” provides the following
information on enabling web Exits:

Table 5-5 Item Description

Enabling Web Exits
State table parameters To control the behaviour of the web
Exit.

Tracking URLs To communicate the state of the web

browsing to Advance NDC

Extension to Web Exit state To specify the state numbers to execute

WebExitURLTable.xml To get the URL path, based on the URL

index table entry in the Web Exit state
flow

Adding Exit web pages to To allow cross‐frame security

the trusted sites zone

Updating STCONT To register the state type letter and

location of the web exit

Updating the state flow To call the Exit at the appropriate time

Local customisation data can be specified in files placed on the SST.

Specifying Local This data can be used to extend or modify data provided in host
Customisation Data 5
downloads. Local customisation data files are loaded at the
following points in the application:
 At Start of Day.
 After a go‐in‐service (GIS) message is received. Therefore,
software management can change local customisation files on
the SST allowing Advance NDC to read new customisation files
after receiving the GIS message.

Note: Keyboard mapping can also be defined using the local

customisation data. For details of associated keyboards, see
“Associated Keyboards for FDKs” on page 1‐29.

To use local customisation data, the following registry entry must

be set to ʹ1ʹ:

HKLM\Software\NCR\Advance NDC\Local Data Available

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-22 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

The files containing the customisation data are either defined within
the SCXLOC file or contained within the LOCAL file.
The SCXLOC file takes precedence, so if it is present on the SST, any
LOCAL file is ignored.
If neither file is found, no local customisation can take place.

Note: If you are testing on a development system, the SCXLOC

and LOCAL files, and any referenced files must be located in the
C:\NTGlobal\Final\XFS\Dll directory. This is the default path at
installation.

SCXLOC File 5

SCXLOC is a control file created on the SST and picked up from the
first location found, as defined in the path environment variable in
the System folder under the Windows Control Panel. The file
contains a list of files to be applied as local customisation files,
allowing you to define local customisation groups as separate files.
Each message is listed on a separate line, and the maximum file size
for SCXLOC is 1024 bytes.
All the files referenced must also be placed in the path defined in the
PATH variable on the SST. As some methods of file copying do not
support filenames with spaces, avoid using spaces in the filenames.
Any screens, states or FITs that are part of the host download, but
are not being locally customised should not be included in these
files.
The referenced files can contain multiple customisations, but each
customisation can be no more than 1024 bytes.
Example SCXLOC File The following is an example of an 5

SCXLOC file, referencing four files:

LOCSC1
LOCSC2
LOCST1
LOCFI1

Example Referenced Files The following list provides examples 5

of the four files referenced in the example SCXLOC file. The tags
used in the examples are defined as follows:

Table 5-6 Tag Hex Code Description

Tags Used in the Files Referenced in
SCXLOC <fs> 1CH Field separator

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-23

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Tag Hex Code Description

<ff> 0CH Clear screen character

<si> 0FH Shift in cursor position character

<etx> 03H End of text character.

Note: You must use this tag as a line delimiter as

the line‐feed or carriage return characters cannot
be used.

Note: The maximum length of each message is limited to 1024

bytes.

 LOCSC1:

The following example defines the locally customised screen

identified as 010:

3<fs><fs><fs>11<fs>010<ff><si>DDPLEASE INSERT YOUR

CARD<si>FDTO BEGIN A TRANSACTION<etx>

 LOCSC2:

The following example defines the locally customised screen

identified as 11:

3<fs><fs><fs>11<fs>011<fs><ff><si>EGWE ARE UNABLE<si>GDTO

PROCESS YOUR CARD<etx>

 LOCST1:
The following example defines the locally customised states
identified as 000 and 095:

3<fs><fs><fs>12<fs>000A010001011002002002001095<fs>095J01
1000011011011000011000<etx>

 LOCFI1:

The following example defines the locally customised FIT table

identified as 000:

3<fs><fs><fs>15<fs>00000025525525525525500000001200001500
0000
000255000000000000000000000000000000000000000000000000000
0000
00000<etx>

LOCAL File 5

The LOCAL file contains all locally customised screens, states and
FIT Tables in a single file. The file must be created in a directory
defined in the path variable.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-24 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Any screens, states or FITs that are part of the host download, but
are not being locally customised should not be included in this file.
The file is in message file format, which mimics the download from
the host.
The maximum length of a message is 1024 bytes.
Example LOCAL File The following is an example of a LOCAL 5

file, with definitions for locally customised screens identified as 010

and 011, states identified as 000 and 095, and a FIT table identified
as 000.
For an explanation of the tags used, see Table 5‐6, “Tags Used in the
Files Referenced in SCXLOC” on page 5‐23.
3<fs><fs><fs>11<fs>010<ff><si>DDPLEASE INSERT YOUR
CARD<si>FDTO BEGIN A TRANSACTION<fs>
011<ff><si>EGWE ARE UNABLE<si>GDTO PROCESS YOUR
CARD<etx>3<fs><fs><fs>12<fs>000A010001011002002002001095<fs>0
95J011000011011011000011000<etx>3<fs><fs><fs>15<fs>0000002552
5525525525500000001200001500000000025500000000000000000000000
0000000000000000000000000000000000000<etx>

A Transaction Reply message contains the state number for the next
Changing the Next State state to be executed. This configuration allows you to redirect the
Number 5
state number provided in the message without any host impact.
Redirecting the next state number is done through a configuration
file, StateTranslator.xml. As this file is not provided on the SST by
default, you must create it in C:\Program Files\NCR
APTRA\Advance NDC\Config. After creating the file, add the
elements and attributes as described in the example below.

Example of StateTranslator.xml 5

This is an example of changing the next state number from 300 to

500 and 400 to 600 for Transaction Request state number 123:

Figure 5-7
Example State Translator XML Extract
<StateTranslator>
<State Number=”123”>
<Translate NextStateNum=”300” TranslateTo=”500”/>
<Translate NextStateNum=”400” TranslateTo=”600”/>
</State>
</StateTranslator>

These elements and attributes are validated through the

StateTranslator.xsd file, which is available as part of the Advance
ANDC installation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-25

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Security camera configuration for USB cameras is defined using the

Security Cameras 5

NDCSecurityCamera.xml file.
The following extract is an example from the NDCSecurityCamera
.xml file:

Figure 5-8
Example Security Camera XML Extract
<SecurityCameraDevice DeviceId="1">
<Name>Camera1</Name>
<Instance>1</Instance>
<SnapshotsFolder Compression="false" Capacity="2000">C:\Program Files\NCR APTRA\Advance
NDC\Snapshots</SnapshotsFolder>
<Flowpoint Delay="2000" NoOfSnapshots="1" CameraPosition ="Person">000</Flowpoint>
<!-- N State -->
<Flowpoint Delay="2000" NoOfSnapshots="1" CameraPosition ="Person">002</Flowpoint>
<!-- Card Taken -->
<Flowpoint Delay="2000" NoOfSnapshots="1" CameraPosition="Person">007</Flowpoint>
<!-- Cash Presented -->
<Flowpoint Delay="2000" NoOfSnapshots="1" CameraPosition="Person">008</Flowpoint>
<!-- Cash Taken -->
<Flowpoint Delay="2000" NoOfSnapshots="1" CameraPosition="Person">024</Flowpoint>
<!-- Supervisor Test - always use NoOfSnapshots="1" -->
</SecurityCameraDevice>

Support for .NET components is provided through the NDC

Camera Service. This is configured as described in “Using the NDC
Camera Service” on page 5‐29.

Using the XML File 5

The NDCSecurityCamera.xml file can be updated through software

distribution, local modification or the XML Configuration
Download message. For details of the XML envelope that must be
used with the NDCSecurityCamera.xml file, see “XML Configuration
Files” on page 5‐37. For details of the XML Configuration Download
message refer to Chapter 10, “Central to Terminal Messages” of the
APTRA Advance NDC, Reference Manual.
The security camera schema, NDCSecurityCamera.xsd, defines the
structure of the configuration data as described in Table 5‐7,
“Security Camera XML Elements” on page 5‐27.
The NDCSecurityCamera.xml and NDCSecurityCamera.xsd files are
stored in the following location:
C:\Program Files\NCR APTRA\Advance NDC\Config

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-26 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Each camera can be configured for one of the following positions:

 Person
 ExitSlot
 Room

The camera positions are then set in the NDCSecurityCamera.xml file

for different flow points which further trigger the associated
camera.

Table 5-7
Security Camera XML Elements

Element Description

SecurityCameraClass Mandatory.

This is the root element.

The whole file is enclosed within SecurityCameraClass tags.

Nested elements:
 SecurityCameraDevice
 SnapshotsFolder
 Compression
 FlowPointType

SecurityCameraDevice Mandatory.

Appears only once.

Identifies the device as a security camera. The required DeviceID attribute

identifies the security camera being configured.

Nested elements:
 Name
 Instance

Name Mandatory.

Identifies the logical name of the CEN XFS camera device class.

Instance Mandatory.

The security camera device to which the configuration applies.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-27

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Element Description

SnapshotsFolder Mandatory.

Appears only once for each device.

Identifies the folder in which the camera files are stored. The optional Capacity
attribute fixes the size of the folder in megabytes (MB). The default capacity is
2000 MB. The optional Path attribute specifies the location of the folder in which
the camera files are stored. The default path is C:\Program Files\NCR
APTRA\Advance NDC\Snapshots. The path length must not exceed 220
characters.

Compression Optional.

Appears only once.

Identifies whether the images are to be compressed. Valid values are as follows:

0 ‐ Do not compress the images. This is the default

1 ‐ Compress the images.

FlowPointType Mandatory.

Identifies flow points in a transaction that triggers an associated camera to take a

picture. The required Name attribute identifies the flow point using the name
given in “Camera Flow Points” on page 5‐30. Each flow point can appear only
once.

Nested elements:
 Delay
 Number
 NoOfSnapshots
 CameraPosition

Delay Optional.

Identifies the delay in milliseconds between images taken by the security camera
at this flow point. The default is 2000, which is the minimum time required to take
and process an image.

Number Mandatory.

Identifies the flow point using the number given in “Camera Flow Points” on
page 5‐30.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-28 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Element Description

NoOfSnapshots Optional.

Identifies how many images should be taken by the security camera at this flow
point.

Valid values are as follows:

1 ‐ Take one image at this flow point (default)

2 ‐ Take two images at this flow point
3 ‐ Take three images at this flow point.

Note: For the Supervisor flow point, this must be set to 1.

CameraPosition Optional.

Identifies the camera that is used to take the image at this flow point. The default
is to use the first security camera be configured at feature‐level.

Valid values are as follows:

Room
Person
ExitSlot

Using the NDC Camera Service 5

The .NET Class Configurator creates the NDC Camera Service at

start of day as defined in the following extract from the
AdvanceNDCCore.accfg file:

Figure 5-9
Example Camera Service Configuration
Extract
<Class ID="NDCCameraService"
Name="NCR.APTRA.NDC.CameraService"
Assembly="NCR.APTRA.NDC.CameraService.dll" CreateAlways="true" >
</Class>

The NDC Camera Service implements the IJournalService

interface and is added as a configuration property to the following
flow classes in the NCR.APTRA.NDC.CashInFlows.dll assembly:
 NCR.APTRA.NDC.CashInFlows.CashAcceptStateFlow
 NCR.APTRA.NDC.CashInFlows.CashInCloseFlow
 NCR.APTRA.NDC.CashInFlows.EncashReplyFlow
 NCR.APTRA.NDC.CashInFlows.RefundReplyFlow

These classes define the camera service used to take pictures during
the transaction.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-29

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

The flow point is passed to the NDC Camera Service using the
DataRecord parameter of the Record method. The RecordType of
the DataRecord is a string representation of the flow point type, the
NDC Camera Service converts the RecordType to the flow point
number and sets CDI 1376 (Camera Flowpoint) before activating the
Take Picture worker.
To use a third‐party camera solution, you must write your own
camera service implementing the IJournalService interface.

Flow Points Defined for the Security Cameras 5

The flow points at which the security cameras are triggered are
predefined as described in Table 5‐8.

Table 5-8 Flow Point Number Flow Point Name

Camera Flow Points
000 N State

001 Card Inserted

002 Card Taken

003 Card Captured

004 PIN Entered

005 Transaction Request Sent

006 Transaction Reply Received

007 Cash Presented

008 Cash Taken

009 Card Ejected

010 Cash Retracted

011 Cash Deposit Enabled

012 Rejected Notes Taken

013 Notes Deposit Confirmed

014 Notes Deposit Cancelled

015 Receipt Taken

016 Notes Refunded

017 Refunded Notes Taken

018 Notes Inserted

019 Cheque Inserted

020 Cheque Taken

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-30 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Flow Point Number Flow Point Name

021 Cheque Ejected

022 Cheque Captured

023 Envelope Deposited

024 Supervisor Test

025 Cardless Initiation

026 CashPresented_2ndCamera

027 CashTaken_2ndCamera

028 Input Refused

029 Notes Encash Success

030 Notes Encash Failed

031 Notes Refund Failed

032 CashIn Retract Success

033 CashIn Retract Failed

Example of Adding Flow Points 5

The following extract shows the default configuration for the

SelfServ SSTs for the second camera:

Figure 5-10
Example Adding Flow Points Extract
<SecurityCameraClass xmlns="http://www.ncr.com/APTRA/NDC/SecurityCamera" xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ncr.com/
APTRA/NDC/SecurityCamera NDCSecurityCamera.xsd">
<SecurityCameraDevice DeviceId="1">
<Name>Camera1</Name>
<Instance>1</Instance>
<SnapshotsFolder>C:\Program Files\NCR APTRA\Advance NDC\Snapshots</SnapshotsFolder>
<Flowpoint>000</Flowpoint> <!-- N State -->
<Flowpoint>002</Flowpoint> <!-- Card Taken -->
<Flowpoint>007</Flowpoint > <!-- Cash Presented -->
<Flowpoint CameraPosition="ExitSlot" NoOfSnapshots="1" Delay="2000">026</Flowpoint >
<!--CashPresented_2ndCamera -->
<Flowpoint CameraPosition="ExitSlot" NoOfSnapshots="1" Delay="2000">027</Flowpoint >
<!--CashTaken_2ndCamera-->
<Flowpoint NoOfSnapshots="2" Delay="3000">008</Flowpoint> <!-- Cash Taken -->
</SecurityCameraDevice>
</SecurityCameraClass>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-31

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Customer‐sensitive data from Interactive Transaction Responses

Configuring Data Masking and Transaction Replies can be masked before the trace data is
and Logging 5
output to the MESSAGEIN trace stream of Silent Debug and
DebugLog. The masked data is replaced by asterisks.
If the application is compliant with the PCI DSS (Payment Card
Industry Data Security Standard), you must mask this data. For
more details of the PCI DSS, see Appendix E, “PCI DSS & PA‐DSS
Compliance in Advance NDC”.
Data sent to the journal, receipt and statement printers can be
logged to the OOXFS trace stream of DebugLog and Silent Debug or
the logging can be disabled.
The configuration for data masking in the MESSAGEIN trace stream
and printer data logging to the OOXFS trace stream can be changed
through the registry.

Interactive Transaction Response 5

Masking of the Screen Data field and the Trailer field (fields ‘j’ and
‘k’) is enabled or disabled using the following DWORD entry in the
registry:
HKLM\SOFTWARE\NCR\Advance NDC\Security\ITR MASKING

Valid values are as follows:

 0 = disable masking (show message data as sent from the host)
 1 = enable masking
The default value is 0. If an invalid value is specified or the key does
not exist, the default value is used.
When Advance NDC is installed, the value of this entry is explicitly
set to 1.

Masking of Buffer B and Buffer C 5

The Buffer B and Buffer C sent in the Transaction Request message

can be masked before the trace data is output to the MESSAGEOUT
trace stream of DebugLog or Silent Debug. The data is replaced with
asterisks for each character of Buffer B and Buffer C.
Masking is enabled or disabled using the following DWORD registry
entry:
HKLM\SOFTWARE\NCR\Advance
NDC\Security\MaskBufferBAndBufferC

Valid values are as follows:

 0 = Buffer B and Buffer C are not masked. This is the default
value.
 1 = Only Buffer B is masked.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-32 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

 2 = Only Buffer C is masked.

 3 = Both Buffer B and Buffer C are masked.
If the registry entry is not present or has an invalid value, Buffer B
and Buffer C will not be masked.

Note 2: If Buffer B and Buffer C are used to store secure

information, NCR recommends that the registry must be configured
to mask the Buffer B and Buffer C.
The following examples show the MESSAGEOUT trace stream extract:
When the registry MaskBufferBAndBufferC is set to 0, the
Transaction Request message with unmasked Buffer B and Buffer C
is as follows:

[1100011***************1251******************C F A
00000000******12345678]

When the registry MaskBufferBAndBufferC is set to 1, the

Transaction Request message with only Buffer B masked is as
follows:

[1100012***************1251******************C F A
00000000**********5678]

When the registry MaskBufferBAndBufferC is set to 2, the

Transaction Request message with only Buffer C masked is as
follows:

[1100013***************1251******************C F A
00000000******1234****]

When the registry MaskBufferBAndBufferC is set to 3, the

Transaction Request message with Buffer B and Buffer C masked is
as follows:

[110001**************************************C F A
00000000**************]

Transaction Reply 5

Masking of the Screen Display Update field and the Printer Data
field (fields ‘n’ and ‘r’ is enabled or disabled using the following
DWORD entry in the registry:
HKLM\SOFTWARE\NCR\Advance NDC\Security\TR REPLY MASKING

Valid values are as follows:

 0 = disable masking (show message data as sent from the host)
 1 = enable masking

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-33

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

The default value is 0. If an invalid value is specified or the key does

not exist, the default value is used.
When Advance NDC is installed, the value of this entry is explicitly
set to 1.

Printer Data Logging to the OOXFS Trace Stream 5

Printer data logging is enabled and disabled using the following

DWORD entry in the registry:
HKLM\SOFTWARE\NCR\Advance NDC\Security\ EXCLUDE PRINTER
DATA

Valid values are as follows:

 0 = log printer data
 1 = do not log printer data
The default value is 0. If an invalid value is specified or the key does
not exist, the default value is used.
When Advance NDC is installed, the value of this entry is explicitly
set to 1.

Masking of Track 2 Data 5

In an envelope deposit transaction, the track 2 data can be masked

while printing it on an envelope if there is no PPD data in the
transaction reply.
This is configured using the following DWORD registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\Security\PPD_Masking

Valid values are as follows:

 0 ‐ Do not mask the track 2 data in debug logs.
 1 ‐ Mask PAN only in the track 2 data (default).
 2 ‐ Mask the entire track 2 data including the PAN.

Masking of PAN 5

Advance NDC allows to configure the masking of PAN in track 2

data. The track 2 data contains the PAN number and this is masked
as it is customer sensitive information.
This is configured using the following DWORD registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\Security\PCI_Masking

Valid values are as follows:

 0 ‐ Unmask the last four digits of PAN in Track 2 data in debug
logs (default).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-34 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

 1 ‐ Unmask the first six digits of PAN in Track 2 data in debug

logs. If the PAN length is not more than six digits, the default
behaviour is applied
 2 ‐ Unmask the first six digits and last four digits of PAN in
Track 2 data in debug traces. If the PAN length is not more than
ten digits, the default behaviour is applied

The following Supervisor functions support the use of DVD drives:

Support for DVDs on SSTs 5

 COPY ON/OFF (on the Dialup Configuration menu)

 RETRIEVE ARCHIVE (on the Troubleshooting menu)
 PD INVESTIGATION (on the Troubleshooting menu)
 INIT EJRNL (Initialise electronic journal)
 RCOPY EJRNL (Recopy electronic journal)
 DIRECT EJ BACKUP
 AUTOMATIC INIT COPY DRIVE
 CREATE SIGS (Create signatures)
 EXTRACT SIGS (Extract signatures)

DVD drivers can also be used with Silent Debug.

Re‐writable and Dual‐layer DVDs 5

It is not possible to create multi‐sessions when writing to re‐writable

and dual‐layer DVDs. This means that if one of these DVD types is
inserted into the DVD drive and the DVD already contains some
data, then no further data can be written to it. There is no issue
creating multi‐sessions on CDs, DVD‐R or DVD+R DVDs.

The following configuration options are not supported:

Unsupported
 Cancel/Clear swap option
Configuration Options 5

 Download of keyboard definitions other than FDK associations.

The configuration settings for the Promote flow points described in

Promote Flow Point Table 5‐9, are stored in the in the following registry key:
Behaviour 5

HKLM\SOFTWARE\NCR\Advance NDC\Promote

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-35

Configuring Advance NDC and Associated Components
Configuring an Advance NDC Application

Table 5-9
Promote Flow Point Configuration
Flow Point Registry Entry Values

Approving Transaction Display Multiple Approving 0 = The flow point is displayed only
Transaction the first time the Transaction
Request state is executed in a
sequence of chained transactions.

1 = The flow point is displayed

every time the Transaction Request
state is executed in a sequence of
chained transactions (default).

Goodbye Close Flowpoint Location 1 ‐ The flow point is executed before

any device tidy‐up is performed.

2 ‐ The flow point is executed after

device tidy‐up is performed
(default).

Goodbye Close Flowpoint on 0 – The flow point is executed

Successful Transaction regardless of transaction success
status or card capture status.

1 – The flow point is executed if

the Last Status Issued byte in field ʹrʹ
of the Transaction Request
is set to 1 (good termination sent)
and the consumer’s card is
ejected successfully.
See Note 1: and Note 2:

For further information on Promote flow points supported by

Advance NDC, refer to the APTRA Promote User’s Guide.

Note 1: For chained transactions, the Last Status Issued byte is

updated for every Transaction Reply. Therefore, only the Last Status
Issued byte in the final Transaction Request is used to trigger the
flow point.

Note 2: If the Close Flowpoint on Successful Transaction is

set to 1, the Goodbye flow point is executed based on the Last Status
Issued byte if the following apply:

 The Close Flowpoint Location is set to 1. This also applies for

cardless transactions
 The Transaction Reply function ejects the card in the Close state.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-36 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuration Files

Configuration Files 5

Two types of configuration file are used to configure Advance NDC,

as follows:
 XML configuration files that can be updated through software
distribution, local modification or the XML Configuration
Download message from the host
 .NET Class Configurator files that are installed with Advance
NDC.
General information on each of these methods is provided in the
sections below. Further information on specific configuration
carried out using either of these methods is referenced from each
section.

If you are using an XML configuration file updated through the

XML Configuration Files 5

XML Configuration Download message, the configuration data in

field ‘j’ consists of two parts, as follows:
 Configuration Update Control. This is an XML envelope used
for all XML configuration files. For details, “Configuration
Update Control”, below
 Embedded configuration data. This is defined in a schema
specific to the device or feature being configured. For details of
the devices and features using XML configuration files, see the
following:
— “Security Cameras” on page 5‐26
— “Resetting USB Devices” on page 5‐94
— “Supervisor Alphanumeric Data Entry” on page 5‐105
— “Cardholder Alphanumeric Data Entry” on page 5‐122
— “Configuring Whole Amount Entry” on page 5‐136
— “Validating Buffer Data” on page 5‐139
— “Advance NDC Display Components” on page 5‐156
— “Barcode Reader Filter and Extraction Rules” on page 5‐210
— “Configuring Voice Guidance” on page 6‐7.
For details of the XML Configuration Download message refer to
the APTRA Advance NDC, Reference Manual.

Configuration Update Control 5

The Configuration Update Control encloses the device or

feature‐specific embedded configuration data. It defines the type of
configuration data included and how this is applied to any existing
configuration. The XML envelope schema,

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-37

Configuring Advance NDC and Associated Components
Configuration Files

NDCConfigurationControl.xsd, defines the structure of the data, as

illustrated in Figure 5‐11.

Figure 5-11
XML Envelope Schema
<?xml version "1.0" encoding="UTF-9"?>
<xs:schema xmlns="http://www.ncr.com/APTRA/NDC/ConfigUpdateControl"
xmlns:xs="http://www.w3.org/201/XMLSchema"
targetNamespace="http://www.ncr.com/APTRA/NDC/ConfigUpdateControl"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:element name="ConfiguationUpdateControl">
<xs:complexType>
<xs:sequence>
<xs:element name="UpdateMode">
<xs:complexType>
<xs:choice>
<xs:element name="ReplaceFile">
<xs:compleType/>
</xs:element>
<xs:element name="InsertNodeBefore">
<xs:complexType>
<xs:attribute name="NodePath" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="AddNodeAfter">
<xs:complexType>
<xs:attribute name="NodePath" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="ReplaceNode">
<xs:complexType>
<xs:attribute name="NodePath" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
<xs:element name="DeleteNode">
<xs:complexType>
<xs:attribute name="NodePath" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name="Content" type="xs:anyType" minOcurs="0"/>
</xs:sequence>
<xs:attribute name="Filename" type="xs:string" use="required"/>
</xs:complexType>
</xs:element>
</xs:schema>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-38 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuration Files

Note: Multiple XML declaration tags must not be included within

the body of XML data; therefore this tag must be omitted from the
embedded file. The XML declaration tag defined for the XML
envelope is used within the saved embedded file.

The XML envelope consists of an attribute that defines the file to be

updated and two nodes, as follows:
 The Update Mode node defines the type of update to be made,
as described in Table 5‐10, “Update Mode”
 The Content node contains the embedded configuration data, as
shown in “Example Replacement XML for a Barcode Reader”
below.

Table 5-10
Update Mode

Element Description

ReplaceFile Indicates that the whole file is to be replaced

InsertNodeBefore Indicates that the new data is to be inserted before the node identified by
the XLink definition in the NodePath attribute
Not supported

AddNodeAfter Indicates that the new data is to be added after the node identified by the
XLink definition in the NodePath attribute
Not supported

ReplaceNode Indicates that the new data is to replace the node identified by the XLink
definition in the NodePath attribute
Not supported

DeleteNode Indicates that the node identified by the XLink definition in the
NodePath attribute is to be deleted
Not supported

Example Replacement XML for a Barcode Reader Figure 5‐12 5

“Example Replacement XML” on page 5‐40 shows the content

passed in the XML Configuration Download when the Barcode
Reader file is to be replaced. The white space must be omitted in the
actual download, but is included here to aid legibility.

Note: The data can be split into more than one part if the length
exceeds the maximum message size.

For further information on the Barcode Reader configuration data,

see “Barcode Reader Filter and Extraction Rules” on page 5‐210.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-39

Configuring Advance NDC and Associated Components
Configuration Files

Figure 5-12
Example Replacement XML
<?xml version="1.0" encoding="UTF-"?>
<ConfigurationUpdatedControl xmlns="http://www.ncr.com/APTRA/NDC/ConfigUpdateControl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ncr.com/APTRA/NDC/ConfigUpdateControl
NDCConfigUpdateControl.xsd" Filename="NDCBarcodeReader.xml">
<UpdateMode>
<ReplaceFile></ReplaceFile>
</UpdateMode>
<Content>

<BarcodeReaderClass xmlns="http://www.ncr.com/APTRA/NNDC/BarcodeReader" xmlns:xsi=

"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ncr.com/
APTRA/NDC/BarcodeReader NDCBarcodeReader.xsd">
<BarcodeReaderDevice DeviceID="f">
<Name>Barcode1</Name>
<Instance>1</Instance>
<BarcodeFilter>
<Index>1</Index>
<Offset>0</Offset>
<Filter>1234@@45</Filter>
</BarcodeFilter>
<BarcodeFilter>
<Index>2</Index>
<Offset>0</Offset>
<Filter>Bill%%12345@@</Filter>
</BarcodeFilter>
<BarcodeExtractionRules>
<Rule ID=””>
<Pattern></Pattern>
<DestinationDataOffset></DestinationDataOffset>
</Rule>
</BarcodeExtractionRules>
</BarcodeReaderDevice>
</BarcodeReaderClass>

</Content>
</ConfigurationUpdateControl>

The .NET Class Configurator instantiates and configures objects

.NET Class Configurator used by an application as defined in XML files with a file extension
Files 5
of accfg.
Advance NDC uses the .NET Class Configurator for the
initialisation and configuration of many of the internal .NET
components.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-40 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuration Files

For details of the .NET Class Configurator, including details of the

XML schema, refer to the APTRA online documentation under
.NET Class Configurator.
The following files contain configuration settings that are applied in
order by the .NET Class Configurator:
1 AdvanceNDC.accfg

2 AdvanceNDCCore.accfg

3 AdvanceNDCCustom.accfg

4 CashInCore.accfg

5 CashInCustom.accfg

6 SupervisorReceiptConfig.accfg

7 NDCLocalTxReceiptConfig.accfg

8 NDCCRMReceiptConfig.accfg

9 TcpipSupportTaskReceiptConfig.accfg

AdvanceNDC.accfg 5

This file is used to aggregate all individual configuration files and is

not intended for any customisation.

AdvanceNDCCore.accfg 5

This file contains core definitions needed for optimal functioning of

the system and is not intended for any customisation.

AdvanceNDCCustom.accfg 5

This file contains definitions which can be customised. XML

comments are added to the configuration properties wherever
appropriate explaining the possible values so that users can modify
them easily.

CashinCore.accfg 5

This file contains Class Configurator definitions that are not

intended to be modified by Advance NDC users. The way the
defined Class ID and Array ID instances are interconnected
generally never changes.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-41

Configuring Advance NDC and Associated Components
Configuration Files

CashinCustom.accfg 5

This file contains Class Configurator definitions that users may have
to change to implement their special requirements. Examples are
the customisation of hooks, the customisation of the cash‐in
confirmation screen, the localisation of journal entries, and the
setting of some configurable parameters such as the Error Recovery
mode.
The default contents of this file shows the default configuration of
Advance NDC.

SupervisorReceiptConfig.accfg 5

This file contains the media definition for receipts issued in

Supervisor mode.

NDCLocalTxReceiptConfig.accfg 5

This file contains the media definition for offline receipts.

NDCCRMReceiptConfig.accfg 5

This file contains the media definition for receipts printed by

APTRA Promote or APTRA relate.

TcpipSupportTaskReceiptConfig.accfg 5

This file contains the media definition for receipts printed by TCP/IP
supervisor task.

Caution: Do not edit any content in CashInCore.accfg, AdvanceNDC.accfg or

AdvanceNDCCore.accfg, unless an editing requirement is explicitly
stated in this publication.

The class configurator files are installed to C:\Program Files\NCR

APTRA\Advance NDC\Config. Advance NDC loads the
AdvanceNDC.accfg file, which contains entries to include other .accfg
files in the order that they appear.

Conventions For Multiple Files 5

The definition of Class ID elements can be split among multiple files

as the .NET Class Configurator merges the definitions. If there is
any duplication or overlap, any later definitions replace the earlier
definitions.
The .NET Class Configurator does not merge Array ID definitions,
and later definitions in any file fully replace any earlier definitions
whether or not there is any duplication or overlap.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-42 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuration Files

Creating Classes 5

The following entry in a class configurator file creates an AANDC

Configuration class, based on the
NCR.APTRA.Configuration.Registry implementation class in the
NCR.APTRA.Configuration.dll file:
<Class ID=”AANDC Configuration”
Name=”NCR.APTRA.Configuration.Registry”
Assembly=”NCR.APTRA.Configuration.dll”/>

The following entry in a class configurator file creates an NDC

Configuration class, based on the
NCR.APTRA.NDC.Configuration.ConfigurationData
implementation class in the NCR.APTRA.NDC.Configuration.dll file:
<Class ID=”NDC Configuration”
Name=”NCR.APTRA.NDC.Configuration.ConfigurationData”
Assembly=”NCR.APTRA.NDC.Configuration.dll”/>

Class Configurator Files 5

For further Advance NDC configuration defined using a class

configurator file, see the following sections:
 “Configuring .NET Archive Manager” on page 5‐65
 “Configuring .NET Retrieve Archive Task” on page 5‐82
 “Configuring the .NET NDC CRM Service” on page 5‐86
 “Integrating New or Existing .NET Supervisor Tasks” on
page 5‐110
 “Promote/Copyfile” on page 5‐116
 “Relate Supervisor Option” on page 5‐116
 “Confirmation Screens During Cash Deposit” on page 5‐126
 “Advance NDC Display Components” on page 5‐156
 “Advance NDC Display Runtime Settings” on page 5‐176
.NET Assemblies Component Configuration For details of the 5

contents of the .NET Assemblies for Advance NDC, refer to Chapter

4, “The Advance NDC Package” of the APTRA Advance NDC,
Overview.
For further configuration settings for components included in the
.NET Assemblies for Advance NDC component, see the following
sections:
 “TCP/IP Configuration” on page 5‐45
 “Configuring Cash Acceptors” on page 5‐313
 “Bunch Cheque Acceptor” on page 5‐422
 “ImageMark Passport ATM Image Agent” on page 5‐426

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-43

Configuring Advance NDC and Associated Components
Configuring Communications

Configuring Communications 5

Some of the settings described in this section can be accessed

through the Configure menu in Supervisor. Changes made using
the Configure menu overwrite changes made through the registry
entries. NCR recommends using the Configure menu to change
these settings.
For details of the configuration options available through the
Supervisor, refer to chapter 4, “Configure Menu” of the APTRA
Advance NDC, Supervisor’s Guide.

The service class specifies the communications type configured on

Service Class 5

the SST and is specified through the following registry entry

HKLM\SOFTWARE\NCR\Advance NDC\VPIComms\VPICommsServiceProgID

This setting can be configured through the Select Communications

Type option on the Supervisor Configure menu.

TCP/IP Setting 5

The setting for TCP/IP is the default, as follow:

NCRaVPITCPIP.TCPIPCommsService

Advance NDC will use the .NET VPITCPIP component at runtime.

CCM PCCM Setting 5

For SSTs using a PCCM‐based protocol, change the setting to the

following:
NCRaVPIPCCM.PCCMCommsService

For details of PCCM, refer to the following:

 APTRA Communications Feature, User’s Guide
 APTRA Documentation | CCM PCCM.

CCM VISA2 Setting 5

For SSTs using CCM VISA2, change the setting to the following:
NCRaVPIVISA2.VISA2CommsService

On power up or following a communications recovery, the

Clearing the communications buffer can be cleared to prevent the host receiving
Communications Buffer 5
confusing responses due to message buffering. Clearing the buffer is
set using the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\VPIComms\ClearCommsBuffer

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-44 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Communications

Valid values are as follows:

0 ‐ clear the communications buffer (default).
1 ‐ retain the messages in the communications buffer.

When off‐line mode is entered, Advance NDC checks every five

Off‐line Timer 5

seconds whether communication has been re‐established by the

communications protocol. If the communications connection is
re‐established, this timer is cancelled. If the connection is not
re‐established before this timer expires, the communications link is
closed for 10 seconds, then re‐opened. This timer and the
five‐second test of the communications state are then restarted.
To configure the number of seconds before timer expiry, edit the
following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\VPIComms\OffLineTimer

The default value is 600 seconds and the valid range of values is
0‐99999.

TCP/IP configuration is supported through the .NET VPITCPIP

TCP/IP Configuration 5

component, which allows SSTs to connect to a TCP/IP network

providing extended security options to comply with PA‐DSS.

Configuring TCP/IP 5

The .NET VPITCPIP component supports the following:

 IPv4 and IPv6 protocols
 Secure Sockets Layer/Transport Layer Security (SSL/TLS) for the
encryption of transmitted data and the decryption of received
data. Valid certificates are required for successful
communications.
In Supervisor, options on the Configure menu allow the
configuration of the TCP/IP settings as well as Windows, firewall
and SSL/TLS settings, and some diagnostics features such as PING.
Configuring TCP/IP through Supervisor applies only to the Local
Area Connection. For details of configuring other connections, see
“Configuring Network Connections and Communications Links”
on page 5‐46.
The .NET VPITCPIP Supervisor tasks are responsible for displaying
Supervisor screens and updating the
TCPIPCommunicationsServiceConfig.xml file, located in the
C:\Program Files\NCR APTRA\Advance NDC\Config folder.
Normally, this file does not need to be modified directly but it can
be used to deploy the same settings across a whole network without
configuring each SST separately through Supervisor.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-45

Configuring Advance NDC and Associated Components
Configuring Communications

If any of the TCP/IP configuration parameters are modified through

the Configure menu, a reboot is required before the change is
recognised by .NET VPITCPIP or for the update of the local network
configuration to take effect. After making such changes, the
operator is given the opportunity to reboot immediately or later.
The registry setting to enable TCP/IP is described in “Service Class”
on page 5‐44.
For more information about TCP/IP configuration, refer to the
APTRA online documentation under .NET CCM TCPIP.
Domain Name Server If you are using .NET VPITCPIP and want 5

to configure a domain name server (DNS), you must make updates

using the TCP/IP Configuration menu in Supervisor through option
11, DNS Address. For IPv6, only the primary DNS can be entered.
XP Keep Alive This option can be enabled or disabled through 5

option 17 on the TCP/IP Configuration menu. The Keep Alive

option is enabled by default. When enabled, the Keep Alive settings
are controlled by the following registry entry:
HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters

The values are in milliseconds for the following:

KeepAliveInterval
KeepAliveTime

Note: If a message exceeds 4 KB in size, a command reject will be

returned.

SSL/TLS Configuration The Secure Socket Layer/Transport Layer 5

Security (SSL/TLS) is enabled and disabled using option 18 on the

Supervisor TCP/IP Configuration menu. SSL/TLS supports the
encryption of transmitted data and the decryption of received data.
Optionally, you can add, edit or delete the details of received and
supplied certificates using the Received Certificate Issuer, Received
Certificate Subject, Supplied Certificate Identifier and Supplied
Certificate Subject options. Selecting any of these options calls the
corresponding .NET TCP/IP Supervisor task and updates the
corresponding entry in the TCPIPCommunicationsServiceConfig.xml
file.

Configuring Network Connections

and Communications Links 5

When there are multiple network connections present on the SST

and you want any one of the network connections other than the
Default Connection, you need to update the configuration file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-46 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Communications

Network Connections The ConnectionNameToUpdate property 5

in the AdvanceNDCCustom.accfg file specifies the network

connection to be configured when there are multiple network
connections, for example, an SST with multiple network cards.
To modify the default network connection name, update the value
of the ConnectionNameToUpdate property in the AdvanceNDC
Custom.accfg file. By default, the value for the ConnectionName
ToUpdate property is Default Connection. When the default
value is configured, application automatically determines and
applies the default connection as per the operating system i.e.
Ethernet for Windows 10 and Local Area Network for Windows 7.
The default network connection setting in the AdvanceNDC
Custom.accfg file is as follows:

Figure 5-13
Example Connections Settings Extract
<Class ID="SetNetworkAddressTask" Name="NCR.APTRA.TcpipSupportTask.SetNetworkAddress"
Assembly="NCR.APTRA.TcpipSupportTask.dll">
<!-- can be used to configure any connection by any name-->
<Interface>
<Property Name="ConnectionNameToUpdate" Value="Default Connection"/>
</Interface>
</Class>

Communications Links The default link name is TPA 5

CONNECTION. If more than one communications link is required

or you want to use a different name, complete the following steps:
1 In the APTRA Author, modify the NAME attribute for the NDC
Comms Connection ID worker to include a value for the new
link ID.

2 In TCPIPCommunicationsServiceConfig.xml, add an entry with a

corresponding link ID.
The following extract is an example from the TCPIPCommunications
ServiceConfig.xml file:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-47

Configuring Advance NDC and Associated Components
Configuring Communications

Figure 5-14
Example TCPIP Communications XML
Extract
<TCPIPCommunicationsLink ReconnectOnClose="1" RetryTimer="3000" KeepAlive="1" LocalPort="0"
RemotePort="0" RemoteHost="127.0.0.1" CommsLinkID="TPA CONNECTION">
<MessageDelimiter PrefixData="0" PrefixSize="0" RCVTimeOut="30000" LengthEmbedded="0"
LengthOffset="0" LengthAdjust="0" LengthSize="2" LengthFormat="1"
Class="NCR.APTRA.VPITCPIP.StdMessageDelimiter" Assembly="NCR.APTRA.VPITCPIP.DLL"
MessageDelimiterID="Anything"/>
</TCPIPCommunicationsLink>

Note: The new link will not be configurable through Supervisor as

only the TPA CONNECTION entry for .NET VPITCPIP can be
modified through the TCP/IP Configuration menu.

Internet Protocols 5

Advance NDC supports TCP/IP communications using either IPv4

or IPv6.
When Advance NDC is installed, the default entry mode in
Supervisor is IPv4. The entry mode can be changed to IPv6 through
option 20 IPV4/IPV6 on the TCP/IP Configuration menu in
Supervisor or through the registry.
The currently selected IP address entry mode is stored in the
following DWORD registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\VPIComms
IPv6AddressEntryMode

Valid values are as follows:

0 = IPv4 entry mode (the default)
1 = IPv6 entry mode
IPv6 Restrictions For other options available on the TCP/IP 5

Configuration menu, the following restrictions apply:

 Subnet Mask (option 10) — applies only to IPv4
 Windows Internet Name Service (option 12) — not supported
for IPv6
 Firewall (option 14) — not supported for IPV6

Note: As the DHCP server normally configures an IPv6 network,

IPv6 local area network settings need not be configured through
Supervisor.
For further information, refer to the .NET TCP/IP Supervisor Tasks
On‐line Documentation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-48 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Communications

Functions in Supervisor An IPv6 address can be entered or 5

viewed through the following Supervisor options on the TCP/IP

Configuration menu:
0 RMT ADDRESS
2 LCL ADDRESS
6 DISP TCP/IP
7 PRINT TCP/IP
8 PING
9 GATEWAY
11 DNS ADDRESS (ENTER PRIMARY DNS)
Changes made for IPv6 through Supervisor menu options update
the TCPIPCommunicationsServiceConfig.xml file accordingly. IPv6
addresses are expressed in standard hexadecimal notation, for
example, 2002:877f:7a5b::877f:7a5b.
IPv6 is also supported when the network hosts are specified by
name, but this requires IPv6 support on the configured domain
name server.
Configuring Advance NDC as a TCP Server Advance NDC can 5

be configured as a TCP server accepting connections from any host,

as follows:
1 Specify the remote host as one of the following:
0.0.0.0 for IPv4
:: for IPv6

2 Ensure no firewall on the SST prevents the expected incoming

connections.
For details of the Supervisor functions for configuring TCP/IP
communications, refer to Chapter 4, “Configure Menu” of the
APTRA Advance NDC Supervisor’s Guide.

Dialup communications is enabled through the registry, as

Dialup Configuration 5

described in “Service Class” on page 5‐44, or by using the Configure

menu in Supervisor:
Configuration is required for both the application and lower‐level
(modem) communications. Configuration values are located as
follows:
 For the application parameters, under the following registry
key:
HKLM\SOFTWARE\NCR\Advance NDC\VPIComms\dialup

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-49

Configuring Advance NDC and Associated Components
Configuring Communications

 For the protocol and modem parameters, in the XML file for
CCM VISA2, VISA2CommunicationServiceconfig.xml. This file has
default values only and is not preconfigured.

Note: Support of dial up in 64‐bit systems (Windows 7 or Windows

10) is not available. For more information, please contact NCR FSE
Product Management.

Status Message Suppression 5

When a deposit cassette reaches the low threshold, an unsolicited

cash handler device status message is sent to Central. This message
is sent each time the cassette is used until the cassette either runs out
of notes or is replenished. In some dialup environments, these
repeated messages can impact the network by requiring additional
dial‐outs. As this can lead to additional network costs and reduction
in the cost advantages of dialup communications, Advance NDC
has introduced a method of suppressing these messages.
The number of messages to send for each cassette before
suppressing any further messages is set using Application
Parameters under 38 ‐ DIALUP on the Configure menu in
Supervisor. This updates the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\VPIComms\Dialup\
SuppressCashLow

Valid values are as follows:

 0 to disable message suppression (default)
 1‐9 to specify the number of messages sent for a cassette before
suppression.

Alphanumeric Entry 5

A defined set of alphanumeric values and special characters can be

configured for the following:
 Communications access routing information using the bank
identification number (BIN)
 Terminal Identification (TID) information
 Primary Number used when first dialling
 Secondary Number used if connection to the primary number
fails
 Modem Initialisation String
 Network Address String.
The values can also be configured by any of the following methods:
 Preconfigured and deployed at rollout
 Edited directly on a development system

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-50 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Communications

 Modified on a secure system using the Supervisor Copy

Off/Copy On function.

Preconfiguration 5

If the XML file for CCM VISA2 is to be preconfigured, the

restrictions described below in “XML Restrictions” must be applied.
Any preconfiguration entry must have a CommsLinkID of TPA
CONNECTION and there must only be one
VISA2CommunicationsLink element in the file.

Connect Life Time 5

On this menu, the two options have the following meaning:

 Normal = in transaction
 Pre‐Dial = in session.

Copy On/Off 5

To facilitate configuration, or modification that is unique to a

particular SST, an option is provided in the Supervisor Configure
menu to transfer the XML configuration file or the application
registry settings, in XML format, to and from removable media. This
functionality can be used, for example, to configure the SST at start
of day.
The function does not validate any changes made to the XML file. It
is responsibility of the person making the change to ensure the
validity both of syntax and values.

XML Restrictions 5

Certain characters are treated by XML as special characters. For

example, an ampersand (&) is a XML special character and must be
entered using the ASCII decimal value (38) as &#38; in XML.
NCR recommends that you have a knowledge of XML before
editing the XML file, or use an XML editor.

Diagnostics 5

For dialup diagnostics to work correctly, configuration is required,

either through preconfiguration or through transfer to removable
media.
The screens for dialup diagnostics are the forms supplied with CCM
VISA2, not those in resrvd.def.
For details of the diagnostic tests available, refer to the APTRA
Advance NDC, Supervisor’s Guide.

Note: Localisation of these forms is not supported.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-51

Configuring Advance NDC and Associated Components
Configuring Communications

Except for Timer 3, which is sent from Central, the timers and baud
Dialup Timers and Modem rate are configurable for numeric entry through the Dialup Config
Baud Rate 5
menu in Supervisor. The duration of the application timers is set in
accordance with the settings for the modem timers.
Setting the timers to the correct value is important for dialup
communications to function correctly. For details of the timers and
the calculations to use when determining the length of time to set,
refer to Chapter 13, “CCM VISA2 Dialup System” in the APTRA
Advance NDC, Reference Manual.

Activity Timer 5

This timer must be set to a large value, determined by how often the
host is expected to send messages in quiet periods. The default
value is 3000 seconds.

Error Redial Timer 5

This timer specifies how long the application will wait before it tries
dialling again to establish a connection after an error has been
experienced with a previous attempt. This timer should be set to a
shorter value than the Activity Timer. The default is 300 seconds.

Timer 3 5

The duration of this timer (communications response timer,

downloaded from the host) has to be sufficient to allow the dialup
connection to complete its operations. In non‐dialup systems, Timer
3 normally has a value of 20 to 30 seconds. In a dialup system the
typical value is 40 to 60 seconds.

Modem Connect Timer 5

The Modem Connect Timer determines how long CCM VISA2 will
wait for an attempt to connect to the host before signalling an error.
The duration of this timer must be shorter than Timer 3.

Dial on Send Timer 5

The duration of this timer must be at least as long as the time taken
to transmit the longest message and receive the corresponding
reply.
For EJ upload, the Dial on Send timer determines the amount of
time the host has available to send an acknowledgement to an EJ
upload message. The call will be disconnected after the Dial on Send
timer expires.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-52 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Diagnostics Options

Configuring Diagnostics Options 5

This section describes the following:

 Displaying additional diagnostics menus
 Showing or hiding the diagnostics shortcut
 Disabling self‐test on exiting diagnostics.

Where there is no access to VDM and VDA diagnostic support, you

Displaying Additional can choose to display additional diagnostics menus within
Diagnostics Menus 5
Supervisor. These menus allow the display of information on the
fitness of present and installed XFS devices. You can then perform a
reset, and in some cases a self test, where required.
By default these menus are not shown, and can only be displayed by
updating the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\Diagnostics\
MVDiagnostics

Valid values are as follows:

0 ‐ hide the diagnostics menus. This is the default.
1 ‐ display the diagnostics menus.
When operator intervention is required in diagnostics, a timeout is
applied. For example, following a reset of the card reader, an
operator must enter a card. If no card is entered before the specified
timeout period, the test times out. The timeout period is set in the
following entry:

HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\Diagnostics\
Timeout

Valid values are entered in seconds. The default is 7 seconds.

At any time on a Graphical Operator Panel (GOP), or when the

Show/Hide Diagnostics Select menu is displayed in Supervisor on any other type of display,
Shortcut 5
a diagnostics shortcut allows entry to the VDM and replicates the
shortcut provided with APTRA XFS.

Note: If the diagnostic shortcut is selected while a cardholder

transaction is in progress, entry to the VDM occurs only after the
transaction has completed.

Depending on the type of display, the diagnostic shortcut is either

the Mini Self‐Service Assistant (MSSA), or the text ‘SERVICE
ASSIST’.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-53

Configuring Advance NDC and Associated Components
Configuring Diagnostics Options

By default, the diagnostics shortcut is displayed, but it can be

hidden using the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\supervisor\MAST

Valid values for this entry are as follows:

0 to hide the diagnostics shortcut
1 to show the diagnostics shortcut (default).
The following are also required to display the MSSA icon:
 The correct product class must be entered in the System
Application configuration. The product class information can be
found on the label that is affixed inside the SST.
 The Self‐Service Assistant aggregate must have been installed
with XFS and its default settings must remain unchanged.

When the APTRA Self‐Service Assistant is installed, a self test of

Disabling Self‐Test on devices with hardware problems is performed on exit from VDM.
Diagnostics Exit 5
You can disable this self test using the following registry entry:

HKLM\SOFTWARE\NCR\APTRA Self-Service Support (NCR

Features)\Task API\PerformTestOnExit

Valid values for this entry are as follows:

0 to disable the self test
1 to enable the self test (default).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-54 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Service Providers

Configuring Service Providers 5

The Advance NDC installation configures the NCR service

providers (SPs) to ensure they will function with Advance NDC.
For SP configuration on other vendors’ SSTs, refer to the
vendor‐specific documentation and the APTRA Advance NDC,
Reference Manual.

If an internal error is detected in a service provider, the default

Configuring Service registry settings will reboot the SST. The default setting is as
Providers (SPs) for Reboot 5
follows:
HKLM\SOFTWARE\NCR\XFS IDC SERVICE PROVIDER\XFS-Framework\
Interoperability RunInternalErrorExecutable
=00000001 (DWORD)

For details of XFS framework, refer to APTRA Documentation |

Active XFS Controls.

By default, one attempt can be made to clear a device fault before

Service Provider Reset intervention is required through the System Application or other
Value 5
Vendor Dependent Mode (VDM).
To support error recovery guidelines for deposit transactions, the
number of attempts to clear a device fault on a cash acceptor can be
configured by adding the following entry to the registry:
HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
MultipleResetSOH = "1" (DWORD)

If this registry entry is set to 1, multiple resets can be called on the

NCR service providers. This registry entry must be set to 1 to ensure
the success of automatic error recovery, the BNA initialisation
option on the Supervisor Replenish menu and the clearing of the
device when exiting Supervisor after a failed attempt to reset during
a Supervisor transaction.

Note: When not in Supervisor mode, no more than two attempts

that fail will be made. When in Supervisor mode, error recovery is
always attempted when the BNA initialisation option is run from
the Supervisor Replenish menu or on exit from Supervisor if the
device is not in a good state.

The following scenario illustrates how a single attempt to clear a

device fault can affect Advance NDC:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-55

Configuring Advance NDC and Associated Components
Configuring Service Providers

 The reset command sent on Supervisor exit is not successful

where a previous attempt to reset a device has been made and
the System Application has not been used to clear the device in
the meantime.
If a reset fails, use the System Application to clear the device.
The CEN‐XFS standard does not allow a vendor‐dependent
application, such as the System Application, to be launched when
other CEN‐XFS compliant applications are not in VDM. If the
System Application is launched outside Advance NDC, for example
from the desktop, an encryptor error is reported when the encryptor
is next used from within Advance NDC. Therefore, only start the
System Application using the Supervisor menu unless Advance
NDC is not currently running.

During installation, Advance NDC turns off SP tracing (0) under the
Service Provider Tracing 5

following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\TraceLevel

For further information on SP tracing and the settings for this

registry entry, refer to the APTRA on‐line documentation under
APTRA XFS | Programmer’s Reference | XFS Service Providers |
XFS Service Provider Errors.

The following configuration is included to support future CEN‐XFS

Configuring SP Support features and functionality in the product. The configuration must
for CEN‐XFS Versions 5
not be changed unless the release bulletin contains details of
acceptable changes.
Where a device is capable of supporting later versions of CEN‐XFS
than the service provider is able to support, each device alias (see
“CEN‐XFS Logical Device Names” on page 5‐17) can be configured
for Advance NDC to restrict the range of CEN‐XFS versions
supported by that device.
The following example shows the SPVersionRange registry entry
configured for a card reader with the CEN‐XFS version range
specified as 3.00 to 3.03:
HKLM\SOFTWARE\NCR\Advance NDC\SPVersionRange\
Card Reader = "03 00 03 03"

The SPVersionRange string registry value must contain four sets of

two‐digit pairs separated by spaces. In the example above, the first
and second pairs (03 00) indicate that the version range starts at
CEN‐XFS 3.00 and the third and fourth pairs (03 03) show that the
version range ends with CEN‐XFS 3.03.
In the above example, the IDC service provider is opened using the
latest CEN‐XFS version that it supports in the range specified. If the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-56 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Service Providers

card reader supports CEN‐XFS versions 3.00 to 3.02, then CEN‐XFS

3.02 is the version used. However, if the card reader supports
CEN‐XFS 3.00 to 3.10, the version used is 3.03 as versions beyond
that are outside the range specified in the registry entry.
If Advance NDC is updated to support later versions of the
CEN‐XFS interface for a particular device, this support must be
enabled by extending the range in the registry entry. Therefore,
using the example above, if the card reader is updated to support
CEN‐XFS 3.10, the entry must be updated as follows:

HKLM\SOFTWARE\NCR\Advance NDC\SPVersionRange\
Card Reader = "03 00 03 10"

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-57

Configuring Advance NDC and Associated Components
Configuring SNMP Traps

Configuring SNMP Traps 5

Advance NDC supports the sending of application‐related Simple

Network Management Protocol (SNMP) traps. When changes in
state occur in Advance NDC, events (known as traps) are sent by
the Unified SNMP agent to the SNMP manager. Only the traps
detailed here originate in Advance NDC. All other traps, for events
such as hardware state changes, originate in APTRA XFS.
Further information on SNMP traps is available as follows:
 A licence must be purchased for the Unified Agent SNMP
product. Refer to the Unified Agent SNMP online
documentation provided with the product.
The ideal communications flow is illustrated in the following figure:

Figure 5-15
APTRA and SNMP

To send SNMP traps, Advance NDC requires a TCP/IP connection

to the SNMP server. The following types of trap are sent:
 No transaction
 Application heartbeats
 Mode changes.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-58 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SNMP Traps

No transaction traps allow monitoring of the health and availability

No Transaction Traps 5

of the SST. The traps are described in the following table.

Table 5-11 Trap Description

No Transaction Traps
NOTRAN9 No transaction or mode change has occurred during the
specified period when the SST was in the defined mode
or modes.

NOTRAN0 The traps are sent during the transaction request state.
The application also checks if any NOTRAN9 traps were
sent to the host before generating NOTRAN0 traps.

To configure the period between sending NOTRAN9 traps, set the

following registry entry to the required period in seconds:
HKLM\SOFTWARE\NCR\Advance NDC\SNMP\NoTransactionDelay

By default, this is set to 0 to disable the sending of transaction traps.

The minimum period is 5 seconds and the maximum is 86400
seconds (24 hours).
To configure the modes in which transaction traps are sent, set the
following registry key:
HKLM\SOFTWARE\NCR\Advance NDC\SNMP\SendNOTRAN9

By default, this is set to 1 to send transaction traps only when the

SST is in service. The modes are defined using any combination of
the bit settings described in the following table. For example:
 To enable traps for all modes, SendNOTRAN9 must be set to 15.
 To send transaction traps when the SST is in service or in
supervisor mode, SendNOTRAN9 must be set to 9.
 To send transaction traps when the SST is in service or out of
service, SendNOTRAN9 must be set to 3.

Table 5-12 Bit Mode

Bit Positions for Modes
0 In Service

1 Out of Service

2 Offline

3 Supervisor

Regular signals (heartbeats) from the Customisation Layer of

Application Heartbeats 5

Advance NDC allow Central to monitor the communications

connections.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-59

Configuring Advance NDC and Associated Components
Configuring SNMP Traps

By default, the initial heartbeat is generated at Start of Day with

subsequent heartbeats generated every 30 minutes. These timings
can be changed by editing the HeartBeatDelay registry entry
under the following registry key
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\SNMP.

As there is no dependency on other signals, you can choose to

reduce or increase the period between heartbeats.
The value for this registry entry is given in seconds. The default is
1800 seconds (30 minutes).
The NCR SNMP implementation uses the Generate Heartbeat type
trap.
The GASPER‐compatible implementation uses the Report State type
trap: see Table 5‐8 for further details.

Advance NDC mode changes generate traps to report application

Advance NDC Mode events that require logging or possible action by the SNMP
Change Traps 5
manager.
The NCR SNMP implementation uses a pair of traps listed in tables
“NCR SNMP Service Traps” and “NCR SNMP Mode Change
Traps” on page 5‐61.
The GASPER‐compatible implementation uses only the traps listed
in table “GASPER‐Compatible SNMP Traps” on page 5‐62.

Service State Changes 5

When Advance NDC relinquishes control of the SST to another

application or process, an Out of Service mode change trap is sent
although no actual mode change occurs. When Advance NDC
regains control of the SST, an In Service mode change trap is sent
although, again, no actual mode change occurs.

There are two methods of implementing application heartbeat and

Implementation of SNMP mode change traps in Advance NDC, as follows:
Traps 5

 As described in “NCR SNMP Implementation” on page 5‐60

 GASPER‐compatible as described in “GASPER‐Compatible
Implementation” on page 5‐62.

Note: “No transaction” traps apply to both implementations.

NCR SNMP Implementation 5

To use this implementation, set the following registry entry to 1:

HKLM\SOFTWARE\NCR\ Advance NDC\SNMP\NCRSNMP

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-60 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SNMP Traps

Two types of traps can be sent, as follows:

 NCR SNMP Service traps
 NCR SNMP Mode Change traps.
An NCR SNMP Service trap shows whether the SST is in or out of
service, as follows:

Table 5-13 Severity (Enum) Meaning in Advance NDC

NCR SNMP Service Traps
0 SST is in service

2 Supervisor mode has been entered; SST is either out of

service or in offline mode

An NCR SNMP Mode Change trap identifies the mode change, as

follows:

Table 5-14 Application Severity Meaning in Advance

Event (String)
NCR SNMP Mode Change Traps Name (String) (Enum) NDC

“AA‐NDC” “IN_SERVICE” 0 Normal operation

‐ In service
or
Advance NDC
has regained
control of the SST
from another
application or
process

“AA‐NDC” “OUT_OF_SERVICE” 2 Critical

‐ Out of service
or
Advance NDC
has relinquished
control of the SST
to another
application or
process

“AA‐NDC” “OFFLINE_MODE” 2 Critical

‐ Offline

“AA‐NDC” “SUPERVISOR_MODE” 2 Critical

‐ Supervisor

“AA‐NDC” “SUSPEND_MODE” 2 Critical ‐ Suspend

condition

“AA‐NDC” “UnKnown” 1 Warning

‐ State Unknown

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-61

Configuring Advance NDC and Associated Components
Configuring SNMP Traps

GASPER‐Compatible Implementation 5

To use this implementation, set the following registry entry to 0:

HKLM\SOFTWARE\NCR\Advance NDC\SNMP\NCRSNMP

Note: This is the default setting for this registry entry

The application heartbeat and mode change traps are given in the
following table:

Table 5-15
GASPER-Compatible SNMP Traps

Name (String) Data (String) Alert Hint Meaning within Advance NDC

“APTRA WEBATM STATUS” “1” TRUE In Service

or
Advance NDC has regained
control of the SST from
another application or
process

“APTRA WEBATM STATUS” “2” TRUE Out of Service

or
Advance NDC has
relinquished control of the
SST to another application
or process

“APTRA WEBATM STATUS” “3” TRUE Supervisor

“APTRA WEBATM STATUS” “4” TRUE Exit Supervisor

“APTRA WEBATM STATUS” “5” TRUE Suspend

“APTRA WEBATM STATUS” “I” TRUE Offline

“APTRA WEBATM STATUS” “J” TRUE Unknown

“APTRA WEBATM HEARTBEAT” DD/MM/YYYY hh:mm:ss TRUE Heartbeat

(current date and time)

GASPER‐Compatible SNMP Traps for a

Contactless Card Reader 5

When Advance NDC interacts with the contactless card reader

through the wrapper session, Advance NDC generates GASPER
compatible SNMP traps to report the device status of a contactless
card reader to the SNMP management server. To use this
implementation, set the following registry entry to 0:
HKLM\SOFTWARE\NCR\Advance NDC\SNMP\NCRSNMP

Note: This is the default setting for this registry entry.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-62 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SNMP Traps

Note: When Advance NDC interacts with the contactless card

reader through the XFS session, the platform generates SNMP traps
to report the device status of a contactless card reader to the SNMP
management server.

Interaction of the Advance NDC application with the contactless

card reader device can be configured either to the XFS session or the
wrapper session through the EnableXFSSessionForContactless
registry. For detail information about the registry, see “Configuring
Contactless Card Reader Device Mode” on page 5‐215.
The application heartbeat and mode change traps are given in the
following table:

Table 5-16
GASPER-Compatible SNMP Traps
for a Contactless Card Reader

Name (String) Data (String) Alert Hint Meaning within Advance NDC

“APTRA WEBATM STATUS” “999” TRUE MS_READER_DATA_ERROR

The data returned by

the reader is invalid. This
could be a result of the
reader firmware getting
corrupted or the installed
reader firmware does not
support the contactless card
reader.

“APTRA WEBATM STATUS” “998” TRUE MS_USB_COMMS_FAILURE

There has been an error due

to transmission of data with
the contactless card reader.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-63

Configuring Advance NDC and Associated Components
Configuring SNMP Traps

Name (String) Data (String) Alert Hint Meaning within Advance NDC

“APTRA WEBATM STATUS” “997” TRUE MS_DEVICE_COMMS_

FAILURE

There has been an error

when USB communications
cable is disconnected from
the contactless card reader.

“APTRA WEBATM STATUS” “996” TRUE MS_DEVICE_TIMEOUT

There has been an error due

to a no response received
from the contactless card
reader.

“APTRA WEBATM STATUS” “995” TRUE MS_DEVICE_HEALTHY

The device has recovered

successfully from an error
and is in a healthy state
now.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-64 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Configuring .NET Archive Manager 5

Advance NDC uses the .NET Archive Manager component to

archive and manage data on the SST.
The .NET Archive Manager is configured using the
AdvanceNDCCore.accfg file installed with Advance NDC. For
information on the AdvanceNDCCore.accfg file, see “.NET Class
Configurator Files” on page 5‐40.
For further information on the .NET Archive Manager, refer to the
APTRA online documentation under .NET Archive Manager.

Note:
 The Archive Manager is enabled by default and runs at the
scheduled time.
 There may be a possibility of transaction slow down or
performance issue when the Archive Manager runs.

The StdArchiveManager class is responsible for managing and

Configuration Properties 5

packaging all archive data. It provides configuration properties that

can be edited using any XML or text editor to perform the following
tasks:
 Scheduling archives
 Setting the default collection directory
 Deleting old archives
 Configuring the data to archive
 Configuring SST properties
The following extract from the AdvanceNDCCustom.accfg file shows
the configurable properties that are available for the
StdArchiveManager instance, which is used by the Retrieve
Archive supervisor option.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-65

Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-16
Example STD Achieve Manager Extract
<Class ID="StdArchiveManager" Name="NCR.APTRA.ArchiveMan.StdArchiveManager"
Assembly="NCR.APTRA.ArchiveMan.dll" CreateAlways="true">
<Interface>
<Property Name="CollectDir" Value="C:\Program Files\NCR APTRA\Advance NDC\Data\
Archives"/>
<Property Name="DeleteOlderThan" Value="8"/>
</Interface>
</Class>v

The following extract from the AdvanceNDCCustom.accfg file shows

the configurable properties that are available for the
StdArchiveManager_Scheduler instance, which is used by the
scheduler.

Figure 5-17
Example STD Achieve Manager Extract
<Class ID="StdArchiveManager_Scheduler" Name="NCR.APTRA.ArchiveMan.StdArchiveManager"
Assembly="NCR.APTRA.ArchiveMan.dll" CreateAlways="true">
<Interface>
<Property Name="CollectDir" Value="C:\Program Files\NCR APTRA\Advance
NDC\Data\Archives"/>
<Property Name="DeleteOlderThan" Value="8"/>
</Interface>
</Class>

The default general configuration settings described in the

General Configuration 5

following sections are provided by Advance NDC in the

AdvanceNDCCustom.accfg file and can be edited using any XML or
text editor.

Scheduling Archives 5

To configure the scheduler, edit the default configuration settings in

the AdvanceNDCCustom.accfg file as shown in the following
example:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-66 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-18
Example 1 Scheduling Archives Extract
<ClassID="Scheduler" Name="NCR.APTRA.ArchiveMan.Scheduler"
Assembly="NCRAPTRAArchiveMan.dll">
<Interface>
<Property Name="Enabled" Value="True"/>
<Property Name="ScheduledDays" Value="ScheduledDaysArray"/>
<Property Name="ScheduledTime" Value="03:00"/>
</Interface>
</Class>

To change the time that files are archived each day, update the
ScheduledTime property to the desired time. The default time is
03:00; the time is given in the 24 hour format.
To change the days that the Archive Manager runs, edit the
ScheduledDaysArray. For example, to set the Archive Manager to
run on Mondays, Wednesdays and Fridays, edit the array as
follows:

Figure 5-19
Example 2 Scheduling Archives Extract
<Array ID="ScheduledDaysArray">
<Element Value="Monday"/>
<Element Value="Wednesday"/>
<Element Value="Friday"/>
</Array>

Setting the Default Collection Directory 5

The default collection directory setting in the

AdvanceNDCCustom.accfg file is as follows:
<Property Name="CollectDir" Value="C:\Program Files\
NCR APTRA\Advance NDC\Data\Archives/>

If you want to archive files to a different folder, update the path

accordingly.

Deleting Old Archives 5

Archive Manager deletes exported files a specified number of days

after the creation date. After each export, the timestamps are
checked and files are deleted if they are older than the value in the
DeleteOlderThan property.

The default setting is as follows:

<Property Name="DeleteOlderThan" Value="8"/>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-67

Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Note: Deleting old archives is not applicable for the serial number
image file and bunch note image file. For information about deletion
of the serial number image file and bunch note image file, see
“Deleting Old SNR Archives” on page 5‐75 and “Deleting Old
Bunch Note Image Archives” on page 5‐76.

The .NET Archive Manager can run at a pre‐configured time to

Archive Data archive the following data:
Configuration Examples 5

 Investigation and trace files, such as those produced by Problem

Determination and the XFS platform
 Log files, such as the EJ data log (ejdata.log) and event logs
 ECB 6 database file
 Registry keys
 User‐configured files
 User‐configured folders
The archived data is saved to a selected destination drive under the
directory specified in the AdvanceNDCCustom.accfg file.

Archive Files Using the Supervisor Task 5

To archive a file using the Supervisor task, it must be included as a

class element in the AdvanceNDCCustom.accfg file and the ID
attribute of the class element must be defined in the following array:

Figure 5-20
Example Archive Manager Array Extract
<Array ID="AMProviderArray">
<Element Value="AMProviderFiles1"/>
<Element Value="AMProviderUEH"/>
<Element Value="AMProviderFile"/>
<Element Value="AMProviderXFSLog1"/>
<Element Value="AMProviderEventLog1"/>
<Element Value="AMProviderECB6Log"/>
<Element Value="AMProviderAlwaysOn1"/>
<Element Value="AMProviderCacheFiles"/>
<Element Value= "AMProviderSerialNumberImages"/>
<Element Value= "AMProviderBunchImages"/>
</Array>

Archive Files Using the Scheduler 5

To archive a file using the Scheduler, it must be included as a class

element in the AdvanceNDCCustom.accfg file and the ID attribute of
the class element must be defined in the following array:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-68 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-21
Example Archive Manager
Array Scheduler Extract
<Array ID="AMProviderArray_Scheduler">
<Element Value="AMProviderFiles1"/>
<Element Value="AMProviderUEH"/>
<Element Value="AMProviderFile"/>
<Element Value="AMProviderXFSLog1"/>
<Element Value="AMProviderEventLog1"/>
<Element Value="AMProviderECB6Log"/>
<Element Value="AMProviderAlwaysOn1"/>
<Element Value= "AMProviderSerialNumberImages"/>
<Element Value= "AMProviderBunchImages"/>
<!--Element Value="AMProviderCacheFiles"/--!>
</Array>

The default general configuration examples in the following

sections are included in the AdvanceNDCCustom.accfg file. The
configurations can be edited using any XML or text editor.

Archiving PD Investigation Files 5

The following example shows the default XML entry in the

AdvanceNDCCore.accfg file. This covers collecting and removing
archives for PD investigation files.

Figure 5-22
Example Archive PD Investigation File
Extract
<Class ID="AMProviderInvestigation1" Name="NCR.APTRA.ArchiveMan.AMProviderInvestigation"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="Groups" Value="AMProviderInvestigation1Groups"/>
<Property Name="RemoveTrace" Value="True"/>
</Interface>
</Class>

<Array ID="AMProviderInvestigation1Groups">
<Element Value="PD INVESTIGATIONS"/>
</Array>

By default, PD investigation files are archived to a group named

PD INVESTIGATIONS. To change the name of the group, edit the
appropriate value in the AMProviderInvestigation1Groups array
in the AdvanceNDCCustom.accfg file.
By default, the .NET Archive Manager deletes PD investigation files
that have been archived during a scheduled collection. PD
investigations that are active or have been paused are not deleted

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-69

Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

until the next scheduled archive time arrives, providing they have
completed. To disable automatic deletion of archived PD
investigation files, set the RemoveTrace property to False in
AdvanceNDCCustom.accfg file.
If a problem occurs during the removal of a PD investigation during
an archive, an exception is logged in the event log.

Archiving Cache Files 5

The following example shows the default XML entry in the

AdvanceNDCCore.accfg file, which covers archiving the cache files.

Figure 5-23
Example Archive Cache Files Extract
<Class ID="AMProviderCacheFiles" Name="NCR.APTRA.ArchiveMan.AMProviderFiles"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="Groups" Value="AMProviderCacheFilesGroups" />
<Property Name="SourcePath" Value="C:\Program Files\NCR APTRA\Problem Determination
Collection\AOTraces\BackUps\" />
<Property Name="SearchPattern" Value="*.xml" />
</Interface>
</Class>

By default, cache files are archived to a group named CACHE LOGS.

To change the name of the group, edit the appropriate value in the
AMProviderCacheFilesGroups array in the
AdvanceNDCCustom.accfg file.
<Array ID="AMProviderCacheFilesGroups">
<Element Value="CACHE LOGS"/>
</Array>

Deleting Cache Files By default, Advance NDC deletes the cache 5

files in the SourcePath after archiving them. The following extract

from the AdvanceNDCCustom.accfg file shows the default value for
the RemoveTrace and RemoveTraceOnArchiveNow properties. If
you do not want to delete the cache files archived by scheduler from
the SourcePath, set the RemoveTrace property to False. If you do
not want to delete the cache files that are backed up by the
supervisor task, set the RemoveTraceOnArchiveNow property to
False.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-70 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-24
Deleting Backed up Cache Files Extract
Class ID="AMProviderCacheFiles" Name="NCR.APTRA.ArchiveMan.AMProviderFiles" Assembly=
"NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="Recursive" Value="True" />
<Property Name="RemoveTrace" Value="True" />
<Property Name="RemoveTraceOnArchiveNow" Value="True" />
</Interface>
</Class>

For further information on cache files, refer to the APTRA on‐line

documentation under Problem Determination Collection.

Note: The Cache functionality is disabled by default. To enable, set

the EnableCache registry value to 1. By default, the value is 0. The
SST must be restarted to apply the registry settings. Following is the
path of the registry:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\APTRA Problem
Determination\AOCacheConfiguration

Archiving XFS Trace Files 5

In the default entry, XFS trace files are archived to the XFS LOGS
group, as follows:

Figure 5-25
Example Archive XFS Trace File Extract
<Class ID="AMProviderXFSLog1" Name="NCR.APTRA.ArchiveMan.AMProviderXFSLog"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="Groups" Value="AMProviderXFSLog1Groups"/>
</Interface>
</Class>

<Array ID="AMProviderXFSLog1Groups">
<Element Value="XFS LOGS"/>
</Array>

To change the name of the group, edit the appropriate value in the
AMProviderXFSLog1Groups array in the AdvanceNDCCustom.accfg
file.

Archiving Event Logs 5

In the default entry, event logs are archived to the Event Logs
group, as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-71

Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-26
Example Archive Event Log Extract
<Class ID="AMProviderEventLog1" Name="NCR.APTRA.ArchiveMan.AMProviderEventLogs"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="Groups" Value="AMProviderEventLog1Groups"/>
</Interface>
</Class>

<Array ID="AMProviderEventLog1Groups">
<Element Value="Event Logs"/>
</Array>

To change the name of the group, edit the appropriate value in the
AMProviderEventLog1Groups array in the
AdvanceNDCCustom.accfg file.

Archiving EJ Data Files 5

Advance NDC uses the AMProviderFiles class provided by the

Archive Manager to archive the EJ data log (ejdata.log) file. In the
default entry, EJ data files and EJ backup files are archived in the EJ
DATA LOGS group. The following is provided in the
AdvanceNDCCustom.accfg file.

Figure 5-27
Example Archive Manager EJ Data Files
Extract
<Class ID="AMProviderFiles1" Name="NCR.APTRA.ArchiveMan.AMProviderFiles"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="Groups" Value="AMProviderFiles1Groups"/>
<Property Name="SourcePath" Value="C:\Program Files\NCR APTRA\Advance NDC\Data"/>
<Property Name="SearchPattern" Value="EJDATA.LOG"/>
<Property Name="Recursive" Value="False"/>
<Property Name="RemoveTrace" Value="False"/>
</Interface>
</Class>

<Array ID="AMProviderFiles1Groups">
<Element Value="EJ DATA LOGS"/>

Note: As Advance NDC does not archive EJ backup files by default,

additional configuration information must be added to the
AdvanceNDCCustom.accfg file. An example of this configuration and
a description of user‐defined properties is provided in “Archiving
User‐Defined Files” on page 5‐79.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-72 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Archiving ECB 6 Database File 5

Advance NDC uses the AMProviderFiles class provided by the

Archive Manager to archive the ECB 6 database file. In the default
entry, the ECB 6 database file is archived in the ECB6 LOGS group.
The following is provided in the CashInCore.accfg file.

Figure 5-28
Example Archive Manager ECB 6
Database Files Extract
<Class ID="AMProviderECB6Log" Name="NCR.APTRA.ArchiveMan.AMProviderFiles" Assembly=
"NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="Groups" Value="AMProviderECB6Groups"/>
<Property Name="SourcePath" Value="C:\Program Files\NCR APTRA\Advance NDC\
PersistedData\ECB6Log"/>
<Property Name="SearchPattern" Value="*.SDF"/>
<Property Name="Recursive" Value="False"/>
<Property Name="RemoveTrace" Value="False"/>
</Interface>
</Class>

<Array ID="AMProviderECB6Groups ">

<Element Value="ECB6 LOGS "/>
</Array>
<Array ID=" AMProviderArray ">
<Element Value=" AMProviderECB6Log "/>
</Array>

If the SST does not have a cash acceptor, attempts to archive the ECB
6 database file can be prevented by deleting or commenting out the
above configuration from the CashInCore.accfg file.

Archiving Unhandled Exception Handler (UEH) Files 5

Advance NDC uses the AMProviderFiles class provided by the

Archive Manager to archive Unhandled Exception Handler (UEH)
files. In the default entry, the UEH files are archived in the UEH
LOGS group.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-73

Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

The following is provided in the AdvanceNDCCustom.accfg file.

Figure 5-29
Example Archive UEH Files Extract
<Class ID="AMProviderUEH" Name="NCR.APTRA.ArchiveMan.AMProviderFiles" Assembly="NCR.APTRA.
ArchiveMan.dll">
<Interface>
<Property Name="Groups" Value="AMProviderUEHGroups"/>
<Property Name="SourcePath" Value="C:\ProgramData\NCR\APTRA\Exception
Handling\Logs”/>
<Property Name="SearchPattern" Value="*.log"/>
<Property Name="Recursive" Value="True"/>
<Property Name="RemoveTrace" Value="False"/>
</Interface>
</Class>

<Array ID="AMProviderUEHGroups">
<Element Value="UEH LOGS"/>
</Array>

Note:
 The ProgramData is a hidden folder.
 On Windows 10, the Logs folder is available in the
C:\ProgramData\NCR\APTRA\Exception Handling\Logs
location.

Archiving SNR Image Files 5

The following example shows the default XML entry in the

AdvanceNDCCustom.accfg file, which covers archiving SNR image
files.

Figure 5-30
Example Archive SNR Image Files Extract
<Class ID="AMProviderSerialNumberImages" Name="NCR.APTRA.ArchiveMan.AMProviderFiles"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="SourcePath" Value="C:\Program Files\NCR APTRA\Advance NDC\Persisted
Data\SerialNumberImageFiles"/>
<Property Name="SearchPattern" Value="*.jpg"/>
<Property Name="Recursive" Value="True"/>
<Property Name="RemoveTrace" Value="True"/>
<Property Name="Groups" Value="SerialNumberImagesGroup" IsArray="true" />
</Interface>
</Class>

By default, SNR image files are archived to a group named SNR

IMAGE FILES. To change the name of the group, edit the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-74 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

appropriate value in the SerialNumberImagesGroup array in the

AdvanceNDCCustom.accfg file.
<Array ID="SerialNumberImagesGroup">
<Element Value="SNR IMAGE FILES" />
</Array>

Deleting Old SNR Archives Archive Manager deletes the 5

exported SNR image files in a specified number of days after the

date of creation. After each export, timestamps are checked and files
are deleted if they are older than the value set in the DeleteOlder
Than property.

Note: When deletion of the SNR archive files is executed, the other
.cab files are not deleted.
Default setting of the DeleteOlderThan property is 365 days. To
change the DeleteOlderThan property, edit the default
configuration settings in the AdvanceNDCCustom.accfg file as shown
in the following example:

Figure 5-31
Example SNR Image Files (Group-wise)
Extract
<Class ID="SNRImageFilesScheduler" Name="NCR.APTRA.ArchiveMan.GroupConfiguration"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="GroupName" Value="SNR IMAGE FILES" />
<Property Name="DeleteOlderThan" Value="365" />
</Interface>
</Class>

Archiving Bunch Note Image Files 5

The following example shows the default XML entry in the

AdvanceNDCCustom.accfg file, which covers archiving bunch note
image files.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-75

Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-32
Example Archive Bunch Note Image Files
Extract
<Class ID="AMProviderBunchImages" Name="NCR.APTRA.ArchiveMan.AMProviderFiles"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="SourcePath" Value="C:\Program Files\NCR APTRA\Advance NDC\Persisted
Data\BunchImageFiles"/>
<Property Name="SearchPattern" Value="*.jpg"/>
<Property Name="Recursive" Value="True"/>
<Property Name="RemoveTrace" Value="True"/>
<Property Name="Groups" Value="BunchImagesGroup" IsArray="true"/>
</Interface>
</Class>

By default, bunch note image files are archived to a group named

BUNCH IMAGE FILES. To change the name of the group, edit the
appropriate value in the BunchImagesGroup array in the
AdvanceNDCCustom.accfg file as shown in the following example:
<Array ID="BunchImagesGroup">
<Element Value="BUNCH IMAGE FILES"/>
</Array>

Note: Bunch note image files are archived to a single .cab file for
both deposit and dispense transactions.

Deleting Old Bunch Note Image Archives Archive Manager 5

deletes the exported bunch note image files in a specified number of

days after the date of creation. After each export, timestamps are
checked and files are deleted if they are older than the value set in
the DeleteOlderThan property. For details about default setting of
the DeleteOlderThan property and how to edit it, see “Deleting
Old SNR Archives” on page 5‐75.
The default setting is as shown in the following example:

Figure 5-33
Example Bunch Note Image
Files (Group-wise) Extract
<Class ID="BunchFilesScheduler" Name="NCR.APTRA.ArchiveMan.GroupConfiguration"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="GroupName" Value="BUNCH IMAGE FILES"/>
<Property Name="DeleteOlderThan" Value="365" />
</Interface>
</Class>

Note: When deletion of the bunch note image archive files is

executed, the other .cab files are not deleted.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-76 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

SST properties are defined in the AdvanceNDCCore.accfg file using

SST Properties the TerminalInfo class as shown in the example below:
Configuration Examples 5

Figure 5‐34
Example SST Properties Extract
<Class ID="TerminalInfo" Name="NCR.APTRA.TermSrvSDK.StdTerminalInfo" Assembly=
"NCR.APTRA.TermSrvSDK.dll">
<Interface>
<Property Name="TerminalOwner" Value="OwnerDetails"/>
<PropertyName="NetworkIdentity" Value="NetworkIdentityArray"/>
<Property Name="TerminalLocation" Value="PostalAddress"/>
</Interface>
</Class>

The following sections provide default configuration examples for

SST properties. These examples are included in the
AdvanceNDCCustom.accfg file and can be edited using any XML or
text editor.

Owner Details 5

To specify the name of a financial institution and any other

identification details, you can use the BankName and BankID
properties on the OwnerDetails class as shown in the example
below:

Figure 5-35
Example Financial Institute Details Extract
<Class ID="OwnerDetails" Name="NCR.APTRA.TermSrvSDK.
StdOwnerDetails" Assembly="NCR.APTRA.TermSrvSDK.dll">
<Interface>
<Property Name="BankName" Value="ABC Bank"/>
<Property Name="BankID" Value="ABC123"/>
</Interface>
</Class>

SST and Network ID 5

To specify the ID for an SST or network, you can use the

TerminalID and NetworkID properties on the NetworkIdentity1
class as shown in the example below:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-77

Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-36
Example SST and Network ID Extract
<Class ID="NetworkIdentity1" Name="NCR.APTRA.TermSrvSDK.
StdNetworkIdentity" Assembly="NCR.APTRA.TermSrvSDK.dll">
<Interface>
<Property Name="TerminalID" Value="12345"/>
<Property Name="NetworkID" Value="22222"/>
</Interface>
</Class>

Note: The NetworkIdentity1 class is an element in the

NetworkIdentity array shown in the example below:

Figure 5-37
Example Network ID Array Extract
<Array ID="NetworkIdentityArray">
<Element Value="NetworkIdentity1"/>
</Array>

Postal Address 5

To specify the address for a financial institution, you can use the
Address, PostalCode, City, StateProv and Country
properties on the PostalAddress class as shown in the example
below:

Figure 5-38
Example Financial Institution Address
Extract
<Class ID="PostalAddress" Name="NCR.APTRA.TermSrvSDK.StdPostalAddress"Assembly=
"NCR.APTRA.TermSrvSDK.dll">
<Interface>
<Property Name="Address" Value="AddressArray"/>
<Property Name="PostalCode" Value="DD1 3XX"/>
<Property Name="City" Value="Dundee"/>
<Property Name="StateProv" Value="Angus"/>
<Property Name="Country" Value="UK"/>
</Interface>
</Class>

Note: The AddressArray value is an array as shown in the

example below:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-78 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-39
Example Financial Institute Address Array
Extract
<Array ID="AddressArray">
<Element Value="XYZ"/>
</Array>

The following sections describe how to add configuration settings to

Additional Configuration 5

the AdvanceNDCCustom.accfg file that are not already included by

default in the AdvanceNDCCore.accfg file.

Archiving User‐Defined Files 5

You can use Archive Manager to archive any user‐defined files or

folders by including the file or folder under the
NCR.APTRA.ArchiveMan.AMProviderFiles class. The properties
are:

Table 5-17 Property Description

Archiving User-Defined Files Properties
Groups Specifies the group into which the file or folder is
archived. By default the group name is
FILESGROUP

SourcePath Specifies the path of the file or folder to be archived

SearchPattern Specifies the name of the files or folders to be

archived as specified in SourcePath. An asterisk
can be used as a wildcard.

Recursive Specifies whether to archive sub‐directories. If the

value is True, sub‐directories are archived.

RemoveTrace Specifies whether to delete the files in the

SourcePath after archiving them. If the value is
True, the files are deleted. Any file that cannot be
deleted because it is locked by another process
causes an exception. By default, the value is False
and files are not deleted.

Note: For AMProviderCacheFiles instance,

the default value is True and files are deleted.

For example, Advance NDC does not archive EJ backup files by

default. To archive the files, add the following to the
AdvanceNDCCustom.accfg file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-79

Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Figure 5-40
Example 1 Scheduling Archives Extract
<Class ID="AMProviderEJBackupFiles" Name="NCR.APTRA.ArchiveMan.AMProviderFiles" Assembly=
"NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="Groups" Value="AMProviderFiles1Groups"/>
<Property Name="SourcePath" Value="C:\Program Files\NCR APTRA\Advance NDC\Data\
EJBackups"/>
<Property Name="SearchPattern" Value="EJ*.*"/>
<Property Name="Recursive" Value=" False"/>
<Property Name="RemoveTrace" Value="False"/>
</Interface>
</Class>

<Array ID="AMProviderArray">
<Element Value=" AMProviderEJBackupFiles "/>
</Array>

Note: The EJ backup files are stored in the EJ Backups folder.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-80 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Archive Manager

Archiving Registry Keys 5

By default, Archive Manager does not archive any registry keys.

The steps below show the configuration information that must be
added to the AdvanceNDCCustom.accfg file:

Figure 5-41
Example Archive Registry Keys Extract
1 Add property group name to Class ID AMProviderRegistryHive1:
<Class ID="AMProviderRegistryHive1" Name="NCR.APTRA.ArchiveMan.AMProviderRegistryHives"
Assembly="NCR.APTRA.ArchiveMan.dll">
<Interface>
<Property Name="RegistryKeys"Value="RegistryKeysArray"/>
</Interface>
</Class>

2 Add the AMProviderRegistryHive1Groups before the RegistryKeysArray array ID:

<Array ID="AMProviderRegistryHive1Groups">
<Element Value="REGISTRYHIVEGROUP"/></Array>
<Array ID="RegistryKeysArray">
<Element Value="HKEY_LOCAL_MACHINE\SOFTWARE\NCR" />
</Array>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-81

Configuring Advance NDC and Associated Components
Configuring .NET Retrieve Archive Task

Configuring .NET Retrieve Archive

Task 5

Advance NDC uses the .NET Retrieve Archive component to select

and export the archives on the SST.
The .NET Retrieve Archive component is configured using the
AdvanceNDCCustom.accfg file. Default configuration settings are
included in the AdvanceNDCCustom.accfg file installed with
Advance NDC. For further information about the
AdvanceNDCCustom.accfg file, see “.NET Class Configurator Files”
on page 5‐40.
The examples in this section illustrate how the RETRIEVE ARCHIVE
option of the Configure menu in Supervisor mode can be updated
using the AdvanceNDCCustom.accfg file.

The examples in the following sections show how to update the

Example Updates to settings in the Retrieve Archive Supervisor option.
Settings 5

If you want to change the setting for more than one of the tasks,
make updates to the entries for each option. The tasks are identified
and defined under the class IDs described in Table 5‐18, “Retrieve
Archive Task Class IDs”.

Table 5-18
Retrieve Archive Task Class IDs

Task Class ID

Create archive and export ArchiveNowAndExport

Export all archives ExportAllArchives

Export archives from last 7 days ExportConfiguredDaysArchives

Expert archives from last 24 hours ExportLast24HrsArchives

Display all archives to allow selection and DisplayAllArchivesAndExportSelected

export the selected archive

Display archives for the last 7 days to allow DisplayAndExportConfiguredDaysArchive

selection and export the selected archive

Display archives for the last 24 hours to allow DisplayLast24HrsArchivesAndExportSelected

selection and export the selected archive

Search archives by date to allow selection and SearchArchiveByDateAndExport

export the selected archive

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-82 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Retrieve Archive Task

Task Class ID

Display all archive groups to allow selection DisplayAllGroupsAndExportSelected

and export the selected group

Display archive groups for last 7 days to allow DisplayAndExportArchiveGroupForConfiguredDays

selection and export selected group

Display archive groups for last 24 hours to Display24HrsArchiveGroupAndExportSelected

allow selection and export selected group

Search archive group by date to allow selection SearchArchiveGroupByDateAndExport

and export the selected group

Changing the Export Folder 5

By default, archives are exported to the ATEXports folder on the

selected destination drive. To change the folder used, you must add
the following entry to each menu option entry that you want to
update:
<Property Name="ExportFolder" Value="<folder name>"/>

The following example shows option 0 SEARCH BY FILE updated

to change the default folder to which the archives are exported to
RetrievedArchives:

Figure 5-42
Example Change Export Folder Extract
<Class ID="DisplayAllArchivesAndExportSelected" Name="NCR.APTRA.RetrieveArchive
Tasks.ExportArchives" Assembly="NCR.APTRA.RetrieveArchiveTasks.dll">
<Interface>
<Property Name="ArchiveManagerInstance" Value="StdArchiveManager"/>
<Property Name="ArchiveSearchOption" Value="SelectArchive"/>
<Property Name="UserActivityTimeout" Value="30"/>
<Property Name="ExportFolder" Value="RetrievedArchives"/>
</Interface>
</Class>

Changing the User Response Timeout 5

To change the default time in seconds allowed for a user to respond,

update the value of the UserActivityTimeout property. The
default time allowed for a user response is 30 seconds.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-83

Configuring Advance NDC and Associated Components
Configuring .NET Retrieve Archive Task

Changing the Date Format 5

By default, the ddmmyyyy date format is used when entering the

date. The following example changes the format to mmddyyyy:

Figure 5-43
Example Change Date Format Extract
<Class ID="SearchArchiveByDateAndExport" Name="NCR.APTRA.RetrieveArchiveTasks.
ExportArchives" Assembly="NCR.APTRA.RetrieveArchiveTasks.dll">
<Interface>
<Property Name="ArchiveManagerInstance" Value="StdArchiveManager"/>
<Property Name="ArchiveSearchOption" Value="SelectArchive"/>
<Property Name="DateSearchOption" Value="Specify"/>
<Property Name="UserActivityTimeout" Value="30"/>
<Property Name="EnterMonthFirst" Value="True"/>
</Interface>
</Class>

Using Only Removable Drives 5

To list only removable drives for selection as the destination for the
archive, change the value of the ListNonRemovableDrives
property to False.

Excluding CD and DVD Drives 5

To disable the inclusion of CD and DVD drives in the list of

destination drives for the archive, change the value of the
EnableCDDVDBurning property to false.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-84 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring .NET Retrieve Archive Task

Changing the Number of Days to Search 5

By default, option 1 on the Enter Search Option screen displays files

created over the last 7 days. The following example changes the
search to display files created over the last 10 days:

Figure 5-44
Example 1 Scheduling Archives Extract
<Class ID="DisplayAndExportConfiguredDaysArchive" Name="NCR.APTRA.RetrieveArchiveTasks.
ExportArchives" Assembly="NCR.APTRA.RetrieveArchiveTasks.dll">
<Interface>
<Property Name="ArchiveManagerInstance" Value="StdArchiveManager"/>
<Property Name="ArchiveSearchOption" Value="SelectArchive"/>
<Property Name="DateSearchOption" Value="LastXDays"/>
<Property Name="NumberOfDays" Value="10"/>
<Property Name="UserActivityTimeout" Value="30"/>
</Interface>
</Class>

Note: If you change the number of days to search, you must also
update screen m36 in resrvd.def. In the above example, option 1 has
to be updated to read “LAST 10 DAYS ARCHIVE”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-85

Configuring Advance NDC and Associated Components
Configuring the .NET NDC CRM Service

Configuring the .NET NDC CRM

Service 5

The .NET NDC CRM Service interacts with CRM services such as
Targeted Marketing Promote and Targeted Marketing Customer
Power for the display and retrieval of campaigns, printing of
coupons and generation of events for process completion. The
service handles the time‐out for targeted messaging response and
displays the minimum and maximum time for the display of a
targeted message or campaign.
The .NET NDC CRM Service component is configured using the
AdvanceNDCCustom.accfg file, which also includes the default
configuration settings. For further information about the
AdvanceNDCCustom.accfg file, see “.NET Class Configurator Files”
on page 5‐40.

Note: To use the .NET NDC CRM Service, APTRA Promote or

APTRA Relate must be enabled through Supervisor options on the
Access menu.

The LanguageMapping property defines the supported language

and its corresponding screen offset in Advance NDC. Based on the
current language selection, the screen offset is mapped to the
respective language code for the CRM.
The default language is English (000=eng), the following example
shows the property updated to the offset for Spanish:

Figure 5-45
Example Language Mapping Extract
<Property Name="LanguageMapping" Value="CRMLanguage
Mappings" />
<Array ID="CRMLanguageMappings">
<Element Value="000=ENG" />
<Element Value="200=GER" />
<Element Value="400=FRE" />
<Element Value="600=SPA" />
</Array>

For details on how Advance NDC handles multi‐language screen,

refer to Chapter 3 “Screen Data” in the APTRA Advance NDC
Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-86 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring the .NET NDC CRM Service

The Terminal ID is sent to the APTRA Relate server by the Target

Terminal ID Source 5

Messaging Services (TMS) client to identify the SST. The source of

the Terminal ID can be configured either through the Supervisor
menus, IP address, or SST identification details. Different sources of
identification can be used as follows:
 An all‐digit machine number (option 4 on the Configure menu)
 An alphanumeric machine number (option 91 on the Configure
menu)
 The first 6 digits of the MAC (Message Authentication Code)
machine number (option 12 on the Access menu)
 The IP address of the SST (option 2 on the Configure > TCP/IP
Configuration menu)

Note: Advance NDC sends the IP address set to an SST to the

APTRA Relate server. This IP address can be changed using the
Configure menu

 The MAC (Media Access Controller) address of the SST (unique

hardware number assigned by the user)
 The machine name of the SST (unique name assigned by the
user)
A property (TerminalIDSource) is provided in the
AdvanceNDCCustom.accfg file to inform the APTRA Relate server
where the Terminal ID has come from. The property identifies the
source of information as shown in the table. In the following XML,
the source is identified as the machine number:

Figure 5-46
Example Terminal ID Source Extract
<Class ID="CRMTerminalService" Name="NCR.APTRA.NDC.TerminalService.
NDCTerminalService" Assembly="NCR.APTRA.NDC.TerminalService.dll">
<Property Name="TerminalIDSource" Value="MachineNumber"/>
</Class>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-87

Configuring Advance NDC and Associated Components
Configuring the .NET NDC CRM Service

The following table describes the Terminal ID Source property:

Table 5-19
Configure Terminal ID Source

Property Name Type Description Possible values Default Value

TerminalIDSource String Source of the Terminal ID MachineNumber "MachineNumber"

MACMachineNumber
MACAddress
IPAddress
or
MachineName

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-88 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SST Recovery

Configuring SST Recovery 5

This section describes the following:

 Detecting and recovering from freeze conditions
 Forced rebooting of an SST
 Resetting USB devices.

The NDC Monitor application can be used to manage the status of

NDC Monitor 5

the SST as follows:

 Polling the SST at defined intervals to check that the SST is
responding
 Checking the CPU consumption of the application identified in
the XML configuration file
 If a freeze condition is detected, resetting the SST and/or
reporting an error.

Note: If the SST is to be reset when a freeze condition is

detected, no attempt is made to return the card to the consumer
before the reset. Depending on the capability of the card reader,
the card is either returned following the reset or it is retained.

By default, NDC Monitor is disabled. If enabled as described in

“Enabling NDC Monitor”, NDC Monitor detects that the SST has
become unresponsive at the following times:
 Start of day
 When the SST is in service
 During the execution of monitored states.
NDC Monitor is configured using the NDCMonitor.xml file,
described in “NDC Monitor XML Elements” on page 5‐90. The
monitored states and associated timeout intervals are defined using
the AdvanceNDCCustom.accfg file as described in “The following
extract is an example from the NDCMonitor.xml file:” on page 5‐91.

Enabling NDC Monitor 5

By default, NDC Monitor is disabled. To enable NDC Monitor, edit

C:\Program Files\NCR APTRA\Advance NDC\StartApps.vbs by
removing the apostrophe from the start of the following line:
'oShell.Run "NCR.APTRA.NDC.Monitor.exe " & chr(34) &
strProgFilesPathname & "\NCR APTRA\Advance NDC\Config\
NDCMonitor.xml" & chr(34), 0, false

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-89

Configuring Advance NDC and Associated Components
Configuring SST Recovery

Note: NCR recommends that you investigate the cause of freeze

conditions if they occur.

NDC Monitor XML Elements 5

Table 5‐20, “NDC Monitor XML Elements” describes the elements

used in the NDCMonitor.xml file. The default file installed with
Advance NDC is in the following folder:

C:\Program Files\NCR APTRA\Advance NDC\Config

Table 5-20
NDC Monitor XML Elements

Element Description

NDCMonitor Mandatory.

This is the root element.

The whole file is enclosed within NDCMonitor tags.

Nested elements:
 ResetATMOnHang
 ResponseDelay
 CycleDelay
 CheckCPUConsumption
 ApplicationToMonitor

ResetATMOnHang Mandatory.

Defines whether to reset the SST when a freeze condition is detected.

Valid values are as follows:

 true ‐ Reset the SST and log an error to the event log
 false ‐ Log an error to the event log. This is the default.

ResponseDelay Mandatory.

Defines the period in seconds that NDC Monitor waits for a response from
the monitored application after sending a test message.

The default is 5.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-90 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SST Recovery

Element Description

CycleDelay Mandatory.

Defines the interval in seconds at which NDC Monitor sends a test

message.

After Advance NDC starts, NDC Monitor waits for the period defined by
this element before checking the availability of the application.

If a freeze condition is detected and ResetATMOnHang is set to false,

NDC Monitor is stopped immediately after the error is logged.

The default is 60.

If this element is set to 0, no test messages are sent.

CheckCPUConsumption Mandatory.

Defines whether to check the CPU consumption of the monitored

application.

Valid values are as follows:

 true ‐ Check CPU consumption. This is the default
 false ‐ Do not check CPU consumption

ApplicationToMonitor Mandatory.

Identifies the application to be monitored using the name used to identify

the application window.

The default is SSDSAPP_ApplicationCore.

The following extract is an example from the NDCMonitor.xml file:

Figure 5-47
Example NDC Monitor XML Extract
<NDCMonitor xsi:schemaLocation="http://www.ncr.com/APTRA/ NDC/NDCMonitor NDCMonitor.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns="http://www.ncr.com/APTRA/
NDC/NDCMonitor">
<ResetATMOnHang>false</ResetATMOnHang>
<ResponseDelay>5</ResponseDelay>
<CycleDelay>60</CycleDelay>
<CheckCPUConsumption>true</CheckCPUConsumption>
<ApplicationToMonitor>SSDSAPP_ApplicationCore</ApplicationToMonitor>
</NDCMonitor>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-91

Configuring Advance NDC and Associated Components
Configuring SST Recovery

Defining the States to Monitor 5

Only the standard states provided by Advance NDC can be

monitored. NDC Monitor cannot monitor user‐defined states or C
Exits.
The AdvanceNDCCustom.accfg file contains all the states that can be
monitored in the HangMonitorStateTypes array. The states are
commented out by default. An extract for example:
<Array ID="HangMonitorStateTypes">
<!--Element Value="StartOfDay=120" /-->

Note: The names of the state types must not be changed.

Each state type has a corresponding timer value. These monitoring

timers are independent of the timer values downloaded from the
host. NDC Monitor uses monitoring timers to identify when a freeze
condition has occurred during state execution. Defining a
monitoring timer value of 0 disables the monitoring of the
associated state.
There are two ways to edit the AdvanceNDCCustom.accfg file to
define the states to monitor, as follows:
1 Uncomment only the states you want to monitor

2 Uncomment the whole array and set the monitoring timer value
for states you do not want to monitor to 0.
Monitoring Timers NDC Monitor starts a monitoring timer when 5

a state starts and stops the monitoring timer when the state finishes.
If the state has not completed before the defined monitoring timer
value is reached, a freeze condition is assumed and NDC Monitor
takes the action defined in the NDCMonitor.xml file.

Note: You must ensure that the defined monitoring timer values
allow sufficient time for the completion of the associated state,
including any potential interaction with the consumer.

Valid Timer Numbers Valid timer numbers are as follows: 5

 Timer0 to Timer10 inclusive

 Timer61
 Timer63
 Timer77 to Timer78 inclusive
 Timer80 toTimer83 inclusive
 Timer86 to Timer87 inclusive
 Timer91 to Timer97 inclusive.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-92 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SST Recovery

Valid Timer Value Definitions The following table describes the 5

valid formats that can be used to define the monitoring timer

values:

Table 5-21
Valid Timer Value Definitions

Example of Valid Format Description

<Element Value="CashAccept=Timer1 + 30" /> The value defined by the cardholder

time‐out response timer (Timer 01) plus 30
seconds for execution of the Cash Accept
state

<Element Value="ChequeAccept=Timer1+30" /> The value defined by Timer 01 plus 30

seconds for execution of the Cheque Accept
state

<Element Value="InfoEntry=Timer0 * 2" /> The value defined by the cardholder

keyboard response time timer (Timer 00)
multiplied by 2 for execution of the
Information Entry state

<Element Value="FourFDKSelect=Timer0*2 + 10" /> The value defined by Timer 00 multiplied

by 2 plus 10 seconds for execution of the
Four FDK Selection state

<Element Value="AmountEntry=Timer0" /> The value defined by Timer 00 for

execution of the Amount Entry state

<Element Value="AmountCheck=30" /> Allow 30 seconds for execution of the

Amount Check state

For details of the timers, refer to Chapter 7, “Configuration

Parameters” in the APTRA Advance NDC, Reference Manual.
Whenever the Time‐Out state is entered, the current monitoring
timer is restarted to allow the state to complete if the consumer
requests more time.
Timer Restarts Whenever the communication message time‐out 5

interval timer (Timer 03) is started during the Transaction Request

state, the monitoring timer is restarted. Timer 03 is started
whenever a message is expected from the host and can be started
multiple times during execution of the Transaction Request state.
Invalid Timer Numbers If an invalid timer number or an invalid 5

format is used, a timer value of 0 is used and the associated state

type is not monitored.

An unhandled exception may occur where the SST does not reboot.
Forced Reboot 5

A forced reboot can be configured to ensure that a reboot occurs at

these times. The reboot timer starts as soon as the Advance NDC

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-93

Configuring Advance NDC and Associated Components
Configuring SST Recovery

applications generate any kind of exception and the following

message is logged to the event log:

Advance NDC raised an unhandled exception

Message: <message>

Reason: <reason>

Advance NDC will reboot in <timer> seconds

The registry entry used to configure a forced reboot timer is:

HKLM\SOFTWARE\NCR\Advance NDC\RebootTimeout

By default, this is set to 240 seconds (0xF0). The minimum time that
can be set in this registry entry is 60 seconds.
If the Unhandled Exception Handler (UEH) is not configured as the
exception handler, the SST is not rebooted and the following
message is logged to the event log:

Advance NDC raised an unhandled exception

Message: <message>

Reason: <reason>

NCR UEH is not configured as the exception handler

Note: This registry entry does not override the normal exception
handling. However, if no reboot occurs before the forced reboot
timer expires, it ensures that a reboot occurs following an exception.

There are two types of reset that can be attempted when errors are
Resetting USB Devices 5

reported for USB devices, as follows:

 XFS reset. This is a software reset to clear device errors and is
supported on all SSTs. The reset is performed only on the
specific device
 Express recovery (24‐volt reset). This allows the 24‐volt power
supply for NCR devices connected using a USB Miscellaneous
Interface to be turned off and on. Express recovery is only
attempted for communications failures on version 6.01 and later
of the APTRA XFS platform. The decision to reset is made on an
individual device basis, but the reset is performed across all USB
devices.

Note: Express recovery is not supported for cash acceptors.

Only one reset is attempted for each device. If the reset fails, no
further resets are attempted and the device remains unavailable
until an operator intervenes.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-94 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SST Recovery

If a communications error is detected, the Service Providers can

raise an exception that results in a reboot of the SST. This is disabled
by Advance NDC at installation using the following registry entry:
HKEY_LOCAL_MACHINE\SOFTWARE\Classes\WOSA/XFS_ROOT\SERVICE
_PROVIDERS\ExceptionOnCommsFail

Valid values are as follows:

 0 = Do not raise an exception (set by Advance NDC at
installation)
 1 = Raise an exception (SP default setting).
An XFS reset is attempted if the device is included in the
DeviceRecovery.xml file and the EnableXFSReset attribute is set to 1.
A 24‐volt reset is attempted if the following conditions are met:
 The device is included in the DeviceRecovery.xml file and the
Enable24vReset attribute is set to 1
 No unsuccessful attempt to reset the device has occurred. A
further reset will not be attempted in this situation until
Supervisor mode has been entered and exited.
USB devices are reset based on the APTRA XFS guidelines, as
described in the following table:

Table 5-22
USB Device Reset Rules

Circumstance System Event Reset Description

No COMMS_FAIL is reported WFS_SYSE_HARDWARE_ERROR with An XFS reset is attempted based on

dwAction=WFS_ERR_ACT_RESET the configuration in the
DeviceRecovery.xml file for the device

WFS_SYSE_HARDWARE_ERROR with No reset is triggered and the device

dwAction=WFS_ERR_ACT_HWMAINT remains unavailable until an
operator intervenes

Another vendor’s platform is WFS_SYSE_HARDWARE_ERROR with An XFS reset is attempted based on

in use dwAction=WFS_ERR_ACT_RESET the configuration in the
DeviceRecovery.xml file for the device

WFS_SYSE_HARDWARE_ERROR with No reset is triggered and the device

dwAction=WFS_ERR_ACT_HWMAINT remains unavailable until an
operator intervenes

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-95

Configuring Advance NDC and Associated Components
Configuring SST Recovery

Circumstance System Event Reset Description

COMMS_FAIL is reported and WFS_SYSE_HARDWARE_ERROR with An express recovery (24‐volt reset) is

express recovery is dwAction=WFS_ERR_ACT_RESET performed
supported

WFS_SYSE_HARDWARE_ERROR with An express recovery (24‐volt reset) is

dwAction=WFS_ERR_ACT_HWMAINT performed if configured in the
DeviceRecovery.xml file

COMMS_FAIL is reported and WFS_SYSE_HARDWARE_ERROR with An XFS reset is attempted based on

express recovery is not dwAction=WFS_ERR_ACT_RESET the configuration in the
supported DeviceRecovery.xml file for the device

WFS_SYSE_HARDWARE_ERROR with No reset is triggered and the device

dwAction=WFS_ERR_ACT_HWMAINT remains unavailable until an
operator intervenes

Both the XFS reset and the 24‐volt reset are fully configured and
controlled by the DeviceRecovery.xml file described in the next
section. By default, both XFS reset and 24‐volt reset are enabled for
all devices except for the Card Reader Second device. For more
information on the schema used by the DeviceRecovery.xml file, see
“Note:” on page 5‐98.

Device Recovery XML File 5

The DeviceRecovery.xml configuration file, installed in C:\Program

Files\NCR APTRA\Advance NDC\Config, can be updated either by
using the XML Configuration Download message or by local
modification. For details of the XML envelope that must be used
with this configuration file, see ʺXML Configuration Filesʺ, on page
5‐37. For details of the XML Configuration Download message refer
to Chapter 10, “Central to Terminal Messages” of the APTRA
Advance NDC, Reference Manual.
The device recovery configuration file includes the USB devices as
<Resource> elements. For example, for the receipt printer, the
device name must be given as follows:
<Resource EnableXFSReset ="1" Enable24vReset ="1">Receipt
Printer</Resource>

The device names in the DeviceRecovery.xml must be the same as the

alias’ names provided under the following registry key:
HKLM\SOFTWARE\NCR\Advance NDC\Aliases

For further information on aliases, see ʺCEN‐XFS Logical Device

Namesʺ, on page 5‐17.
The XML entry is case sensitive. If either the configuration file or the
schema contain invalid data or do not exist, all reset functions are
turned off.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-96 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SST Recovery

Note: If no attributes are defined for a device in the XML file, then
no XFS reset or 24‐volt reset commands are sent to the device.

The following extract is an example from the DeviceRecovery.xml file:

Figure 5-48
Example Device Recovery XML Extract
<DeviceRecovery xsi:schemaLocation="http://www.ncr.com/
APTRA/NDC/DeviceRecovery DeviceRecovery.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.ncr.com/APTRA/NDC/DeviceRecovery">
<ActiveDeviceList>
<Resource Enable24vReset="1" EnableXFSReset="1">
Card Reader</Resource>
<Resource Enable24vReset="0" EnableXFSReset="0">
Card Reader Second</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Cash Acceptor</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Cash Dispenser</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Cash Dispenser Second</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Coin Dispenser</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Night Safe</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Journal Printer</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Document Printer</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Receipt Printer</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Envelope Depository</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Envelope Dispenser</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Cheque Processor</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Barcode Reader</Resource>
<Resource Enable24vReset="1" EnableXFSReset="1">
Security Camera</Resource>
</ActiveDeviceList>
</DeviceRecovery>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-97

Configuring Advance NDC and Associated Components
Configuring SST Recovery

Note:
 Advance NDC does not support XFS reset for a contactless card
reader. So if the contactless card reader is configured as the
primary card reader, then the EnableXFSReset value must be
set to 0 for Card reader, and if the contactless card reader is
configured as the secondary card reader, then the
EnableXFSReset value must be set to 0 (default) for Card
Reader Second in the DeviceRecovery.xml file.
 In the DeviceRecovery.xml file, the application configures the
Enable24vReset attribute to 1 for the primary card reader by
default. This value can be changed as required when the
contactless card reader is configured as the primary card reader.

Device Recovery Schema 5

The schema, DeviceRecovery.xsd, defines the structure of the

configuration data for the resets described in Table 5‐23, “Device
Recovery Elements”.

Table 5-23
Device Recovery Elements

Element Description

ActiveDeviceList The whole file is embedded within ActiveDeviceList tags.

This is the root element

Nested elements:
 Resource

Resource Defines the device alias name.

The following attributes define whether a reset is enabled or disabled for the
device:
 EnableXFSReset
Mandatory
Defines whether XFS reset is enabled for the device
Valid values are as follows:
0 ‐ XFS reset is disabled
1 ‐ XFS reset is enabled (default)
 Enable24vReset
Mandatory
Defines whether express recovery is enabled for the device
Valid values are as follows:
0 ‐ Express recovery is disabled
1 ‐ Express recovery is enabled (default)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-98 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring SST Recovery

UPS devices are supported through the SIU service provider (SIU
Uninterruptible Power SP) and can be configured through the System Application. For full
Supply 5
configuration details refer to the APTRA on‐line documentation
under APTRA XFS | Programmer’s Reference | Feature
Management | Power Supplies | PCUnintPowerSupply.
The CheckMainPowerStatus (DWORD) registry is used to keep the
SST either in service or out of service when the mains power is
active and the battery level is below the low threshold. The registry
is available in the following path:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\UPS

A summary of UPS power management when the registry value is

set to 0 (default) is given in the following table.

Table 5-24 Mains Failed Battery Low Action taken

UPS Power Management when registry is
set to 0 False False SST runs as normal using the mains supply

False True SST switches to Out of Service until the battery

level exceeds the low threshold, at which point
it goes in service. If the mains power fails
again during this period, SST performs a
controlled shutdown.

True False SST switches to Out of Service

True True SST performs a controlled shutdown

A summary of UPS power management when the registry value is

set to 1 is given in the following table.

Table 5-25 Mains Failed Battery Low Action taken

UPS Power Management when registry is
set to 1 False False SST runs as normal using the mains supply

False True SST runs as normal using the mains supply

If the mains power fails during this period,

SST performs a controlled shutdown.

True False SST switches to Out of Service

True True SST performs a controlled shutdown

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-99

Configuring Advance NDC and Associated Components
Configuring Suspend Timeout

Configuring Suspend Timeout 5

As devices are now accessed through the CEN‐XFS interface,

clearing the Suspend mode is controlled by the SPs, but the
CEN‐XFS specification does not define whether applications can
clear Suspend mode themselves.
The Advance NDC application detects a Suspend mode at the end
of the Close state and before the idle loop recommences. The SP
clears the Suspend state at the SP level, after the timeout defined in
the SP configuration.
When the SST detects that a device has been tampered with, the
application goes out of service temporarily and the SST goes into
Suspend mode until one of the following occurs:
 The host sends a go‐in‐service (GIS) message
 The host sends a out‐of‐service (OOS) message
 The application Suspend timeout expires
 Supervisor is entered by pressing the Mode switch.
The SST does not go into Suspend mode until the end of the
transaction in which tampering has been detected.
When the SST attempts to come out of Suspend mode, the SP
attempts to clear the device that caused the suspension of service. If
this succeeds then the SST is no longer suspended.
The SPs have their own configurable timers for coming out of
Suspend mode and will attempt to clear the devices when these
timers expire. SPs report devices as still in the Suspend state
(WFS_STAT_DEVUSERERROR) until the SP timers expire. Registry
entries are used to set the SP timers.
Although the host removes the application from the Suspend state,
a command to change the mode (Supervisor, In Service, Out of
Service, Initialise or Power‐up) will not be actioned nor will a Ready
9 response be sent until the SP has cleared the device Suspend state.
When the Suspend state is cleared, Advance NDC responds to the
terminal command and then sequentially processes all other
messages received.

The Suspend Timeout registry entry is located in the

Setting the Service GENERAL_CONFIGS subkey for each supported SP. The default
Provider Timeout 5
timeout duration for Advance NDC is 120 seconds, which is the
minimum duration recommended in Advance NDC. For more
information about setting the Suspend Timeout registry entry, refer

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-100 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Suspend Timeout

to the APTRA on‐line documentation, under APTRA XFS |

Programmers Reference | XFS Service Providers.
Ensure that the SP timers are set to a value greater than the time it
takes to complete a transaction. If the value is less, the application
will not enter the Suspend state even though the host receives a
Suspend message. This is the equivalent of the application going
into a Suspend state and coming out again after a very short
application timeout.

Note: The SP Suspend Timeout for recycling units is set by

Advance NDC to the maximum limit of 900 seconds. This means
that Advance NDC can issue the reset command to bring the
recycling unit out of suspend in any of the following situations:

 A go in service or go out of service message is sent

 The timeout for Advance NDC expires
 Supervisor mode is entered or exited.

For more information, see “GBXX Cassette Configuration” on

page 5‐388.
For more information about Suspend time outs, refer to the
Extensions for Financial Services (XFS) interface specification (CWA
14050).

The Advance NDC application timeout is set to 5 minutes (300

Setting the Application seconds). The timer can be changed through the Author (Timer
Timeout 5
worker “5 Mins”). The application timeout must always be longer
than that of the service provider (SP). This will allow the SP to clear
the device ready for use by the application. If the application timer
setting is less than the SP timer, the application will stay in the
Suspend state until the SP timer expires. Moreover, if the host sends
a GIS or OOS message, the SST will stay in Suspend mode until the
SP timer expires.

When the Skimming Protection System (SPS) detects a skimming

Setting the Unusual Object device, it protects the customer’s data by jamming the device. The
Monitoring Timeout 5
Advance NDC application is notified about the tampering and goes
into a Suspend mode. The behaviour of the application suspend
timeout when an unusual object is detected is dependent on the
configuration of the Unusual Object Monitoring TimeOut
(DWORD) XFS registry key.
The Unusual Object Monitoring TimeOut (DWORD) registry key
location is dependant on the type of card reader.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-101

Configuring Advance NDC and Associated Components
Configuring Suspend Timeout

Table 5-26
Registry Entry for Unusual
Object Monitoring Timeout

Device Type Registry Location

USBSmartDipCardReader HKEY_LOCAL_MACHINE\SOFTWARE\NCR\APTRA Self-Service Support

(NCR Features)\UsbSmartDipCardReader\Operational
Parameters\MCRW-01-UsbSmartDipReader\Device

USBIMCRW HKEY_LOCAL_MACHINE\SOFTWARE\NCR\APTRA Self-Service Support

(NCR Features)\USBIMCRW\Operational Parameters

When any unusual object is identified, the Advance NDC

application will remain in a suspend state even after the application
suspend timeout is completed and will remain so until the unusual
object monitoring timeout is completed. Once the unusual object
monitoring time expires, the application comes to service without
any host interaction or supervisor entry/exit. The timer value can be
any value that is supported by the SPS device. For example, 5
minutes, 3 hours or 3 days.
However, after the unusual object monitoring timeout is completed,
one of the following occurs:
 If the unusual object is still present in the card reader, the device
reports the status as fatal and an unsolicited message with card
reader fatal (D04) is sent to the host.
 If there is no unusual object in the device, then within the
application a suspend time‐out takes place and a reset is
performed on the card reader device to make it available for the
next user interaction.
If the unusual object monitoring timer value is set to zero, the
application will wait in a suspend state for an indefinite time or till
the unusual object is removed from the card reader. If the unusual
object is removed, then a suspend time‐out takes place and a reset is
performed on the card reader device to make it available for the
next user interaction.
For more information about unusual object monitoring timeout,
refer Motorised Card Reader and Dip Card Reader driver
documentation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-102 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Configuring Supervisor
Functionality 5

This section describes the functionality that can be configured for

Supervisor.
Where configuration is done using the class configurator file,
default configuration settings are included in the
AdvanceNDCCustom.accfg file installed with Advance NDC. For
information on the AdvanceNDCCustom.accfg file see “.NET Class
Configurator Files” on page 5‐40.

The Supervisor settlement screens can be configured. Changing

Settlement Screen these screens may overwrite the input data, or result in
Customisation 5
misalignment. If this happens, update the Operator Echo workers in
the Application Core to reposition the input data. The affected
screens and associated workers are shown in Table 5‐27.

Table 5-27 Screen Number Operator Echo Worker Name

Correcting Settlement Screen
Customisation Misalignment i93 One Key Input: 1

i94 32 Key Input

i95

i98 8 Key Input

12 Key Input

For further information on the screens, refer to the APTRA Advance

NDC, Reference Manual. For further information on the workers,
refer to the Author on‐line help.

The Extended Add Cash option on the Configure menu in

Extended Add Cash Supervisor is offered, in particular, for use on multi‐vendor
Option 5
networks. It can be configured as follows:
 The currencies that are displayed on the Update SP Currency ID
screen are configurable using the following registry key:

HKLM\SOFTWARE\NCR\Advance NDC\supervisor\CurrencyIDs

 The names used to identify the physical position of the cassettes

are configurable using the following registry key:

HKLM\SOFTWARE\NCR\Advance NDC\Physical Cassettes

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-103

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

This key contains four entries. If a value is changed, the currency

ID must be a valid ISO currency code.

For more information about the Extended Add Cash Supervisor

option, refer to the APTRA Advance NDC, Supervisor’s Guide.
For more information about configuring currencies on other
vendors’ SSTS, refer to the APTRA Advance NDC, Multi‐Vendor
Support Reference Manual.

Rear settlement is available on DAPI 7 firmware only. To configure

Rear Settlement 5

the PIN Entry and PIN Block for rear settlement transactions, use
the following:

PIN Entry 5

To configure PIN entry on the rear display of an SST with a

PCI‐compliant EPP, use the EnhancedOptionDigit6A entry under
the following registry key:

HKLM\SOFTWARE\NCR\Advance NDC\supervisor\Rear Settlement

The default value is 0 which is used if the entry does not exist or if it
contains an invalid value. If the value is set to 0, the value is ignored
and PIN entry is required at the front interface only.
If the value is set to 1, PIN entry can be performed at the rear
interface. A dummy PIN block is included in the Transaction
Request Message if Message Mode Option digit 6A is
enabled.Details of the option digit are given in Appendix

Dummy PIN Block 5

To configure the number of zeros to include in a dummy PIN block

in the Transaction Request Message, use the DummyPINBlockZeros
entry under the following registry key:

HKLM\SOFTWARE\NCR\Advance NDC\supervisor\Rear Settlement

Valid values are 1 to 32. The default value is 6, which is used if the
key does not exist or if it contains an invalid value.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-104 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Alphanumeric data entry is supported in the SMS style using either

Supervisor Alphanumeric numeric keys or through a PC keyboard if one is available.
Data Entry 5

As well as alphanumeric input in the range 0‐9, A‐F, the SMS

keyboard input system allows users to enter data in the full
alphanumeric range (0‐9, a‐z and A‐Z). The SMS keyboard system
also supports data entry using a PC keyboard.
SMS‐style data entry is enabled by default and the data is collected
and processed by an SMS Data Collector worker. This worker is
configured through an XML configuration file,
SupervisorKeyboard.xml, which is provided in Advance NDC in
C:\Program Files\NCR APTRA\Advance NDC\Config. The XML
defines the alphanumeric values associated with each key, as
described in “Supervisor Keyboard XML Configuration File” below.
An associated XML schema file, SupervisorKeyboard.xsd, is also
provided in the same location to validate SupervisorKeyboard.xml.
The schema ensures that all values are within defined ranges, and
all required entries are present, and in their correct location.
The configuration file can be updated locally or through XML
Configuration Download message from the host. For details of the
XML envelope that must be used with this configuration file, see
“XML Configuration Files” on page 5‐37. For details of XML
Configuration Download, refer to the APTRA Advance NDC,
Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-105

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Supervisor Keyboard XML Configuration File 5

The following extract is an example from the SupervisorKeyboard.xml

file:

Figure 5-49
Example Supervisor Keyboard XML
Extract
<?xml version="1.0" encoding="utf-8"?>
<SupervisorKeyboard xmlns=http://www.ncr.com/APTRA/NDC/SupervisorKeyboard xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ncr.com/
APTRA/NDC/SupervisorKeyboard SupervisorKeyboard.xsd">
<SupervisorKeyboardType>SMS</SupervisorKeyboardType>
<SMSKeyboardConfiguration>
<SMSKeyboardLayout>
<Key0>0</Key0>
<Key1>1</Key1>
<Key2>abc2</Key2>
<Key3>def3</Key3>
<Key4>ghi4</Key4>
<Key5>jkl5</Key5>
<Key6>mno6</Key6>
<Key7>pqrs7</Key7>
<Key8>tuv8</Key8>
<Key9>wxyz9</Key9>
</SMSKeyboardLayout>
<SMSEntryDelay>2000</SMSEntryDelay>
<SMSKeypressBeep>KeypressBeep1</SMSKeypressBeep>
<SMSNextCharBeep>NextCharBeep1</SMSNextCharBeep>
</SMSKeyboardConfiguration>
</SupervisorKeyboard>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-106 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Table 5-28
Supervisor Keyboard: Elements

Element Description Range of Values Default Value

SupervisorKeyboardType Specifies the keyboard type: SMS SMS

If SMS, input is through the TTU or PCKeyboard
the PINpad depending on the
interface.
If PCKeyboard, input is through
the standard PC keyboard
regardless of the interface.

SMSKeyboardConfiguration SMS‐style keyboard configuration ‐ ‐

information, with the following
nested elements:
 SMSKeyboardLayout
 SMSEntryDelay
 SMSKeypressBeep
 SMSNextCharBeep

SMSKeyboardLayout Defines the key mapping, with ‐ ‐

Key0 to Key9 nested

Key0 SMS character string representing Any string 0

one or more indexed characters
when key 0 is pressed; must be
lowercase

Key1 SMS character string representing Any string 1

one or more indexed characters
when key 1 is pressed; must be
lowercase

Key2 SMS character string representing Any string abc2

one or more indexed characters
when key 2 is pressed; must be
lowercase

Key3 SMS character string representing Any string def3

one or more indexed characters
when key 3 is pressed; must be
lowercase

Key4 SMS character string representing Any string ghi4

one or more indexed characters
when key 4 is pressed; must be
lowercase

Key5 SMS character string representing Any string jkl5

one or more indexed characters
when key 5 is pressed; must be
lowercase

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-107

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Element Description Range of Values Default Value

Key6 SMS character string representing Any string mno6

one or more indexed characters
when key 6 is pressed; must be
lowercase

Key7 SMS character string representing Any string pqrs7

one or more indexed characters
when key 7 is pressed; must be
lowercase

Key8 SMS character string representing Any string tuv8

one or more indexed characters
when key 8 is pressed; must be
lowercase

Key9 SMS character string representing Any string wxyz9

one or more indexed characters
when key 9 is pressed; must be
lowercase

SMSEntryDelay Defines the delay in milliseconds 2000—5000 2000

between a key being pressed and
the SMS character being processed
as input.

SMSKeypressBeep Defines whether a beep is sounded NoKeypressBeep KeypressBeep1

when a key press occurs KeypressBeep1

SMSNextCharBeep Defines whether a beep is sounded NoNextCharBeep NextCharBeep1

when a series of keystrokes is NextCharBeep1
converted into an SMS character NextCharBeep2
and accepted as input NextCharBeep3
NextCharBeep4

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-108 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

For details of the SMS Data Collector worker, see “Self‐Service

Core” on page B‐16, and refer to the Self‐Service Core Worker Class
Help in the APTRA Author.

Delayed Password Masking 5

To assist with the correct entry of the alphanumeric password, the

last character entered can be displayed briefly before it is masked.
This is configured in the registry as follows:

Table 5-29
Registry Entry for Delayed Password
Masking

Name Type Description Valid Values

SMSPasswordMaskTimer REG_DWORD Time in seconds to display  0 ‐ Characters are

the last character entered immediately masked
before it is masked without being displayed
(default)
 1 to 3 ‐ Characters are
masked after the
required/specified delay
 If the value is out of range
or the registry name is not
present, the default value
is used

PA‐DSS Compliance The Supervisor password is masked 5

immediately by default, and applying a delay of one to three

seconds for each characters also complies with PA‐DSS guidelines.
 For further information on PA‐DSS compliant solutions, see
“PCI DSS & PA‐DSS Compliance in Advance NDC” on page E‐1
 For information on Supervisor functions that support a PA‐DSS
compliant solution, refer to section “PCI DSS and PA‐DSS
Compliance” in Chapter 1, “Introduction to Supervisor Mode”
of the APTRA Advance NDC, Supervisorʹs Guide.

You can extend the functionality of Advance NDC by integrating an

.NET Supervisor Task 5

existing .NET Supervisor task or developing a new .NET Supervisor

task.

Developing a New .NET Supervisor Task 5

To be valid a new .NET Supervisor task must conform to the SPL

guidelines for a Supervisor function and implement the
ISupervisorTask interface. For information about SPL guidelines,
refer to the following:
 Software Engineering Institute web site

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-109

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

 SPL Development Rules and Conventions (NCR intranet users

only)
The .NET Supervisor task inherits from
NCR.APTRA.SupervisorTaskCore.StandardTask class which is
located in the NCR.APTRA.SupervisorTaskCore.dll.

Integrating New or Existing .NET Supervisor Tasks 5

Advance NDC executes a .NET Supervisor task through either the

Supervisor Exit Executor worker or the Supervisor Task Executor
worker. The configuration required for the .NET Supervisor task
must be added to AdvanceNDCCore.accfg file so that the Supervisor
Task Executor and the Supervisor Exit Executor can refer to the task
from the authored flow.
If printing to journal or receipt printer is required, each .NET
Supervisor task must identify the Journal Service and Receipt
Service, as shown in the following example from the
AdvanceNDCCore.accfg file showing the StartInvestigation and
DeleteInvestigation class definitions:

Figure 5-50
Example Start Investigation and Delete
Investigation Extract
<Class ID="StartInvestigation" Name="NCR.APTRA.PDCSupportTasks.StartInvestigation" Assembly=
"NCR.APTRA.PDCSupportTasks.dll">
<Interface>
<Property Name="UserActivityTimeout" Value="0"/>
<Property Name="DisplayTimeout" Value="0"/>
<Property Name="JournalService" Value="FormattedJournalService"/>
</Interface>
</Class>

<Class ID="DeleteInvestigation" Name="NCR.APTRA.PDCSupportTasks.DeleteInvestigation"

Assembly="NCR.APTRA.PDCSupportTasks.dll" >
<Interface>
<Property Name="UserActivityTimeout" Value="0"/>
<Property Name="DisplayTimeout" Value="0"/>
<Property Name="JournalService" Value="FormattedJournalService"/>
</Interface>
</Class>

The default settings for the FormattedJournalService class are

also provided in AdvanceNDCCore.accfg.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-110 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

The SupervisorTaskWrapper class is defined in

AdvanceNDCCore.accfg as follows:

Figure 5-51
Example Supervisor Task Wrapper Extract
<Class ID="SupervisorTaskWrapper" Name="NCR.APTRA.NDC.SupvTaskWrapper.
SupervisorTaskWrapper" Assembly="NCR.APTRA.NDC.SupvTaskWrapper.dll">
<Interface>
<Property Name="CIFRenderer" Value="ConsumerGUIRenderer" IsLink="true"/>
<Property Name="TTURenderer" Value="OperatorTextRenderer" IsLink="true"/>
</Interface>
</Class>

Table 5‐30 Property Description

SupervisorTaskWrapper Properties
CIFRenderer The consumer interface renderer to be used if on the
front interface

TTURenderer The renderer for the text terminal unit (TTU) to be

used if on the rear interface

The properties defined by the SupervisorTaskWrapper class are

used to configure all .NET Supervisor tasks that are subsequently
executed by any Supervisor Task Executor or Supervisor Exit
Executor.
The configuration of the .NET Supervisor task to be executed will
vary for each Supervisor task. For more information, refer to the
.NET Supervisor Tasks On‐line Documentation.
Supervisor Exit Executor This worker allows Activate .NET 5

Supervisor tasks to be configured and executed in the same way as a

Supervisor Exit, without any additional authoring updates.
However, like the execution of Supervisor Exits, only the top two
levels of the Supervisor menus can be configured to execute a .NET
Supervisor task.
Supervisor Task Executor This worker requires additional 5

authoring in the Supervisor project to implement the required

functionality, but the .NET Supervisor task can be executed
anywhere in the application flow.
For information about configuring SUPCTR to enable the
Supervisor Exit Executor to execute .NET Supervisor tasks, refer to
the publication APTRA Advance NDC, Extending the Product, chapter
8, “Developing Exits for Supervisor Functions”.
For information about the Supervisor Exit Executor and Supervisor
Task Executor, refer to the on‐line help in the APTRA Author.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-111

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Advance NDC uses the .NET Software Update Tasks component to

.NET Software Updates 5

install or update software and configuration files (without the need

to use a PC keyboard) on an SST from a removable medium such as
a diskette, CD‐ROM or USB stick.
As the .NET Software Update Service is installed and run as a
Windows service by default, the .NET Software Update Tasks
component uses it to install or update software on an SST without
requiring Advance NDC to run with administrator privileges.
For details of configuring the .NET Software Update Service, see
“.NET Software Update Service” on page 5‐114.
For more information about the functionality of the .NET
components, refer to the following:
 .NET Software Update Tasks On‐line Documentation
 .NET Software Update Service On‐line Documentation.
In Advance NDC, the software update functionality is disabled by
default. If enabled, access to it from the Misc Funcs menu in
Supervisor, requires secure authentication (user ID and password).
Any text terminal unit (TTU) screen definitions associated with
running files or copying files must be present in the
NCR.APTRA.SoftwareUpdateTasks.frmttu file in the C:\Program
Files\NCR APTRA\Printing\TTU\Forms folder.

Configuring the Installation Script 5

By default, selecting the Run Executable File option in Supervisor

runs install.bat if it is found on the removable medium. To run a
different file, edit the InstallScript property in
AdvanceNDCCustom.accfg.
The default entry is as follows:

Figure 5-52
Example Configuring Installation Script
Extract
<Class ID="RunExecutableFile" Name="NCR.APTRA.SoftwareUpdateTasks.SoftwareUpdateTasks"
Assembly="NCR.APTRA.SoftwareUpdateTasks.dll">
<Interface>
...
<Property Name="InstallScript" Value="install.bat"/>
</Interface>
</Class>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-112 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Enabling the Software Update Function To enable the function, 5

update the SoftwareUpdateEnabled property in

AdvanceNDCCustom.accfg to True, as follows:

Figure 5-53
Example Enabling Software Update
Function Extract
<!-- Software Update Tasks - Run Executable File -->
<Class ID="RunExecutableFile" Name="NCR.APTRA.Software UpdateTasks.SoftwareUpdateTasks"
Assembly="NCR.APTRA.Software UpdateTasks.dll">
<Interface>
<Property Name="SoftwareUpdateService"Value="SWUpdateService"/>
<Property Name="SoftwareUpdateEnabled" Value="True"/>
<Property Name="InstallScript" Value="install.bat"/>
<Property Name="InstallationRootDirectory" Value=""/>
<Property Name="UserActivityTimeout" Value="0"/>
<Property Name="VerifySignature" Value="True" />
</Interface>
</Class>

Configuring the Copy File Directory 5

By default, the .NET Software Update Tasks component copies files

to the following:

C:\Program Files\NCR APTRA\Advance NDC\UpdateSoftware.

To change the destination folder, edit the Installation
RootDirectory property in AdvanceNDCCustom.accfg.

The default entry is as follows:

Figure 5-54
Example Configuring Copy File
Directory Extract
<Class ID="Copy Files" Name="NCR.APTRA.SoftwareUpdateTasks.SoftwareUpdateTasks"
Assembly="NCR.APTRA.SoftwareUpdateTasks.dll">
<Interface>
...
<Property Name="InstallationRootDirectory" Value="C:\program Files\NCR APTRA\Advance
NDC\UpdateSoftware "/>
</Interface>
</Class>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-113

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Enabling File CopyTo enable file copying, update the 5

SoftwareUpdateEnabled property in AdvanceNDCCustom.accfg to

True, as follows:

Figure 5-55
Example Enabling File Copy Extract
<!--Software Update Tasks - Copy File -->
<Class ID="CopyFiles" Name="NCR.APTRA.SoftwareUpdateTasks.SoftwareUpdateTasks" Assembly=
"NCR.APTRA.SoftwareUpdateTasks.dll">
<Interface>
<Property Name="SoftwareUpdateService" Value="SWUpdateService"/>
<Property Name="SoftwareUpdateEnabled" Value="True"/>
<Property Name="InstallScript" Value=""/>
<Property Name="InstallationRootDirectory" Value="C:\program Files\NCR APTRA\Advance
NDC\UpdateSofware"/>
<Property Name="UserActivityTimeout" Value="0"/>
<Property Name="VerifySignature" Value="True" />
</Interface>
</Class>

For details of the Software Update menu functions in Supervisor,

refer to the APTRA Advance NDC Supervisor’s Guide.

.NET Software Update Service 5

If the .NET Software Update Service is not installed, updates can be

performed but with the same access restrictions as Advance NDC. If
the user account that Advance NDC runs under has sufficient
privileges, the .NET Software Update Service does not need to be
installed.
Configuring .NET Software Update Service The .NET Software 5

Update Service is configured through the property, UseService,

which specifies whether it must be used or not. By default, the
UseService property has a value of False, as follows:

Figure 5-56
Example Configuring .NET Software
Update Service Extract
<!-- Software Update service -->
<Class ID="SWUpdateService" Name="NCR.APTRA.SWUpdateSrv.SWUpdate" Assembly="NCR.APTRA.
SWUpdateSrv.dll">
<Interface>
<Property Name="UseService" Value="False"/>
</Interface>
</Class>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-114 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

This means that the update will be performed under the user
account that Advance NDC runs under and with the same
restrictions.
If UseService is set to True, the .NET Software Update Service will
always be used to perform the update and any installation will be
run with the full system privileges available under the Local System
user account. If the .NET Software Update Service is not installed,
registered and running, the update will fail.
For Advance NDC to be PCI compliant, the Signature Verification
Service must be used as described in the following section. For
further information, refer to the APTRA Advance NDC, Payment
Application Data Security Standard Implementation Guide.

Security Considerations 5

It is acceptable for file copying to be performed under the Local

System user account as the directory is specified by the task, but
install script updates can be used to run any commands. Security is
maintained by the VerifySignature property under the
RunExecutableFile and CopyFiles class IDs. By default, the
VerifySignature property has a value of True, meaning that
signature verification is required, as follows:
<Property Name="VerifySignature" Value="True" />

Signature Verification Service All the deliverables of Advance 5

NDC are digitally signed. The Signature Verification Service

component verifies the signature on signed files to ensure that the
files are not maliciously altered or accidentally corrupted since the
time of signing. For further information, refer to the Signature
Verification Service On‐line Documentation.
The Signature Verification Service component requires signed files
to be one of the following types:
 .cab
 .dll
 .exe
 .msi
Compatibility with Other Products The .NET Software Update 5

Tasks component is compatible with SolidCore for APTRA and

Security for APTRA. The .NET Software Update Tasks component
does not perform any security validation of the installation medium
before installing or copying files.
The .NET Software Update Service has no means of validating batch
files or executables, which will run with system‐wide privileges and
are able to perform any action. It is the client applicationʹs
responsibility to validate the batch file or executable if required.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-115

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Software signing works and integrates with Security for APTRA

and Solidcore for APTRA.

The Promote/Copyfile option on the Supervisor Access menu uses a

Promote/Copyfile 5

.NET Supervisor task to interact with APTRA Promote. This option

is configured using the AdvanceNDCCustom.accfg file.

Configuring the Export File Path 5

The details of the APTRA Promote screens played and coupons

printed are stored in the presentation log. The presentation log is
exported to a filename of the following format:
<MachineNumber>_Summary_<StartDate>_<EndDate>.arulog

The format for a presentation log for the 28th June 2011 created on
machine number WINAC185092‐ZNV, for example, would be as
follows:
WINAC185092-ZNV_Summary_26-06-2011_28-06-2011.arulog

When the Extract Presentation Log option is selected, the

presentation log is exported to the path defined in the
ConfigurableExportFilePath property of the
PromoteOrCopyFile class. By default, this is set as follows:
<PropertyName="ConfigurableExportFilePath"
Value="C:\Program Files\NCR APTRA\Advance NDC\Data\
PresentationLog"/>

To set a different path, edit this entry in the

AdvanceNDCCustom.accfg file.

The Relate option on the Supervisor Access menu uses a .NET

Relate Supervisor Option 5

Supervisor task to enable or disable APTRA Relate. This option is

configured using the AdvanceNDCCustom.accfg file.
By default, APTRA Relate is disabled. If you need to enable APTRA
Relate and cannot use the Supervisor menu, update the value of the
ServiceEnabled property under the
NCR.APTRA.TMSCustomerPowerTMSrv class as follows:
<PropertyName="ServiceEnabled" Value="true"/>

Advance NDC can be configured to show or hide fixed drives. By

Configuring Multiple default, fixed drives are displayed but this can be changed to avoid
Destination Screens to files being saved by mistake to a fixed drive. To change the display
Display Fixed Drives 5 of fixed drives, use the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\HideFixedDrives

Valid values are as follows:

 0 = Display the fixed drives on the SST (default)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-116 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

 1 = Do not display the fixed drives on the SST.

Changing this setting affects the following Supervisor menus:
 INIT EJRNL (Initialise electronic journal) on Replenish Menu
 RCOPY EJRNL (Recopy Electronic Journal) on Replenish menu
 COPY ON/OFF on the Dialup Configuration menu
 COPY LOGS on Silent Debug menu
 RECONFIGURE on Silent Debug menu.

The Create Signatures option in Supervisor prompts the operator to

Configuring the Default select a destination for the signatures. One option is the
Location for Note pre‐configured location on a fixed drive, which is displayed as
Signatures 5 ‘DEFAULT LOCATION’ in the Supervisor task.
Advance NDC is installed with a default location of C:\Program
Files\NCR APTRA\Advance NDC\Data\Signatures. This can be
changed by editing the CreateSignaturesPath property in
CashInCustom.accfg, as follows:

Figure 5-57
Example Default Location Note
Signature Extract
<Class ID="CreateSignatures" Name="NCR.APTRA.ECB6SupervisorTasks.CreateSignatures"Assembly=
"NCR.APTRA.ECB6SupervisorTasks.dll">
<Interface>
<Property Name="CreateSignaturesPath" Value=" C:\Program Files\NCR APTRA\Advance
NDC\Data\Signatures "/>
<!-- Property Name="AutoSelectSignaturePath"
Value="false"/-->
</Interface>
</Class>

To automatically select the destination defined in the

CreateSignaturePath property during execution of the Create
Signatures Supervisor option, complete the following:
1 Uncomment the AutoSelectSignaturesPath property

2 Update the value to true.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-117

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

The Extract Signatures option in Supervisor copies the signatures

Configuring Extracted recorded in a database during transactions to a selected destination.
Signatures 5
You can configure the file name and format and the location of
extracted signatures.
Advance NDC is installed with a default location of C:\Program
Files\NCR APTRA\Advance NDC\Data\Signatures. This can be
changed by editing the ExtractSigsOutputPath property in
CashInCustom.accfg, as follows:

Figure 5-58
Example Configuring Extracted
Signature Extract
<Class ID="ExtractSignatures" Name="NCR.APTRA.ECB6SupervisorTasks.CreateSignatures"
Assembly="NCR.APTRA.ECB6SupervisorTasks.dll">
<Interface>
<Property Name="ExtractSigsOutputPath" Value=" C:\Program Files\NCR APTRA\
Advance NDC\Data\Signatures "/>
<Property Name="CompressToCab" Value="true"/>
<Property Name="OutputFilename" Value="ECBExt.xml"/>
</Interface>
</Class>

The CompressToCab and OutputFilename properties can be

configured as follows:
 The CompressToCab property defines whether the extracted
signature file is to be saved as a zipped file. By default, the file
will be saved as a zipped file
 The OutputFilename property defines the name of the saved
file. By default, the filename is ECBExt.xml. You can change the
filename if required.

The HandlingValidation property in the CashInCustom.accfg file

Configuring must be set to IgnoreDenomination to ignore validating the
Denomination and Note denomination and note ID while performing the Create Signatures
ID Validation 5 option to capture the signatures for the as follows:
<Class ID="CreateSignatures"
Name="NCR.APTRA.ECB6SupervisorTasks.CreateSignatures"
Assembly="NCR.APTRA.ECB6SupervisorTasks.dll">
<Interface>
<Property Name="HandlingValidation"
Value="IgnoreDenomination" />
</Interface>
</Class>

This allows to create signatures for a note, which is identified as

another category note in any of the orientations when they are
validated while performing the Create Signatures task. that are

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-118 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

identified as a different category note when compared to the

categories identified in other orientations in any of the orientation
when they are validated.
This allows to create signatures for the type of notes which are
detected as a different category note when they are validated in a
different orientation.
By default, the value is set to Default, which validates the
denomination and note ID when the Create Signatures option is
performed.
For example, if a 50 EURO denomination note is detected as
category 2 (counterfeit) type in three orientations and category 1
(invalid) in one orientation while performing Create Signature task
and if the HandlingValidation property is set to
IgnoreDenomination, then the signatures are created for all the
four orientations. If the property is set to Default then only three
signatures will be created for three orientations where note is
identified as category 2 and throws a error while capturing the
signature in the fourth orientation.

Journaling Supervisor Mode Whenever supervisor mode change is attempted during a

Change During a transaction, either using the supervisor switch, opening the safe
Transaction 5
door or cabinet door, Advance NDC allows the transaction to
complete.
After the transaction is completed, the application goes to
supervisor mode with a supervisor entry message to the host and a
message is journaled to the EJ to identify it as a fraudulent activity.
The application journals (reserved screen j0090) the following text:

SUPERVISOR ENTRY ATTEMPTED DURING TRANSACTION

Note: During a transaction, if supervisor entry and exit happens,

the above text is journaled in the EJ. The transaction will be
completed and the application goes to In Service mode.

A simulated Supervisor Entry/Exit message is sent to the host

Configuring Supervisor during automatic error recovery for a device. It is also sent when a
Entry/Exit Messages 5
24‐volt reset is initiated or when an mStatus of 35 is generated.
To distinguish between an unsolicited sensors status message sent
to Central when a Supervisor mode change occurs and a simulated
Supervisor Entry/Exit, an extra field can be configured using the
following DWORD registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\
EnableAERFlagDuringSimSupervisor

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-119

Configuring Advance NDC and Associated Components
Configuring Supervisor Functionality

Valid values are as follows:

 0 = Send P21 and P20 messages for both Supervisor mode
changes and simulated Supervisor Entry/Exit (default)
 1 = Send P21 and P20 messages for Supervisor mode changes
and P211 and P201 messages for simulated Supervisor
Entry/Exit.
If an invalid value is specified or the key does not exist, the default
value is used. This key has no impact on the Supervisor Entry/Exit
message during Supervisor mode change.

Simulated Supervisor Entry/Exit Messages 5

Simulated Supervisor Entry/Exit messages can be sent to the host

after the automatic error recovery by configuring the following
registry value:
HKLM\SOFTWARE\NCR\Advance
NDC\Supervisor\SuppressSupervisorAERMessages

Valid values are as follows:

0 = Send simulated Supervisor Entry/Exit messages to the host if
automatic error recovery is successful (default).
1 = Do not send simulated Supervisor Entry/Exit messages to the
host.
2 = Send simulated Supervisor Entry/Exit messages to the host
irrespective of automatic error recovery result.

Note: This registry value has no impact on the real Supervisor

Entry/Exit messages during Supervisor mode change.
When simulated Supervisor messages are suppressed, the host will
not be aware that a device that has been reported as fatal previously,
might have recovered and is operational. You must ensure that
there is mechanism in place to always update the status on the host.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-120 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Configuring Cardholder
Functionality 5

This section describes configuration details for cardholder

functionality.
Where configuration is done using the class configurator file,
default configuration settings are included in the
AdvanceNDCCore.accfg file installed with Advance NDC. For
information on the AdvanceNDCCore.accfg file see “.NET Class
Configurator Files” on page 5‐40.

The format of cardholder input that is echoed on the screen is

Configuring Input Type, defined using table entry 9 of the Information Entry state table. The
Buffer and Display Format 5
format defined in this state table can be overridden using the
DisplayDataFormat.xml file which can be updated locally or through
XML Configuration Download message from the host. To use the
values defined in table entry 9, the DisplayDataFormat.xml must
match the state table or contain invalid XML.
The following extract is an example from the DisplayDataFormat
.xml file:

Figure 5-59
Example Display Data Format Extract
<?xml version="1.0" encoding="UTF-8"?>
<DisplayDataFormat xsi:schemaLocation="http://www.ncr.com/APTRA/NDC/DisplayDataFormat
DisplayDataFormat.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.ncr.com/APTRA/NDC/DisplayDataFormat">
<DisplayData>
<!-- Example: <StateNumber EntryType="Numeric" InputFormat="****-****-****-****"
DataBuffer="B" ReplaceChar="X">015</StateNumber> -->
</DisplayData>
</DisplayDataFormat>

For details of the XML envelope that must be used with this
configuration file, see “XML Configuration Files” on page 5‐37. For
details of the XML Configuration Download, refer to the APTRA
Advance NDC, Reference Manual.
If the DisplayDataFormat.xml file is invalid, the values defined in
table entry 9 of the Information Entry state are used. For details of
the Information Entry state, refer to Chapter 2, “State Tables” in the
APTRA Advance NDC, Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-121

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

The DisplayDataFormat.xml file is stored in the following location:

C:\Program Files\NCR APTRA\Advance NDC\Config

The schema, DisplayDataFormat.xsd, defines the structure of the
configuration data for the keyboard. The defaults stated in the
following table are the settings provided in the file installed with
Advance NDC.

Table 5-31
Display Data Format XML Schema

Element Description

DisplayData The whole file is embedded within DisplayData tags.

This is the root element

Nested elements:
 StateNumber

StateNumber Defines the state number to which the formatting applies.

The format is defined using the following attributes:

 InputFormat. Mandatory. Defines the format of the display of cardholder
input. The characters entered by the cardholder are represented by asterisks
(*). The maximum length of data is defined by the number of asterisks and
the number of asterisks cannot exceed 32. If this attribute is not defined or
the number of asterisks exceeds 32, the XML is considered to be invalid.
 EntryType. Optional. Defines whether the entered information is numeric
or alphanumeric. Valid values are as follows:
Numeric
Alphanumeric.
 DataBuffer. Optional. Defines the data buffer to use to store the
cardholder input. Valid values are as follows:
B
C.
 ReplaceChar. Optional. Defines the character to use when masking the
cardholder input. If this attribute is set to blank (“”), no masking is applied.

Various options are available for consumer data entry, as follows:

Cardholder Alphanumeric
 SMS‐style data entry
Data Entry 5

 PC keyboard
 Touch‐screen keyboard
SMS‐style data entry using the numeric keypad is supported
through entry 9 of the Information Entry (‘H’) state table or the
DisplayDataFormat.xml file described in “Configuring Input Type,
Buffer and Display Format” on page 5‐121.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-122 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Data entry using a PC keyboard is also supported through entry 9 of

the Information Entry state table or the DisplayDataFormat.xml file.
For a touch‐screen keyboard, the Information Entry screen must be
updated or defined as a new screen. For details, see “Touch‐screen
Keyboards for Alphanumeric Data Entry” on page 5‐152.

Configuring SMS‐style Data Entry or PC Keyboard 5

SMS‐style data entry and PC keyboard configuration are defined in

the NDCKeyboard.xml file, which can be updated locally or through
XML Configuration Download message from the host.
For details of the XML envelope that must be used with this
configuration file, see “XML Configuration Files” on page 5‐37. For
details of the XML Configuration Download, refer to the APTRA
Advance NDC, Reference Manual.
The NDCKeyboard.xml file is stored in the following location:

C:\Program Files\NCR APTRA\Advance NDC\Config

The keyboard schema, NDCKeyboard.xsd, defines the structure of the

configuration data for the keyboard.

Table 5-32
NDC Keyboard XML Schema

Element Description

NDCKeyboard The whole file is embedded within NDCKeyboard tags.

This is the root element

Nested elements:
 AlphanumericEntryStyle
 PCKeyboardConfiguration
 SMSKeyboardConfiguration
AlphanumericEntryStyle Defines the type of alphanumeric entry.

Valid values are as follows:

SMS ‐ Enter information using SMS‐style alphanumeric input (default)
PCKeyboard ‐ Enter information using a PC keyboard

PCKeyboardConfiguration Contains the PC keyboard configuration information.

Nested elements:
 MakeUppercase
 JournalEntry

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-123

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Element Description

MakeUppercase Defines whether to display all input in upper case.

Valid values are as follows:

true ‐ Display alpha characters in uppercase irrespective of the position of the
Caps Lock or Shift key (default)
false ‐ Display alpha characters in upper and lower case, as normal using a PC
keyboard

JournalEntry Defines whether to journal the message.

Valid values are as follows:

true ‐ Journal the message
false ‐ Do not journal the message (default)

SMSKeyboardConfiguration Contains the SMS‐style keyboard configuration information.

Nested elements:
 SMSKeyboardLayout
 EntryDelay
 Timer0Multiplier
 Cursor
 JournalEntry

SMSKeyboardLayout Contains the mapping of the keys.

Nested elements:
 Key0
 Key1
 Key2
 Key3
 Key4
 Key5
 Key6
 Key7
 Key8
 Key9

Key0 Defines the characters displayed when Key 0 is pressed.

By default, this is 0.

Key1 Defines the characters displayed when Key 1 is pressed.

By default, this is 1QZ.

Key2 Defines the characters displayed when Key 2 is pressed.

By default, this is 2ABC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-124 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Element Description

Key3 Defines the characters displayed when Key 3 is pressed.

By default, this is 3DEF.

Key4 Defines the characters displayed when Key 4 is pressed.

By default, this is 4GHI.

Key5 Defines the characters displayed when Key 5 is pressed.

By default, this is 5JKL.

Key6 Defines the characters displayed when Key 6 is pressed.

By default, this is 6MNO.

Key7 Defines the characters displayed when Key 7 is pressed.

By default, this is 7PRS.

Key8 Defines the characters displayed when Key 8 is pressed.

By default, this is 8TUV.

Key9 Defines the characters displayed when Key 9 is pressed.

By default, this is 9WXY.

EntryDelay Defines the delay in milliseconds between key presses before the cursor is
displayed at the next character location.

The default delay is 2000 milliseconds. The minimum delay that can be defined
is 500 milliseconds and the maximum is 5000 milliseconds.

Timer0Multiplier Defines the multiplier used to extend Timer 00 when using this timer as an
overall timeout for the character entry.

The default multiplier is 2.0.

For more information on Timer 00, refer to the APTRA Advance NDC,
Reference Manual.
Cursor Defines the symbol to use as the cursor. The cursor is displayed in the position
to be used when the next character is entered.

Any single character can be used. By default, the asterisk (*) character is used.

JournalEntry Defines whether to journal the message.

Valid values are as follows:

true ‐ Journal the message
false ‐ Do not journal the message (default)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-125

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

The entry in STCONT for the Cardholder Verification state allows

Cardholder Verification cardholder verification by Central for transactions such as web
State in STCONT 5
transactions to be processed on another host. This reduces the
burden of authorisation and identification on the other host.
This state can be managed through local customisation, described in
“Specifying Local Customisation Data” on page 5‐22, without the
host downloading any additional data. It can be used in conjunction
with the Web Exit state, described in “Cardholder Alphanumeric
Data Entry” on page 5‐122, to process web‐based transactions. A
typical local customisation might be to add a sequence of states
(Pre‐Set Operation Code ‐> Cardholder Verification ‐>Web Exit) to a
selection in the main cardholder menu.
Cardholder verification state type 1 is defined in STCONT as
follows:
1NState Cardholder Authorised
VerificationApplicationLink0ZZZ0099900ZZZ00ZZZ00ZZZ000000
0000000000

To change this state to state type O, change the number ‘1’ in

‘1NState’ to the letter ‘O’.
The name of the application DLL built for this state is
StateCardholderAuthorisedVerification.dll.
For further information on the Cardholder Verification state, see
Appendix G, “User‐Configurable States”.

The following two screens are configured for use with the Cash
Confirmation Screens Accept state:
During Cash Deposit 5

 Confirmation screen
 ECB 6 screen.
The properties described in the following sections are configured
using the CashInCustom.accfg file.
For details of the Cash Accept state, refer to Chapter 2, “State
Tables”, in the APTRA Advance NDC, Reference Manual. For details
of the timers used during the execution of this state, refer to Chapter
7, “Configuration Parameters”, in the APTRA Advance NDC,
Reference Manual.

Direct Deposit Confirmation Screen on Error 5

Advance NDC can be configured to display the confirmation screen

and optionally an error message when an error occurs during a
direct deposit transaction. For details, see “Displaying Direct
Deposit Error Messages” on page 5‐326.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-126 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Cash Accept Screen Formatter Classes 5

The ConfirmationScreenDialog class delegates the formatting of

the dynamic screen data to the ConfirmationScreenFormatter
and CounterfeitNotesRetainedScreenFormatter classes.
The following table describes the properties of the
ConfirmationScreenFormatter and
CounterfeitNotesRetainedScreenFormatter classes.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-127

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Table 5-33
Cash Accept Screens Formatting
Properties

Property Description

IncludeAllAcceptableDenominations Used by the ConfirmationScreenFormatter class

Defines whether denominations that are not stored in the
escrow are listed on the screen
Return type: bool
Default: false

TemplateForReportLine Used by the ConfirmationScreenFormatter class

Defines the string template used when the screen is formatted
for each denomination
Composite formatting rules are used
See Table Note 1 for information on composite formatting rules
Return type: string
Default: "{0,3} {1,3} X {2,3} = {3,5}"
The object list contains the following items:
 0 ‐ denomination
 1 ‐ currency ID
 2 ‐ number of notes
 3 ‐ total value of denomination
The default formats the display of denominations as follows:
10 PLN X 1 = 10
This display is derived from the default as follows:
 10 is the three‐character denomination defined by {0,3}
 PLN is the three‐character currency ID defined by {1,3}
 The three‐character note count defined by {2,3} is
" 1"
 The five‐character total value of the currency defined by
{3,5} is " 10"

TemplateForTotalLine Used by the ConfirmationScreenFormatter class

Defines the template to use for the value of the currency
Composite formatting rules are used
See Table Note 1 for information on composite formatting rules
Return type: string
Default: "TOTAL = {1,5} {0,3}"
The object list contains the following items:
 0 ‐ currency ID
 1 ‐ total value of currency
 2 ‐ total number of notes of this currency

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-128 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Property Description

TemplateForSummaryLine Used by the ConfirmationScreenFormatter class

Defines the string template used when the screen is formatted
for each currency
Composite formatting rules are used
See Table Note 1 for information on composite formatting rules
Return type: string
Default: "{0,3} = {1,5}"
The object list contains the following items:
 0 ‐ currency ID
 1 ‐ total value of this currency
 2 ‐ total number of notes of this currency

TemplateForTotalRetainedLine Used by both the ConfirmationScreenFormatter and the

CounterfeitNotesRetainedScreenFormatter classes
Defines the string template used to report retained notes when
the ECB 6 regulations are applied
Composite formatting rules are used
See Table Note 1 for information on composite formatting rules
Return type: string
Default: "NOTES RETAINED = {0,3}"
The object list contains the following items:
 0 ‐ total number of retained counterfeit and suspect notes
 1 ‐ number of retained counterfeit notes
 2 ‐ number of retained suspect notes

TemplateForRemainingAmountLine Used by the ConfirmationScreenFormatter class

Defines the string template used to report the difference
between the Amount buffer and the amount that has been
deposited so far in a direct deposit transaction
This is evaluated only when the Amount buffer is not zero and
the current operation is a single currency direct deposit
Composite formatting rules are used
See Table Note 1 for information on composite formatting rules
Return type: string
Default: empty string
The object list contains the following items:
 0 ‐ currency ID
 1 ‐ Amount buffer (decimal)
 2 ‐ amount deposited (decimal)
 3 ‐ remaining amount (decimal)

ReportHeader Used by both the ConfirmationScreenFormatter and the

CounterfeitNotesRetainedScreenFormatter classes
Defines the string used as the heading of the screen
Return type: string
Default: empty string

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-129

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Property Description

ReportFooter Used by both the ConfirmationScreenFormatter and the

CounterfeitNotesRetainedScreenFormatter classes
Defines the string used as the footer of the screen
Return type: string
Default: empty string

FormatterID Used by the ConfirmationScreenFormatter class

Defines a unique identifier for the formatter used to map the
screen offset for the chosen language

NumberOfAvailableLines Used by the ConfirmationScreenFormatter class

Defines the number of lines available on the screen for the
confirmation screen data.
This is used when the formatter switches between detailed and
summary mode. When the number of inserted denominations
plus one line exceeds this number, the display switches to
display items by currency. If UseSummaryOnly is set, this is
ignored

Caution: This property must be set only after careful analysis

of the screen data sent by the host and the number of accepted
denominations and currencies. If this is set incorrectly, screen
corruption can occur and the data on the confirmation screen
may be displaced or not visible.

Return type: integer

Default: 8

Culture Used by both the ConfirmationScreenFormatter and the

CounterfeitNotesRetainedScreenFormatter classes
Defines the formatter used for number formatting.
Return type: string
Default: empty string
The culture code is a combination of an ISO 639 two‐letter
lowercase culture code associated with a language and an ISO
3166 two‐letter uppercase sub‐culture code associated with a
country or region. For example ʺes‐ARʺ configures number
formatting for Argentina.

Translator Used by both the ConfirmationScreenFormatter and the

CounterfeitNotesRetainedScreenFormatter classes
The component used for the translation and formatting of
dynamic data after all other formatting is applied. The
translator object implements the IFormatProvider and
ICustomFormatter interfaces
Return type: IFormatProvider
Default:
NCR.APTRA.NDC.CashInFlows.NDCScreenDataTranslator

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-130 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Property Description

IncludeNotesRetainedCount Used by the ConfirmationScreenFormatter class

Defines whether to list the number of retained notes on the
screen.
Return type: bool
Default: true

UseOnlySummary Used by the ConfirmationScreenFormatter class

Defines whether switching to reporting per denomination is
permitted.
Return type: bool
Default: true

NoReturnableNotesMessage Used by the ConfirmationScreenFormatter class

Defines the message displayed when only counterfeit notes are
accepted and the accepted notes report is empty.
Return type: string
Default: " "

ShowOnlyWhenCounterfeit Used by the

CounterfeitNotesRetainedScreenFormatter class
Defines whether the ECB 6 screen is displayed only when
counterfeit notes are detected, or when counterfeit and/or
suspect notes are detected
Return type: bool
Default: false

Table Note 1: Composite formatting uses strings and object lists.

For full details on composite formatting, refer to
http://msdn.microsoft.com/en‐us/library/txafckwd.aspx. There can be
any number of fixed‐text strings with one or more format items.
Each format item corresponds to an object or boxed structure
defined in the object list. The composite formatting returns a new
result string where each format item is replaced by the string
representation of the corresponding object or structure in the object
list.

Table Note 2: The settings in the Regional and Language Options

folder of the Windows Control Panel can influence the formatting
results. It is the responsibility of the financial institution to ensure
that the regional settings for cultures used by formatters are
correctly installed and configured.

Screen Control Characters As XML does not permit ASCII 5

characters lower than 0x20, you must provide any screen control
characters as a character sequence. The character sequence is
converted to ASCII before being set to the screen displayer. The
character sequences that can be used and the ASCII equivalent are
given in Table 5‐55, “Screen Control Character Sequences”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-131

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Table 5-34 Character Sequence ASCII Equivalent Description

Screen Control Character Sequences
|HT| 0x09 Displays the name encoded on Track
1 of the card

|VT| 0x0b Displays the next character from the

secondary character set

|FF| 0x0c Clears the screen and positions the

cursor at the top left corner of the
screen

|SO| 0x0e Inserts the screen called by the next

3, 5 or 8 characters

|CR| 0x0d Moves the cursor to the following

line and positions it at the left‐hand
margin

|SI| 0x0f Positions the cursor on the row and

column specified by the next two
characters

|ESC| 0x1b Control character introducing

supplementary control codes for
extra features

For example, to set a white foreground on the summary screen and

position the string and value for the totals at row H, column A, set
the TemplateForSummaryLine property as follows:
"|SI|HA|ESC|[27m{2,13} = {1,5} {0,3}"

Data Translator The data translator is used to replace the 5

character sequences with the equivalent screen controls in ASCII

characters. The data translator can also be used to configure an
array of strings to place on the confirmation screen using the
UserDictionary property in the CashInCustom.accfg file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-132 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

The following example shows the format that must be used if

creating data translators:

Figure 5-60
Example Data Translators Extract
<Class ID="ConfirmationScreenDialog"Name="NCR.APTRA.NDC.CashInFlows.
ConfirmationScreenDialog"Assembly="NCR.APTRA.NDC.CashInFlows.dll" Transient="true">
<Interface>
<Property Name="DataFormatters" Value="ConfirmationScreenDataFormatters" />
</Interface>
</Class>

<Class ID="StringTranslator" Name="NCR.APTRA.NDC.CashInFlows.

NDCScreenDataTranslator"Assembly="NCR.APTRA.NDC.CashInFlows.dll" Transient="true">
<Interface>
<Property Name="UserTranslationDictionary" Value="CurrencyNamesMapping"/>
</Interface>
</Class>

<Class ID="DefaultConfirmationScreenDataFormatter" Name="NCR.APTRA.NDC.CashInFlows.

ConfirmationScreenDataFormatter" Assembly="NCR.APTRA.NDC.CashInFlows.dll" Transient="true">
<Interface>
<Property Name="FormatterID" Value="0"/>
<Property Name="TotalString" Value="SUMA"/>
<Property Name="Translator" Value="StringTranslator"/>
</Interface>
</Class>

<Array ID="ConfirmationScreenDataFormatters">
<Element Value="DefaultConfirmationScreenDataFormatter"/>
</Array>

<Array ID="CurrencyNamesMapping">
<!-- The equals sign is used as the separator -->
<Element Value="EUR=EURO" />
<Element Value="USD=$"/>
</Array>

Screen Formatter You can create a component that implements 5

the interface for the data formats used in the confirmation screen
and replaces the provided formatter. To use a different formatter,
implement the System.IFormatProvider and
System.ICustomFormatter interfaces.

The following extract shows how the configuration file is updated

to use the MyFormatter class, which has been created using
VB.NET. The MyFormatter class implements the confirmation
screen data formatter interface and is compiled to MyFormatter.dll.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-133

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Figure 5-61
Example Screen Formatter Extract
<Class ID="DefaultConfirmationScreenDataFormatter" Name="MyFormatter" Assembly=
"MyFormatter.dll">
<Interface>
<Property Name="FormatterID" Value="200"/>
</Interface>
</Class>

The following extract shows how the configuration file has to be

updated to use the MyScreenDataTranslator class, which has been
created in C#. The MyScreenDataTranslator class implements the
format provider and custom formatter interfaces and is compiled to
MyScreenDataTranslator.dll.

Figure 5-62
Example Screen Data Translator Extract
<Class ID="MyTranslator" Name="MyScreenDataTranslator" Assembly=
"MyScreenDataTranslator.dll">
</Class>

<Class ID="PolishFormatter" Name="NCR.APTRA.NDC.CashInFlows.

ConfirmationScreenDataFormatter" Assembly="NCR.APTRA.NDC.CashInFlows.dll">
<Interface>
<Property Name="FormatterID" Value="200"/>
<Property Name="Formatter" Value="MyTranslator" />
<Property Name="ReportHeader" Value ="|SI|CFmNAGLoWEK|SI|EA" />
<Property Name="TotalString" Value ="SUMA" />
</Interface>
</Class>

Using Multiple Languages If you are using multiple languages in 5

an interface, you must define formatters for each language. States Y

and A set the screen offset value depending on the language
selection and this offset value is used to select the appropriate
formatter. The ConfirmationScreenFormatters array is searched
for a FormatterId with a matching offset value and this formatter
is used to generate the screen.
To correctly display three languages, three instances of formatters
must be defined and the ConfirmationScreenFormatters array
must be updated as shown in the following extract:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-134 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Figure 5-63
Example Using Multiple Languages Extract
<Class ID="EnglishFormatter" Name="NCR.APTRA.NDC.CashInFlows.
ConfirmationScreenDataFormatter" Assembly="NCR.APTRA.NDC.CashInFlows.dll">
<Interface>
<Property Name="FormatterID" Value="0"/>
<Property Name="ReportHeader" Value="|SI|CF|ESC|[27mHEADER|SI|EA|ESC|[B0m" />
<Property Name="TemplateForReportLine" Value="|ESC|[B3m{0,3} {1,3} X {2,3} =
|ESC|[23m{3,8}" />
<Property Name="TotalString" Value="TOTAL" />
</Interface>
</Class>

<Class ID="PolishFormatter" Name="NCR.APTRA.NDC.CashInFlows.

ConfirmationScreenDataFormatter" Assembly="NCR.APTRA.NDC.CashInFlows.dll">
<Interface>
<Property Name="FormatterID" Value="200"/>
<Property Name="ReportHeader" Value ="|SI|CFmNAGLoWEK|SI|EA" />
<Property Name="TotalString" Value ="SUMA" />
</Interface>
</Class>

<Class ID="SpanishFormatter" Name="NCR.APTRA.NDC.CashInFlows.

ConfirmationScreenDataFormatter" Assembly="NCR.APTRA.NDC.CashInFlows.dll">
<Interface>
<Property Name="FormatterID" Value="400"/>
<Property Name="ReportHeader" Value ="|SI|CBENCABEZAMIENTO|SI|EA" />
<Property Name="TotalString" Value ="SUM" />
</Interface>
</Class>

<!-- CashIn Confirmation Screen formatters -->

<Array ID="ConfirmationScreenFormatters">
<Element Value="EnglishFormatter"/>
<Element Value="PolishFormatter"/>
<Element Value="SpanishFormatter"/>
</Array>

ECB 6 Dialog Class 5

The ECB6Dialog class defines how to display the number of

counterfeit notes retained for verification during the cash deposit.
The ECB 6 screen is only displayed if notes are to be retained in a
transaction.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-135

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

The Clear key can be disabled in PIN Entry state using the following
Disabling Clear Key in PIN registry:
Entry State 5

HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\Security\
DisableClearKeyinPin

Valid values are as follows:

0 ‐ Clear key will be enabled (default)

1 ‐ Clear key will be disabled

Any value greater than 1, Clear key is disabled. If the value is

missing the default is used.

You can configure the Amount Entry Length and Whole Amount
Configuring Amount Entry using an XML file.
Entry 5

Note: If Display Manager is used, the screen download is

mandatory. If the screen download is missing and the
AppendBuffer.xml file is used, the amount may not be displayed on
the HTML screen.

Configuring Amount Entry Length 5

This feature allows the cardholder to enter an amount length up to

12 digits. After the number of entered digits reaches the maximum
value, further input is prevented.
The Amount Entry Length is defined in the AppendBuffer.xml file.
For the details of the attributes, AmountEntryLength and
AllowUpToMaxLength, and their description, see “Amount Entry
XML Schema” on page 5‐138.

Configuring Whole Amount Entry 5

Whole Amount Entry can be configured for the following states:

 F (Amount Entry)
 R (Enhanced Amount Entry)
 X (FDK Information Entry)
 z017 (Note Mix Selection).
This automatically adds extra zeros after the decimal point to the
data to conform to the format expected by the host.
Whole amount entry configuration is defined in the
AppendBuffer.xml file. This file can be updated through software
distribution, local modification or the XML Configuration
Download message from the host. For details of the XML envelope
that must be used with this configuration file, see “XML
Configuration Files” on page 5‐37. For details of the XML

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-136 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Configuration Download refer to the APTRA Advance NDC,

Reference Manual.
The Append Buffer schema, AppendBuffer.xsd, defines the structure
of the configuration data for whole amount entry.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-137

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

The following extract is an example from the AppendBuffer.xml file:

Figure 5-64
Example Appendix Buffer XML Extract
<?xml version="1.0" encoding="UTF-8"?>
<AppendBuffer xsi:schemaLocation="http://www.ncr.com/APTRA/NDC/AppendBuffer
AppendBuffer.xsd"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.ncr.com/APTRA/NDC/AppendBuffer">
<AppendStates>
<!-- You can define Any No of States. Example: <StateNumber NoOfZeros="2"
AmountEntryLength="1" AllowUpToMaxLength="NO">999</StateNumber> -->
</AppendStates>
</AppendBuffer>

The AppendBuffer.xml and AppendBuffer.xsd files are stored in

C:\Program Files\NCR APTRA\Advance NDC\Config.

Table 5-35
Amount Entry XML Schema

Element Description

AppendBuffer This is the root element.

Nested element: AppendStates

AppendStates Defines the states that can have extra zeros appended after the decimal point.
Nested element: StateNumber

StateNumber The state number. Any number of states can be defined.

The state number must be an Amount Entry, Enhanced Amount Entry, or FDK
Information state or the StateNumber element is ignored.

This element includes attributes called NoOfZeros, AmountEntryLength

and AllowUpToMaxLength.

NoOfZeros NoOfZeros = “0”.

This attribute holds a positive integer value defining the number of zeros to be
appended after the decimal point. The maximum number of zeros that can be
defined is 4, and the minimum is 0.

The NoOfZeros attribute value should be set to zero if no additional zeros are
required when limiting the Amount Entry maximum length or disabling/
enabling the clearing on reaching the max length.

AmountEntryLength This attribute defines the Amount entry length. If this attribute is not present,
the Amount entry length set to 8 or 12 based on Enhanced configuration
parameter option 01.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-138 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Element Description

AllowUpToMaxLength AllowUpToMaxLength = “YES”. Limits the number of digits to the configured

amount entry length, which has a value of 8 or 12 in the attribute
AmountEntryLength.

AllowUpToMaxLength = “NO”. If the entered digits exceed the configured

amount entry length of 8 or 12 or the AmountEntryLength configured value,
then reset the amount entered to be 0 and restart the entry from the beginning.

If this attribute is not present or is invalid, “NO” is the default.

If the total length of the entered and appended amount buffer

exceeds the configured length in Enhanced Configuration
Parameter option 01, the Cancel Next State Number is taken.

The Buffer Validation state (z009) is used to validate data entered by

Validating Buffer Data 5

the cardholder and held in Buffer A, Buffer B or the Amount Buffer.

For details of the Buffer Validation state, refer to Chapter 2, “State
Tables” in the APTRA Advance NDC, Reference Manual.
The Buffer Validation state allows validation of the content of Buffer
B, Buffer C or the Amount Buffer against the rules provided in the
ValidationRuleSet.xml configuration file. This file can be updated
through software distribution, local modification or the XML
Configuration Download message. For details of the XML
Configuration Download message, refer to the APTRA Advance
NDC, Reference Manual.
The configuration file uses the ValidationRuleSet.xsd schema. The
XML elements must match those defined in the schema and are
case‐sensitive. The default Close state is executed if any of the
following are true:
 Invalid data is identified in either the schema or the
configuration file.
 The schema is not present.
 The configuration file is not present.
 The boundary values for elements or their attributes in the
configuration file exceed the limits defined in the schema.
The ValidationRuleSet.xml and ValidationRuleSet.xsd files are stored in
C:\Program Files\NCR APTRA\Advance NDC\Config.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-139

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Table 5-36
Buffer Validation XML Schema

Element Description

ValidationRulesSet Mandatory.

The whole file is embedded within ValidationRuleSet tags.

This is the root element

Nested element: RuleSet

RuleSet Mandatory.

Appears once or more times.

Identifies the rule to use in validating the buffer data. The required ID attribute
identifies the rule being configured and is used to match the validation
requested from the Buffer Validation state. The ID attribute value must be 3
characters in length. If duplicate ID attributes are found, the last entry is used
for validation.

Rule Mandatory.

Appears at least once.

Defines the rule to use in validating the buffer data. The required Pattern
attribute defines the rule being configured. The Pattern attribute value is
defined using regular expressions.

For more information on regular expressions, refer to the following:

http://msdn.microsoft.com/en‐us/library/2k3te2cs(VS.80).aspx

When the cardholder’s card is ejected or cash is presented, a beep is

Configuring Beep for sounded. This beep can be configured to use one of several sounds
Cardholder Transactions 5
using the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\Alerts\Cardholder

If this registry entry is missing or invalid, the default value is used

to sound the beep.
Valid values and the associated sound are described in Table 5‐37.
For descriptions of the beeps, refer to the APTRA online
documentation under Programmer’s Reference | XFS SIU Service
Provider | Configurable Parameters | BEEP DATA.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-140 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Table 5-37 Registry Value Description

Configurable Alert Sounds
2 Sounds the key press beep (default)

4 Sounds an exclamation beep

8 Sounds a warning beep

16 Sounds an error beep

32 Sounds a critical error beep

PC Beep 5

The PC beep is used as default.

If the PC beep is not working or is not configured, no beep is
sounded unless the SIU SP Audio is configured by setting the
following registry entry to 1:
HKLM\SOFTWARE\NCR\Advance NDC\Alerts\CardHolder Use SIU
AUDIO

Contactless Card Reader Beep 5

When a Contactless Card Reader is tapped, a beep is sounded using

the SIU for every card tap. For a good card tap, there is a short beep
and for a bad card tap, a long beep is sounded.
The device beep can be enabled using the ContactlessEnabler.xml file.
However, it is not recommended as the beep sound is not audible.
The device beep is disabled by default as following:
<Beep>0</Beep>

For information on ContactlessEnabler.xml file, see “Configuration

Data” on page 5‐229.
The application beep is configured using the following DWORD
registry entry. The valid values are described in the following table:

Table 5-38
Registry Entry to Configure Beep
Name Type Possible Values

HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\ContactlessReader

BeepForContactless DWORD 1 (default)- Application beep is enabled. A short beep for a good
tap and a long beep for a bad tap is sounded.

0 ‐ Application beep is disabled

For any other value or if the value is not present, the default value is
used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-141

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Instead of using a card, consumer transactions can be started using

Cardless Transactions 5

FDKs, FDK emulation, or PINpad key entry. If an active FDK or a

PINpad key is pressed with no card inserted, the transaction
proceeds as configured in the registry.
Entries under the following registry key are used to configure
cardless transactions:
HKLM\SOFTWARE\NCR\Advance NDC\Extensions\
Cardless Transaction

By default, cardless transactions are not enabled. Cardless

transactions can be enabled through Supervisor or by modifying the
registry. Enabling cardless transactions requires a valid next state
number. The next state number can be set through Supervisor, by
modifying the registry, or by the host using Enhanced
Configuration option 77.

Note: When cardless transactions are disabled using the

Supervisor menu option, the next state number is stored and is used
when cardless transactions are re‐enabled.

Supervisor Configuration of Cardless Transactions 5

Option 93 Cardless Transactions on the Configure menu in

Supervisor both enables or disables cardless transactions and allows
the next state number to be set at the local level. Access to this
function is password controlled to ensure only authorised personnel
can make these changes.
Enabling cardless transactions requires a valid next state number. If
it is not available, the operator must first set the next state number.
If this option is taken, a test teller transaction is required to check
that the state flow goes to the expected state.
Changes made through Supervisor updates the Next State
Number registry entry, described in Table 5‐13, “Cardless
Transaction Registry Entries” on page 5‐144.
For details of the Supervisor function, refer to the APTRA Advance
NDC Supervisor’s Guide.

Registry Configuration of Cardless Transactions 5

To configure cardless transactions, modify the following registry

entries:
 Active FDK Mask or/and Active PIN Pad Key Mask
 Next State Number.

Table 5‐39, “Cardless Transaction Registry Entries” describes the

registry entries used to define the processing of cardless
transactions. For details of the key mask settings, see “Key Mask

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-142 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Definition” on page 5‐147.

PAN Data The consumer who initiates the cardless transaction 5

cannot be identified using Track 2 or PAN data. The registry entries

allow static generic data to be used. Host applications have to
recognise that this data is not specific to a consumer and therefore
be able to restrict the transactions available, for example, offer
balance enquiries but not cash dispense transactions.
You can modify the PAN Data registry entry if CRM applications
(APTRA Promote or APTRA Relate) are used. APTRA Promote or
APTRA Relate applications can use the PAN data to provide a
generic flow for the consumer using the SST. As the data supplied is
not real consumer PAN data, it does not affect PA‐DSS compliance.
Alternatively, you can use dummy PAN data or a dummy PIN if
SkipFITSearch is set to 1.

Map Entire Touch Area to FDK D The Enable Great FDK registry 5

allows to map the entire touch area on the screen to FDK D in the
Card Read state.
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\NCR\Advance
NDC\Extensions\Cardless Transaction

Valid values are as follows:

0 ‐ (default) The entire touch area is not enabled and the touch areas
are configured based on the Active FDK Mask registry
configuration.
1 ‐ The entire touch area on the screen is mapped to FDK D. When
the user touches anywhere on the screen, FDK D will be triggered.

Note: Though the registry is set to 1, the Active FDK Mask registry
must be set to FDK D.

Other Registry Entries Other values can be modified to suit the 5

requirements of the financial institution.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-143

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Table 5-39
Cardless Transaction Registry Entries

Registry Entry Description

Active FDK Mask FDK mask value for cardless transactions in the range 0—255.

Default is 0, no FDK keys are defined.

If this is not present or is invalid, the default is used.

Active PIN Pad Key Mask Pin Pad key mask value for cardless transactions in the range 0—262143.

Default is 0, no PIN keys are defined.

If this is not present or is invalid, the default is used.

Next State Number The next state number following a cardless transaction initiation.

See Table Note 3 If this entry contains an empty string (default value), 0 or 255 (invalid
values), cardless transactions are disabled. If this entry contains any valid
value, cardless transactions are enabled.
NCR recommends that the next state number is configured using Enhanced
Configuration Parameters option 77 or Supervisor.

PAN Data The PAN data to be stored in the PAN field (CDI 2077) for cardless
transactions where a FIT search is not carried out (SkipFITSearch is set to
1).
Default is an empty string

SkipFitSearch Defines whether a FIT search is carried out or not. If set to 1, the FIT match
processing is not carried out.
See Table Note 3
Default is 0, FIT search is carried out.

Track 2 Data Track 2 data for cardless transactions.

See Table Note 3 If this is not present, no FIT search is carried out, no PIN prompt is displayed
and the cardless next state number is taken.

Enable Great FDK Enable the mapping of the entire touch area on the screen to FDK D in
the Card Read state.

See “Map Entire Touch Default is 0, which doesn’t enable the mapping of the entire touch area to
Area to FDK D” on FDK D.
page 5‐143”

Table Note 3: The cardless next state is taken if either of the

following is true:

 FIT search is to be skipped (SkipFITSearch = 1)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-144 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

 FIT search is to be performed (SkipFITSearch = 0) but

Track 2 Data is not set.

For further information see Figure 5‐65 “Cardless Transaction

Flow” on page 5‐146. The Good FIT Match and No FIT Match next
state exits are taken from the Card Read state.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-145

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Figure 5-65
Cardless Transaction Flow

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-146 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

Key Mask Definition 5

The Active FDK Mask and Active PIN Pad Key Mask registry
entries define the FDK and PIN pad keys to activate.
These masks are binary‐coded values. To activate an FDK, PIN pad
key or touch area, set the associated bit, as shown in the following
table. To activate more than one FDK or PIN pad key, enable
multiple bits.

Table 5-40 Set Bit Associated FDK Associated PIN Pad Key
Key Mask Settings
0 A 0

1 B 1

2 C 2

3 D 3

4 F 4

5 G 5

6 H 6

7 I 7

8 8

9 9

10 ENTER

11 CANCEL

12 CLEAR

13 BACKSPACE

14 HELP

15 DECPOINT

16 00

17 000

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-147

Configuring Advance NDC and Associated Components
Configuring Cardholder Functionality

For example, if you want to set the Enter key and PIN pad keys 8, 5,
and 2, enter 1316 in the Active PIN Pad Key Mask registry value.
This is calculated as shown in the following table:

Table 5-41 Key ENTER 9 8 7 6 5 4 3 2 1 0

Binary to Decimal Conversion Example
Binary 1 0 1 0 0 1 0 0 1 0 0

Decimal 1024 512 256 128 64 32 16 8 4 2 1

Active 1024 256 32 4

Total 1316

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-148 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Keyboards

Configuring Keyboards 5

This section describes the how the front keyboard and operator
keyboard can be configured. It also covers enabling a beep when an
emulated FDK is selected from a touch screen.

The front keyboard or the PIN SP must be configured so that, all

Front Keyboard 5

numeric keys (0‐9), 000, the Enter, Clear and Cancel keys are set up.
Default key configurations are provided; however, NCR
recommends the Clear key be configured to clear the full input
buffer, not just one character. To support this, the Clear key must
return the WFS_PIN_FK_CLEAR value to the application.

Note: By default, the 000 key is not enabled. To enable the 000 key,
refer to the APTRA on‐line documentation, under APTRA XFS |
Programmer’s Reference | XFS Service Providers | Feature
Management
Support for 000 key is implemented in the Amount Entry and
Enhanced Amount Entry states.
To do this for NCR SSTs, complete the following instructions using
the Aggregate Builder Tool:
1 To create a new archive on the development PC, select a new
empty directory

2 Import the APTRA XFS Platform Aggregate from the

distribution media.

3 Open the APTRA Self Service Support Aggregate, select the

version and click Contents.

4 Scroll to the Keyboards component and select the current

revision, for example 04.00.04. In the Configuration Sets
window at the bottom, it will show the Default (NCR) set.

5 Select the Default (NCR) set with right mouse and perform
Duplicate.

6 Rename the newly created set, for example, to Advance NDC.

7 Right click the new set and select open, then click Change. This
brings up the Change Wizard with the default keyboard
selected.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-149

Configuring Advance NDC and Associated Components
Configuring Keyboards

8 Select Copy to display a Custom Keyboard Information dialog.

Pick a Custom keyboard feature number from the dropdown
menu.

9 Enter a description in the Custom keyboard description dialog,

for example, “APTRA NDC Keyboard”.

10 Select Keyboard to configure the Custom keyboard for the Front

Keyboard.

11 Find the Backspace key and double click it to display the Set Key
Configuration dialog.

12 In the list of Virtual key names, find Delete (= Clear) and select
it. Click OK twice to close both dialogs.

13 Select Next to proceed to Step 2 of the wizard detailed below

under “Operator Keyboard”.
The function display keys (FDKs), if present, must be set up with
the following layout:

Table 5-42 WFS_PIN_FK_FDK01 WFS_PIN_FK_FDK05

Front Keyboard Layout
WFS_PIN_FK_FDK02 front WFS_PIN_FK_FDK06

WFS_PIN_FK_FDK03 display WFS_PIN_FK_FDK07

WFS_PIN_FK_FDK04 WFS_PIN_FK_FDK08

Audible Alert on Emulated FDK Selection 5

To enable Advance NDC to sound a beep whenever an FDK is

selected, set the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\CardholderKeyboard\
UseXFSBeepWithFDKs=1

By default, this is set to 0.

In voice‐guided sessions, a single beep is always sounded on FDK
selection regardless of the setting of this registry entry.

Mapping the Enter Key to an FDK 5

The behaviour of the Enter key for the Information Entry, Amount
Entry, and Enhanced Amount Entry states depends on the value
that is set in the following registry entry:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\
CardholderKeyboard\MapEnterKeyToFDK

Valid values are as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-150 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Keyboards

 0 — The Enter key is equivalent to FDK A (or FDK I if Message

Mode option digit 7a is set). This is the default value.
 1 — The Enter key is equivalent to the FDK that is active from the
top of FDK A to FDK D (or the top‐most active FDK of FDK I to
FDK H if Message Mode option digit 7a is set).
 2 — The Enter key is equivalent to the FDK that is active from the
bottom of FDK A to FDK D (or the bottom active FDK of FDK I
to FDK H if Message Mode option digit 7a is set).
If an invalid value is specified, the default value is used.

The operator panel keyboard or the TTU SP is configured by

Operator Keyboard 5

default, to support FDKs as individual keys. However, NCR

recommends the Clear key be configured to clear the full input
buffer, not just one character. For further information on
configuring the key and updating the registry for this, refer to the
APTRA on‐line documentation under APTRA XFS | Text Terminal
Device Class | User Guide | CEN XFS | Frequently Asked
Question.
To configure this for an NCR SST follow these instructions as “Step
2 of 2" of the Change Wizard as introduced in section “Front
Keyboard”:
1 Click Copy to bring up a Custom Keyboard Information dialog.
Pick a Custom keyboard feature number from the dropdown
menu.

2 Enter a description in the Custom keyboard description dialog,

for example, “APTRA NDC Rear Keyboard”.

3 Click Keyboard to configure the Custom keyboard for the Rear

Keyboard.

4 Find the Backspace key and double click it to bring up the Set
Key Configuration dialog.

5 In the list of Virtual key names find Delete (= Clear) and select it.
Click OK to close the dialog.

6 Click Finish to close the wizard. Click OK to close the

Configuration Property sheet.

7 Click Profiles under the APTRA Self‐Service Support aggregate

to create a new profile. Name the new profile for example,
SSSProfile.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-151

Configuring Advance NDC and Associated Components
Configuring Keyboards

8 Select the profile and scroll to the Keyboards component. Under

the Installation Instruction dropdown select the configuration
set AdvanceNDC that has been created.

9 Click Profiles under the APTRA XFS aggregate to create a new

profile. Name the new profile for example, XFSProfile.

10 Select the profile and scroll to the APTRA Self‐Service Support

aggregate. Under the Installation Instruction dropdown select
the profile SSSProfile that has been created.

11 Export the APTRA XFS Platform Aggregate by selecting the

aggregate version, right‐clicking and selecting Export from the
context menu.

12 Close the Aggregate Builder tool.

The customised aggregate with a custom keyboard configuration
can now be deployed to the SST network.

A touch‐screen keyboard can be supported for consumer data entry

Touch‐screen Keyboards in the Information Entry state (‘H’). When a touch‐screen keyboard
for Alphanumeric Data is used, the numeric keypad is also available.
Entry 5

Keyboard Definitions 5

Keyboard definitions are defined in offline screen definition files

<keyboardname>.ndcacsdf. The keyboard board definition file is
referenced from the Information Entry screen in a nested screen and
overlaid on the NDC screen display.
Each touch button on the keyboard can be defined to return the
appropriate ASCII code to be placed in the input buffer.
As the scaling and layout change when the resolution changes,
example keyboard definitions are provided for a few of the
commonly used resolutions, as follows:
 Simple.acsdf
 ExampleAlphaKeyboard.ndcacsdf
For both keyboard definitions, the characters and layout are for an
English language keyboard. The following figure illustrates the
keyboard provided in Simple.acsdf:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-152 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Keyboards

Figure 5-66
Touch-screen Keyboard

Defining the Screen 5

The following points apply:

 The Information Entry screen (‘H’) must be updated or defined
as a new screen.
 The Information Entry screen that is displayed must reference
the configured keyboard overlay.
 Any FDK touch areas defined for the screen must not interfere
with the keyboard touch areas.
Keyboard Definition The following points apply: 5

 The valid range for the touch key codes is 20h—EFh.

 Advance NDC reserves F0h—FFh for use as the FDK, CLEAR,
CANCEL and ENTER key codes.
 A Windows font is required that is capable of echoing any
special character to be displayed, for example, É or Å.
 The ASCII code must match the code specified in the keyboard
definition. This is usually the same code used by the active
country code page.
 Only languages that have code pages can be displayed.

Customising a Keyboard Definition 5

You can customise a touch‐screen keyboard by editing the required

keyboard definition file. This XML file has various fields that can be
updated for the required data entry
The example keyboard definitions and associated button images
supplied with Advance NDC are located in the following folders:
 Keyboard definitions
C:\Program Files\NCR APTRA\Advance NDC\Forms
 Button images
C:\Program Files\NCR APTRA\Advance NDC\Forms\Media.
NCR recommends you take a backup of the keyboard definition file
before modifying it.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-153

Configuring Advance NDC and Associated Components
Configuring Keyboards

Copy or rename the file you want to use to the required nested
screen number in the ‘u’ screen group. For example, a screen with
nested screen number 012 requires screen definition u0012.ndcacsdf
to be preset in the Forms directory.
Key Codes For each touch key, a TouchButton element contains 5

the Key attribute, which can be updated (in the range 20h—EFh) to
return the ASCII hexadecimal code for the required key press. The
Text attribute is the character to display on the keyboard button, as
shown in the following extract:
<TouchButton … X="97" Y="186" Key="51" Enabled…">
<Label Name="" …Text="Q" … />

This will allow all characters for a particular code page to be

displayed and entered.

Note: The coordinates must be within the visible screen area.

Touch Area Position The position of the touch area is specified by 5

the X and Y attributes for each TouchButton definition.

<TouchButton … X="97" Y="186" Key="51" Enabled…">
<Label Name="" …Text="Q" … />

To move the keyboard up or down, a search and replace can be

performed for each Y coordinate in each of the keyboard rows.

Touch‐screen Keyboard Display 5

The following are required for the touch‐screen keyboard to be

displayed:
 For language offsets, the appropriately named files must be
copied and available.
 The correct display must be active in the Information Entry state
screen before it is displayed.
 The cursor must be placed at the appropriate position to echo
the data.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-154 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

Configuring Screen Displays 5

This section describes how aspects of screen display can be

configured.

In DAPI 7 mode, the keyboard layout is dynamically remapped by

Secure Key Entry 5

the XFS PIN service provider, to enable the relevant data to be

entered through the encryptor keyboard.
The application queries the XFS PIN service provider regarding the
dynamic keyboard layout, and then uses the secure keyboard,
however, the application uses a static screen I30 in the resrvd.def file
to show the secure key entry mapping to the cardholder.

Note: Different layouts are supported for secure key entry. If the
configured layout is different from the default layout, update screen
I30 in resrvd.def to match the keyboard layout in use. For details of
how the keyboard is mapped for secure key entry, refer to the
APTRA on‐line documentation under APTRA XFS | Programmer’s
Reference | XFS Service Providers | XFS PIN Service Provider
|Conformance Matrix – Commands.

For details of configuring Display Manager for the display of HTML

Display Manager for screens, refer to the APTRA Advance NDC, User Guide for Display
HTML Screens 5
Manager, which describes how to install and configure Display
Manager on your development PC and SST.

Note: This component is separate from the display manager used

to handle NDC screens in .NET.

If the System Application is started on the rear operator panel, the

Hide Taskbar 5

Windows taskbar may be shown on the front screen. By default the

taskbar is always hidden with the following registry setting added
during installation:
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVer
sion\
Policies\Explorer
"NoDriveTypeAutoRun"=dword:00000091
"Clearrecentdocsonexit"=dword:00000001
"NoSMBalloonTip"=dword:00000000
"NoSimpleStartMenu"=dword:00000001

If required, the settings can be edited to display the taskbar.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-155

Configuring Advance NDC and Associated Components
Configuring Screen Displays

There is an operating system imposed system limit on the number

AVI System Limit 5

of distinct AVI windows open within a process. This means that you
cannot use more than 24 AVI files.
If you need to play more than 24 AVI files, use partial AVI files. A
partial AVI is not a full screen display, but is superimposed on a
JPEG background. The JPEG can provide a static picture over which
the partial AVI files can provide the moving part of the display. This
separation of the static and moving parts helps to reduce the
number of AVI files required.

Note: The 24‐file limit also applies to partial AVI files.

Advance NDC display components are configured using XML

Advance NDC Display configuration files. These files can be updated through software
Components 5
distribution, local modification or the XML Configuration
Download message. For details of the XML Configuration
Download refer to Chapter 9, “Terminal to Central Messages”, of
the APTRA Advance NDC, Reference Manual.
Details of the components and their associated schemas are given in
the following sections.
The .NET Class Configurator configures any properties that are set
at runtime using the AdvanceNDCCustom.accfg file. For details of the
properties set by the .NET Class Configurator see “Advance NDC
Display Runtime Settings” on page 5‐176. For details of the .NET
Class Configurator, refer to the APTRA online documentation
under .NET Class Configurator.

Note: The C:\Program Files\NCR APTRA\Advance NDC\Screens

folder is used internally by Advance NDC to hold screens for
display.

Offline Keyboard Layouts 5

As an alternative to downloading keyboard layouts from the host,

you can use one or more XML configuration files to define
keyboards and associated keyboards.
You can use either of the following approaches:
 Create a single XML file containing all keyboards and associated
keyboards
 Create multiple XML files each containing one or more
keyboards and associated keyboards.
The keyboard configuration file is stored in the location defined in
the ScreenRetrievers property as described in “Offline Screens”
on page 5‐176.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-156 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

The keyboard schema defines the structure of the configuration data

for the keyboards and associated keyboards as described in
Table 5‐43 on page 5‐157.

Table 5-43
Offline Keyboard XML Elements

Element Description

keyboardDefinition Mandatory.

This is the root element.

The whole file is enclosed within keyboardDefinition tags.

Nested elements:
 keyboard
 associations

keyboard Mandatory.

Appears at least once.

Identifies the keyboard definition. The required number attribute identifies the
keyboard being configured and is 3 alphanumeric characters long in the range 000
to ZZZ.

Nested elements:
 physical
 touch

physical Optional.

Appears only once in each keyboard element.

Defines the physical SST.

Nested elements:
 pinKeys
 functionKeys
 Mappings

pinKeys Optional.

Appears only once in each physical element.

Defines the PINPad keys to enable in the keyboard.

Nested elements:
 key

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-157

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

key Optional.

Appears up to 16 times in each pinKeys element.

Defines a PINPad key to enable on the keyboard. The key can only be enabled if a
matching key is configured at the Service Provider level.

The required value attribute identifies the key to enable. Valid values are as
follows:
 WFS_PIN_FK_0
 WFS_PIN_FK_1
 WFS_PIN_FK_2
 WFS_PIN_FK_3
 WFS_PIN_FK_4
 WFS_PIN_FK_5
 WFS_PIN_FK_6
 WFS_PIN_FK_7
 WFS_PIN_FK_8
 WFS_PIN_FK_9
 WFS_PIN_FK_ENTER
 WFS_PIN_FK_CANCEL
 WFS_PIN_FK_CLEAR
 WFS_PIN_FK_BACKSPACE
 WFS_PIN_FK_DECPOINT
 WFS_PIN_FK_00
 WFS_PIN_FK_000

functionKeys Optional.

Appears only once in each physical element.

Defines the FDKs to enable in the keyboard.

Nested elements:
 fdk

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-158 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

fdk Optional.

Appears up to eight times in each functionKeys element.

Defines an FDK to enable on the keyboard. The FDK can only be enabled if a
matching FDK is configured at the Service Provider level. If physical FDKs are not
present, a corresponding button is enabled on the touch screen.

The required value attribute identifies the key to enable. Valid values are as
follows:
 WFS_PIN_FK_FDK01
 WFS_PIN_FK_FDK02
 WFS_PIN_FK_FDK03
 WFS_PIN_FK_FDK04
 WFS_PIN_FK_FDK05
 WFS_PIN_FK_FDK06
 WFS_PIN_FK_FDK07
 WFS_PIN_FK_FDK08

Mappings Optional.

Appears only once in each physical element.

Defines any remapping o FDK values to alternative NDC values.

Nested elements:
 mapping

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-159

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

mapping Optional.

Appears up to eight times in each Mappings element.

Defines the mapping of an FDK position to an alternative NDC value code. For
details of the mapping layout, refer to Chapter 4, “Keyboard Data and Layouts”
in the APTRA Advance NDC, Reference Manual.

The required position attribute identifies the FDK to be mapped. Valid values
are as follows:
 17
 18
 19
 20
 21
 22
 23
 24

The required code attribute defines the new NDC value code that the FDK is to
be mapped to. Valid values are as follows:
 F3
 F4
 F5
 F6
 F7
 F8
 F9
 FA

Note: Advance NDC does not support the remapping of PINPad key
values.
touch Optional.

Appears only once in each keyboard element.

Defines the touch screen keyboard for an SST.

Nested elements:
 area

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-160 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

area Mandatory.

Appears up to 200 times in each touch element.

Defines an on‐screen touch button area.

The required returnCode attribute defines the key code of the touch button and is
2 alphanumeric characters long. The characters are each in the range 0 to F.

Nested elements:
 topLeft
 bottomRight

topLeft Mandatory.

Appears only once in each area element.

Defines the co‐ordinate of the top left corner of the touch button area.

The required x attribute defines the x‐axis co‐ordinate and is 8 numeric characters
long in the range 0‐9.

bottomRight Mandatory.

Appears only once in each area element.

Defines the co‐ordinate of the top left corner of the touch button area.

The required y attribute defines the y‐axis co‐ordinate and is 8 numeric characters
long in the range 0‐9.

associations Optional.

Appears only once in each keyboardDefinition element.

Defines the screen associated with a keyboard.

Nested elements:
 association

association Mandatory.

Appears at least once in each associations element.

The required keyboardNumber attribute identifies the keyboard to associate

with the screen and is 3 alphanumeric characters long.

Nested elements:
 Screen

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-161

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

Screen Mandatory.

Appears at least once in each associations element.

The required number attribute identifies the screen to associate with the
keyboard and is 5 alphanumeric characters long.

Advance NDC Display Configuration File 5

The Advance NDC display configuration file,

DisplayManagerConfig.xml, is located in C:\Program Files\NCR
APTRA\Advance NDC\Config. The file must conform to the
structure defined in the related schema. Invalid XML is written to
the PD log but processing continues. Advance NDC does not
always ensure that the content is valid and cannot provide detailed
information for use in troubleshooting for all entries. It is the
responsibility of the XML author to ensure that the content is valid.
The file defines the following configuration settings:
 Colour configuration. Sixty‐four colour control codes are
supported. The colour value assigned to each control code is
fully configurable using either an alpha, red, green, blue (ARGB)
or red, green, blue (RGB) format. For details of the control codes,
refer to Chapter 3, “Screen Data” in the APTRA Advance NDC,
Reference Manual. For details of the colour configuration XML
elements, see colourDefinitions on page 5‐163
 Font configuration. The fonts are specified using unique font
designators and associated parameters to control how the font is
displayed. For further details of fonts and their use in Advance
NDC, see Appendix D, “Font Definition”. For details of the font
configuration XML elements, see fontDefinitions on
page 5‐167
 Language configuration. Language offsets are mapped to
language strings. For details, see languageDefinitions on
page 5‐169
 Grid configuration. The grid settings allow a fine granularity of
control over the positioning of display elements. For details, see
gridConfig on page 5‐170
 Hook configuration. The hooks specify the expression index and
assembly for dynamic screen content. For details, see
hookConfig on page 5‐170. An example of defining a dynamic
screen is provided in “Example Definition of Dynamic Screen
Content” on page 5‐173

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-162 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

 Configuration of cheque image display. Two Boolean

parameters can be used to control the image scale and aspect
ratio of cheques of different sizes. The cheque images can be
displayed in either of the following ways:
— According to the height and width of the cheque image
— According to the height and width of the screen.

By default, this functionality is disabled for backwards

compatibility. For details, see chequeDisplayConfig on
page 5‐171 and “Resizing the Cheque Image for Display” on
page 5‐174.

 Miscellaneous configuration. Miscellaneous settings include

whether Display Manager operates in full screen mode, the
display of an out of service screen and whether nested screens
can perform keyboard updates. For details, see miscConfig on
page 5‐172.
The Advance NDC display schema defines the structure of the
configuration data for these settings as described in “Advance NDC
Display XML Elements” on page 5‐163.

Table 5-44
Advance NDC Display XML Elements

Element Description

displayManager Mandatory.

This is the root element.

The whole file is enclosed within displayManager tags.

Nested elements:
 colourDefinitions
 associations

colourDefinitions Mandatory.

Appears only once.

Defines the colours to use in screen foreground and background.

Nested elements:
 foreground
 background
 defaultForeground
 defaultBackground

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-163

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

foreground Mandatory.

Appears only once in each colourDefinitions element.

Defines the colour for the text present on the desired screen.

Nested elements:
 foregroundColour

foregroundColour Mandatory.

Appears 16 times in each foregroundColour element.

The required control attribute defines the control code to map to the colour.

Valid values are as follows:

 20 – low intensity black

 B0 – high intensity black
 21 – low intensity red
 B1 – high intensity red
 B2 – low intensity green
 22 – high intensity green
 B3 – low intensity yellow
 23 – high intensity yellow
 24 – low intensity blue
 B4 – high intensity blue
 25 – low intensity magenta
 B5 – high intensity magenta
 26 – low intensity cyan
 B6 – high intensity cyan
 B7 – low intensity white
 27 – high intensity white

The required colour attribute defines the colour value of the control code. This is
either 6 or 8 characters in length. If 6 characters are specified, it is interpreted as an
RGB value. If 8 characters are specified, it is interpreted as an ARGB value.

Note: The default value for the foreground colour is 23. The default value
is applied to your desired screen when you do not select any value.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-164 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

background Mandatory.

Appears only once in each colourDefinitions element.

Defines the colour for the background of the text used on the desired screen.

Nested elements:
 backgroundColour

backgroundColour Mandatory.

Appears 16 times in each backgroundColour element.

The required control attribute defines the control code to map to the colour.
Valid values are as follows:
 30 – low intensity black
 C0 – high intensity black
 31 – low intensity red
 C1 – high intensity red
 C2 – low intensity green
 32 – high intensity green
 C3 – low intensity yellow
 33 – high intensity yellow
 34 – low intensity blue
 C4 – high intensity blue
 35 – low intensity magenta
 C5 – high intensity magenta
 36 – low intensity cyan
 C6 – high intensity cyan
 C7 – low intensity white
 37 – high intensity white

The required colour attribute defines the colour value of the control code. This is
either 6 or 8 characters in length. If 6 characters are specified, the control code is
interpreted as an RGB value. If 8 characters are specified, it is interpreted as an
ARGB value.

Note: The default value for the background colour is 34. The default value
is applied to your desired screen when you do not select any value.
defaultForeground Mandatory.

Appears only once in each colourDefinitions element.

Defines the default colour for the text present on all screens.

Nested elements:
 defaultForegroundColour

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-165

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

defaultForegroundColour Mandatory.

Appears 16 times in each defaultForeground element.

The required control attribute defines the control code to map to the colour.

Valid values are as follows:

 60 – low intensity black

 F0 – high intensity black
 61 – low intensity red
 F1 – high intensity red
 F2 – low intensity green
 62 – high intensity green
 F3 – low intensity yellow
 63 – high intensity yellow
 64 – low intensity blue
 F4 – high intensity blue
 65 – low intensity magenta
 F5 – high intensity magenta
 66 – low intensity cyan
 F6 – high intensity cyan
 F7 – low intensity white
 67 – high intensity white

The required colour attribute defines the colour value of the control code. This is
either 6 or 8 characters in length. If 6 characters are specified, it is interpreted as an
RGB value. If 8 characters are specified, it is interpreted as an ARGB value.

Note: The default value for the default foreground colour is 63. The
default value is applied to all screens when you do not select any value.
defaultBackground Mandatory.

Appears only once in each colourDefinitions element.

Defines the default colour for the background of the text used on all screens.

Nested elements:
 defaultBackgroundColour

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-166 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

defaultBackgroundColour Mandatory.

Appears 16 times in each defaultBackground element.

The required control attribute defines the control code to map to the colour.

Valid values are as follows:

 70 – low intensity black

 G0 – high intensity black
 71 – low intensity red
 G1 – high intensity red
 G2 – low intensity green
 72 – high intensity green
 G3 – low intensity yellow
 73 – high intensity yellow
 74 – low intensity blue
 G4 – high intensity blue
 75 – low intensity magenta
 G5 – high intensity magenta
 76 – low intensity cyan
 G6 – high intensity cyan
 G7 – low intensity white
 77 – high intensity white

The required colour attribute defines the colour value of the control code. This is
either 6 or 8 characters in length. If 6 characters are specified, it is interpreted as an
RGB value. If 8 characters are specified, it is interpreted as an ARGB value.

Note: The default value for the default background colour is 74. The
default value is applied to all screens when you do not select any value.
fontDefinitions Mandatory.

Appears only once.

Defines the fonts to use in the screen.

Nested elements:
 font

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-167

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

font Mandatory.

Appears up to 95 times.

Defines the font used to display information on the screen.

The required id attribute identifies the font and is one character in the visible
ASCII range (0x21 ‐ 0x7E). The id must be unique. If duplicate ids exist, the first
definition encountered in the XML file is used.

The required face attribute identifies the name of the font and is the name of an
installed font.

The optional charset attribute identifies the character set to use. Valid values
are as follows:
 ANSI_CHARSET (default)
 DEFAULT_CHARSET
 SYMBOL_CHARSET
 SHIFTJIS_CHARSET
 HANGEUL_CHARSET
 HANGUL_CHARSET
 GB2312_CHARSET
 CHINESEBIG5_CHARSET
 OEM_CHARSET
 JOHAB_CHARSET
 HEBREW_CHARSET
 ARABIC_CHARSET
 GREEK_CHARSET
 TURKISH_CHARSET
 VIETNAMESE_CHARSET
 THAI_CHARSET
 EASTEUROPE_CHARSET
 RUSIAN_CHARSET
 MAC_CHARSET
 BALTIC_CHARSET

The optional height attribute specifies the height of the font in logical units and
is an integer. The default is 100.

The optional size attribute specifies the size of the font. Valid values are as
follows:
 Single (default)
 Double

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-168 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

font (cont.) The optional fixedSpacing attribute specifies whether to use fixed spacing.
Valid values are as follows:
 True – use fixed spacing (default)
 False – do not use fixed spacing.

The optional xOffset attribute specifies the initial horizontal position of the text
relative to the default initial horizontal position. A positive integer offsets the text
to the right, a negative integer offsets the text to the left. The default is 0 (no
offset).

The optional yOffset attribute specifies the initial vertical position of the text
relative to the default initial vertical position. A positive integer offsets the text
upward, a negative integer offsets the text downward. The default is 0 (no offset)

The optional weight attribute specifies whether to use a weighted font or not.
Valid values are as follows:
 FW_BOLD – use bold font
 FW_NORMAL – do not use bold font (default).

The optional italic attribute specifies whether to use an italic font or not. Valid
values are as follows:
 True – use italic font
 False – do not use italic font (default).

The optional underline attribute specifies whether to use an underlined font or

not. Valid values are as follows:
 True – use underlined font
 False – do not use underlined font (default).

The optional strikeout attribute specifies whether to use a strikeout font or not.
Value values are as follows:
 True – use a strikeout font
 False – do not use a strikeout font (default).

languageDefinitions Mandatory.

Appears only once.

Defines the language to use.

Nested elements:
 language

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-169

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

language Mandatory.

Appears at least once.

Defines the mapping between a language string and a language offset.

The required lang attribute specifies the language string to be mapped to the
offset and is 3 characters in length in the range A‐Z or a‐z.

The required offset attribute specifies the offset to be mapped to the language
string and is an integer.

gridConfig Mandatory.

Appears only once.

Defines the grid used for positioning of display elements on the screen.

Nested elements:
 xGrid
 yGrid

xGrid Mandatory.

Appears only once.

Defines the position of the display elements on the x‐axis of the grid.

The required coord attribute specifies the coordinate string to use when
positioning elements.

yGrid Mandatory.

Appears only once.

Defines the position of the display elements on the y‐axis of the grid.

The required coord attribute specifies the coordinate string to use when
positioning elements.

hookConfig Mandatory.

Appears only once.

Defines hook configuration information.

Nested elements:
 dynamicContentHooks

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-170 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

dynamicContentHooks Mandatory.

Appears only once.

Defines the hooks used in defining dynamic screen content.

Nested elements:
 contentHook

contentHook Mandatory.

Appears at least once.

Identifies the expression index and assembly used to match dynamic screen
content.

The type attribute identifies the implementation of the hook. Valid types are as
follows:
 native – a C function
 managed – a managed class

The id attribute provides the index to match with the expression given in the
screen control sequence

The assembly attribute identifies the DLL.

The name attribute identifies the function name if the type attribute is native or
the class name used to evaluate the expression if the type attribute is managed.

chequeDisplayConfig Mandatory.

Appears only once.

Enables re‐interpretation of the Lift Cheque Image Control escape sequence to

scale a cheque image using the following Boolean attributes:
 scaleToScreenSize
 maintainAspectRatio

The default value for each attribute is false for backwards compatibility.
The first attribute is set to true to scale the image to the width and height of the
available screen display area.
Both are set to true to maintain the aspect ratio in one dimension while scaling
the other proportionally. See “Resizing the Cheque Image for Display” on
page 5‐174.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-171

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

miscConfig Mandatory.

Appears only once.

Defines general configuration information.

Nested elements:
 windowMode
 defaultOutOfService
 nestedScreens

windowMode Mandatory.

Appears only once.

Defines whether the Advance NDC display window runs in window mode or full
screen mode.

The required mode attribute specifies the screen mode. Valid values are as
follows:
 Windowed
 FullScreen

The optional width attribute specifies the width of the window if the screen mode
is set to Windowed and is an integer. The default window width is 640 pixels.

The optional height attribute specifies the height of the window if the screen
mode is set to Windowed and is an integer. The default window width is 480
pixels.

The optional topMost attribute specifies whether the Advance NDC display
window is always on top. Valid values are as follows:
 true – The NDC Display Window is always on top
 false – The NDC Display Window is not always on top (Runtime installation
and Development PC installation default).

Note: If another window requires focus and the Advance NDC display is
set to always be on top, the Advance NDC display window is minimised.
When the next screen is to be displayed, the Advance NDC display
window is automatically maximised and, if configured, will become the
top window again.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-172 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

Element Description

defaultOutOfService Optional.

Appears only once.

Defines whether a default screen is displayed immediately after initialisation

completes.

The required useDefault attribute specifies whether a default screen is used.

Valid values are as follows:
 true – Use a default screen following initialisation. (default)
 false – Do not use a default screen following initialisation.

The required screenNumber attribute identifies the screen to display if the

useDefault attribute is set to true. The screen number is 3, 5, or 6 digits in
length and the default is C02.

nestedScreens Optional.

Appears only once.

Defines whether nested screens can be used to perform keyboard updates.

The required allowkeyboardUpdates attribute specifies whether keyboard

updates are allowed. Valid values are as follows:
 true – keyboard updates are allowed (default)
 false – keyboard updates are not allowed.

Example Definition of Dynamic Screen Content Dynamic screen 5

content can be defined using conditional expressions in either the

Dynamic Button or Dynamic Text control sequence.These control
sequences call the methods in the content hooks. If the expression is
true, the dynamic content is displayed.
The following examples show the following:
 The Dynamic Button control sequence used in the screen to
determine whether to display a button in Figure 5‐67.
 An example hookConfig entry from the
DisplayManagerConfig.xml file containing hook configuration
information in Figure 5‐68

Figure 5-67
Example Dynamic Button Control
Sequence
<ESC>P b F2;Quick
Cash;CashIcon.png;004;(E002|E003&E004)<ESC>\

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-173

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Figure 5-68
Example hookConfig Extract
<hookConfig>
<dynamicContentHooks>
<contentHook type="native" id="001" assembly"NativeDynamicContentHook.dll"
name= "DeviceDynamicMenuHook"
<contentHook type="managed" id="002" assembly"ManagedDynamicContentHook.dll"
name= "ManagedDynamicContentHook.DeviceConditionTwo"
<contentHook type="managed" id="003" assembly"ManagedDynamicContentHook.dll"
name= "ManagedDynamicContentHook.AvailabilityConditionThree"
<contentHook type="managed" id="004" assembly"ManagedDynamicContentHook.dll"
name= "ManagedDynamicContentHook.DynamicConditionFour"
</dynamicContentHooks>
</hookConfig>

In the above examples, the control sequence defines the position of

the FDK (F2), the button text (“Quick Cash”), the button image
(CashIcon.png) and the conditional expression.

Note: The button image can be specified, but the default

WinRenderer style is always used.

The conditional expression states that either E002 or E003 and E004
must be true for the button to be displayed on the screen. This
expression is passed to the hook function at index 004, evaluated
and, if true, the button is displayed on screen.
For details of these control sequences and building conditional
expressions, refer to Chapter 3, “Screen Data” in the APTRA
Advance NDC, Reference Manual.
For information on key code mapping see Chapter 4, “Keyboard
Data and Layouts” in the APTRA Advance NDC, Reference Manual.
Resizing the Cheque Image for Display Configuration in 5

DisplayManagerConfig.xml can be used to re‐interpret the Lift

Cheque Image Control escape sequence and handle how cheque
images of varying sizes are displayed on screen.
Two Boolean attributes are provided in DisplayManagerConfig.xml to
configure how a cheque is scaled for the screen display area, as
follows:
 scaleToScreenSize

This attribute determines the way the cheque image scaling

factor is interpreted, as follows:

false Cheque images are scaled according to the height and

width of the cheque image. For backwards compatibility,
this is the default value

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-174 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

true Cheque images are scaled according to the height and

width of the available screen display area

 maintainAspectRatio

This attribute determines whether the aspect ratio of the cheque

images is maintained during scaling and it applies only when
the scaleToScreenSize attribute is set to true.

false Cheque images are scaled according to the x and y

co‐ordinates. This is the default value

true Cheque images are scaled in one dimension and

proportionally in the other, so that the scaled image fits
into the area defined by the x and y co‐ordinates

The Lift Cheque Image Control escape sequence is as follows:

<ESC>PS(x,y)ImagePath/FileName<ESC>\

The (x,y) values are numbers in the range 1 to 100 inclusive and
represent the scaling factor to fit the image into the area defined by
the x and y coordinates in the Lift Cheque Image control
With the following control sequence as an example
<ESC>PS(90,40)C:\Graphics/image.bmp<ESC>\

the impact of setting these attributes is as follows:

 Scaling to screen size (true) without aspect ratio (false)
The image will occupy 90% of the horizontal display size and
40% of the vertical display size.
 Scaling to screen size (true) with aspect ratio (true)
The image will not be distorted but scaled in one of the
following ways to ensure it fits into the area defined by the x
and y co‐ordinates:
— The image will occupy 90% of the horizontal display size
and up to 40% of the vertical display size
— The image will occupy 40% of the vertical display size and
up to 90% of the horizontal display size
The following XML extract shows the configuration to maintain the
aspect ratio when the cheque image is scaled for display in the
available screen area.

Figure 5-69 L
Maintaining the Aspect Ratio of Displayed
Cheque Images
<chequeDisplayConfig scaleToScreenSize="true" maintainAspectRatio="true"/>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-175

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Note: This configuration also applies to the Bunch Cheque Display

Image Control.
For details of the cheque image controls, refer to chapter 3, “Screen
Data” of the APTRA Advance NDC Reference Manual.

The .NET Class Configurator is used to configure any screen

Advance NDC Display properties that are set at runtime using the
Runtime Settings 5
AdvanceNDCCustom.accfg file. Details of the configuration settings
are given in the following sections. For details of the class
configurator, refer to the APTRA online documentation under .NET
Class Configurator. For details of the AdvanceNDCCustom.accfg file,
see “.NET Class Configurator Files” on page 5‐40.
Advance NDC display components are configured using XML files.
For details of the XML files, see “Advance NDC Display
Components” on page 5‐156.
If you want to extend or customise these settings, contact NCR FSE
Product Management for implementation details and advice.

Offline Screens 5

Offline screen and keyboard files are loaded by screen retrievers.

The screen retriever uses the following properties to set the location
of the files:

Table 5-45
Offline Screen Properties

Property Type Description

FormsPath String Specifies the path to the offline screen directory

KeyboardsPath String Specifies the path to the offline keyboard directory

Reserved Screens 5

Reserved screen files contain screens defined in ASCII format for

display on the operator interface. If there are multiple reserved
screen files, the following rules apply:
 All reserved screen files must be of the same format as resrvd.def
 If there are multiple definitions of the same screen identifier, the
definition in the last file to be loaded is used as the previous
definition is overwritten.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-176 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

The paths to these screens are configured using the following

property:

Table 5-46
Reserved Screen Property

Property Type Description

ReservedScreenFiles String Specifies the paths to files containing reserved screens

Paths can be defined in the following ways:

 Absolute path
 File name. If the file name is used, the PATH environment variable
is used to determine the full path. The first file found on the path is
loaded

The files are loaded in the order listed in this property. Any
multi‐vendor screen files must be specified after the NCR screen files to
ensure that the vendor‐specific screens are not overwritten

Screen Manager Class 5

The screen manager class configures the screen retrievers and

reserved screen collections using the following properties:

Table 5-47
Screen Manager Properties

Property Type Description

RawScreenCollections String Specifies the reserved screen collection to use when loading raw
reserved screen definitions

ScreenRetrievers String Specifies the offline screen retrievers to use when loading offline
screen files and keyboard definitions

Display Manager Class 5

The display manager class configures the display of screens and the
conversion of any content to a suitable display format.

Note: Since Advance NDC only supports the .NET WinRenderer

component, any text will always overlay an image in a screen
display, as WinRenderer always renders text at the end.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-177

Configuring Advance NDC and Associated Components
Configuring Screen Displays

Hide Mouse Pointer 5

Whether the mouse pointer is hidden or shown is configured using

the following property of the renderer:

Table 5-48
Hide Mouse Pointer Property

Property Type Description

HideCursor Boolean Specifies whether the mouse pointer is hidden or not

The default is True: the mouse pointer is hidden

The following example shows the mouse cursor:

<Class ID="StdRenderer"
Name="NCR.APTRA.ChnApp.WinRenderer.StdRenderer"
Assembly="NCR.APTRA.ChnApp.WinRenderer.dll">
<Interface>
<Property Name="HideCursor" Value="False" />
</Interface>
</Class>

Customer Relationship Management 5

The targeted messaging service is configured using the following

NDCCRMService property:

Table 5-49
CRM Property

Property Type Description

TargetedMessaging NCR.APTRA.ITargetedMessagingService Specifies the targeted messaging

service to use when providing
customer relationship management
(CRM) content to the CRM service

Multi‐language consumer screens are identified for display by

Enabling Extended Screen applying a language offset to the screen number defined in the state
Groups 5
tables or host message. The language offset is defined in the
language selection state tables.
A group of screens is defined for each language (screen group). The
screen group is chosen using the Language Select from Card (‘V’)
state. For example, if each language has a group of 2500 screens and
four languages are available, the screen groups are as follows:
 Language 1 uses screen numbers 0000 to 2499
 Language 2 uses screen numbers 2500 to 4999

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-178 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Screen Displays

 Language 3 uses screen numbers 5000 to 7499

 Language 4 uses screen numbers 7500 to 9999.
The first screen in each group is defined by the screen base. The
screen base is defined using either the Eight FDK Selection Function
(‘Y’) or PIN and Language Select (‘m’) state. In the example above,
the screen base for each language would be as follows:
 Language 1 has a screen base of 0000
 Language 2 has a screen base of 2500
 Language 3 has a screen base of 5000
 Language 4 has a screen base of 7500.
The following formatting is applied:
 If the screen group in table entry 9 of the Language Select from
Card state is set to 001, it is multiplied by 1000
 If any screen base field in extension table 2 of the Eight FDK
Selection Function state is in the range 001 to 009, it is multiplied
by 1000
 If any screen base field in extension table 3 of the PIN and
Language Select state is in the range 001 to 009, it is multiplied
by 1000.
If extended screen groups are enabled, the following formatting is
also applied:
 If the screen group in table entry 9 of the Language Select from
Card state is in the range 010 to 050, it is multiplied by 100
 If any screen base field in extension table 2 of the Eight FDK
Selection Function state is in the range 010 to 099, it is multiplied
by 100
 If any screen base field in extension table 3 of the PIN and
Language Select state is in the range 010 to 099, it is multiplied
by 100.
By default, extended screen groups are disabled. To enable them, set
the following registry entry to 1:
HKLM\SOFTWARE\NCR\Advance NDC\Extensions\Screens\
ExtendedScreenGroupSize

Note: Before enabling extended screen groups, ensure that existing

language selection states do not include ranges of 010 to 050 or 010
to 099, as appropriate.

For details of the states and how they are affected by enabling
extended screen groups, refer to Chapter 2, “State Tables” in the
APTRA Advance NDC, Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-179

Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

Configuring the Electronic Journal 5

This section describes the configuration of various options for the

electronic journal (EJ).

Advance NDC can be configured to compress the EJ file on

EJ Compression 5

performing an initialisation option on the Configure menu in

Supervisor.
This sets the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\
EJCompression

Valid values are as follows:

 0 = disabled (default)
 1 = enabled.

EJ privacy compresses and applies password protection to the EJ

EJ Privacy 5

file. If the password is forgotten, the EJ files can no longer be

accessed. To allow access to future EJ files, you must de‐install
Advance NDC, delete the UCDIPers.dat file, and re‐install Advance
NDC.
The UCDIPers.dat file is located in the C:\Program Files\NCR
APTRA\Advance NDC\Data directory.

The size of the EJ file can be configured using the EJ Options option
Maximum EJ File Size 5

on the Configure menu in Supervisor to set the following registry

entry:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\EJFileSize

In Supervisor, the value is entered in kilobytes (KB). The default is

1411000 bytes, or 1378 KB, for backwards compatibility. The
minimum value is 1 KB. The maximum value is calculated as
follows:
available disk space / (maximum number of backups + 4)

A checksum is added to the EJ file by default. This cannot be

EJ Checksum 5

changed through Supervisor. However, if required, the checksum

can be disabled by adding the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\EJChecksum

Valid values are as follows:

 0 to disable the checksum

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-180 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

 1 to enable the checksum

The checksum is added when no registry value is present.

The initialisation of the EJ can be run in a number of ways without

Automatic Initialisation having to manually select the INIT EJRNL Supervisor function. The
Options 5
backup of the EJ log file is created in the following directory:

c:\program files\advance ndc\data\EJBackups

A copy of the automatic initialisation file can also be saved to a

specified destination. The name of this file can be configured as
described in “EJ Backup Filenames” on page 5‐185.
For details of all options set in Supervisor mode, refer to the APTRA
Advance NDC, Supervisor’s Guide.

Note: Multiple destinations must be enabled to use any of the

automatic initialisation features.

Cutover 5

Advance NDC can be configured to run automatic initialisation

whenever the EJ file reaches 90% of the specified maximum size
using the EJ Options option on Configure menu in Supervisor
mode.
The cutover option sets the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\EJCutover

Valid values for this entry are as follows:

 0 = disabled (default)
 1 = enabled.
If Cutover is not used, an unsolicited status message is sent when
the EJ file reaches 90% of the specified maximum size. This message
is suppressed when Cutover is used. Also, when Cutover is used,
the EJ file never reaches 100% of the specified maximum size, so the
fatal message will never be seen.
For details of the unsolicited message, refer to the APTRA Advance
NDC, Reference Manual.

Scheduled 5

Advance NDC can be configured to run the automatic initialisation

at a specified time and day or date using the EJ Options option on
the Configure menu in Supervisor mode.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-181

Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

The scheduled option sets the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\RecurrenceOptions\
EJRecurrence

Valid values for this entry are as follows:

 0 = disabled (default)
 1 = enabled.
The scheduled initialisation pattern option allows the setting of the
interval at which to run the Scheduled automatic initialisation.
The recurrence pattern sets the following registry entry:
HKLM\SOFTWARE\NCR\Advance
NDC\EJOptions\RecurrenceOptions\
EJRecurrencePattern

Valid values for this entry are as follows:

 1 = daily (default)
 2 = weekly
 3 = monthly.
The recurrence pattern selected determines the other options that
must be set, as follows:
 Daily—set time
 Weekly—set day of the week and time
 Monthly—set day of the month and time.
The time sets the following registry entry:

HKLM\SOFTWARE\NCR\Advance
NDC\EJOptions\RecurrenceOptions\
Time

Valid values for this entry are any four digit number between 0000
and 2359 inclusive. This represents the 24 hour clock, and is based
on the local time.
The day of the week sets the following registry entry:
HKLM\SOFTWARE\NCR\Advance
NDC\EJOptions\RecurrenceOptions\
DOW

Valid values are as follows:

 0 = Sunday (default)
 1 = Monday
 2 = Tuesday
 3 = Wednesday
 4 = Thursday

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-182 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

 5 = Friday
 6 = Saturday.
The day of the month sets the following registry entry:

HKLM\SOFTWARE\NCR\Advance
NDC\EJOptions\RecurrenceOptions\
DOM

Valid values for this entry are in the range 1 to 31 inclusive. The
default is 1 (the first day of the month). If the value is greater than
the days in the current month, the automatic initialisation will run
on the last day of the month.

Agent 5

Advance NDC can be configured to run the automatic initialisation

when called by third‐party software or a batch file. This is
configured using the Configure menu in Supervisor mode.
This sets the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\EJAgent

Valid values are as follows:

 0 = disabled (default)
 1 = enabled.
To run automatic initialisation successfully requires the following:
 The third‐party software or batch file must be installed in the
appropriate directory. For SST installations, this is C:\Program
Files\NCR APTRA\Advance NDC. For development
installations, the default is <drive>:\ntglobal.
 The agent automatic initialisation must be enabled
 Advance NDC must be running.
Once these prerequisites are met, the agent can run an automatic
initialisation using third‐party software or a batch file.
Third‐Party Software Third party software must call InitEJ.dll: 5

extern ‘C’ IMP_OR_EXP BOOL EJAgentInit()

which is declared in InitEH.h.

Batch File If using a batch file, you have to use InitEJ.exe to call 5

InitEJ.dll.
The batch file can be called by remote third‐party software or run
from the command line at the SST. Any error codes are returned to
the batch file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-183

Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

The following is an example of a batch file used to perform an

automatic initialisation:

Figure 5-70
Example Batch File
@echo off

::InitEJ.exe

InitEJ.exe
if errorlevel 1 goto errhand
echo EJ Initialised
goto end

:errhand
echo EJ failed to initialise
:end

Automatic Initialisation Copy Drive 5

Advance NDC can be configured to make a copy of the automatic

initialisation EJ file using the EJ Options option on the Configure
menu in Supervisor mode.
This sets the following in the registry:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\SecondaryBKP

This entry stores the drive letter of the selected destination. The
destination drive must be writable and it cannot be the diskette
drive.
The following registry key can be used to configure a folder path
within the drive specified for the secondary backup:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\FolderPath

This is not configurable through the EJ Options Supervisor option

and must be configured directly in the registry.
Example: If the EJ backup location is configured as
D:\EJFiles\Backups, the EJOptions registry entries need to be set as
follows:
SecondaryBkp = "D:\"
FolderPath = "\EJFiles\Backups\"

Note: If either the C drive or a CD drive is specified as the

secondary backup drive, the FolderPath registry entry is ignored
and the secondary backup destination is the root of the drive.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-184 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

Initialisation After Settlement 5

Advance NDC can be configured to initialise the EJ after a

settlement transaction using the Configure menu in Supervisor
mode.
This sets the following registry entry:
HKLM\SOFTWARE\NCR\Advance
NDC\EJOptions\EjinitAfterSettlement (DWORD)

Valid values are as follows:

 0 = disabled (default)
 1 = enabled.
If this function is enabled, EJ initialisation is performed after the
settlement transaction and then the SST is put into service. If this
function is disabled, the SST is directly put into service, after the
settlement transaction. Since initialisation of EJ is a part of automatic
initialisation, there will not be any user prompt to indicate its
success or failure.

Advance NDC can be configured to prevent a transaction entry

Delaying Initialisation being split over multiple EJ files by delaying EJ initialisation until
During Transactions 5
any in‐progress transaction completes. This delay does not affect the
next scheduled EJ initialisation.
This is configured using the following(DWORD)registry entry:
HKLM\SOFTWARE\NCR\AdvanceNDC\EJOptions\
EJScheduledInitOnlyOnIdle

Valid values for this entry are as follows:

 0 to perform a scheduled EJ initialisation operation at the time it
is due (default). This is used if the entry is missing or an invalid
value is specified.
 1 to perform a scheduled EJ initialisation operation at the time it
is due only if a transaction is not in progress, otherwise delay
initialisation until the transaction is complete.

You can configure Advance NDC to allow alternative EJ backup

EJ Backup Filenames 5

filenames by using the entries described below which are under the
following registry key:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions

EJFileDateFormat 5

This entry allows you to specify a date format to be included in the

filename of the EJ backup file. If this value is present, and the value
of this entry is one of the supported date formats, then an EJ backup

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-185

Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

file is created with the specified date format included in its name.
For example, if the value is ‘ddmmyy’, the EJ filename generated is
EJNNNNNNddmmyy.xxx where ‘NNNNNN’ is the machine number
and ‘xxx’ is the sequence number.
Valid values for this entry are:
ddmmyy
ddyymm
mmddyy
mmyydd
yyddmm
yymmdd
ddmmyyyy
ddyyyymm
mmddyyyy
mmyyyydd
yyyymmdd
yyyyddmm

Note: Each day, month and year part of the value must be entered
in the same case. For example, ddMMyy is a valid entry, but
ddMmyy is invalid.

If this entry is not present or blank, this feature is disabled and the
filename is EJNNNNNN.xxx or EJ.xxx, depending on whether the
EJShortFilename registry entry is configured. If the date format is
not one of the supported date formats, the ddmmyyyy is used.

EJShortFilename 5

This entry allows you to specify EJ backup files with a short

filename. This option is only available when a machine number is
not configured for the terminal.
Using this option, the EJ filename can be as short as EJ.xxx.
However, if the EJFileDateFormat registry entry is also
configured, the shortest filename possible is EJddmmyy.xxx.
Valid values for this registry entry are as follows:
 1 to indicate that the machine number is not configured,
allowing an EJ backup file to have a short filename such as
EJ.xxx, where ‘xxx’ is the sequence number.
 0 to indicate that this feature is disabled. This is the default
value.

Advance NDC can be configured to prompt for a drive each time

Multiple Destinations for the EJ is backed up or copied using the Configure menu in
EJ Backup 5
Supervisor mode.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-186 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

This sets the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\
MultipleDestination

Valid values for this entry are as follows:

 0 for single EJ backup destination. This is the default.
 1 for multiple EJ backup destinations.
By default, if the CDRW is selected as the destination drive, the CD
is ejected after the backup is taken. This can be controlled by the
following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\
EjectCD

Valid values for this entry are as follows:

 0 to keep the CD in the drive following a backup.
 1 to eject the CD following a backup. This is the default.

Advance NDC provides the ability to create multiple EJ backup

Enhanced EJ Backup 5

files. Multiple EJ backup allows up to 1000 EJ files to be stored

depending on disk space. Standard EJ backup is the default,
allowing only a single EJ backup file to be retained.
EJ backup can be changed either through option 36 of the Enhanced
Configuration Parameters Download, or through Supervisor.

Note: There is an option in Supervisor to prevent the host from

changing this setting. For more details, see “Disable Host Control of
Enhanced EJ Backup” on page 5‐188.

Each method updates the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\
EJMode

Valid values for this entry are as follows:

 0 for standard EJ backup. This is the default
 1 for multiple EJ backup.
If standard EJ backup is enabled, files are backed up to C:\Program
Files\Advance NDC\data.
If multiple EJ back up is enabled, files are backed up to C:\Program
Files\Advance NDC\data\ejbackups.

Maximum Number of Backups 5

With multiple EJ backup set, the maximum number of backups can

be set using the Configure menu in Supervisor mode.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-187

Configuring Advance NDC and Associated Components
Configuring the Electronic Journal

This updates the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\
NoOfBackups

Valid values for this entry are 2 to 1000, provided there is enough
space on disk. The default is 10.
If the requested number of backups exceeds the available disk
space, the following message is displayed:

INVALID; MAX POSSIBLE VALUE = <var>

Disable Host Control of Enhanced EJ Backup 5

The EJ backup mode can be changed either through option 36 of the

Enhanced Configuration Parameters Download, or through
Supervisor. Sometimes local control is required and the host control
can be disabled using the Configure menu in Supervisor mode.
This sets the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\EJOptions\
EJBackupECP

Valid values are as follows:

 0 to prevent the host from changing the EJ backup mode
 1 to allow the host to change the EJ backup mode (the default).

The information that is journaled for a transaction to the EJ can be

EJ Level 5

configured using the EJ Options option on the Configure menu in

Supervisor. The EJ level can be different from the level configured
for the journal printer. The following registry entry (DWORD)
specifies what is journaled for the EJ:
HKLM\SOFTWARE\NCR\Advance NDC\EJLevel

Valid values for this entry are 0, 1, 2 or 3. For a full description of the
values, refer to the APTRA Advance NDC, Supervisor’s Guide.

Journal Page Workers 5

To provide an additional level of control over the data to be

journaled (EJ or journal printer), the Journal Page workers in the
authored application can be modified to restrict what is printed in
conjunction with the journal levels configured through the
Supervisor (option 35 on the Configure menu).
The attribute Journal Level Trigger Value is provided to restrict the
data to be journaled. Data will be journaled according to the value
specified by this attribute. The default value places no restriction on
the data. For more information about modifying the attribute value,
see “Level 1 Modification Example” on page 8‐10.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-188 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

Configuring Printers 5

Reconfiguration of the default settings provided by Advance NDC

may be required for particular printers.
When Advance NDC is installed, printers are configured with
default registry settings. If you require a different configuration
setting for your printer, you must edit and run the ANDCSST.xml
file, as described in “Automatic Configuration at Start‐up” on
page 5‐2.
 To configure forms‐based printing for an Open Document
Printer on a Personas SST, the settings must be as described in
“Forms‐Based Printing” on page 5‐196
 To configure USB printers, the setting must be as described in
“USB Statement Printer” on page 5‐196

Note: NCR recommends using form‐based printing on USB

printers; however, raw data printing is supported. For more
information on configuring a USB printer for raw data printing,
see “USB Receipt and USB Journal Printers” on page 5‐199. For
details of creating graphics for USB printers, see “Creating
Graphics Files” on page 5‐200. To extend the available fonts,
create a Windows font as described under “Creating Fonts” on
page D‐2

 To print Promote coupons on a dot matrix printer, see “Promote

Coupons” on page 5‐192.
Specific registry entries for journal, receipt and statement printers
can be found under the following keys:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\<printer>

The variable <printer> is one of the following:

 Journal or Journal Forms
 Receipt or Receipt Forms
 Statement or Statement Forms.

The following registry entry allows you to report to host whenever

Journal Printer Status 5

journal printer is not configured:

HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Journal\
JournalMissingUnsol

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-189

Configuring Advance NDC and Associated Components
Configuring Printers

Valid values are as follows:

Table 5-50 Name Data Value Description

Journal Printer Registry Value
JournalMissingUnsol 0 Do not generate unsolicited
message to report device not
configured (default value).

1 Generate unsolicited message to

report device not configured.

Journal Printer Level 5

The information that is journaled for a transaction on the journal

printer can be configured using the Configure menu in Supervisor.
The following registry entry specifies what is journaled:
HKLM\SOFTWARE\NCR\Advance NDC\
JournalLevel (DWORD)
Valid values for this entry are 0, 1, 2 or 3. For a full description of the
values, refer to the APTRA Advance NDC, Supervisor’s Guide.
Cash Count Reporting By default, cash counts are journaled after 5

notes have been presented when the journal level is set to 3.

Journaling of cash counts can be disabled or modified by editing the
relevant screen in resevd.def. To disable the journaling of a cash
count, remove the text from the appropriate screen. If a screen is
blank, no journaling occurs and no blank line is printed.
The screens are described in Table 5‐51, “Cash Count Journal
Screens”. For details of the screens in resrvd.def, refer to Appendix A,
“Reserved Screens”, in the APTRA Advance NDC, Reference Manual.

Table 5-51 Screen Number Description

Cash Count Journal Screens
j0027 Heading line for NDC cassette types 1 to 4

j0028 Heading line for NDC cassette types 5 to 7

j0029 Heading line for the currency value of the notes in

the cassette type identified in screen j0027 or j0028
The currency symbol is not included
The cassette type must be configured
For details of configuring the cassette types, see
“Configuring Cash Handlers” on page 5‐267

j0030 Cash counts for dispensed notes

j0031 Cash counts for rejected notes

j0032 Cash counts for remaining notes

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-190 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

Journal Page Workers To provide an additional level of control 5

over the data to be journaled (journal printer or EJ), the Journal Page
workers in the authored application can be modified to restrict what
is printed in conjunction with the journal levels configured through
the Supervisor (option 35 on the Configure menu).
The attribute Journal Level Trigger Value is provided to restrict the
data to be journaled. Data will be journaled according to the value
specified by this attribute. The default value places no restriction on
the data. For more information about modifying the attribute value,
see “Level 1 Modification Example” on page 8‐10.

The default configuration for the receipt printer service provider is

Receipt Printer 5

the following:
 Thermal printer
 Variable length receipt
 ‘Black Mark’ disabled, to prevent the printer automatically
ejecting receipts that exceed the printer’s standard receipt
length.

Receipt Handling 5

Any receipts that are not removed will be retracted, if the hardware
has the capability, as follows:
 At Start of Day
 In the Close state
 On execution of INIT RECEIPT (Initialise Receipt function in
Supervisor).
Receipt Retract By default, receipts are retracted. To disable 5

retract for receipts, change the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\RECEIPT\
DisableCaptureIfPageNotTaken

Valid values are as follows:

0 = Enable receipt retract (default value)
1 = Disable receipt retract.
For any other value or if the value is not present, the default value is
used.
Long Receipt Retract When retract receipt is enabled 5

(DisableCaptureIfPageNotTaken is 0), and Supervisor Message

Mode option 6B (max 49 lines printed before cut) is set, a further
registry entry controls whether long receipts are retracted, as
follows:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\RECEIPT\
RetractLongReceipt

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-191

Configuring Advance NDC and Associated Components
Configuring Printers

Valid values are as follows:

0 = Disable retract for long receipts (default value)
1 = Enable retract for long receipts.
For any other value or if the value is not present, the default value is
used.
If the last receipt of multiple receipts is a long receipt, it is retracted
if RetractLongReceipt is enabled and the retract bin is not full.

Note: Long receipts will not be retracted unless the two registry
entries described above are set to enable receipts and long receipts
to be retracted.

Reporting Capture Bin Full When the capture bin is full, receipts 5

continue to be printed but are no longer retracted if not taken by the

consumer. After the capture bin has been emptied, receipts will be
retracted if not taken. The capture bin can be reported as full in
messages to the host and on the fault display.
On NCR SSTs, an unsolicited message can be sent when the capture
bin is full to report a fatal condition for the receipt printer. The
following registry entry controls whether a fatal condition is
reported for the receipt printer when the capture bin is full:
HKLM\SOFTWARE\NCR\APTRA Self-Service Support (NCR
Features)\Usb80mmThermalPrinters\
Operations Parameters\RPNT-01-UsbThermal\CONFIG

Valid values are as follows:

0 = Do not report receipt printer as fatal when capture bin is full
(default).
1 = Report receipt printer as fatal when capture bin is full.
For any other value or if the value is not present, the default value is
used.

Promote Coupons 5

The format to use when printing Promote coupons has to be

configured for the specific receipt printer in use.
To permit Promote coupon printing, a string value must exist under
the following:

HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\RECEIPT\
PROMOTE_COUPON_FORMAT

Valid data values are as follows, running ANDCSST.xml sets these

as defaults:
 RCPT:PFM-LOWRES for NCR 40 column thermal printers.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-192 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

 RCPT:PFM-HIGHRES for NCR 60mm thermal printers

 RCPT:BMP-HIGHRES for NCR USB printers
 RCPT:BMP-LOWRES for non‐NCR printers

Printing Promote Coupons Promote coupons can be printed on 5

the back of the transaction receipt if the following are true:

 The receipt printer is a two‐sided USB thermal printer
 Promote returns the delivery type as Back.
Where the receipt is printed when the delivery type Back is
specified depends on the capabilities of the printer and the type of
paper loaded, as described in Table 5‐52.

Table 5-52
Promote Coupon Printing

2ST printer? 2ST paper? Delivery Type Used: Receipt Requested/Required? Host Data on Back? Coupon Printed on:

Yes No Attached Yes ‐ Front

Attached to
receipt

No ‐ Attached Yes ‐ Front

Attached to
receipt

Yes Yes Back No ‐ Back

Yes No Standalone Yes ‐ Front

Separate from
receipt

No ‐ Standalone No ‐ Front
Separate from
receipt

Yes Yes Back Yes ‐ Back

On transaction
receipt

Yes Yes Attached Yes Yes Front

Attached to
receipt

Printing Promote Coupons During Transaction Reply

Functions You can choose to print Promote coupons only when a 5

receipt is successfully printed. The coupon can be printed during

the following Transaction Reply functions:
 Dispense and Print
 Next State and Print
 Fast Cash

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-193

Configuring Advance NDC and Associated Components
Configuring Printers

 Card Before Cash

 Card Before Dispense and Print
 Print Statement and Next State
 Envelope Deposit and Print
 BNA Encash and Set Next State
 BNA Encash and Wait
 BNA Refund and Set Next State
This feature is enabled through the following DWORD registry
entry:
HKLM\SOFTWARE\NCR\Advance NDC\Promote\
Print Coupon Only After Successful Receipt Print

Valid values are as follows:

 0 = Print a Promote coupon even when no receipt is printed
(default)
 1 = Print a Promote coupon only when a receipt is printed.
If an invalid value is specified or the registry entry does not exist,
the default value is used. 5

Dot‐Matrix Receipt Printers When using a dot‐matrix receipt 5

printer that supports multi‐vendor coupon printing, the following

must be set to “ ” (empty string):

HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\RECEIPT\
PROMOTE_COUPON_FORMAT

This stops any attempt to print a coupon.

If you use APTRA Promote SST RTL 02.07.01, which does not
support multi‐vendor coupon printing, this must be set to RECEIPT.

Top Margin of Receipts 5

The receipt top margin can be configured through reserved screen

K01 for raw data printing or, for forms‐based printers, the following
registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Receipt Forms\
Print Data\Form Alignment

In addition, the receipt top margin can be configured through

Supervisor (option 92, RECEIPT TOP MARGIN on the Configure
menu) and the values are stored in the following registry entries:
 Raw data printing (personas printers)
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\RECEIPT\
ReceiptTopMargin

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-194 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

 Forms‐based printing (USB printers on SelfServ SSTs)

HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Receipt Forms\
ReceiptTopMargin

By default, the registry value for each is NULL (undefined). Valid

values are 0 to 24 and NULL. If a valid value is entered in Supervisor,
the registry entries are updated with the new value.
The receipt top margin can also be configured remotely through the
ReceiptTopMargin entry in UniversalPrinters.reg and
PersonasPrinters.reg.
Priority of Values The order of priority in processing the values is 5

as follows:
1 The value entered through Supervisor

2 The value defined in the K01 screen

3 The value set in the Form Alignment registry entry

The first two options apply to both raw‐data printing and
forms‐based printing. The third option applies only to forms‐based
printing.
If an invalid value is entered in Supervisor, the previous valid value
entered in Supervisor takes priority over the value in screen K01.
If the ReceiptTopMargin registry entry is updated manually and an
invalid value is entered, the value in screen K01 screen takes
priority.
For raw‐data printing, if the ReceiptTopMargin registry value is
NULL (the default value), the value in screen K01 is used.

For forms‐based printing, if the ReceiptTopMargin registry entry is

NULL (the default value), the value provided in screen K01 is used.
If the top margin value in screen K01 is also defined as 0, the value
in the Form Alignment registry entry is used.
For details of screen K01, refer to Chapter 3, “Screen Data”, of the
APTRA Advance NDC Reference Manual.
For more information about option 92 RECEIPT TOP MARGIN,
refer to Chapter 4, “Configure Menu” of the APTRA Advance NDC
Supervisor’s Guide.

You can set a maximum statement length, which sets the maximum
Statement Printer 5

number of lines to be printed before a cut. This ensures that the

statement will be cut when the black mark is not used. The
maximum number of lines is set using the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Statement\Length

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-195

Configuring Advance NDC and Associated Components
Configuring Printers

The default value is 20. The valid range is 12 to 92.

If you are using forms‐based printing with the statement printer
and require a font, for example for a specific language, you must
create the font. For details of creating fonts, see “Creating Fonts” on
page D‐2. You cannot use a mapping file to translate an unknown
character as this only applies to raw data printing. For more
information on mapping files, refer to Appendix B, “Character Sets”
in the APTRA Advance NDC, Reference Manual.

For a USB statement printer, edit ANDCSST.xml and change the

USB Statement Printer 5

value of the Document Printer alias from

“Document Printer”=”OpenDocumentPrinter1”
to
“Document Printer”=”USBStatementPrinter1”

Forms can be dynamically generated for each print operation for

Forms‐Based Printing 5

statement, receipt or journal printers. The form generation process

can be customised using the registry entries described in Table 5‐53.
The <printer type> variable in the registry keys represents the
printer type as follows:
— STATEMENT
— RECEIPT
— JOURNAL

Registry Entries for Configuring Forms 5

The settings to configure the forms generation process are provided

under the following registry key:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\
<printer type> Forms

Table 5-53
Registry Entries for Configuring Forms

Registry Entry Values Description

Dynamic Forms Can be either of the following: Specifies whether forms can be
See Table Note 4  0 to prevent form‐based printing used.
 Any non‐zero number to allow
form‐based printing (default is 1)

FUNCTIONNAME In the following format: Specifies the function name to use

 Convert <printer type> Forms. for field conversion during form
generation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-196 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

Registry Entry Values Description

SCALING Valid values are as follows: Specifies the scaling to apply to

 0 to scale the graphic to fit the graphics when printing using the
boundaries of the graphic field, the Print Graphic control sequence.
aspect ratio may be lost (default)
 1 to scale the graphic to fit within the For details of the Print Graphic
boundaries of the graphic field, control sequence, refer to Chapter
maintaining the aspect ratio 5, “Printer Data” in the APTRA
Advance NDC, Reference Manual.
 2 to print the graphic at normal size. This
prints only the part of the graphic that
fits within the boundaries of the graphic
field. The part of the graphic that is
printed depends on the horizontal and
vertical positioning of the field

Media Definition Default values for USB printers are as Specifies the media definition
follows: name to use when printing forms.
 Journal printer: Journal1
 Receipt printer: Receipt1 If the SST Configuration
Component identifies the UPTR
 Statement printer: Statement80
service provider, it sets this to an
Default value for the Open Document printer empty string (“”). Otherwise, a
is Statement80. media definition file must be
present and contain the definition
matching the name used in this
registry entry.

Print Data\Form Units The only valid value is the default, as Specifies the units of measurement
follows: used in forms generation.
 ROWCOLUMN, 1, 1.

Print Data\Form Valid values are vendor dependent, but will Specifies the starting coordinates
Alignment be one of the following: for the form using ROWCOLUMN
 TOPLEFT, 1, 1. This is the default. format.
 TOPLEFT, 0, 0

Print Data\Forms The value is found in the key values for your Specifies the file extension for the
Extension printer. By default, it is as follows: generated form.
 .DEF.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-197

Configuring Advance NDC and Associated Components
Configuring Printers

Registry Entry Values Description

Print Data\Forms Name The value is found in the key values for your Used to generate a unique form
printer. name, and provide the filename of
the generated form.

Print Data\Forms Path The default paths are as follows: Specifies the directory in which to
generate the form.
 C:\Program Files\NCR
APTRA\Advance NDC\ Some service providers need the
Printing\<printer type>\Forms form to be stored in a specific
 C:\Program Files\NCR directory, or the form will not load
APTRA\Advance NDC\ at run time. Refer to the
Printing\<printer type>\Media appropriate vendor publications
for the value required for this
entry.

Table Note 4: If configuring an Open Document Printer on a

Personas SST, you must update this entry as follows:

— Update the Dynamic Forms entry in the ANDCSST.xml file

from 0 to 1
— Update the Aliases entry in the ANDCSST.xml file from
“Document Printer”=”StatementPrinter1” to “Document
Printer”=”OpenDocumentPrinter1”.

Registry Entries for Configuring Fonts 5

The <var> part of the registry entries for configuring fonts

represents a font identifier. Any ASCII character can be used as the
font identifier, but only those present in the print stream are
actioned.
The settings to configure the font identifiers are provided under the
following registry key.
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\<printer type>
FORMS\Print Data\Font Identifiers\<var>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-198 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

Table 5-54
Registry Entries for Configuring Fonts
Registry Entry Values Description

Font Name This is vendor‐dependent. Refer to the The name of the font, used in the font field
appropriate vendor publications for the of the form.
values accepted for this entry.

By default this entry is blank, which means

that the default font will be used.

CPI The value is vendor‐dependent. Refer to the The characters per inch setting, used in the
appropriate vendor publications for the CPI field of the form for the following font
values accepted for this entry. identifiers:
 F
For NCR printers, the default is 12 CPI.  G
 H
 O
 P

Font Size Valid values are as follows: Specifies the font size in characters.
 1 for single size
 2 for double size
 3 for condensed size

Registry Entry for Configuring LPI 5

Entries to configure the number of lines per inch (LPI) are provided
under the following registry key:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\<printer type>
FORMS\Print Data\LPI Index

Table 5-55
Registry Entry for configuring LPI
Registry Entry Values Description

<var> The LPI indexes, 0 to 7 inclusive The lines per inch setting, used in the LPI
field of the form. A missing index indicates
that it is to be ignored and no LPI setting is
added to the XFSFIELD definition.

Although the supported LPI setting is the same across all printer
USB Receipt and USB types, other features may require specific configuration on
Journal Printers 5
particular printers.
For details of the differences in registry entries for the USB Receipt
and Journal printers, refer to the APTRA Advance NDC, Reference
Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-199

Configuring Advance NDC and Associated Components
Configuring Printers

For details of the printer SP, refer to the APTRA online

documentation.
For raw data on a USB printer, the following registry entries are
used:

Table 5-56 Registry Entry Description

Raw data: USB Receipt and
Journal Registry Entries CHAR_MAP_FILENAME Stores the character map filename,
which translates the code page
used by the USB Receipt and
Journal printer into the
corresponding Arabic and
International characters.

CHAR_MAP_DESIGNATOR Stores the designator used to

identify the user‐specified font in
the mapping file.

For details of the mapping file and associated registry entries, refer
to the APTRA Advance NDC, Reference Manual.

Registry Entry for Receipt Retract 5

Disabling or enabling receipt retract is the same as for non‐USB

printers. For details of the registry settings, see “Receipt Handling”
on page 5‐191.

Creating Graphics Files 5

Note: The .prn files for SDC printers will not print on USB printers.

For forms‐based printing, you must create a .bmp file with the same
name as the .prn file. Advance NDC automatically uses the .bmp file
during forms‐based printing.
For raw data printing on USB printers, you must create a usable .prn
file. To create .prn files for use with USB Receipt and USB journal
printers, do the following:
1 Locate the NCR80RDR.INF file on your PC and note the path.
This file is installed as part of an APTRA XFS development
installation.

2 Select Start from the Windows Taskbar, then Printers and Faxes
| Add Printer. The Add Printer Wizard opens.

3 Select the Next button.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-200 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

4 Select the Local printer attached to this computer radio button

and deselect the Automatically detect and install my Plug and
Play printer check box. Select the Next button.

5 Select the Use the following port radio button, and select File
(Print to File) from the associated drop‐down menu. Select the
Next button.

6 Select the Have Disk button. The Install from Disk dialog box
appears, select the Browse button and browse to the
NCR80RDR.INF file in the location you identified in step 1.
Select the NCR80RDR.INF file from the file list, and select the
Open button. You are returned to the Install from Disk dialog
box, select the OK button to return to the Add Printer Wizard.

7 Select “NCR USB 80mm Renderer” from the Manufacturer list

box, and then select the Next button.

8 Choose the default printer by selecting one of the following

radio buttons:
— If you have a different printer that you want to use as the
default, select the No radio button
— If you want to use the NCR USB 80mm Renderer as the
default, select the Yes radio button.

Select the Next button.

9 Select the Do not share this printer radio button, then select the
Next button.

10 As this is printing to a file, you do not need to print a test page,

so select the No radio button, then select the Next button.

11 Select the Finish button.

As the NCR USB 80mm Renderer driver is not signed, you might be
prompted before installation. Choose to continue with the
installation. A message will appear notifying you of a successful
installation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-201

Configuring Advance NDC and Associated Components
Configuring Printers

To print a logo with forms‐based printing on USB printers, ensure

that an equivalent .bmp file is available.
For raw data printing on USB printers, the logo may need to be
resized. To print a correctly sized logo file, ensure that the paper
size is set to match the receipt paper size as follows:
1 Select Start from the Windows Taskbar, then Printers and Faxes
| NCR USB 80mm Renderer |Open | Printer | Printing
Preferences | Advanced | Paper Size.

2 Update the paper size to match the receipt paper size. By default
the paper size is set to NCR 80x500mm. For normal size receipt
paper, this should be changed to NCR 80x25mm.
To produce a .prn file, open the graphic you require and select Print
to File.

Registry Entry for Printing Graphics on the Next Page 5

The following registry entry allows you to print the graphic on the
next page when the image is being printed at the end of the receipt
and if the size of the image doesn’t fit into the current page:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance
NDC\PRINTING\Receipt Forms\PrintGraphicOnNextPage

Valid values are as follows:

Table 5-57 Name Data Value Description

Print Graphic on Next Page Registry Value
PrintGraphicOnNext 0 Scale the graphic to the available
Page page size and print the graphic on
the same page

1 Print graphic on the next page if the

size of the image doesn’t fit into the
page (default)

The default value of the Media property for .NET Supervisor tasks
LEAP Receipt Printer 5

and offline receipt printing is configured as Receipt1 in the

AdvanceNDCCore.accfg, AdvanceNDCCustom.accfg, CashInCore.accfg
and the CashInCustom.accfg configuration files. However for a LEAP
Receipt printer, the value must be updated to ShortReceipt due to
restrictions on the media length from XFS. For example,
TCPIPReceiptSrv for the PRINT TCPIP task has the default media
value Receipt1, which must be updated for a LEAP Receipt printer
as follows:
<!-- TCPIPReceiptSrv for PRINT TCPIP task -->
<Class ID="TCPIPReceiptSrv" Name="NCR.APTRA.RcptSrv.XFS
ReceiptService" Assembly="NCR.APTRA.RcptSrv.dll">

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-202 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

<Interface>
<Property Name="Media" Value="ShortReceipt" />
</Interface>
</Class>

Reconfiguration is required for journal, receipt and statement

Non‐Thermal Printers 5

printers that do not support the printer control codes set as default
in Advance NDC, such as ESC G for graphics. If an unsupported
control code is sent for printing, a square bracket ( [ ) is printed.
The configuration can be made either through the host or through
the registry settings on the SST. The registry entries for printers are
under:

HKLM\SOFTWARE\NCR\Advance NDC\PRINTING

The following subkeys may need to be reconfigured for your

particular printer:
 BARCODE
 GRAPHICS
 HZ_HGHT_BARCODE
 POS_HRI_CHAR
 SW_ON
 SW_OFF
 WIDTH_BARCODE

For information about supported control codes, refer to the

documentation for your particular printer.

If you develop an authored flow using the Passbook Printer worker

Passbook Printer 5

classes provided in the APTRA Author, the following registry key is

available to control page mark or line number processing:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Passbook

You can set the values so the Passbook Reader worker does not read
the page mark for the page number or scan the passbook for the
next line number. Valid values are as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-203

Configuring Advance NDC and Associated Components
Configuring Printers

Table 5-58 Name Data Value Description

Passbook Printer Registry Values
BypassPageMark 0 The page mark is read and the
resulting value stored in the Page
Number Store (default)

1 The page is not read and a value of 0

(zero) is stored Page Number Store
If this is set, the page mark scan still
occurs when the first READ_FORM
command is issued, but the Passbook
Reader worker does not read the scan

BypassLineScan 0 The page is scanned for the next

available line and the result is stored
in the Line Number Store (default)

1 The page is not scanned and a value of

0 (zero) is stored in the Line Number
Store

As the Passbook Definition and Passbook Definer worker classes

use form and media definitions to interface with XFS, the following
registry entries are included in ANDCSST.xml file, giving the
default location where these definitions will be dynamically created
by the workers:
HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
PPTR\GENERAL_CONFIGS
FormsDir = C:\Program Files\NCR APTRA\Printing\
Passbook\Forms
MediaDir = C:\Program Files\NCR APTRA\Printing\
Passbook\Media

For more information, refer to the Passbook Printer worker class

help in the Author.

Implementation 5

The following steps illustrate how these settings affect the

implementation.
1 The Passbook Acceptor worker issues a READ_FORM command to
enable the device. When media is inserted, this worker signals

2 An attempt is made to read the magnetic stripe on the passbook

3 If this is the first transaction following a reboot of the SST, the

line scan is performed. This occurs whatever the value of the
ByPassLineScan registry setting

4 Depending on the registry settings, one of the following occurs:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-204 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Printers

— If both ByPassPageMark and ByPassLineScan are set to 1

no further READ_FORM commands are issued. Typically,
information from the magnetic stripe is used by the
application instead of that in the Page Number and Line
Number stores
— If both ByPassPageMark and ByPassLineScan are set to 0, a
second and third READ_FORM command is issued to read the
page mark and look for empty lines
— If ByPassPageMark is set to 1 and ByPassLineScan is set to
0, Advance NDC does not attempt to read the page mark,
and a second READ_FORM is issued to look for empty lines
— If ByPassPageMark is set to 0 and ByPassLineScan is set to
1, a second READ_FORM is issued to read the page mark, but
no attempt is made to look for empty lines.

To manually import printer registry files such as

64‐Bit Windows 7: UniversalPrinters.reg on a 64‐bit Windows 7 system, complete the
Importing Printer following steps:
Registry Files Manually
1
5

Run the 32‐bit version of regedit.exe, which is located in

C:\Windows\SysWOW64\

2 On the File menu, select Import and browse to the required

registry file. All printer settings are added under the following
registry key:
HKLM\Software\Wow6432Node\NCR\Advance NDC

3 As there is no view of the Wow6432Node registry hive in the

32‐bit registry editor, open the 64‐bit registry editor, which is
also called regedit.exe but located in C:\Windows, to see the
printer settings on the Wow6432Node path.

Note: Instead of steps 1 and 2, you can execute the 32‐bit registry
editor from a batch file and provide the required printer registry file
as an input parameter.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-205

Configuring Advance NDC and Associated Components
Configuring E-Receipt

Configuring E‐Receipt 5

This section describes how E‐receipt can be configured.

The e‐receipt functionality delivers digital receipts to consumers as
an email or SMS through the CxM server.

Advance NDC uses the e‐receipt service (CxMEReceiptsSrv)

E‐Receipt Service component to enable this functionality. For any transaction, the
Component 5
application provides CustomerID, Opcode and AmountBuffer to
the CxMEReceiptsSrv component after the transaction reply has
been received from the host and the application is in the Close state.
The CxMEReceiptsSrv component further sends this data to the
CxM server and the server sends the e‐receipt to consumers.

The application sends the e‐receipt data irrespective of the

transaction status (successful or failed).

In case of chain transactions, only one e‐receipt data is sent to the

CxMEReceiptsSrv component in the Close sate and contains the last
transaction details.

Note: The e‐receipt does not support offline transactions such as

Local Cash Dispense state (z010) and Cash Deposit Handling state
(z014).

The e‐receipt functionality is enabled by the property Service

Configuring E‐Receipt 5

Enabled of the NDCEReceipt class in the AdvanceNDCCustom.accfg

file. By default, this property is set to False. If the ServiceEnabled
property is set to True, the application sends the e‐receipt data to
the CxMEReceiptsSrv component.
The following extract from the AdvanceNDCCustom.accfg file shows
how to enable the e‐receipt functionality:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-206 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring E-Receipt

Figure 5-71
Example E-Receipt Property Extract
<!-- Advance NDC EReceipt Service -->
<Class ID="NDCEReceipt" Name="NCR.APTRA.NDC.NDCEReceipt.NDCEReceipt"
Assembly="NCR.APTRA.NDC.NDCEReceipt.dll" CreateAlways="true">
<Constructor>
<Argument Name="commonData" Value="NDCCommonData"/>
Argument Name="EReceiptService" Value="EReceiptService"/>
</Constructor>
<Interface>
<Property Name="ServiceEnabled" Value=True"/>
<Property Name="TransactionData" Value="TransactionDataArray" IsLink="true"
IsArray="true"/>
</Interface>
</Class>
<Array ID="TransactionDataArray">
<Element Value="AmountBuffer"/>
</Array>

By default, the AmountBuffer element is configured under the

TransactionDataArray array in the AdvanceNDCCustom.accfg file.
Using the AmountBuffer element, the application sends the
amount entered by the consumer to the CxMEReceiptsSrv
component.
For cash/cheque deposit and balance enquiry transactions, the
AmountBuffer is sent as 0.00.

Note: A known limitation is that irrespective of the screen

definition, the decimal point is always placed from the last two
digits in the consumer entered amount, which is sent to the
CxMEReceiptsSrv component.

For example, when screen definition is configured as 0.00, if a

consumer wants to withdraw 200, the consumer should enter 20000.
The application sends the AmountBuffer data as 200.00 to the
CxMEReceiptsSrv component.

When screen definition is configured as 0.000, if a consumer wants

to withdraw 200, the consumer should enter 200000. The application
sends the AmountBuffer data as 2000.00 instead of 200.000 to the
CxMEReceiptsSrv component.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-207

Configuring Advance NDC and Associated Components
Configuring E-Receipt

The properties available in the EReceiptService class in the

AdvanceNDCCustom.accfg file are used to configure the
CxMEReceiptsSrv component. Following is the extract of the
EReceiptService class from the .accfg file.
Example E-Receipt Service Class Extract
<Class ID=" EReceiptService" Name="NCR.APTRA.CxMEReceiptService.EReceiptService"
Assembly="NCR.APTRA.CxMEReceiptsSrv.dll" X="10457" Y="1422">
<Interface>
<Property Name="Url" Value=" Server_URL"/>
<Property Name="Title" Value=" BankName"/>
<Property Name="Timeout" Value="750"/>
<Property Name="TerminalID" Value="Machine ID"/>
<Property Name="FooterText" Value="ERECEIPT_FOOTER"/>
</Interface>
</Class>

The following table describes the properties:

Table 5-59 Property Description

E-Receipt Service Class Properties
URL Mandatory

The address of the e‐receipt web‐service. This

property must use HTTP or HTTPS protocol.

Title Optional

The title of the formatted transaction receipt. If the

value is null, the title is not added to the e‐receipt
displayed.

Timeout Mandatory

The time in milliseconds that the e‐receipt waits for

a response from the EReceipt service. By default,
the timeout is set to 750 milliseconds.

TerminalID Optional

ID of the SST where transaction is performed.

FooterText Optional

The footer information of the formatted transaction

receipt.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-208 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Configuring Readers 5

This section describes the configuration of card readers under the

following headings:
 Accepting Smart Cards in Motorised Card Readers
 Additional DASH Reader Fatal/Suspend Handling
 Barcode Reader Filter and Extraction Rules
 Contact and Contactless Card Readers
 Journaling Card Reader Events

Advance NDC can be configured to allow smart (non‐magnetic)

Accepting Smart Cards in cards to be accepted by setting the following in the registry:
Motorised Card Readers 5

HKLM\SOFTWARE\NCR\APTRA Self-Service Support (NCR

Features)\<var>\Operational Parameters\
NON MAGNETIC ACCEPT
where <var> represents the specific card reader, for example,
SdcMotorisedCardReader. An entry is created for each card reader
attached to the SST during the service provider configuration.
Valid values are as follows:
 0 = non‐magnetic cards are not accepted
 1 = non‐magnetic cards are accepted
You must also create the following registry key and DWORD entry:
HKLM\SOFTWARE\NCR\Advance NDC\Extensions\
Option39\AcceptMagCardsOnly = 0

When using a DASH reader with Card Read State A, or Card Read
Additional DASH Reader State T with no chip connect bit set, the reader acts as a standard
Fatal/Suspend Handling 5
DIP reader and does not enter a suspend state.
To use the additional fatal/suspend handling the following registry
entry must be set to ʹ1ʹ:
HKLM\Software\NCR\Advance NDC\DASH\EnableSeverity

By default, this option is not enabled.

When enabled, the following additional fatal/suspend handling
occurs:
 If a card is entered in a DASH reader and not removed before
Timer 72 expires, a suspend message is sent and the DASH
reader enters a suspend timeout.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-209

Configuring Advance NDC and Associated Components
Configuring Readers

 If the card is still detected in the DASH reader after the suspend
timeout expires, the reader reports a fatal status and goes out of
service. The card entry screen is displayed, but no cards can be
accepted.

Note 1: Because the suspend and fatal states are initiated by the
application, they are not reflected in the fault display information.

Note 2: In a DASH card reader, if a card is already present in the

card reader during Insert Card State z008, or Card Read State A, or
Card Read‐PIN Entry Initiation State T, an unsolicited message with
mStatus 13 and error severity 2 is sent to the host.

The configuration of barcode readers and extraction rules is defined

Barcode Reader Filter and in the NDCBarcodeReader.xml file. This file can be updated through
Extraction Rules 5
software distribution, local modification or the XML Configuration
Download message. For details of the XML envelope that must be
used with this configuration file, see “XML Configuration Files” on
page 5‐37. For details of the XML Configuration Download refer to
the APTRA Advance NDC, Reference Manual.
The NDCBarcodeReader.xml file is stored in the following location:
C:\Program Files\NCR APTRA\Advance NDC\Config
The Barcode Reader schema, NDCBarcodeReader.xsd, defines the
structure of the configuration data and extraction rules for the
barcode reader.

Table 5-60
Barcode Filter Structure Definition
Element Description

BarcodeReaderClass The whole file is embedded within BarcodeReaderClass tags.

This is the root element.

Nested elements:
 BarcodeReaderDevice

BarcodeReaderDevice The identification number of the barcode reader device.

Nested elements:
 Name
 Instance
 BarcodeFilter

Name A free format name assigned to the device. This name is for information only.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-210 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Element Description

Instance The barcode reader device that the configuration applies to. There is only one
barcode reader available for the barcode reader device class.

BarcodeFilter A list of barcode filters that are used for comparison within the Barcode Read
state. These filters ensure that the barcode conforms to an application template
and allow the state flow to branch, based on the barcode presented.

Nested elements:
 Index
 Offset
 Filter

Index This value is used as an index for the Barcode Read state parameters and is used
to select an exit. Index is in the range 0 to 48. See “&‐Barcode Reader State” in
Chapter 2, “State Tables” of the APTRA Advance NDC, Reference Manual.

Note: The values should be kept as low as possible to minimize the number of
extension states required. The most common filters are assigned lower range
index identifier values.

Offset Within the barcode, the position of the character at which the comparison is to
start.

Filter Specifies a character filter, which ensures that only barcodes of the correct format
are accepted by the application.
Filter can contain any ASCII hex character from 0x20 to 0x7E. The following
characters have a special meaning within the filter process:
 @ = numeric character 0‐9
 % = any character from 0x20 to 0x7E
For example, ‘abc@@@@%%%def’ would be used to select a string within the
barcode that begins at the index specified by the Offset and exactly matches the
following sequence:
1 The characters ‘abc’
2 Any four numeric characters in the range 0‐9
3 Any three characters from 0x20 to 0x7E
4 The characters ‘def’.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-211

Configuring Advance NDC and Associated Components
Configuring Readers

Example Barcode Filter Configuration File 5

The following extract is an example from the barcode filter

configuration file:

Figure 5-72
Example Barcode Filter
Configuration File Extract
<?xml version="1.0" encoding="UTF-8"?>
<BarcodeReaderClass xmlns="http://www.ncr.com/APTRA/NDC/BarcodeReader"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=
"http://www.ncr.com/APTRA/NDC/BarcodeReader NDCBarcodeReader.xsd">
<BarcodeReaderDevice DeviceID="f">
<Name>Barcode1</Name>
<Instance>1</Instance>
<BarcodeFilter>
<Index>0</Index>
<Offset>0</Offset>
<Filter>1234@@45</Filter>
</BarcodeFilter>
<BarcodeFilter>
<Index>1</Index>
<Offset>0</Offset>
<Filter>Bill%%12345@@</Filter>
</BarcodeFilter>
</BarcodeReaderDevice>
</BarcodeReaderClass>

Table 5-61
Barcode Extraction Rules
Element Description

Rule ID The Index number that matches state table entry 2 (rule set ID) of the Barcode
Read Primary Extension state table.

Pattern The regular expression used to extract data from the barcode data if the barcode
data is within specified limits.
For example, for the configured rule pattern ʺ .{6}=.{8} ʺ, if the barcode data is
612345000000001251=0512101222000000, the extracted data will be
001251=05121012.

DestinationDataOffset The position at which the data is to be replaced in the Track 2 data store
(idT2Data) in the range 0‐39.

Note: If state table entry 7 of the Barcode Read state has a value other than 002
(Track 2 buffer), the barcode data is copied to the corresponding buffers in the
state tables irrespective of the Barcode Extraction Rules.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-212 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Example Barcode Extraction Rules 5

The following extract is an example from the barcode extraction

rules file:

Figure 5-73
Example Barcode Extraction Rules Extract
<?xml version="1.0" encoding="UTF-8"?>
<BarcodeReaderClass xmlns="http://www.ncr.com/APTRA/NDC/BarcodeReader"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ncr.com/APTRA/NDC/
BarcodeReader NDCBarcodeReader.xsd">
<BarcodeReaderDevice DeviceID="f">
<Name>Barcode1</Name>
<Instance>1</Instance>
<BarcodeFilter>
<Index>0</Index>
<Offset>0</Offset>
<Filter>1234@@45</Filter>
</BarcodeFilter>
<BarcodeFilter>
<Index>1</Index>
<Offset>0</Offset>
<Filter>Bill%%12345@@</Filter>
</BarcodeFilter>
<BarcodeExtractionRules>
<Rule ID=””>
<Pattern></Pattern>
<DestinationDataOffset></DestinationDataOffset>
</Rule>
</BarcodeExtractionRules>
</BarcodeReaderDevice>
</BarcodeReaderClass>

Advance NDC can be configured to support a contact and a

Contact and Contactless contactless card reader as follows:
Card Readers 5

 Either one alone, as the primary card reader.

 Both together, as the primary and the secondary card reader.

Note: Two card readers are not supported on other vendors’ SSTs.

Primary and Secondary Card Readers 5

When an SST has both a contact and a contactless card reader, the
contact card reader is always the primary card reader and the
contactless card reader is the secondary card reader. Advance NDC
does not support configuration of a contactless card reader as the
primary card reader when a contact card reader is also present.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-213

Configuring Advance NDC and Associated Components
Configuring Readers

As part of the Advance NDC Start of Day configuration, the registry

is updated as shown in the following table:

Table 5-62 Registry Entry Type Value

Registry Entry for both Contact and
Contactless Card Readers HKLM\SOFTWARE\NCR\Advance NDC\ REG_SZ IDCardUnit1
Aliases\Card Reader

HKLM\SOFTWARE\NCR\Advance NDC\ REG_SZ

Aliases\Card Reader Second

HKLM\SOFTWARE\NCR\Advance NDC\ 2
REG_
ContactlessReader\ DWORD
NCRContactlessReader

Contact Card Reader as the Primary Card Reader 5

When an SST has a contact card reader alone, the contact card
reader is the primary card reader.
As part of the Advance NDC Start of Day configuration, the registry
is updated as shown in the following table:

Table 5-63 Registry Entry Type Value

Registry Entry for Contact Card Reader as
the Primary Card Reader HKLM\SOFTWARE\NCR\Advance NDC\ REG_SZ IDCardUnit1
Aliases\Card Reader

HKLM\SOFTWARE\NCR\Advance NDC\ REG_SZ

Aliases\Card Reader Second

HKLM\SOFTWARE\NCR\Advance NDC\ REG_ 0

ContactlessReader\ DWOR
NCRContactlessReader D

Contactless Card Reader as the Primary Card Reader 5

When an SST has a contactless card reader alone, the contactless

card reader is the primary card reader.
As part of the Advance NDC Start of Day configuration, the registry
is updated as shown in the following table:

Table 5-64 Registry Entry Type Value

Registry Entry for Contactless Card
Reader as the Primary Card Reader HKLM\SOFTWARE\NCR\Advance NDC\ REG_SZ
Aliases\Card Reader

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-214 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Registry Entry Type Value

HKLM\SOFTWARE\NCR\Advance NDC\ REG_SZ

Aliases\Card Reader Second

HKLM\SOFTWARE\NCR\Advance NDC\ REG_ 1

ContactlessReader\ DWOR
NCRContactlessReader D

Configuring Contactless Card Reader Device Mode 5

Device mode of the contactless card reader to interact with the

Advance NDC application can be configured either to the XFS
session or to the wrapper session. By default, Advance NDC
interacts with the contactless card reader device through the XFS
session with the help of contactless enabler 2.0.
Interaction with the device through the XFS session supports the
contactless card reader on the other vendors’ SST. Whereas,
interaction through the wrapper session does not support the
contactless card reader on the other vendors’ SST.
Advance NDC can also be configured to interact with the device
through the wrapper session using the following (DWORD) registry
entry:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance
NDC\ContactlessReader\EnableXFSSessionForContactless

Table 5-65
Registry Entry for Contactless Card
Reader to Configure Device Mode

Registry Entry Value Description

EnableXFSSessionFor 1 Defines how device mode in a contactless card

Contactless reader is configured.
Possible values are as follows:

0 ‐ Application opens the device session in the

wrapper mode. In the wrapper Mode, the
contactless enabler controls the device directly.

1(default) ‐ Application opens the device session

in the XFS mode. In the XFS mode, the contactless
enabler controls the device through the XFS
platform.

Note: The XFS platform must support the

CEN 3.30 for contactless card reader device
to use in the XFS session.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-215

Configuring Advance NDC and Associated Components
Configuring Readers

In the NCR SST, the Service Variant registry must be set as per the
setting of the EnableXFSSessionForContactles registry to use
the contactless card reader either in the XFS session or wrapper
session.
For example, In the NCR SST, if the EnableXFSSessionFor
Contactles is set to 1, the Service Variant registry must also be set
to 1 to use the contactless card reader in the XFS session in the
following paths:
KIOSK II device:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\APTRA Self-
Service Support (NCR Features)\USBContactlessCardReader\
OperationalParameters\MCRW-01-USBContactlessReader\Group1

Service Variant=dword:00000000

KIOSK III device:

HKEY_LOCAL_MACHINE\SOFTWARE\NCR\APTRA Self-Service Support
(NCR Features)\USBContactlessCard
Reader2\Operational Parameters\MCRW-01-USBContactless
Reader2\Group1

Service Variant=dword:00000000

Note: After setting the registry value, the SST must be rebooted.

Transaction Activation 5

When an SST has both a contact and a contactless card reader, the
way a transaction is carried out depends on the card reader that is
activated as described in the following sections:
Contact Card Reader Activation When the contact card reader is 5

activated, Advance NDC disables the contactless card reader after

the card has been inserted and the contact card reader transaction
continues.
Contactless Card Reader Activation When the contactless card 5

reader is activated and the contactless card track data is returned,

Advance NDC attempts to disable the contact card reader. The
transaction will be carried out as follows:
 If the contact card reader is successfully disabled, the contactless
transaction continues.
 If the consumer attempts to use both and the contact card reader
is not disabled in time, the contactless card track data is ignored
and the contact card reader transaction continues if the card has
been inserted.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-216 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Read Conditions 5

The processing of the cards varies depending on the read

conditions. For information on read conditions, refer to section
“Read Conditions for Smart Card Readers” in Chapter 2, “State
Tables” of the APTRA Advance NDC, Reference Manual.

Automatic Language Selection 5

Advance NDC supports automatic language selection for contact

and contactless cards through the EMV Exit states.
Contactless Cards Following the successful completion of State 5

Type ‘A’ (Card Read State) or State Type ‘T’ (Card Read ‐ PIN Entry
Initiation State), it may be possible to determine the language
preference of the cardholder from ICC data using State Type ‘‐’
(Automatic Language Selection State).
Contact Cards Following the successful completion of State Type 5

‘,’(Complete ICC Initialisation) or State Type ‘/’(Complete ICC

Application Selection & Initialisation), it may be possible to
determine the language preference of the cardholder from ICC data,
using State Type ‘‐’ (Automatic Language Selection State).
For information on EMV Exit states, refer to the EMV Integrated
Circuit Card (ICC) Reference Manual.

Voice Guided Sessions 5

For transactions where voice guidance is provided, audio messages

are associated with the card readers available and active in the SST.
The audio messages are played based on the audio IDs that are
mapped to the integer value of the attribute in the
AudioGuidanceData.xml file as follows:

Table 5‐66 Active Card Readers Attribute Example

Attributes for Voice Guided Sessions
Contact card reader cardPromptScreen Please insert
the card
See
“cardPromptScreen”
on page 6‐26

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-217

Configuring Advance NDC and Associated Components
Configuring Readers

Contactless card reader contactlessPrompt Please tap the

Screen card

See “contactlessPrompt
Screen” on page 6‐26

Contact and contactless contactAnd Please insert

card reader ContactlessPrompt or tap the
Screen card

See “contactAnd
ContactlessPrompt
Screen” on page 6‐26

For information on mapping audio IDs to the attributes, see

“Example XML Configuration File” on page 6‐45.

Device Faults 5

Device fault messages for the contact and contactless card readers
are displayed on the rear operator panel to enable the operator to
identify which card reader is not in a good state as explained in the
following sections.
Contact Card Reader When a contact card reader is the only card 5

reader available and active on the SST, the messages are displayed
based on the status of the card reader as follows:

Table 5-67 Status Fault Display Message

Contact Card Reader
Fatal CARD READER FATAL
<details>

See “Device Fault Messages for a Contact Card

Reader”

Offline or Power off CARD READER

DEVICE OFFLINE

Contactless Card Reader When a contactless card reader is the 5

only card reader available and active on the SST, the messages are
displayed based on the status of the card reader as follows:

Table 5-68 Status Fault Display Message Comment

Contactless Card Reader
Fatal CARD READER A contactless card
POSSIBLE JAM reader can be fatal due
to communications
failure

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-218 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Offline or Power off CARD READER

DEVICE OFFLINE

Fatal MALFUNCTION A contactless card

reader can be fatal when
the reader is configured
with a Contactless
Enabler.xml file
containing invalid data

Fatal FIRMWARE A contactless card

MISMATCH reader can be fatal if the
data returned by the
reader is invalid due to
the reader firmware
getting corrupted or the
installed firmware does
not support the
contactless card reader

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-219

Configuring Advance NDC and Associated Components
Configuring Readers

Contact and Contactless Card Readers When both card readers 5

are available and active on the SST, the messages are displayed
based on the status of the card readers as follows:

Table 5-69 Status Contact Message Contactless Message

Contact and Contactless Card Readers
Both the card CARD READER SECONDARY CARD READER
readers are fatal FATAL FATAL
<details>

See “Device Fault

Messages for a
Contact Card
Reader”

Both the card CARD READER SECONDARY CARD READER

readers are DEVICE OFFLINE DEVICE OFFLINE
offline or
powered off

Contact Card CARD READER SECONDARY CARD READER

Reader is fatal FATAL DEVICE OFFLINE
and contactless <details>
card reader is
offline or See “Device Fault
powered off Messages for a
Contact Card
Reader”

Contact Card CARD READER SECONDARY CARD READER

Reader is DEVICE OFFLINE POSSIBLE JAM
offline or
powered off
and contactless
card reader is
fatal

Contactless - SECONDARY CARD READER

Card Reader is MALFUNCTION
the secondary
card reader and
is fatal

Device Fault Messages for a Contact Card Reader The following 5

are the possible messages that are displayed for device faults of a
contact card reader:
 CARD JAM
 SEC MOD NOT READY
 CARD POS UNKNOWN
 CAPTURE BIN FULL

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-220 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

 CAPTURE BIN FULL SOON

 POSSIBLE JAM
 OFFLINE

If the contact card reader is fatal due to communications failure, the

following message is displayed:

CARD READER
POSSIBLE JAM

If the contact card reader is tampered, the following message is

displayed:

CARD READER ERROR

POSSIBLE TAMPERING

Messages are also displayed when the card reader is in a good state.
For example, if the contact card reader bin is full, the following
message is displayed:

CARD READER
CAPTURE BIN FULL

If the contact card reader bin is almost full, the following message is
displayed

CARD READER
CAPTURE BIN FULL SOON

For more information on the display of device faults, see “Fault

Display” on page 4‐10

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-221

Configuring Advance NDC and Associated Components
Configuring Readers

Status Messages 5

Advance NDC does not send Unsolicited/Solicited Device Fault

Status information messages for the card readers as explained in the
following table:

Table 5-70
Status Message

Message Message
Message Destination Comment
Class Sub-Class

1 2 Card Reader/Writer Central The Transaction/Device Status values of ‘6’ to ‘9’ are
2 2 Device Fault Status not reported if a contact card reader is the primary
Information card reader.

The Transaction/Device Status values of ‘1’ to ‘9’ and

also Supplies Status values ‘0’ and ‘4’ are not reported
if a contactless card reader is the primary card reader.

1 2 Secondary Card Central The Transaction/Device Status values of ‘1’ to ‘9’ and
Reader Supplies Status values ‘0’ and ‘4’ are not reported if a
2 2 Device Fault Status contactless card reader is the secondary card reader.
Information Advance NDC supports only a contactless card reader
as the secondary card reader.

Reset Contactless Reader 5

When a contactless card reader is configured with a

ContactlessEnabler.xml file containing invalid data or manually
copying the invalid ContactlessEnabler.xml file, the firmware of the
contactless card reader can get corrupted and become unusable.
When this happens, the cardholder can not initiate any transaction
with the contactless card reader and the application performs the
following:
 Sends an unsolicited message to the host with mStatus 55
(MS_READER_DATA_ERROR) and reports the contactless card
reader status as FATAL.
 Displays MALFUNCTION on the fault display.
The contactless card reader can be reset to working state by
executing the 62 RESET CONTACTLESS READER Supervisor
option.
If the host receives an unsolicited message with mStatus 55 , then
the host sends the updated ContactlessEnabler.xml file download or
the file should be copied manually to the SST before executing the
62 RESET CONTACTLESS READER Supervisor option. This will
reset the contactless card reader with the latest XML configuration.
For more information see “Error Reporting for Contactless Card
Readers” on page 5‐228.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-222 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

If the host does not send an updated ContactlessEnabler.xml file

download, then the firmware of the contactless card reader
continues to remain in the fatal state.
For information on how to reset the contactless card reader, refer to
section “62 RESET CONTACTLESS READER” in chapter 3,
“Replenish Menu” of the APTRA Advance NDC, Supervisor’s Guide.

24‐Volt Reset for Contactless Reader 5

A 24‐volt reset is required for a contactless reader under the

following conditions:
 Transmission Error ‐ This can occur during exchanging of
the data (both sending and/or receiving) with the contactless
card reader. The application sends an unsolicited message
with mStatus 96 while attempting to enable the contactless
card reader. An INTERNAL/PORT ERROR error is displayed on
the fault display.
 Unresponsive Device ‐ This can occur when the contactless
enabler does not receive any response from the contactless
card reader. This is different from timeout when a
contactless card is not tapped within a defined time after the
contactless card reader is enabled. The application sends an
unsolicited message with mStatus 97 while attempting to
enable the contactless card reader. An UNRESPONSIVE error is
displayed on the fault display.
 USB Comms Failure ‐ This can occur when the USB
communication cable of contactless card reader is
disconnected. The application sends an unsolicited message
with mStatus 98 while attempting to enable the contactless
card reader. A POSSIBLE JAM error is displayed on the fault
display.
The status of the contactless card reader is reported as fatal and the
application performs the 24‐volt reset in the close state to bring the
device into working state. If the device continues to remain in the
fatal condition, then the application has failed to enable the
contactless card reader and will continue to remain in the fatal state.
The Transmission Error and Unresponsive Device errors can occur
for any command that is issued on the contactless card reader.
To perform the 24‐volt reset on the contactless card reader, the
Enable24vReset attribute must be set to 1 in the DeviceRecovery.xml
file for the contactless card reader. When the contactless card reader
is configured as the primary card reader, then the Enable24vReset
attribute must be set to 1 (default) for the Card Reader, and when
the contactless card reader is configured as the secondary card
reader, then the Enable24vReset attribute must be set to 1 for the
Card Reader Second in the DeviceRecovery.xml file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-223

Configuring Advance NDC and Associated Components
Configuring Readers

For more information, see “Error Recovery” on page 5‐364 and

“Resetting USB Devices” on page 5‐94.

Card Misreads 5

An Error Misread screen is displayed and the card is ejected from

the contact card reader when the following conditions are true:
 SST has both card readers
 A card is inserted into the contact card reader and another card
is tapped on the contactless card reader simultaneously
 The contact card reader does not read the card completely
This is because the Card Acceptor worker class exits as soon as one
of the card readers reads the card.
After ejecting the card, the card reader is reactivated and waits for
the next card entry.

Controlling the Card Entry Retries 5

A card can be misread in the Insert Card State (z008) due to an

invalid card or a mechanism error. In a card misread condition, the
application displays error screen and then the card reader is
re‐activated to re‐insert the card. This situation leads the consumer
to insert his/her card repeatedly until a valid card is inserted or a
cancel key is pressed.
Advance NDC can be configured to control the number of card
insertion retries after a card is misread. Once the maximum number
of card entry retries are exceeded, the application goes to the
FatalNextState. The above functionality can be enabled using the
following (DWORD) registry entry:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\CardReader\
MaxCardEntryRetries

The following table describes the registry with the name

MaxCardEntryRetries:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-224 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Table 5-71
Registry Entry for Controlling
Card Insertion Retries

Registry Entry Value Description

MaxCardEntryRetries 3 Defines the number of card entry retries when a

card is misread in the z008 state. Possible value is
as follows:

3 (default) ‐ Maximum number of card entry

retries.

Note: If the value is not present or the value

is set to zero, then the application behaves
same as the default registry setting.

Journaling Card Entry Retries 5

Whenever the card entry retries are exceeded as per the specified
value, the following message is journaled (reserved screen j0089):
THE MAXIMUM RETRIES FOR CARD ENTRY ARE EXCEEDED.

Media Entry/Exit Indicator (MEI) for Contact and

Contactless Card Readers 5

MEI for Contact and Contactless Card Readers For an SST that 5

has both the contact and the contactless card readers enabled as the
primary and secondary card readers, the Media Entry/Exit Indicator
(MEI) flashes for both the card readers. Both the card readers MEIs
stop flashing when either a contact card is inserted into a contact
card reader or a contactless card is tapped on a contactless card
reader. When a contactless card reader is configured as the
secondary card reader, then WFS_SIU_EXTRAMEI should be
configured for the contactless card reader MEI through System
Application.

MEI for Contact Card Readers For an SST that has only a contact 5

card reader and enabled as the primary card reader, its

corresponding MEI flashes. The MEI stops flashing when a contact
card is inserted into the contact card reader.
MEI for Contactless Card Readers For an SST that has only a 5

contactless card reader and enabled as the primary card reader, its
corresponding MEI flashes. The MEI stops flashing when a
contactless card is tapped on the contactless card reader. When a
contactless card reader is configured as the primary card reader,
then WFS_SIU_CARDUNIT should be configured for the contactless
card reader MEI through System Application.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-225

Configuring Advance NDC and Associated Components
Configuring Readers

Note: For information on how to configure the MEI, refer to the

Self‐Service Support System Application User Guide.

Journaling Card Reader Events 5

Events from activated card readers are journaled as follows:

 When the primary card reader is activated, the following is
journaled:
PRIMARY CARD READER ACTIVATED

 When the secondary card reader is activated, the following is

journaled:
SECONDARY CARD READER ACTIVATED

 When both card readers are activated, the following is

journaled:
PRIMARY CARD READER ACTIVATED

SECONDARY CARD READER ACTIVATED

Card Inserted When a card is inserted into the contact card 5

reader, the following is journaled:

CARD INSERTED

Card Tapped When a contactless card is tapped on the contactless 5

card reader, the following is journaled:

CONTACTLESS CARD TAPPED

Note: These events are journaled only if the journal level is either 2
or 3. For information about configuring journal levels through
Supervisor options, refer to section, “35 Journal Level” in Chapter 4,
“Configure Menu” of the APTRA Advance NDC, Supervisor’s Guide.
For information about configuring journal levels through Author,
see “Level 1 Modification Example” on page 8‐10.

Tracing for Contactless Transactions 5

A contactless transaction provides different levels of traces for

diagnostic and performance measuring. The traces contain
information on interface calls by the user, data exchange with the
chip, time taken to perform a contactless transaction and other data.
By default, nothing is traced by a contactless transaction. The traces
can only be viewed by opening the CONTACTLESSTRACE window in
DebugLog.
The trace levels can be configured using the registry value
ContactlessTraceLevel under following registry key:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-226 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

HKLM\SOFTWARE\NCR\Advance NDC\ContactlessReader\
ContactlessTraceLevel

The values that can be set to ContactlessTraceLevel are 0 to 5.

Note: The value of the ContactlessTraceLevel registry should

match with the value in the Trace Level element of the XML file. For
information on the Trace Level element values, see “TraceLevel” on
page 5‐253
The meaning of each value is described in the following table:

Table 5-72
Contactless Trace Level Values

Value Name Type Values Description

Contactless REG_DWORD 0 noTrace_Level

TraceLevel This is the default value and no information is
traced.

1 performance_Level
Only minimum level of information is traced.

2 error_Level
Only performance information and unexpected
events that cancel a process are traced.

3 warning_Level
Only performance information and unexpected
events are traced.

4 debug_Level
Normal level of trace for debugging contactless
transactions.
Recommended setting by Advance NDC

5 deep_Level
Lowest level of traces for unitary tests.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-227

Configuring Advance NDC and Associated Components
Configuring Readers

Error Reporting for Contactless Card Readers 5

When the contactless card reader fails as a result of any error, one of
the following m‐status for the unsolicited status messages is
reported to the host:

Table 5-73
M-Status for Card Reader Failure

M-Status (Dec) Severity Literal Description

53 ROUTINE MS_XML_CONFIG_ERROR There has been an error when configuring

the device using the contactlessenabler
.xml file.

54 ROUTINE MS_TRANSIDNOTFOUND_ER Transaction Identifier not found in the

ROR contactlessenabler.xml file.

55 FATAL MS_READER_DATA_ERROR The data returned by the reader is invalid

and this could be as a result of the reader
firmware getting corrupted, or the
installed reader firmware does not
support the contactless card reader.
See :Table Note 5

96 FATAL MS_USB_COMMS_FAILURE There has been an error due to

transmission of data with a contactless
card reader.

97 FATAL MS_DEVICE_TIMEOUT There has been an error due to no

response received from the contactless
card reader.

98 FATAL MS_DEVICE_COMMS_ There has been an error when USB

FAILURE communications cable is disconnected
from the contactless card reader.

Table Note 5: When m‐Status 55 is sent to the host, FIRMWARE

MISMATCH is displayed on the fault display, indicating that the
correct version of USB contactless card reader must be installed. For
Kiosk 2, USB CCR Component USBCCR_93.01.00.19 must be
installed. For Kiosk 3, latest USB CCR2 component available in the
latest XFS released version must be installed.

A contactless enabler interface provides a simple way for Advance

Configuring Contactless NDC application to deal with contactless cards.
Card Reader 5

Prior to performing any contactless transactions the reader must be

configured. The information required to configure the contactless
card reader and the transaction being performed, are the data items
relating to the terminal, the applications to be supported by the
reader and any application specific data item values.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-228 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

This information is supplied to the contactless enabler through the

ContactlessEnabler.xml file. During Advance NDC installation, this
xml file is copied to the default folder C:\Program Files\NCR
APTRA\Advance NDC\Config.
The host can update the ContactlessEnabler.xml file by sending
downloads using the XML Configuration Download message. It
downloads the parts of xml in sequence. For details of this message,
refer to Chapter 10, Central to Terminal Messages of the APTRA
Advance NDC, Reference Manual.
Advance NDC responds to the XML configuration command in the
same way as for the other data commands, that is, it sends a ‘Ready
9’ for a successful receipt of the configuration file part or a reject
solicited message. The reject message is sent when the XML is
incorrectly formed or when the XML is not successfully stored on
the hard drive. When an XML download is rejected, the Central
should perform a complete XML download again. After a valid
XML is received from the Central, the ContactlessEnabler.xml file is
overwritten and the contactless reader is reconfigured with the new
XML. If the configuration of the contactless reader with the updated
XML fails due to a hardware error, then an unsolicited message is
reported to the Central to indicate the hardware error. The Central
must resend the ContactlessEnabler.xml file after clearing the device
error in order to continue with the contactless transactions.

Configuration Data 5

The contactless enabler user must supply a set of objects to

configure the device and the transaction being performed. These
objects are supplied through the ContactlessEnabler.xml file. The only
objects the contactless enabler automatically populates are the
transaction time and date. These are read from the system clock.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-229

Configuring Advance NDC and Associated Components
Configuring Readers

The following tags are the only ones which should be changed from
the values contained in the default XML file:

Table 5-74
Contactless Enabler Configuration Data

Tag Tag Name Default Value Sub-elements

9F1A Terminal Country Code Any The ISO 3166 numeric code
appropriate for the location of the
SST.

9F15 Merchant Category Code 6011 Classifies the type of merchant. For
example, 6011 Automated Cash
Disburse, or 6012 Financial
Institutions.

9F4E Merchant Name and Any ASCII String of up to 30 containing

Location the name and location of the SST
owner/operator.
There are specific formatting
requirements for this value. See
“Configuration Values” on
page 5‐234 for the requirements.
See Note:

5F36 Transaction Currency Any The number of decimal places

Exponent associated with the currency.

9C Transaction type Any A two digit code indicating the type

of transaction being performed. The
individual payment systems define
the value to be used for each
transaction.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-230 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Tag Tag Name Default Value Sub-elements

5F2A Transaction Currency Any A four digit ISO 4217 code

Code indicating the currency being used
for the transaction.

9F1E,FFF2 Terminal IFD Serial Any Unique and permanent serial

Number number assigned to the IFD by the
manufacturer.
For the IDTech card reader, this data
element is populated by the
Contactless Enabler using the last 8
digits of the serial number read from
the device. The serial number
information can be found marked on
the device.
Alternatively, it can be configured
via the XML file using the FFF2 tag.
This tag is not present by default
and must be configured with any
eight alphanumeric characters. If the
XML file is used, it will override the
value read from the device.

9F66 VISA’s TTQ B6804000 Among other options, this controls

which card profiles are to be
supported by the VISA kernel of the
reader, either EMV‐like only
(36804000) or Magnetic stripe‐like
and EMV (B6804000).
The default value enables both
Magnetic stripe‐like and EMV‐like
card profiles.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-231

Configuring Advance NDC and Associated Components
Configuring Readers

Tag Tag Name Default Value Sub-elements

FFFC MasterCard Paypass 00 This can be used to force support for

Profile either only EMV‐like or only
Magnetic stripe‐like card profiles.
Valid values are as follows:
00 ‐ Enables both Magnetic
stripe‐like and EMV‐like card
profiles (default)
01 ‐ Support only for Magnetic
stripe‐like only profiles
02 ‐ Support only for EMV‐like
profiles.

DF7F Improved Collision 04 This controls the reader’s collision

Detection detection behaviour.
Valid values are as follows:
00 ‐ Disables improved collision
detection.
01 to 07 ‐ Selects the various levels of
collision detection sensitivity.
Changing this value will impact the
time taken during card discovery
and therefore negatively affects the
overall tap times.
The recommended settings are:
 00 to disable all collision
detection, providing the shortest
time to discover a tapped card
 04 (default) to enable collision
detection, providing the best
compromise between the
detection of collisions and time
taken to discover a tapped card.
Values less than 04 do not result in
consistent detection of collisions,
and values above 04 increase the
card discovery times but do not
result in any better collision
detection.
A value of 02 adds approximately 40
milliseconds to the time taken to
detect the card.
A value of 04 adds approximately
120 milliseconds.
A value of 07 adds approximately
250 milliseconds.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-232 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Tag Tag Name Default Value Sub-elements

DF8124 PayPass Reader 30000 This value is MasterCard and

Contactless Transaction Firmware version GR2.0 specific.
Limit (No On‐device It indicates the transaction amount
CVM) above which the transaction is not
allowed, when “On‐Device
cardholder verification” is not
supported.
The default XML is set with a value
of 30000. However, applications
must ensure to set this to an
appropriate limit based on
individual bank requirements.

Note: If IDTech’s firmware GR 2.0 is used, this data element has to

be configured using a string in double quotation marks with a fixed
length set to 30 characters in the XML file. Spaces can be used to
compensate the missing characters, if required. The following is an
example of the Merchant Name and Location tag:

<Tag Name = "9F4E">"ATM, NCR Lab, NCR Office "</Tag> <!--

Merchant Name and Location -->

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-233

Configuring Advance NDC and Associated Components
Configuring Readers

Table 5-75
Configuration Values
Payment System Recommendation Notes/Comments

VISA Europe Merchant name and location is used The merchant name and location
within consumer device’s history (9F4E) can be configured via the
logs and issuer’s records so it is XML file.
important to configure it correctly.
It should start with “ATM”, or the
equivalent in the local language,
and then identify the SST provider’s
name and location. Cardholder
friendly information should be
provided in the first 20 characters as
this field is often truncated after this
point.

Master Card Terminal Contactless Floor Limit The default XML file is set with a
should be set to zero to force all zero contactless floor limit.
transactions to go online for
authorisation.

Master Card The Cardholder Verification The default XML file is

Method (CVM) required limit must pre‐configured to meet this
be set at zero. requirement.

Master Card The CVM that is supported must be The default XML file is
an Online PIN. All other CVM pre‐configured to meet this
should not be supported, including requirement.
on device CVM.

VISA Europe Terminals must always perform The default XML file is
CVM through Online PIN. The pre‐configured to support all CVM
TTQʹs and other settings should be types for VISA.
configured to support all other CVM The application must always ask for
types, so that any card can be the PIN irrespective of the CVM
accepted. selected by the card and Contactless
Enabler.

VISA Europe Magnetic stripe‐like transactions Action May Be Required ‐ The

should not be supported within default XML file has the Magnetic
Europe. Stripe Data (MSD) support enabled.
The TTQ tag 9F66 for VISA is set at
B6804000 to indicate MSD and
EMV support.
If MSD is not required to be
supported then the TTQ value
within the XML file should be
updated to 36804000.

Data objects required to be configured The following terminal 5

and transaction related data can be configured on the device.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-234 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

 General Terminal Data Objects ‐ These tags are general tags that
need to be configured for a contactless transaction.

Table 5-76
General Terminal Data Objects

Tag Tag Name Default Value Description

9F35 Terminal type 14 Terminal is an SST.

9F33 Terminal capabilities 604000 Magnetic Stripe, IC with contact and

Online PIN.

9F1A Terminal Country Code Any The ISO 3166 numeric code
appropriate for the location of the
SST.

9F1B Terminal Floor limit 00000000 An online only SST should have a
zero floor limit.

9F40 Additional terminal E800B053FF A standard SST additional terminal

capabilities capabilities value.

9F03 Amount Other 000000000000 Represents the cash back amount, so

(Numeric) for an SST this must always be zero.

9F15 Merchant Category Code 6011 Classifies the type of merchant. For
example, 6011 Automated Cash
Disburse, or 6012 Financial
Institutions.

9F4E Merchant Name and Any ASCII String of up to 30 containing

Location the name and location of the SST
owner/operator.
See “9F4E” on page 5‐230 for more
information.

9F53 Transaction Category Z A MasterCard value indicating the

Code type of transaction. “Z” indicating
SST Cash Disbursement.

5F36 Transaction Currency Any The number of decimal places

Exponent associated with the currency.

 Transaction Related Data Objects ‐ These tags are specific to the

transaction that is to be performed. These can be configured
anywhere in the XML file. However, these tags are the only ones
that must be used in a transaction identifier section.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-235

Configuring Advance NDC and Associated Components
Configuring Readers

Table 5-77
Transaction Related Data Objects

Tag Tag Name Value Description

9C Transaction Type Any A two digit code indicating the type

of transaction being performed. The
individual payment systems define
the value to be used for each
transaction.

5F2A Transaction Currency Any A four digit ISO 4217 code

Code indicating the currency being used
for the transaction.

9F02 Amount Authorized Any A numeric value indicating the

amount for the transaction. If this is
present in this section of the XML
file, it is used in place of the amount
supplied as a parameter to the
contactless enabler function. When
this tag is present, it takes
precedence over the value of the
amount buffer. Therefore, this tag
should be added only for the
transactions having pre‐defined
amount, for example Fast Cash.

9F1A Terminal Country Code Any A four digit ISO 3166 country code
indicating the location of the
terminal.

 Transaction Identifier for Insert Card State ‐ When Insert Card

State z008 is used, the transaction type and the transaction
amount may already be known. The transaction type (value of
OpCode buffer) and amount (if already selected by the
customer) are used to perform a transaction on the contactless
card reader. This OpCode needs to be configured as a
transaction identifier in ContactlessEnabler.xml. For every
OpCode, there should be a matching tag in the
<TRANSACTIONIDENTIFIERS> element. For example, if the
value of the OpCode when insert card state is executed is “AD
“ (empty spaces as many as the size of the OpCode buffer), then
there should be a transaction identifier configured as
<TransactionID Name =“AD “>.

Advance NDC supports the usage of wild characters in

transaction identifiers. This allows configuring the
TransactionID tag with wildcard characters (‘*’ and ‘?’) instead
of the entire Opcode Buffer to cover different state flows. A wild
character “*” will match any number of characters in the
transaction identifier, and a wild character “?” will match any

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-236 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

single character in the transaction identifier. If a user does not

want to configure individual transaction identifiers for each
transaction flow, he can then define a transaction identifier with
wild characters. For example, if a transaction identifier
<TransactionID Name = "AD*"> or <TransactionID Name =
"AD??????">is defined, then this allows the transaction types
that have “AD” as the first two characters in OpCode Buffer.
The rest of the characters are ignored.

If there is no matching entry for a particular OpCode in the

XML, then the transaction cannot be completed using the
contactless card reader in the Insert Card State z008. An
unsolicited message is sent to the host indicating the same. For
more information on unsolicited messages for contactless card
reader as primary card reader and secondary card reader, refer
to sections “Card Reader/Writer (Solicited/Unsolicited) and
“Secondary Card Reader (Unsolicited)” in Chapter 9, “Terminal
to Central Messages” of the APTRA Advance NDC, Reference
Manual.

For tags associated with the transaction identifier that need to be

configured, see “Transaction Related Data Objects” on
page 5‐236.
 Visa Specific Terminal Data Objects ‐ These tags are specific to
VISA.

Table 5-78
Visa Specific Terminal Data Objects

Tag Tag Name Description

9F66 Terminal Transaction Qualifiers (TTQ) Set to a value of B6 80 40 00 to indicate

an online only SST as required by VISA.

FFF4 Visa Risk Flags Enables and disables specific features

within the reader’s VISA kernel.
Default value is zero.

Note: The default value is 000403 when

IDTech firmware GR 2.0 is used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-237

Configuring Advance NDC and Associated Components
Configuring Readers

 MasterCard Specific Terminal Data Objects ‐ These tags are

specific to MasterCard.

Table 5-79
MasterCard Terminal Data Objects

Tag Tag Name Description

9F09 Application Version Number Version number associated with PayPass

MChip. Must be 0002.

9F6D Application Version Number Version number associated with PayPass

MSD. Must be 0001.

DF28 Terminal Capabilities – No CVM 604000

Required

DF29 Terminal Capabilities – CVM Required 604000

DF811E PayPass Mag‐stripe CVM Capability – The CVM capabilities to be used when the
CVM Requirement transaction amount is greater than the
CVM required limit in a magnetic stripe
transaction.
See Note:

DF812C PayPass Mag‐stripe CVM Capability – No The CVM capabilities to be used when the
CVM Requirement transaction amount is less than or equal to
the CVM required limit.
See Note:

DF8120 PayPass Terminal Action Code ‐ Default This tag is similar to IDTech Terminal
Action Code (Default) tag (FFFE). See
FFFE. The value must be FFFFFFFFFF.
See Note:

DF8121 PayPass Terminal Action Code ‐ Denial This tag is similar to IDTech Terminal
Action Code (Denial) tag (FFFE). See
FFFF. The value must be 0000980000.
See Note:

DF8122 PayPass Terminal Action Code ‐ Online This tag is similar to IDTech Terminal
Action Code (Online) tag (FFFD). See
FFFD. The value must be FFFFFFFFFF.
See Note:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-238 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Tag Tag Name Description

DF8124 PayPass Reader Contactless Transaction The transaction amount above which the
Limit (No On‐device CVM) transaction is not allowed when
“On‐Device cardholder verification” is not
supported.
Default value is 30000.
Set this to an appropriate limit based on
the requirement.
See Note:

DF8126 PayPass Reader CVM Required Limit The transaction amount above which a
CVM check is required.
Default value is 0.
The value must not be changed.
See Note:

FF69 Card application proprietary tag list This tag is a list of proprietary tags that
are retrieved if present in the card.
Length is less than or equal to 32 bytes.
See Note:

Note: This tag is only recognized and accepted on IDTech firmware

GR 2.0.

 Interac Specific Terminal Data Objects ‐ These tags are specific to

Interac.

Table 5-80
Interac Specific Terminal Data Objects

Tag Tag Name Description

9F58 Merchant Type Indicator Merchant Type Indicator that has five
possible values. Must be 03.

9F59 Terminal Transaction Information.

9F5A Terminal Transaction Type

DF2A Threshold Value for Random Selection

DF2B Maximum Target % for Random Selection

DF2C Target % for Random Selection

9F5D Terminal Contactless Receipt Required

Limit

9F5E Terminal Option Status Default value is E0 00

9F5F Terminal Contactless Floor Limit

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-239

Configuring Advance NDC and Associated Components
Configuring Readers

 IDTech Device Specific Data Objects ‐ These tags are specific to

the IDTech device and represent contactless parameters that do
not have any official payment systems tag value. Refer to the
IDTech manual for more information on these settings.

Table 5-81
IDTech Device Specific Data Objects

Tag Tag Name Description

DF51 ExpressPay Terminal Capabilities Used by the reader’s American Express

kernel to create the 9F6D tag. Default
value is 80.

FFF2 Terminal IFD Serial Number Unique and permanent serial number
assigned to the IFD by the manufacturer.
Configure as required.
If this tag is not defined, the Contactless
Enabler will use a part of the IDTech’s
Devices serial number to populate the
value.

FFF5 CVM Required Limit Used by the reader’s VISA kernel.

Indicates the amount at which a CVM
check is required.
For an SST this must be set to 0.
Do not change this setting.

FFFC PayPass Profile Used by the reader’s MasterCard kernel.

Can be used to force the transaction to be
performed in magnetic stripe emulation
mode.

FFFD Terminal Action Code (Online) Each issuer has its own recommended
setting for this item and so it must be
located within the AID section of the XML
configuration file.

FFFE Terminal Action Code (Default) Each issuer has its own recommended
setting for this item and so it must be
located within the AID section of the XML
configuration file.

FFFF Terminal Action Code (Denial) Each issuer has its own recommended
setting for this item and so it must be
located within the AID section of the XML
configuration file.

 IDTech Device Behavioural Data Objects ‐ These tags control

specific behaviour of the IDTech device. They must not be
changed from their default settings in the provided XML file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-240 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Table 5-82
IDTech Device Behavioural Data Objects

Tag Tag Name Default Value Description

DF63 Anti‐collision or 00 Defines device behaviour when multiple

Collision Detection cards are tapped at the same time.
Do not change.

DF64 Enable/Disable Visa 00 Disables support for these card types.

Wave Cards 00 ‐ Reject VISA Wave cards
01 ‐ Accept VISA Wave cards

DF65 Heartbeat Idle 00 Enables the reader device to expect a

heartbeat frame from the SST.
None Expected.

DF66 Unsupported Card 00 Changes the message displayed on the

behaviour reader device when an unsupported card is
tapped.

DF7C Auto‐Switch to 00 Auto‐switching is disabled.

Pass‐Through Mode

DF7D Track 1 and Track 2 Data 00 Disables the adding of the start/end
Format sentinels to the track data returned from
the reader.

DF7F Improved Collision 00 Disables improved collision detection.

Detection

FFF0 Specific Feature Switch 0E0000 Enables VISA’s VCPS 2.1.1/2.1.2 and
CVN17 processing.

FFF3 Application Capability 07FF Enables all the device’s payment system’s
kernels.

FFF7 Enable/Disable Burst 02 Configures the reader to automatically

Mode look for card taps or to only accept cards
when it receives a command.

FFF8 UI Scheme 03 Sets the User Interface scheme of the

reader.
Do not change.

XML File Format 5

All the configuration information for the Contactless Enabler is held

in an XML formatted file. The elements’ names within the XML file
are not case sensitive. For example TransactionIdentifiers is
considered the same as transactionidentifIERS.
The CONTACTLESSCONFIG element must be the first and highest level
element of the XML file. Where multiple CONTACTLESSCONFIG
elements are found, the first element is the one that is used and any
subsequent elements are ignored. The Tag elements are the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-241

Configuring Advance NDC and Associated Components
Configuring Readers

exceptions to this where if multiple tags exist within the same

element, the last value read will be the one which is used.
Where the same tags are listed in multiple different elements, the
tags used are the one from the highest element in the list below:
1 TransactionID

2 AID

3 DefaultTerminalTags

If the XML format is found to be invalid, then no transactions will

be possible until a valid file is supplied.
The schema, ContaclessEnabler.xsd defines the structure of the
configuration data as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-242 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Table 5-83
Contactless Enabler Schema
Elements Description Attributes Sub-elements

ContactlessConfig Mandatory. None Transaction

Identifiers,
This must be the root element of DefaultTerminal
the XML file that contains all other Tags,
Contactless Enabler elements. AID ,
This must be the first element ReaderUI
within the XML file. Configuration,
ATMOffline
Check,
Exclude
SentinelsFrom
TrackData,
Contactless
Trace
Transaction Mandatory. None TransactionID
Identifiers
This element is a container for
multiple transactionID elements.
This element can be empty.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-243

Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

TransactionID Optional. Name – This is a string Tag

that identifies each set of
This element is a container for transaction specific tags
multiple tag elements. contained within the
The tags contained in this apply to TransactionID element.
the selected transaction. When enabling the reader
Only the following tags are used for a transaction, the
by the device: application supplies this
 Amount Authorised (9F02) string to the Contactless
enabler. The name is case
 Transaction Currency Code
insensitive. The first
(5F2A)
match found is used.
 Terminal Country Code (9F1A) If the transaction
 Transaction Type (9C) identifier Name in the
Any other tags that are present in XML file contains
this section are ignored. wildcard characters “*” or
“?”, these would be
matched with the
Note: In Card Read State A and transaction identifier
Card Read ‐ PIN Entry Initiation supplied by the
State T, Advance NDC always uses application. Wildcard
Idle Tap as the transaction matching is supported by
identifier. using the “*” and “?”
<TransactionID Name = characters in the Name
"IDLE TAP"> field. A “*” will match
This element is a container for any number of characters
multiple TransactionID elements. from the application
This element is mandatory but can supplied transaction
be empty. identifier. A “?” will
In Insert Card State z008, the value match any single
of the operation code (OpCode) character from the
buffer is used as the transaction application supplied
identifier. For more information on transaction identifier. It is
the configuration of transaction recommended that an
identifier for insert card state, see application does not use
Transaction Identifier for Insert these characters in the
Card State explained above. transaction identifier it
supplies to the
Contactless Enabler.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-244 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

Reader Mandatory. Name ‐ This specifies the Tag

ProprietaryTags tag value and a
This element is a container for a mandatory element.
number of tag elements.
The tags contained in this element Length ‐ This specifies the
are any new proprietary tags that length of the tag data.
are not defined by EMVCo. Once a This element is optional
tag is defined in this section, the and can be an empty
contactless enabler recognizes the string (ʺʺ).
tag and stores in its dictionary.
This element can be empty. Format ‐ This specifies the
format of the tag so they
are converted in a human
readable string. This
element is optional and
can be an empty string
(ʺʺ). This tag is considered
as a binary formatted tag.

MaskExpression ‐ This
specifies the mask
expression. The allowed
values are:
 b for binary
 n for numeric
This element is optional
and can be an empty
string (ʺʺ). This tag is
considered as a Binary
formatted tag.
For more information
about the Mask
Expression, See ʺMask
Expressionʺ, on page
5‐254.

Source ‐ This specifies the

origin of the tag. The
allowed values for this
attribute are:
 ICC for card based
tags
 Terminal for terminal
based tags

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-245

Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

This element is optional

and can be an empty
string (ʺʺ). This tag is
considered as a terminal
based tag.

Description ‐ This
specifies the description
of the tag and this value is
used in the enabler trace.
This element is optional
and can be an empty
string (ʺʺ).

DefaultTerminal Mandatory. None Tag

Tags DeviceVariant
This element is a container for
multiple tag elements.
The tags contained in this element
apply to the terminal and are not
dependent on either the
transaction or the application that
has been selected.
This element can be empty.

DeviceVariant Optional Name ‐ This is a string Tag,

that identifies the device AID
This element is a container for any variant or firmware.
tag or AID elements which are Kiosk2 should be used for
specific to a device variant or its the tags or AIDs
firmware version. specifically for the Kiosk
It can be used around any of the II device.
tag elements present within the Kiosk3 should be used for
DefaultTerminalTags and the tags or AIDs
around any of the AID elements. specifically for the Kiosk
If required, this element can III device.
appear multiple times. Additionally, to specify
If multiple DeviceVariants are the firmware version, an
applied that contain the same tags underscore “_” should be
or AIDs values, then the tags or added to the Kiosk2 or
AIDs values of the last applicable Kiosk3 followed by the
DeviceVariants will be used. last 3 digits of the
For more information about the required firmware.
Device Variant, See ʺDevice For more information
Variants and Firmware Versionsʺ, about the Device Variant,
on page 5‐255. See ʺDevice Variants and
Firmware Versionsʺ, on
page 5‐255.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-246 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

AID This defines the Application Value – This is the None

Identifier of an Application to be Application Identifier
accepted by the reader. There can (AID) of the application,
be multiple AID elements within encoded as ASCII
the XML, one for each supported hexadecimal,
AID. for example
There must be at least one valid “A0000000031010”.
element of this type present in the Values containing non
XML file, otherwise it is hexadecimal characters or
considered invalid. that do not have an even
length is ignored and not
sent to the device.
KernelID – This is the
EMVCo kernel identifier
associated with the
application. The IDTech
device currently does not
support this. It can be set
to “”.
AIDTagGroup – This is a
number in the range of 1
to 7 that identifies set of
tags associated with the
current AID. The tags are
defined under the
separate AIDGroupTags
element.

AIDTagGroup This element is a container for Value ‐ This is an Tag,

multiple tag elements related to identifier for the set of AdditionalHost
one or more AIDs. tags and is a number in Objects
The element may contain one or the range of 1 to 7.
more Tag elements. The tags This value is used by the
within this element relate to the AID element to identify
specific application (AID) and are which set of tags relate to
only used if that application has that AID.
been selected by the reader. Values outside this range
This element is optional. are ignored.

AdditionalHost This element is a container for None Tag

Objects multiple tag elements.
The tag names listed in this section
are included in the EMV data
returned by the contactless enabler
if they are returned by the device.
Only the name Attribute and no
element value are required for the
tags contained in this section.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-247

Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

Tag This defines a Tag and its value. Name – This is the tag None
The tag id is encoded in the Name identifier encoded as
attribute and the elements value ASCII hexadecimal for
field is the tag’s value. example “9F02”.
Names containing non
hexadecimal characters or
that do not have an even
length are ignored and
not sent to the device.

ReaderUI This element is a container for None Beep, LED

Configuration elements controlling the reader’s
user interface settings.

Beep The value contained in this None None

element controls the audio
feedback settings. Audio feedback
is provided when the reading of
the contactless card has completed.
 0 means no audio feedback
 1 means use the reader’s audio
feedback (default)
 2 means the Contactless
Enabler provides the audio
feedback and the reader’s
audio feedback is disabled.
This option is currently not
supported.

This setting applies to IDTech

device types only.
See Note 1:

LED The value contained in this None None

element controls the visual
feedback settings. The device has
multiple LEDs that are based on
how the reader is integrated into
the SST. This device may or may
not be visible to the cardholder.
 0 means no visual feedback
(default)
 1 means use the reader’s visual
feedback

This setting applies to IDTech

device types only.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-248 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

EnhancedForm This value controls the return of None None

FactorReporting two additional formfactor values:
the tablet_FormFactor and the
smartwatch_FormFactor by the
contactless enabler. Valid values
are as follows:
 0 (default) ‐ It does not return
the above two new formfactors
but return the best possible
match from the existing set of
the formfactors (for backward
compatibility).
 1 ‐ It returns the above two new
formfactors based on the
device being tapped.

EnableMedia This value controls the readerʹs None None

StatusEvents functionality to send out card
arrival and removal events to the
application.
 A zero value indicates card
arrival and removal events are
disabled.
 A non‐zero value indicates that
the reader sends card arrival
and removal events.
The default XML file has this
enabled.
When this is disabled, the
contactless enabler does not
generate any card arrival or
removal events.
Additionally, it always report an
unknown_MediaStatus for the
mediaStatusOnError field of the
ClessError structure.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-249

Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

CardTapWait Optional None None

Timer
This element controls the internal
timer used by the contactless
enabler when waiting for a card to
be tapped.
The reader is given this amount of
time to wait for a card. If no card is
detected, the reader responds after
this time and the contactless
enabler again re‐enables the reader
for this time. This is repeated until
the application wait time is
reached. The reader returns the
result of a card tap, when the
reader returns an error or an
application cancel request is
received.
The units are in seconds and the
valid range is from 150 to 255.
If this is not present or if it contains
an invalid value, then an internal
timeout value of 150 seconds is
used.
No behavioural differences are
seen by altering this value apart
from the time taken to report the
error caused by a reader that has
stopped responding to the
commands.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-250 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

SuppressEMVData Optional None None

OnMSD
This value controls if the
contactless EMV enabler
suppresses the EMV data that are
sent to the application on the MSD
profile transactions.
This option is introduced for the
customers who prefer no host
impact when implementing the
contactless MSD transactions.
 A non‐zero value results in the
contactless enabler
suppressing the EMV data
provided to the application.
Only Track data are sent.
 A zero value results in the
contactless enabler including
the EMV data.
The default XML file has this value
set to 0.
If this element is not present in the
XML file, the contactless enabler
includes the EMV data by default.

ATMOfflineCheck Identifies if the Contactless EMV None None

Enabler should perform a VISA
and SST specific check on the
results received from the reader.
The contactless transaction may be
declined and you can use another
interface (contact card reader) to
perform the transaction.

Valid values are as follows:

0 ‐ no ATM offline Check

1 ‐ perform ATM offline check
(default, if value is not present)

However, the value in the default

XML file that is provided is set to
0.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-251

Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

Exclude Optional None None

Sentinels
FromTrackData Identifies the inclusion or
exclusion of start and end sentinels
from the track data returned by the
enabler.

Valid values are as follows:

0 ‐ Includes the sentinels in the

track data.
Non‐zero value ‐ Excludes the
sentinels from the track data
returned by the Contactless
Enabler.

By default, this element is not

present in the XML file. The
default behaviour of the
Contactless Enabler when this
element is not present in the XML
file is to include the sentinels in the
track data.

Contactless Optional. None TraceLevel,

Trace TraceFileName,
This element is a container for TraceFileSize,
trace setting elements. TraceMaxFiles,
TraceHeader
The sub‐elements can be used for
the Tracing function calls to enable
and configure the required
logging.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-252 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

TraceLevel Optional. None None

Controls the trace level of the

Contactless enabler.

Valid values are as follows:

0 ‐ No tracing
1 ‐ Performance trace (Only
performance info is traced)
2 ‐ Error trace (Only peformance
information and unexpected
events that cancel a process are
traced)
3 ‐ Warning trace (Only
performance and unexpected
events are traced)
4 ‐ Debug trace (Normal level of
trace for debugging the
Contactless Enabler)
5 ‐ Deep trace (Lowest level of
traces for unitary tests)

See Note 2:

TraceFileName Optional. Name ‐ This is a string None

which identifies the file
Contains the trace file name. name for the kernel log
file

TraceFileSize Optional. None None

The maximum trace file size in

mega‐bytes when using circular
log files.

For this setting to take effect, the

TraceMaxFiles element must
also be present

TraceMaxFiles Optional. None None

The maximum number of trace

files when using circular log files.

For this setting to take effect the

TraceFileSize element must
also be present.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-253

Configuring Advance NDC and Associated Components
Configuring Readers

Elements Description Attributes Sub-elements

TraceHeader Optional None None

The elements of the header you to

include in each trace log entry.

The individual header field values

can be found in the
HeaderField_ClessTrace
enumeration of the ITrace.h
interface file. To select multiple
header elements, add all the
individual header fields values
and place the result in this
element.

Inadvertent Tap Optional None WidthSwitchTimer,

EnablerDelayTimer,
This element is a container for a OutcomeOnNoCard
multiple tag elements related to Insert
avoiding the inadvertent tap. For See Note 1:
information about the inadvertent
tap elements, See “Avoid
Inadvertent Tap” on page 5‐257.

Note 1: The SST must be rebooted after changing value of the Beep,
widthSwitchTimer and/or EnableDelayTimerelement to reflect
the change at the driver level when the XFS mode is enabled
through the EnableXFSSessionForContactless registry setting.
For information on the EnableXFSSessionForContactless
registry values, see “Configuring Contactless Card Reader Device
Mode” on page 5‐215.

Note 2: The Trace Level value must match with value of the
Contactless Trace Level registry. For information on the Contactless
Trace Level registry values, see “Contactless Trace Level Values” on
page 5‐227.

Mask Expression 5

The following table gives the examples of mask expressions for the
existing tags:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-254 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Table 5-84
Examples of Mask Expression

Tag Name Length Converter Name Mask Format ID

9F40 Additional Terminal 5 Binary b binary_Format

Capabilities

81 Amount Authorised 4 BinaryNum b binary_Format

9F02 Amount Authorised 6 Numeric n12 numeric_Format

50 Application Label 1‐16 AlphaNumeric a1‐16 alphanumeric_Format

5A Application Primary ‐10 CompressedNum c‐19 compressedNumeric_

Account Number Format
(PAN)

A5 File Control null Binary null constructed_Format

Information (FCI)
Proprietary Template

97 Transaction ‐252 Binary b constructed_Format

Certificate Data
Object List (TDOL)

9F7F Card Production Life 42 Binary b binary_Format

Cycle (CPLC) History
File Identifier

9F53 Transaction Category 1 AlphaNumeric a1 alphanumeric_Format

Code

Device Variants and Firmware Versions 5

The DeviceVariant element in the ContaclessEnabler.xsd identifies

values that are only used on a specific device variant and/or
firmware version. It can be used around the tag elements appearing
within the DefaultTerminalTags section and around the AID
elements.
When the DeviceVariant element is used with a Kiosk II reader, if
a tag or AID element is contained within the DeviceVariant
element and the DeviceVariant Name attribute is Kiosk 2, then the
contactless EMV enabler only uses the tag or AID data.
Similarly, when the DeviceVariant element is used with a Kiosk III
reader, if a tag or AID element is contained within the
DeviceVariant element and the DeviceVariant Name attribute is
Kiosk 3, then the contactless EMV enabler only uses the tag or AID
data.
To check the firmware version, the DeviceVariant Name attribute
can be extended with an underscore character ʹ_ʹ and then by the
last three characters of the required firmware version.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-255

Configuring Advance NDC and Associated Components
Configuring Readers

For example, Kiosk3_113 or Kiosk2_C49.

The tag or AID is only used, if both devices variant matches and the
firmware version is the same or greater than the firmware defined
in the Name attribute.
To support the v1.20 Kiosk III firmware version, the Kiosk3_20
header must be used followed by the firmware version of the v1.20.
If 20 is not present then Kiosk III v1.10 firmware is assumed. For
example Kiosk3_140 relates to Kiosk III v1.10.140 firmware but
Kiosk3_20.074 relates to Kiosk III v1.20.074 firmware.
When current device meets multiple DeviceVariants that contain
the same tags, then the tags from the last matching DeviceVariant
are used.
The following XML shows the four different AID elements.

Figure 5-74
AID Elements for Device Variant
XML File Example
<DeviceVariant Name = "Kiosk2"> <!-- Applicable for all Kiosk II readers -->
<AID Value = "A0000000043060" kernelID="02" AIDTagGroup = "3"> </AID> <!-- MasterCard
Maestro -->
<AID Value = "A0000000046000" kernelID="02" AIDTagGroup = "3" SystemAID = "false"> </AID>
<!-- MasterCard Cirrus -->
</DeviceVariant>

<DeviceVariant Name = "Kiosk3"> <!-- Applicable for all Kiosk III readers -->
<AID Value = "A0000000043060" kernelID="02" AIDTagGroup = "3"> <Tag
Name="FFE9">020003029303020103</Tag> </AID> <!-- MasterCard Maestro -->
<AID Value = "A0000000046000" kernelID="02" AIDTagGroup = "3" SystemAID = "false"> <Tag
Name="FFE9">020003029303020103</Tag> </AID> <!-- MasterCard Cirrus -->
</DeviceVariant>

<DeviceVariant Name = "Kiosk3_113"> <!-- Applicable for all Kiosk III readers with firmwares
Neo #113 and above -->
<AID Value = "A0000000043060" kernelID="02" AIDTagGroup = "3"> <Tag
Name="FFE9">020003029303020103</Tag> </AID> <!-- MasterCard Maestro -->
<AID Value = "A0000000046000" kernelID="02" AIDTagGroup = "3" SystemAID = "true"> <Tag
Name="FFE9">020003029303020103</Tag> </AID> <!-- MasterCard Cirrus -->
</DeviceVariant>

<DeviceVariant Name = "Kiosk3_20.074">

<AID Value = "A0000000046000" kernelID="02" AIDTagGroup = "3">
<Tag Name="FFE9">020003029303020103</Tag>
</AID>
</DeviceVariant>

Note: The first AID group only applies if the device is a Kiosk II
device. The second AID group applies to all the Kiosk III devices,

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-256 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

except, if the Kiosk III device contains firmware version 113 or

above. The following third DeviceVariant section overwrites the
values as the third group contains the same AID as the second
group. The third AID group is only applicable to the Kiosk III when
firmware version is 113 or greater. The fourth AID group only
applies to the Kiosk III Neo v1.20 when firmware is 074 or greater.

Avoid Inadvertent Tap 5

When a dual interface card (used for both contact and contactless
transaction) is inserted in a contact card reader, there are chances
that the contactless card read could also be triggered inadvertently.
This happens when the contact and contactless card readers are in
close proximity.
The application detects such scenarios and continues the transaction
without impacting the flow. The application assumes the
cardholderʹs intention of carrying out a contact transaction even
when the card insertion is followed immediately by a card tap
(inadvertent tap).
The early detection in the contact card reader can be configured
using the EnableCardDetectEvent (DWORD) XFS registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\NCR\APTRA Self-Service Support

(NCR Features)\USBIMCRW\Operational Parameters\

Valid values are as follows:

 0 = disabled (default)
 1 = enabled
Along with the above registry setting, the processing is enabled by
the inadvertent tap elements in the ContactlessEnabler.xml
configuration file as described below:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-257

Configuring Advance NDC and Associated Components
Configuring Readers

Table 5-85
Inadvertent Tap Elements

Element Name Description

WidthSwitchTimer Defines the time in milliseconds. It is the time to wait after a contactless card tap, to
detect the insertion of a card at the contact card reader. The value 0 (default) indicates
that processing of the inadvertent tap is not enabled. The suggested value for
WidthSwitchTimer is 1400.

EnableDelayTimer Defines the time in milliseconds. The timer delays the contactless tap outcome that
enables the application to detect the card insert event following a tap. After the card
read is successful, the application disables the timer and the transaction proceeds to
the next state.
If the card read is not successful within the specified time, the transaction flow will be
as defined in the xml element OutcomeOnNoCardInsert. The suggested value for
EnableDelayTimer is 4000.

OutcomeOnNo This is the result returned by the enabler if the application initially receives a card
CardInsert inserted event followed by an unsuccessful card read. There are two valid strings:
EndApplication ‐ This will end the card holder session (default). This value is used
if the entry does not match either of the two valid strings.
TryAgain ‐ The application will re‐enable the cardholder session by enabling both
the contact and contactless readers to initiate the transaction.

Note:

 The Contactless EMV Enabler’s Inadvertent tap avoidance

processing requires USB Integrated Motorised Card Reader
Writer component version 02.09.00. This was initially released as
part of the NCR APTRA XFS version 06.05.00.
 If this functionality is enabled, even when a contactless
transaction is performed, the cardholder has to wait for the time
defined in the widthSwitchTimer element to proceed further.
However, issues with the application can arise if the user
configures widthSwitchTimer and EnableDelayTimer values
less than the suggested values.

Simple XML File Example 5

The following example is only intended to show the format and

structure of the XML file. The entries it contains have been
simplified. A fuller default XML file is supplied with the APTRA
Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-258 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

Figure 5-75
Simple XML File Example
<?xml version="1.0" encoding="iso-8859-1"?>
<CONTACTLESSCONFIG>
<TransactionIdentifiers>
<TransactionID Name = "IDLE TAP">
<Tag Name = "9F02">000000000000</Tag> <!-- Amount, Authorized (Numeric)-->
</TransactionID>
<TransactionID Name = "AD ">
<Tag Name = "9C">01</Tag> <!-- Transaction Type-->
<Tag Name = "5F2A">978</Tag> <!-- Transaction Currency Code-->
</TransactionID>
</TransactionIdentifiers>
<DefaultTerminalTags>
<!-- List of ALL the applicable Terminal Tags-->
<Tag Name = "5F2A">840</Tag> <!-- Transaction Currency Code USD-->
<Tag Name = "5F36">02</Tag> <!-- Transaction Currency Exponent-->
<Tag Name = "9F02">100</Tag><!-- Amount, Authorized (Numeric)-->
<Tag Name = "9F03">0</Tag><!-- Amount, Other (Numeric)-->
<Tag Name = "9F09">0002</Tag><!-- Application Version Number (PayPass M/Chip)-->
<Tag Name = "9F1A">840</Tag><!-- Terminal Country Code-->
<Tag Name = "9F1B">0000</Tag><!-- Terminal Floor Limit-->
<Tag Name = "9F33">604000</Tag><!-- Terminal Capabilities-->
<Tag Name = "9F35">14</Tag><!-- Terminal Type-->
<Tag Name = "9F40">E800B053FF</Tag><!-- Additional Terminal Capabilities-->
<Tag Name = "9F53">Z</Tag><!--
-->
<Tag Name = "9F5F">8000</Tag><!-- Terminal Contactless Floor Limit-->
</DefaultTerminalTags>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-259

Configuring Advance NDC and Associated Components
Configuring Readers

<!-- List of ALL the AIDS -->

<AID Value = "A0000000031010" KernelID = “02” AIDTagGroup = "1" ></AID>
<AID Value = "A0000000032010" KernelID = “02” AIDTagGroup = "1" ></AID>
<AID Value = "A0000000041010" KernelID = “03” AIDTagGroup = "2" ></AID>
<AIDTagGroup Value="1">
<Tag Name = "9F66">B6804000</Tag> <!-- Visa Terminal Transaction Qualifier (TTQ)-->
<Tag Name = "9C">01</Tag> <!-- Transaction Type for IDLE TAP-->
</AIDTagGroup>

<AIDTagGroup Value="2">
<Tag Name = "FFFC">01</Tag> <!-- PayPass Profile - Force Magstripe Transaction-->
<Tag Name = "9C">93</Tag> <!-- Transaction Type for IDLE TAP-->

</ AIDTagGroup >

<ReaderUIConfiguration>
<Beep>1</Beep> <!-- 0 = No Buzzer also enabler does not beep, 1 = Use Reader Buzzer
only, 2 = Use Enabler Buzzer -->
<LED>0</LED> <!-- 0 = No LEDs, 1 = Use Reader LEDs -->
</ReaderUIConfiguration>
<InadvertentTap>
<!-- The time to wait, following a contactless card tap, to detect the insertion of a
card at the contact card readers width switch-->

<WidthSwitchTimer>0</WidthSwitchTimer> <!--Timer unit : MilliSeconds -->

<!--Following a width switch event the Enabler will wait for this timer for an
application cancel request. If a cancel is not received withing this time, the outcome
value defined in the “OutcomeOnNoCardInsert” element below will be returned by the
Enabler -->

<EnablerDelayTimer>0</EnablerDelayTimer><!--Timer unit : MilliSeconds -->

<!-- This is the outcome returned by Enabler if application does not cancel a
contactless tap after receiving a card inserted event,
String values allowed here are “EndApplication” & “TryAgain” only -->

<OutcomeOnNoCardInsert> “EndApplication”</OutcomeOnNoCardInsert>
</InadvertentTap>
</CONTACTLESSCONFIG>

The above sample shows how the transaction type, tag 9C, can be
configured as a fixed value during an IDLE TAP. The transaction type
is defined within the AID elements, allowing different payment
systems to be provided with different fixed values. The transaction
type is not defined within the IDLE TAP element itself.
However, if the tap occurs when the transaction type is known, the
application can supply one of the non‐IDLE TAP transaction

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-260 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

identifiers. In this case the transaction type in the transactionId

element is used in place of the value in the AID element due to the
Transaction Identifiers higher precedence.
This also shows that the transaction currency is 840 or USD
Currency Code for all transactions by default, unless the
transactionID CASH WITHDRAWAL IN EUROS is chosen by the
application. In this case, the 978 or EURO currency code defined in
the transaction identifier element takes precedence over the USD
code defined in the DefaultTerminalTags element.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-261

Configuring Advance NDC and Associated Components
Configuring Readers

In an SST which has a smart dip card reader with a hybrid card
Smart Delay Timer for environment where the majority of card holders use the magnetic
Smart Dip Card Reader 5
cards, the process of latching the magnetic cards can be eliminated.
Latching is required only for smart cards, and can be latched after
the smart delay timer expires.
The smart delay functionality can be configured in the T State (Card
Read ‐ PIN Entry Initiation State) and z008 State (Insert Card State).
The card reader must be a DASH (Dip and Smart Hardware) card
reader and the chip connect bit must be set with one read condition
to 008.
When the card holder inserts a card in a DASH Card reader,
SmartDelayTimer starts and the following conditions determine
whether or not to latch the card:
 If the card holder removes the card before the timer expires,
then the timer is cancelled and the card is treated as a magnetic
card and the tracks are read.
 If the card holder keeps the card until the timer expires, then the
card is latched and the ATR (Answer to Reset) data from the
card is read.
The time delay can be configurable using the registry value
SmartDelayTimer under the following registry key:
HKLM\SOFTWARE\NCR\Advance NDC\DASH

The registry setting for SmartDelayTimer can be configured as

shown in the following table:

Table 5-86
Smart Delay Timer Registry Entry for EMV
Dip Card Readers

Value Name Type Values Default Value Description

SmartDelayTimer DWORD Numeric 10  The default value is 1 second (value

10 is 1 second).
 If the value is empty then the time
delay is 0.
 If the value configured is more than
10, then the time delay will be the
configured value. For example, if the
value used is 15, then the time delay
will ne 1.5 seconds.

ReadRawDataTime DWORD Numeric 20 The time required to read the data from
Out the card. This time starts after the
SmartDelayTimer expires.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-262 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Readers

If the card reader is not a DASH card reader or if the chip connect
bit not set (no read condition is 008), then the SST treats the inserted
card as magnetic, and reads the magnetic tracks only.

USB and RS232 DASH Card Readers 5

When a USB or an RS232 DASH card readers are used, the ACCEPT
IGNORE FRONT SENSOR key value must be set to 1 under the
following registry keys:
 USB DASH Card Readers ‐ HKLM\SOFTWARE\NCR\APTRA
Self-Service Support (NCR Features)\UsbSmartDip
CardReader\Operational Parameters\MCRW-01-UsbSmart
DipReader\Device
 RS232 DASH Card Readers ‐ HKEY_LOCAL_MACHINE\SOFTWARE\
NCR\APTRA Self-Service Support (NCR Features)\
RS232DASHCardReader\Operational Parameters

For information on T State, z008 State and smart dip card readers for
EMV processing, refer to chapter 2, “State Tables” of the APTRA
Advance NDC Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-263

Configuring Advance NDC and Associated Components
Configuring Coin Dispensers

Configuring Coin Dispensers 5

A coin mapping table held in the registry of the SST is used to map
the cash units to the Advance NDC coin hopper types. On NCR
SSTs, the mappings between the physical hoppers, the cash units
and the Advance NDC hopper types are automatically set up.
Therefore, no additional operator configuration is needed after the
initial installation of Advance NDC, nor any reconfiguration after
replenishment. Advance NDC applies a one‐to‐one mapping of
hopper type to cash unit.

Note: If either the CDM SP or the coin mapping table is changed

from the default, errors will occur or incorrect coins will be
dispensed. This will be obvious from testing, or the errors
generated.

The coin dispenser does not maintain a record of the number of

coins dispensed. This means that if a power failure occurs during a
coin dispense, the counts will be incorrect.

Registry entries for coins are held under the following eight registry
Registry Keys for the Coin keys:
Dispenser 5

HKLM\SOFTWARE\NCR\Advance NDC\CoinTable\NDCHopperType<x>

The variable <x> in NDCHopperType<x> is a number from 1 to 8 to

identify the hopper type.

The currency dispensed by a hopper is set using the CurrencyID

Setting the Currency 5

registry entry. The default setting for the currency is USD for
American dollars.

Note: The CurrencyID value must be a valid ISO currency code as

defined by ISO 4217.

The value of the coins dispensed by a hopper is set using the Value
Setting the Coin Value 5

registry entry: Advance NDC provides eight entries, one for each
hopper type, set by default as follows:

Table 5-87 Type Default Coin Value Default Value in the Default Currency
Default Hopper Values
1 10 10 cents

2 20 20 cents

3 50 50 cents

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-264 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Coin Dispensers

Type Default Coin Value Default Value in the Default Currency

4 100 1 dollar

5 10 10 cents

6 20 20 cents

7 50 50 cents

8 100 1 dollar

You can set low thresholds for the number of coins in a hopper. The
Setting the Low Threshold for registry entry LowCoinsThreshold defines the threshold for coins
Coins 5
remaining in a hopper before they are reported as low. Advance
NDC provides eight entries, one for each hopper type, set by default
to 30.

Caution: Allowing the coin dispenser to become too low can cause jams as
the coins are dispensed using gravity only.

Supplies and severity information is updated to reflect the known

Supplies and Severity state of the coin dispenser as described in the following table:
Information 5

Table 5-88
Supplies and Severity

Point at which update occurs... Cassette Status Severity Reported As... Supplies Reported As...

Start of Day Good Good Sufficient Coins

Low Good Coins Low

Empty Good Coins Low

Missing Good No new state

Supervisor Exit Good Good Sufficient Coins

Low Good Coins Low

Empty Good Coins Low

Missing Good No new state

Following a CHECK COIN Good Good Sufficient Coins

operation
Low Good Coins Low

Empty Fatal Out of Coins

Missing Good No new state

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-265

Configuring Advance NDC and Associated Components
Configuring Coin Dispensers

Point at which update occurs... Cassette Status Severity Reported As... Supplies Reported As...

Following a coin dispensing Good Good Sufficient Coins

transaction, status information
is updated only for hoppers Low Good Coins Low
used in the transaction Empty Fatal Out of Coins

Missing Fatal Out of Coins

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-266 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Configuring Cash Handlers 5

A currency cassette mapping table held in the registry of the SST is

used to map the XFS logical cassette units to the Advance NDC
cassette types. On NCR SSTs, the mappings between the physical
cassette units, the XFS logical cassette units and the Advance NDC
cassette types are automatically set up. Therefore, no additional
operator configuration is needed after the initial installation of
Advance NDC, nor any reconfiguration after replenishment, unless
you are using one of the following:
 A recycling unit in any capacity, including as part of a dual cash
handler setup. If a recycling unit is used, all settings used must
conform to the stricter requirements of a recycling unit
 A cash handler with a fifth physical cassette. If a fifth physical
cassette is used, you must update the registry entry for this
cassette as described in “Cash Handler with a Fifth Physical
Cassette” on page 5‐280. The journaling of tamper indications
for the fifth cassette is supported. Also, the tamper indication
messaging and logging to the journal for the fifth cassette is
supported when the Enhanced TI/Sensor Status unsolicited
message is enabled.
 Gasper. For information on requirements required for Gasper,
refer to the Gasper documentation.

Note: If either the CDM SP or the currency cassette mapping table

is changed from the default, errors will occur or incorrect notes will
be dispensed unless both are changed to matching valid values.
Any inconsistencies will be obvious from testing, or the errors
generated. The default values are stored in AdvanceNDC.reg in the
DLL directory and theANDCSST.xml file in the Config directory.

The cash handler can also be configured using the Extended Add
Cash option in Supervisor. This option is offered, in particular, for
mixed NCR and other vendor networks. For details of configuring
the Extended Add Cash option, see “Extended Add Cash Option”
on page 5‐103.

The currency used by each cassette type is set using the following
Setting the Currency 5

registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\CurrencyTable\NDCTypex\
CurrencyID

Each cassette type must be defined using the x in NDCTypex to

identify the cassette type.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-267

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

The value is the Currency ID using ISO 4217 alphabetic currency

codes, for example EUR for euro or GBP for sterling.

The kind of cassette in use is set using the following registry entry:
Setting the Media Type 5

HKLM\SOFTWARE\NCR\Advance NDC\CurrencyTable\NDCTypex\
MediaType

Each cassette type must be defined using the x in NDCTypex to

identify the cassette type.
The content of this setting is the CEN‐XFS media type. For a
recycling unit, this must be set to one of the following:
 3 (WFS_CDM_TYPEBILLCASSETTE)
 12 (WFS_CDM_TYPERECYCLING).
For details of the media types, refer to the APTRA on‐line
documentation for usType, under APTRA XFS | Programmers
Reference | XFS Service Providers.

The value of the notes used by each cassette is set using the
Setting the Denomination 5

following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\CurrencyTable\NDCTypex\
Value

Each cassette type must be defined using the x in NDCTypex to

identify the cassette type.

Each cassette can optionally be uniquely identified to allow a

Setting the Cassette denomination to be mapped to multiple cassettes. The identifier is
Identifier 5
set using the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\CurrencyTable\NDCTypex\
UnitID

Each UnitID must be a unique string. For example, on NCR SSTs

the cassettes are identified using numbers in the range 1 to 7.

The position of each cassette can be defined using options on the

Setting the Cash Unit Extended Add Cash menu, as described in Chapter 3, “Configure
Identifiers for Supervisor 5
Menu” of the APTRA Advance NDC, Supervisor’s Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-268 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

The screens used to set the cassette mapping are as follows:

Table 5-89
Cash Unit Identifiers in Supervisor Screens

Screen Description

Update SP Cash Unit ID This is displayed during the sequence of screens for the Configure Cash
Units option
The SP cash unit identifiers are mapped to the physical cassette identifiers
defined in the CEN‐XFS cUnitID field
For further information on the cUnitID field, refer to the APTRA online
documentation under APTRA XFS | Programmer’s Reference | XFS
Service Providers | XFS GBRU‐GBNA Service Provider | Application
Guidelines

Update Cash Unit ID This is displayed during the sequence of screens for the Update Note
Types option
The cash unit identifier s are mapped to the NDC cassette type defined in
the UnitID registry entry
For further information on the UnitID registry entry, see “Setting the
Cassette Identifier” on page 5‐268

The cash unit identifiers used in these screens are defined using the
following registry entries:
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\CashUnitIDs\1
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\CashUnitIDs\2
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\CashUnitIDs\3
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\CashUnitIDs\4
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\CashUnitIDs\5
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\CashUnitIDs\6
HKLM\SOFTWARE\NCR\Advance NDC\Supervisor\CashUnitIDs\7

Each cassette type must be defined to identify the cassette type

displayed on the Supervisor screens. By default, the cassettes are
identified using numbers in the range 1 to 7.

By default, if a cash dispenser cassette has an XFS status of

Cash Dispenser Cassette STATCUMANIP or STATCUNOVAL, the status of the cassette is
Status 5
automatically cleared using the XFS exchange operation (Start
Exchange/End Exchange). Any cassette with a status of
STATCUMANIP or STATCUNOVAL is reported through the fault display
and terminal commands. XFS exchange also sets the cassette
thresholds; for more information, see “Setting Note Thresholds” on
page 5‐281.
The execution of XFS exchange is controlled by the following
registry entry:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance
NDC\CashHandler\EnableManualExchange

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-269

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Valid values are as follows:

0 = Start XFS exchange automatically (the default).
1 = Start XFS exchange manually.

If the registry entry contains an invalid value (anything other than 0

or 1), the default behaviour occurs. On other vendors’ SSTs, the
default configuration may be different. For details refer to Chapter
6, “Advance NDC on Specific Vendors’ SSTs” of the APTRA
Advance NDC Multi‐Vendor Support Reference Manual.

Automatic XFS Exchange 5

When automatic XFS exchange is enabled (EnableManualExchange

= 0), XFS exchange is performed to clear the status of cash dispenser
cassettes as follows:
 At start of day regardless of the cassette status. This also sets the
threshold values, using the LowBillsThreshold for each NDC
cassette type and the MaxBillsThreshold for the reject bin
configured under the registry key
HKLM\SOFTWARE\NCR\Advance NDC\CurrencyTable.
 Whenever a cassette with an XFS status of STATCUMANIP or
STATCUNOVAL is inserted in the SST.
 When Add Cash or Standard Cash on the Supervisor Replenish
menu is selected.
 When Add Cash on the Supervisor Configure/Extended Add
Cash menu is selected.

Manual XFS Exchange 5

If manual XFS exchange is enabled (EnableManualExchange = 1), XFS

exchange is performed to clear the status of cash dispenser cassettes
as follows:
 When Add Cash, Standard Cash or Test Cash on the Supervisor
Replenish menu is selected.
 When Add Cash or Test Cash on the Supervisor Configure/
Extended Add Cash menu is selected.
 At start of day only if none of the cassettes has an XFS status of
STATCUMANIP or STATCUNOVAL; this allows the cassette
thresholds to be set at start of day.

Note: The cassette threshold values are also set during the
Supervisor functions.

Cassette Status Reporting During Manual Exchange If the 5

replenished cassette has an XFS status of STATCUMANIP or

STATCUNOVAL, the following is performed:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-270 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

 The cassette is disabled for dispensing until one of the

Supervisor cash functions is executed successfully.
 A Fatal severity (4) is reported in response to a Get Fitness
terminal command.
 An error message is reported on the fault display as shown in
the following example for the topmost cassette:

Table 5‐90 Top Cassette Status Fault Display Message

Fault DIsplay for the Top Cassette
STATCUMANIP TOP CASS MANIPULATED

STATCUNOVAL TOP CASS VALS ERR

XFS Exchange and Cassette Information 5

If the optional Cassette Information screen is displayed at the start

of the cash handling functions in Supervisor, XFS Exchange is not
executed if the operator presses the Cancel key.
If the Cassette Information screen is displayed while automatic XFS
exchange is enabled and the operator presses Enter, XFS exchange is
executed in Add Cash and Standard Cash only, not in Test Cash.
If the Cassette Information screen is displayed while manual XFS
exchange is enabled and the operator presses Enter, XFS exchange is
executed in Add Cash, Standard Cash and Test Cash.

On the Replenish menu in Supervisor, the Add Cash, Standard Cash

Cassette Information and Test Cash functions can each display a screen and journal
Screen 5
before and after the operation giving detailed cassette information
as reported by the dispenser. This allows the operator to verify that
the cassette information returned by the dispenser corresponds to
the physical cassette details before proceeding to execute the
function and also after the task is executed.
By default, this screen is not displayed in Advance NDC but can be
configured for display by editing the
ShowCassetteInformationScreen property in the
AdvanceNDCCustom.accfg file, as described in the next three
subsections.
By default, this screen is journaled before the replenishment tasks
and can be configured to journal after the replenishment tasks by
editing the JournalCassetteInformation property in the
AdvanceNDCCustom.accfg file, as described in the next three
subsections.
Note 1: The Cassette Information screen does not support dual
dispensers. Only the details of the cassettes for the primary cash
handler are displayed on screen.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-271

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Note 2: For a cash recycling unit, option 54, Initialise BNA, on the
Replenish menu, or exiting Supervisor mode clears the status of the
recycling cassettes without displaying the Cassette Information
screen.

Add Cash 5

To display and journal the cassette information before and after

Add Cash, the properties of
BeforeAddCashCDMCassetteReportTasks and
AfterAddCashCDMCassetteReportTasks should be updated as
follows:
 To display, set the ShowCassetteInformationScreen property
to True.
 To journal, set the JournalCassetteInformation property to
True.

Figure 5-76
Example Add Cash Extract
<Class ID="BeforeAddCashCDMCassetteReportTasks"
Name="NCR.APTRA.NDC.CDMCassetteReportTasks.CDMCassetteReportTasks"
Assembly="NCR.APTRA.NDC.CDMCassetteReportTasks.dll">
<Interface>
<Property Name="ShowCassetteInformationScreen" Value="True"/>
<Property Name="JournalCassetteInformation" Value="True"/>
</Interface>
</Class>
<Class ID="AfterAddCashCDMCassetteReportTasks"
Name="NCR.APTRA.NDC.CDMCassetteReportTasks.CDMCassetteReportTasks"
Assembly="NCR.APTRA.NDC.CDMCassetteReportTasks.dll">
<Interface>
<Property Name="ShowCassetteInformationScreen" Value="True"/>
<Property Name="JournalCassetteInformation" Value="True"/>
</Interface>
</Class>

Standard Cash 5

To display and journal the cassette information before and after

Standard Cash, the properties of
BeforeStdCashCDMCassetteReportTasks and
AfterStdCashCDMCassetteReportTasks should be updated as
follows:
 To display, set the ShowCassetteInformationScreen property
to True.
 To journal, set the JournalCassetteInformation property to
True.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-272 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Figure 5-77
Example Standard Cash Extract
<Class ID="BeforeStdCashCDMCassetteReportTasks"
Name="NCR.APTRA.NDC.CDMCassetteReportTasks.CDMCassetteReportTasks"
Assembly="NCR.APTRA.NDC.CDMCassetteReportTasks.dll">
<Interface>
<Property Name="ShowCassetteInformationScreen" Value="True"/>
<Property Name="JournalCassetteInformation" Value="True"/>
</Interface>
</Class>
<Class ID="AfterStdCashCDMCassetteReportTasks"
Name="NCR.APTRA.NDC.CDMCassetteReportTasks.CDMCassetteReportTasks"
Assembly="NCR.APTRA.NDC.CDMCassetteReportTasks.dll">
<Interface>
<Property Name="ShowCassetteInformationScreen" Value="True"/>
<Property Name="JournalCassetteInformation" Value="True"/>
</Interface>
</Class>

Test Cash 5

To display and journal the cassette information before and after Test
Cash, the properties of BeforeTestCashCDMCassetteReportTasks
and AfterTestCashCDMCassetteReportTasks should be updated
as follows:
 To display, set the ShowCassetteInformationScreen property
to True.
 To journal, set the JournalCassetteInformation property to
True.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-273

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Figure 5-78
Example Test Cash Extract
<Class ID="BeforeTestCashCDMCassetteReportTasks"
Name="NCR.APTRA.NDC.CDMCassetteReportTasks.CDMCassetteReportTasks"
Assembly="NCR.APTRA.NDC.CDMCassetteReportTasks.dll">
<Interface>
<Property Name="ShowCassetteInformationScreen" Value="True"/>
<Property Name="JournalCassetteInformation" Value="True"/>
</Interface>
</Class>
<Class ID="AfterTestCashCDMCassetteReportTasks"
Name="NCR.APTRA.NDC.CDMCassetteReportTasks.CDMCassetteReportTasks"
Assembly="NCR.APTRA.NDC.CDMCassetteReportTasks.dll">
<Interface>
<Property Name="ShowCassetteInformationScreen" Value="True"/>
<Property Name="JournalCassetteInformation" Value="True"/>
</Interface>
</Class>

Note: If the ShowCassetteInformationScreen and

JournalCassetteInformation properties are not present in both
the classes, the cassette information is not displayed but is logged to
the journal before and after the replenishment tasks.
For details of the cassette information displayed on the screen, refer
to Chapter 3, “Replenish Menu” of the APTRA Advance NDC
Supervisor’s Guide.

Reporting the MANIP Status of CDM Cassettes 5

To enable or disable the reporting of the MANIP status for CDM

cassettes, the EnableManip entry under following registry keys is
used as appropriate for the primary and secondary cash handlers:
HKLM\Software\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS
\CDM\Interoperability

or
HKLM\Software\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS
\CDM2\Interoperability

Valid values for EnableManip are as follows:

0 = Do not report WFS_CDM_STATCUMANIP
1 = Report WFS_CDM_STATCUMANIP

The default value is 0. (The status of the physical cassette is

reported.)
Setting EnableManip indicates that when a physical cassette is
inserted, it can have a status of WFS_CDM_STATCUMANIP. In this

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-274 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

case, before the XFS logical cash unit can be configured for use, the
application must send a WFS_CMD_END_EXCHANGE.
The status of an XFS logical cash unit is affected only if all the
physical cassettes associated with the CDM have a status of
WFS_CDM_STATCUMANIP or WFS_CDM_STATCUINOP.

Multiple currencies are defined by setting up all present cassette

Setting Multiple types in the currency cassette mapping table as described in “Setting
Currencies 5
the Currency”, “Setting the Media Type”, and “Setting the
Denomination”as mentioned above. Cash handlers can then
provide alternate currencies using the defined cassette types, as
illustrated in the following examples:
 Set cassette types 1 and 2 up for euro (EUR) denominations
while cassette types 3 and 4 are set up for sterling (GBP)
denominations.
 On dual cash handlers, if Option 76 supports up to four cassette
types, cassette types 1 and 2 in the primary cash handler can be
set up for EUR denominations while cassette types 3 and 4 are
set up in the secondary cash handler for GBP denominations.
 On dual cash handlers, if Option 76 supports up to seven
cassette types, cassette types 1, 2, 3 and 4 can be set up for EUR
denominations while cassette types 5, 6 and 7 can be set up for
GBP denominations. The cassette types can be in either cash
handler as required.

On NCR SSTs, retract can be disabled to prevent retract from

Disabling Retract after occurring, even after a suspend condition.
Suspend 5

Note: This configuration is not required for GBXX devices as they

can validate retracted notes.

To disable retract, complete the following steps:

1 In the Suspend Mode application link in the Customisation
Layer, remove the Cash Handler Resource ID worker
(4|1094y20) from the following:
 Terminal Suspend worker (189n4798dc128)
 Short Terminal Suspend worker (7s689g213)

2 Update the service provider suspend timeout settings as

follows:
HKLM\Software\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
CDM\GENERAL_CONFIGS\CDM\SuspendTimeout = "0"
HKLM\Software\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
CDM\GENERAL_CONFIGS\CDM2\SuspendTimeout = "0"

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-275

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

For details of the suspend timeout, see “Configuring Suspend

Timeout” on page 5‐100.

3 Update the following registry entry as shown to disable the

clearing of the cash handler at Start of Day:
HKLM\Software\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
CDM\GENERAL_CONFIGS\CDM\ClearTransportOnStartup = "0"

4 Disable the following in the DeviceRecovery.xml file:

 24‐volt reset for all devices
 XFS reset for the Cash Dispenser
 XFS reset for the Cash Dispenser Second
For details of disabling 24‐volt reset, see “Resetting USB Devices”
on page 5‐94.

The CDM continues to remain in a good condition even when the

CDM Status When Notes notes that are dispensed during the last dispense transaction are not
are at Exit Slot 5
collected by the customer and when the notes retraction is disabled.
Further dispense transactions are allowed only when the notes at
the exit slot are removed. This is configured using the following
DWORD registry entry. The valid values are described in the
following table:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-276 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Table 5-91
Registry Entry for Reporting Good Status
When Notes are at Exit Slot
Name Type Description Possible Values

HKLM\SOFTWARE\NCR\Advance NDC\CashHandler\ReportGoodWhenNotesAtExit

ReportGoodWhen REG_DWORD Configured to let the machine 0 (default value)- During a

NotesAtExit remain enabled or suspended dispense transaction, if the
notes are found at the exit slot,
the device goes to a suspend
state and it reports a solicited
message with mStatus 19 and
severity 3 (suspend). For
subsequent dispense
transactions, the device reset
takes place in the Close state
and the notes are moved to the
retract bin.

1 - During a dispense
transaction, if the notes are
found at the exit slot, the device
will not go into a suspend state
and it reports a solicited
message with mStatus 19 and
severity 0. For subsequent
dispense transactions, the
application sends the same
solicited message until the
notes are removed from the exit
slot.
Example of a solicited status
message:
22 FS 000 FS FS 8 FS
E200000000 FS 00000 FS 19
FS 10000

On an NCR single cash handler with four cassette types, the

Reporting Pick Failure reporting of error conditions following consecutive pick failures in
Errors 5
one transaction or over several transactions can be configured.
The level of error reporting is configured using the following
registry setting:
HKLM\Software\NCR\Advance NDC\CashHandler\
EnableErrorSeverity

Valid values are as follows:

0 to report no error for the first and second pick failure and a
fatal error for the third pick failure (default)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-277

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

1 to report a routine error for the first pick failure, a warning for
the second pick failure and a fatal error for the third pick
failure.
On BRM and S2 devices, the first pick failure is reported as a fatal
error irrespective of the registry setting.

If the status of notes is unknown following a power failure during a

Unknown Status of Notes transaction, the notes are treated as presented by default. This
After a Power Failure 5
situation can occur, for example, if a power failure occurs during
note stacking.

Caution: The following solution is not CEN‐XFS compliant. Changing this

registry entry from the default setting may open the SST to fraud
because notes dispensed when a power failure occurs are not
debited from the cardholder’s account. If any notes are moved to the
reject bin during recovery from a power failure, all notes are
regarded as rejected although notes may have been removed from
the transport during device recovery.

If you need to treat notes with an unknown status as not presented

because the default setting is causing issues at the SST, you can
update the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\CashHandler\
UnknownAsRejectedAfterPowerfail

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-278 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Valid values are described in the following table:

Table 5-92
Treatment of Notes After a Power Failure

Value Description

0 Treat notes as presented (default)

Notes are treated as presented and the presented count is updated

Note counts are journaled; both the notes presented count and the notes remaining count are updated
The counts in field ‘r’ (Last Transaction Status) of the next Transaction Request are reported

1 Treat notes as not presented

Notes are treated as rejected and the reject count is updated

Note counts are journaled; the notes presented count is unchanged, but the notes remaining count is
updated
Reserved screen j0026 (LAST DISPENSED COUNTS ARE UNKNOWN) is journaled
The note count of notes with an unknown status is logged to the object oriented XFS (OOXFS) log file
The counts in field ‘r’ (Last Transaction Status) of the next Transaction Request are set to zero. However,
the counts are reported when a power failure occurs after notes are moved from the stacker and
the device is not detected or a communications error is detected on power up irrespective of the
location of notes (taken by the consumer or present in the device)

Note: On a GBRU, the registry entry is set to 1 at start of day.

The counts can be checked using the Display Cash option on the
Supervisor Replenish menu.

In a dispense transaction, when a present is attempted and a

Journaling the Count if a power‐fail occurs before the notes are presented to the consumer,
Present is Attempted then at the time of power‐up, the count of notes that are requested
Before a Power Fail 5 from each cassette type are journaled (reserved screens j0091 and
j0092) in the EJ. The notes jammed in the transport during the
transaction are cleared during a device reset.

In a dispense transaction, if a hardware error occurs after the notes

Count of Notes in are picked from the cassette and the notes are not presented to the
Unknown Location 5
customer or not moved to any other cassette, the notes count is
reported as unknown in Display Supplies Counters ‐ Cash
supervisor option. The same counts are also printed when the Print
Supplies Counters option is executed. The ‘j4070’, ‘j4071’, ‘j4072’ and
‘j4073’ screens are displayed only when there are unknown location
counts.

Note: This functionality is not supported on Recyclers and Dual

Dispensers.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-279

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

If the cash handler has a fifth cassette, this can be reported on the
Cash Handler with a Fifth Fault Display and the Test Cash option in Supervisor and as part of
Physical Cassette 5
tamper indication journaling. To configure a fifth cassette, you must
enter the physical name of the fifth position in the following
registry, which is blank by default:
HKLM\Software\NCR\Advance NDC\PhysicalCassettes\Fifth

For information on the XFS registry for fifth cassette, refer to the
APTRA on‐line documentation, under APTRA XFS |Programmer’s
Reference | XFS Service Providers |XFS MDM Service Providers.

To configure support for seven cassette types, you must do the

Enabling Support for following:
Seven Cassette Types 5

1 Ensure that the Advance NDC currency cassette mapping table

is correctly set up for seven cassette types, as described in
“Setting the Currency”, “Setting the Media Type”, and “Setting
the Denomination” above.

2 Enable extended cassettes for the service provider by setting the

following registry entry to 1:

HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDER
S\
CDM\GENERAL_CONFIGS\EnableExtendedCassettes

Note: For dual cash handlers, you must also set the following
registry entry:

HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\
SERVICE_PROVIDERS\
CDM2\GENERAL_CONFIGS\EnableExtendedCassettes

3 Define a currency and value for cassette types 5 to 7. For

example, to enable support for 10 GBP in cassette type 5 add the
following keys:
HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\
SERVICE_PROVIDERS\
CDM\GENERAL_CONFIGS\CurrencyIDType5="GBP"
HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\
SERVICE_PROVIDERS\
CDM\GENERAL_CONFIGS\ValuesType5="10"

Note 1: This can be done using the ANDCSST.xml file, which

includes keys for cassette types five to seven commented out by
default, and can be updated as follows:

<ActionList name="NCR Cash Dispenser">

<Action Implements="registry">

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-280 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Note 2: Set the following registry key setting to configure the

fifth cassette in 5 High S2 Dispenser and ensure to restart the
SST:

HKLM\Software\NCR\XFS MDM Service

Provider\XFS-DeviceControl\MDM\Migration\CassetteTypes
=”5”

4 Set Enhanced Configuration option 76 to 001 to use extended

messages for seven cassette types. For details of option 76, refer
to the APTRA Advance NDC, Reference Manual.

5 At the SST, use the System Application to set up the note

configuration for cassette types 5 to 7. For details of the System
Application, refer to the Self‐Service Support, System Application
User Guide. You can access this PDF from the on‐line APTRA
Documentation: select APTRA XFS | Runtime Maintenance |
System Application.

You can set low and maximum thresholds for the number of notes
Setting Note Thresholds 5

in a cash handler.

Maximum Notes to be Dispensed 5

The maximum number of notes that can be dispensed is set by the

hardware capabilities. For bunch dispensers, the MaxBills registry
entry can be set to either 40 or 50 in the configurable parameters for
the CDM SP (NCR only). For S2 dispensers, the MaxBills registry
entry can be set to 75. For spray dispensers, the MaxBills registry
entry must not exceed 70 in the configurable parameters for the
CDM SP. For details, refer to the APTRA on‐line documentation,
under APTRA XFS | Programmers Reference | XFS Service
Providers.

Low Threshold for Notes in Cassettes 5

The threshold for notes remaining in a cassette before reporting the

cassette as low is set using the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\CurrencyTable\NDCTypex\
LowBillsThreshold

Each CDM cassette type is defined using the variable x in NDCTypex,

in the range 1 to 7.
The default is ʹ0ʹ and uses the hardware sensors. For details, refer to
the APTRA on‐line documentation for ulMinimum, under APTRA
XFS | Programmers Reference | XFS Service Providers.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-281

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Reject Bin Maximum Threshold 5

The threshold for notes deposited into the reject bin to trigger a
device status of high is set using the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\CurrencyTable\RejectBin\
MaxBillsThreshold

The default is ʹ0ʹ, which switches off the counter thresholds. For
details, refer to the APTRA on‐line documentation for ulMaximum,
under APTRA XFS | Programmers Reference | XFS Service
Providers.

The MEI can be enabled and configured for use on a spray dispenser
Configuring the MEI for a using registry entries under the following key:
Spray Dispenser 5

HKLM\SOFTWARE\NCR\AdvanceNDC\CashHandler\SprayDispenser

Table 5‐93 “MEI Spray Dispenser Registry Entries” on page 5‐283

describes the DWORD registry entries used to enable the MEI and to
configure when flashing is turned on and off during a dispense
operation. The default values are used if an entry is missing or
invalid. At installation, Advance NDC sets values as described in
the table.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-282 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Table 5-93 Registry Entry Description

MEI Spray Dispenser Registry Entries
MEI Enabled Enables and disables the MEI flashing on a spray
dispenser
Valid values are as follows:
 0 = disabled (default)
 1 = enabled (installed value)
MEI Start Delay Defines the delay, in seconds, between the
dispense command being sent and the MEI being
turned on
This delay can be used to ensure that the MEI
starts flashing before the first note is presented
Valid values are in the range 0 to 5
The default setting is 0, Advance NDC sets the
value to 1 at installation
The dispense operation may complete before the
delay time elapses if a value greater than 3
seconds is set. In this situation, the MEI does not
flash
MEI End Delay Defines the delay, in seconds, between the last
note being dispensed and the MEI being turned
off
This delay can be used to ensure that the MEI
stops flashing after the final note is presented
Valid values are in the range 0 to 5
The default setting is 0, Advance NDC sets the
value to 3 at installation

Note: Depending on the performance of the cash

dispenser, there could be a delay of up to 3
seconds between the dispensing of the last note
and the sending of the command to turn off the
MEI. Adjust the MEI End Delay if you need to
compensate for this situation

By default, supplies and severity information is updated to reflect

Supplies and Severity the known state of the cash handler, as described in the following
Information 5
table:

Table 5-94
Supplies and Severity

Update Point Cassette Status Severity Reported As... Supplies Reported As...

Start of Day Good Good Sufficient Notes

Low Good Notes Low

Empty Fatal Out of Notes

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-283

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Update Point Cassette Status Severity Reported As... Supplies Reported As...

Missing Good No new state

Supervisor Exit Good Good Sufficient Notes

Low Good Notes Low

Empty Fatal Out of Notes

Missing Good No new state

Following a TEST CASH Good Good Sufficient Notes

operation
Low Good Notes Low

Empty Fatal Out of Notes

Missing Good No new state

Following a Good Good Sufficient Notes

note‐dispensing transaction
status information is Low Good Notes Low
updated only for cassettes Empty Fatal Out of Notes
used in the transaction
Missing Fatal Out of Notes

All points above, Good Good No overfill

the status reported for the
Reject bin Overfilled Fatal Overfill

Missing Fatal No overfill

Replenishment Status of Cassettes 5

The default configuration of Advance NDC can be changed to

report the actual replenishment status of all cassettes after a
note‐dispensing transaction, not just the status of cassettes used in
the transaction. The following registry entry shows the default
value:
HKLM\SOFTWARE\NCR\Advance NDC\ActualSupplies = 0

To report the actual status of all cassettes, change the value of

ActualSupplies to 1.

Supplies Reporting for S2 Media Dispenser Module 5

The reporting of supplies information for an S2 dispenser is

different from the conventional CDM as the S2 dispenser has three
bins ‐ retract, reject and single note divert bin.
Overall Supplies Byte Status The overall supplies byte is 5

represented by the individual retract, reject and single note divert

bins. The rule to calculate the supplies is:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-284 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Firstly, calculate the overall supplies of reject bin which is the

composite of the reject bin and single note divert bin (reject 2). The
overall supplies for the reject bin is determined by the registry
setting Divert Bin Full Enabled.
Divert Bin Full Enabled Registry The registry setting determines 5

if the SST has to remain in service when the divert bin is full. The
rejected items are moved to the purge bin if enabled, else the device
will go into an out of service mode. The registry setting is as follows:
HKLM\SOFTWARE\NCR\APTRA Self-Service Support (NCR
Features)\USBMediaDispenser\Operational
Parameters\Divert Bin Full Enabled

Valid values for this entry are as follows:

1 = The rejected notes are moved to the purge bin.
0 = The device goes into a fatal mode.

Table 5-95
Overall Supplies Reporting for Reject Bin Overall Status Description
when Divert Bin Full
Enabled = 1 Good Supplies status of the reject bin is good (irrespective of the
status of single note divert bin).

Full Supplies status of the reject bin is full (irrespective of the

status of single note divert bin).

Table 5-96
Overall Supplies Reporting for Reject Bin Overall Status Description
when Divert Bin Full
Enabled = 0 Good Supplies status of the single note divert bin is good and
reject bin is good.

Full Supplies status of the single note divert bin or reject bin is
full.

Secondly, the most severe supplies status is calculated based on the

supplies status of the individual retract, reject and single note divert
bins and is reported as the overall supplies byte as described below.
Supplies severities from least to most severe are: Good; Full.

Table 5-97 Overall Status Description

Most Severe Status Reporting
Good Supplies status of reject and retract bins is good.

Full Either of the reject or retract bin has a supplies status of

full.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-285

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Fitness Reporting for S2 Media Dispenser Module 5

The reporting of fitness information for an S2 dispenser is different

from the conventional CDM.
Overall Fitness Byte Status 5

The overall fitness byte is represented by the individual retract,

reject and single note divert bins.The rule to calculate the fitness is:
Firstly, calculate the overall fitness of reject bin which is the
composite of reject bin and single note divert bin (reject 2). The
overall fitness byte for a reject bin is determined by the Divert Bin
Full Enabled and Divert Gate Fail at Stack Position
Enabled registries.

For information on the Divert Bin Full Enabled registry, see “Divert
Bin Full Enabled Registry” on page 5‐285.
The registry setting Divert Gate Fail at Stack Position
determines if the SST has to remain in service when the divert gate
fails in the stack position. The rejected items are moved to the purge
bin if enabled, else the device will go into an out of service mode.
The registry setting is as follows:
HKLM\SOFTWARE\NCR\APTRA Self-Service Support (NCR
Features)\USBMediaDispenser\Operational
Parameters\Divert Gate Fail at Stack Position

Valid values for this entry are as follows:

1 = The rejected notes are moved to the purge bin.
0 = The device goes into a fatal mode.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-286 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

The overall fitness for the reject bin is calculated as follows:

Table 5-98 Overall Status Description

Overall Fitness Reporting for Reject Bin
Divert Bin Full Enabled = 0 and Divert Gate Fail at
Stack Position Enabled = 0

Good Fitness status of reject and single note divert bin is good.

Fatal Either of the reject or single note divert bin has a fitness
status as full.
or
When the divert gate fails.

Divert Bin Full Enabled = 0 and Divert Gate Fail at

Stack Position Enabled = 1

Good Fitness status of reject and single note divert bin is good.

Fatal Either of the reject or single note divert bin has a fitness
status as full.

Divert Bin Full Enabled = 1 and Divert Gate Fail at

Stack Position Enabled = 0

Good Fitness status of reject bin is good (irrespective of the

status of single note divert bin).

Fatal Fitness status of reject bin is full (irrespective of the status

of single note divert bin).
or
When the divert gate fails.

Divert Bin Full Enabled = 1 and Divert Gate Fail at

Stack Position Enabled = 1

Good Fitness status of reject bin is good (irrespective of the

status of single note divert bin).

Fatal Fitness status of reject bin is full (irrespective of the status

of single note divert bin).

Secondly, the most severe fitness status is calculated based on the

fitness status of the individual retract, reject and single note divert
bins and is reported as the overall fitness byte as described below.
The overall fitness byte is determined as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-287

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Table 5-99 Overall Status Description

Most Severe Fitness Status Reporting
Good The overall fitness of the reject and retract bin is good or
high.

Fatal The overall fitness of either the reject or retract bin is fatal
or missing.

To read serial numbers, the SST must have a BRM device installed.
Reading and Journaling
Serial Numbers 5
The serial numbers of good (category 4), suspect (category 3) and
counterfeit (category 2) notes are journaled based on the following
DWORD registry setting:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance
NDC\CashHandler\JournalSNRForDispenseTransaction

By default, the JournalSNRForDispenseTransaction registry value is

set to 0, in which case the serial number is not journaled.
When the value is set to 1, the serial number information of the
Category 4, Category 3 and Category 2 notes is journaled.

Journaling Serial Number Information 5

The operation type and serial numbers of notes are journaled in the
following situations:
 Notes stacked during a dispense transaction
 Notes moved to reject bin as part of a pick failure
 Notes moved to retract bin during a retract transaction
 Notes cleared during a device reset (notes jammed in the
transport during a transaction)
In a dispense (including pick failure), retract and recovery
operations, the serial number for all the notes that have been read
successfully and the number of failed reads are journaled based on
their category (category 4, category 3, category 2).

Note: In a reset operation, if the device recovery fails, the serial

number of notes will not be journaled on the EJ.
With the serial numbers, the location, currency and denomination of
the notes can also be journaled by setting the properties under the
SerialNumberJournalConfig class in the CashInCustom.accfg file.
For more information on journaling serial numbers and location,
refer to Chapter 7, “Journaling Serial Numbers in a Dispense
Transaction” in the APTRA Advance NDC, Supervisor Guide.
For information on setting the properties, see Table 5‐117, “Serial
Number Journal Configuration Properties” on page 5‐332.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-288 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

On a BRM device, during a dispense transaction, bunch camera,

Capturing Bunch Note present at the entry or exit slot, captures image of a bunch of notes.
Image 5
For details about capturing the bunch note images during a deposit
transaction, see “Capturing Bunch Note Image” on page 5‐344.
The image of a bunch of notes is captured before opening the
shutter to present the notes and after the shutter is closed to retract
or recover the notes present in the pocket. The above functionality
can be enabled using the following XFS registry entry:
HKLM\SOFTWARE\NCR\XFS BRM Service
Provider\XFS-DeviceControl\BRM\Operations\CaptureBun
chImages

For details about the registry, refer to the APTRA on‐line

documentation under APTRA XFS | Programmer’s Reference |
XFS Service Providers | XFS BRM Service Providers |
Configurable Parameters | Operations.
The following is the file format of a bunch note image:
NNNNNN_TTTT_MMDDYY_HHMMSS_CCCC_OPERATION.JPG

Table 5-100 Variable Description

Bunch Note Image File Format
NNNNNN SST Machine Number

TTTT Transaction Serial number

See Note 1:

MMDDYY Date in a format dependent on Enhanced

Configuration Option 3

HHMMSS Time in HHMMSS format

CCCC Last four digits of the consumer’s card

number

See Note 2:

OPERATION DISP ‐ After notes are presented to the

consumer

RET ‐ After notes are retracted

REC ‐ After notes are recovered during a

reset operation after a shutter jam

Note 1: The host populates the Transaction Serial number for a

transaction. If there is no reply from the host, the Transaction Serial
Number is kept blank in the bunch note image file format. For
example the bunch note image file format is similar to

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-289

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

NNNNNN__MMDDYY_HHMMSS_CCCC_OPERATION.JPG

Note 2: In a cardless transactions, the card number is kept blank in

the bunch note image file format. For example the bunch note image
file format is similar to

NNNNNN_TTTT_MMDDYY_HHMMSS__OPERATION.JPG

The captured bunch note images are stored in the below path:
C:\Program Files\NCR APTRA\Advance NDC\Persisted
Data\BunchImageFiles\Dispense

The bunch note images are captured in the following scenarios:

Scenario 1: Dispense 5

During a dispense transaction, before the shutter is opened to

present notes to the consumer, the bunch note image is captured
with a name similar to
123456_1234_110918_124553_5678_DISP.JPG

Scenario 2: Retract 5

During a dispense transaction, the notes that are not taken by the
consumer when presented are retracted after the shutter is closed
and the bunch note image is captured with a name similar to
123456_1234_110918_124553_5678_RET.JPG.

Scenario 3: Hardware Error Recovery 5

During a dispense transaction, while opening the shutter to present

notes to the consumer, if a hardware error occurs, the bunch note
image is captured for the notes present in the exit slot and the error
recovery is performed. The bunch note image is captured with a
name similar to
123456_1234_110918_124553_5678_DISP.JPG

During the error recovery, the shutter is closed and the bunch note
image is captured for the notes present in the exit slot. The bunch
note image is captured with a name similar to
123456_1234_110918_124553_5678_REC.JPG.

In a dispense transaction, the card details and note information of

Logging Signatures of category 2 and category 3 notes are logged to a database named
Dispensed Notes to ECB6DBDISPENSELOG.SDF, where the data is stored in the form of
Database 5 records. This is located in the C:\Program Files\NCR
APTRA\Advance NDC\PersistedData\ECB6DBDispenseLog folder.
The note information is logged to the database irrespective of the
ECB6 mode (see GBRUMode and CatMode in “XML Schema

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-290 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Elements” on page 5‐392). The information is stored for 60 days

from the date of creation and then the records are deleted from the
database automatically. The following information is logged to the
database:
 Card Number
 Timestamp
 Currency
 Denomination
 NoteID
 Orientation
 Category
 Signature

Note: If the card number consists of only four digits, all the four
digits are masked. If there are more than four digits, except the last
four digits the rest of the digits are masked.
To enable the capturing of signatures, set the XFS registry path of
ReportCDMCat23 key value to 1. The path for the GBRU device is:
HKEY_LOCAL_MACHINE\Software\NCR\XFS GBRU-GBNA Service
Provider\XFS-DeviceControl\GBRU-GBNA\Interoperability

Logging the note information to the database is configured using

the following (DWORD) registry entry:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\AdvanceNDC\CashRecycler
LogDispensedNotesSignatureInfo

The valid values are:

 0 = The information is not logged to the database (default).
 1 = Logs category 2 and category 3 note information.
During a retract operation, if any notes are identified as counterfeit
(category 2) or suspect (category 3) notes, the note information is
logged to the database based on the registry configuration.
Failed Signatures If the reading of the note signature fails for 5

counterfeit or suspect notes, this is journaled using the reserved

screens U0124 and U0125.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-291

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

The database elements are described in the following table:

Table 5-101
Database Structure

Element Description

DispenseDBInfo This is the root element.

Nested element:
 TransInfo

TransInfo Contains the child element for transaction details.

TransactionInfo Defines the transaction information.

Nested elements:
 DisputeReference
 TransactionTimeStamp
 IdentificationData

DisputeReference Provides the consumer card details.

TransactionTimeStamp Defines the time of the transaction performed.

IdentificationData Reserved for future use. (Only used to store user specific data.)

NoteInfo This consists of note information.

Nested element:
 BankNoteDetail

BankNoteDetail Contains the child element for note details.

Currency This is a three character array storing the ISO format currency ID.

Denomination This supplies the value of a dispensed note.

NoteID This is the identification of note type.

Category Defines the note level.

Orientation Defines the orientation of the dispensed banknote.

Signature Provides the signature of the note.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-292 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Figure 5-79
Example Log Signatures Extract
<DispenseDBInfo>
<TransInfo>
<TransactionInfo>
<DisputeReference>Card NO. ************1852</DisputeReference>
<TransactionTimeStamp>1/24/2017 2:49:35PM</TransactionTimeStamp>
<IdentificationData/>
</TransactionInfo>
</TransInfo>
<NoteInfo>
<BankNoteDetail>
<Currency>EUR</Currency>
<Denomination>20</Denomination>
<NoteID>10</NoteID>
<Category>2</Category>
<Orientation>3</Orientation>
<Signature>
0301022504040EFFEEE211AC00580032001F00330010271D080208000008020808020000520002220004
0000050000020006C2007A009F006C0
18E0187007E008C006E0068000E018300C400B6007C00C600F9005F00630073005C00B900C000D400E80
00000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000004017101C7
009D0139011801F9000F01F2007301FF0005012D010D01EF000E011101F00001010501E700E4000E0107
011001FE000001BC00D40002010001000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000001EB
003100FE0000000000000000000000000000000000020000000000000000000000000000006203B40245
03BD03000000000000000000000000000000000000
0000000000000000000024AA000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000000
000000000000000000000000000000000000000000000000
</Signature>
</BankNoteDetail>
</NoteInfo>
</DispenseDBInfo>

A second cash handler (known as the secondary cash handler) can

Dual Cash Handler be added to create one logical cash handler, which emulates a single
Configuration 5
cash handler for the host.
A dual cash handler configuration can include a recycling unit. If a
recycling unit is used, the stricter cassette mappings required for
recycling unit configuration must be used for all cash handlers in
the dual cash handler.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-293

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Note 1: As increased cash‐handler capacity has been implemented

without host impact, the host cannot select the cash dispenser to be
used for dispensing cash.

Note 2: The Cassette Information screen (described on page 5‐271)

does not support dual dispensers. Only the details of the primary
cash handler are displayed.

Note 3: In messages, the cash handlers are identified using 0 and 1;

on Advance NDC screens they are identified using 1 and 2.

Note 4: Advance NDC does not support the combination of S1 and

S2 dispensers as a dual cash handler.

Registry Entries for Dual Cash Handlers 5

The registry entry for dual cash handler settings is:

HKLM\SOFTWARE\NCR\Advance NDC\DualCashHandler

The secondary cash handler has the following alias:

HKLM\SOFTWARE\NCR\Advance NDC\Aliases\
Cash Dispenser Second

Setting the Cash Handler Priority 5

The cash handler that is given priority is checked first and used to
dispense whenever possible. If a recycling unit is used, it must be
set as the priority cash handler.

Note: If there is no primary cash handler attached to the SST, the

secondary cash handler will never be available, even if it is set as the
priority cash handler.

The following registry entry contains the setting for cash handler
priority:

HKLM\SOFTWARE\NCR\Advance NDC\DualCashHandler\Priority

Valid values for this entry are as follows:

0 = priority to the primary cash handler (default)
1 = priority to the secondary cash handler.

Note: If a recycling unit is used, it must be both the primary

cash handler and the priority cash handler.

Setting the Counter Entry Mode 5

The counters for a dual cash handler can be set as combined or

separated. If combined counters are used, the total count for both

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-294 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

cash handlers is entered, displayed and printed in Supervisor mode.

If separated counters are used, the counts for each cash handler are
entered, displayed and printed in Supervisor mode.
The following registry entry contains the setting for combined or
separated counts:

HKLM\SOFTWARE\NCR\AdvanceNDC\DualCashHandler\
CountersEntryMode

Valid values for this entry are as follows:

0 = use combined counters (default)
1 = use separated counters.

Setting the Counter Clearing Mode 5

If separated counters are used, the counters for each cash handler in
a dual cash handler can be cleared separately or together. If cleared
separately, the cash handler must be selected in the Clear Cash and
Standard Cash functions on the Supervisor Replenish menu. If
cleared together, the Clear Cash and Standard Cash functions do
not prompt for selection of a cash handler.
The following registry entry contains the setting for the counter
clearing mode:

HKLM\SOFTWARE\NCR\AdvanceNDC\DualCashHandler\
CountersClearMode

Valid values for this entry are as follows:

0 to clear the cash handler counters for both cash handlers
together (default)
1 to enable the selection of the cash handler in the Supervisor
functions.

Note: If the dual dispenser is a combination of GBRU and CDM

and if the GBRU is in the recycling mode, the CLR BNA option
clears GBRU and CDM counts by default. If the
CountersClearMode registry value is set to 1, the CLR BNA option
clears only the GBRU counts.

Status Reporting 5

As each cash handler has a separate dispenser, each transaction uses

one cash handler.
The status of dual cash handlers is reported as a single logical cash
handler as follows:
 The severity is reported for the cash handler with the best status.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-295

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

 The fitness is reported for the cash handler with the best status
or a suspend status. A suspend status is always reported
whatever the fitness of the other cash handler.

Cash Handler Status Message 5

The following registry entry defines whether to report a combined

(best overall) or suspend status when the specified note mix cannot
be dispensed by one cash handler:

HKLM\SOFTWARE\NCR\Advance NDC\DualCashHandler\
CassSuspendedValue

Valid values for this entry are as follows:

0 = report a combined status (default)
3 = report a suspend status.
The following scenario illustrates the effect of this registry setting:

If only one of the cash handlers can dispense the requested note
mix, the following occurs:

— The cash handler that can dispense the note mix is used.
— A solicited status message is sent if a cassette type runs out
of notes during the dispense operation.

In this situation, neither cash handler can now provide the note
mix required, and the status message reports a combined status
by default. This reports the best overall status, which states that
sufficient notes are available for the dispense. The host therefore
continues to request a note mix that cannot be dispensed. If
configured to report a suspend status, the host can continue
requesting the cassette type as it is still available in one of the
cash handlers, but will not request the note mix.

If both cash handlers could have dispensed the note mix, the
priority cash handler is used. If the priority cash handler runs
out of notes during the dispense operation, using the suspend
setting means that the transaction can be re‐attempted.

The following example illustrates this situation:

 Each cash handler contains cassette types 1 and 2
 Cassette type 1 is already fatal in the priority cash handler
 Cassette type 2 runs out of notes during a dispense using the
second cash handler.

This situation means that a mix of cassette types 1 and 2 cannot

be dispensed from either cash handler. However, reporting a
combined status means that the supplies appear to be good
because cassette type 2 is available in the priority cash handler.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-296 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Reporting a suspend status allows the host to continue

requesting cassette type 2 as it is still available in the priority
cash handler, but not in a mix with cassette type 1.

The following registry entry defines whether a message is sent to

the host reporting that the cash handler has recovered from a fatal
status:

HKLM\SOFTWARE\NCR\Advance NDC\DualCashHandler\
CU_ReturnedToGood_Severity

Valid values for this entry are as follows:

0 = do not report recovery from a fatal status (default)
1 = report recovery from a fatal status.

Interlock Handling 5

Dual cash handlers may each have a safe door interlock or there can
be a single interlock that disables power to both cash handlers. If
there are two interlocks on dual cash handlers that emulate a single
cash handler, the interlock open M‐Status can be reported with a
non‐fatal severity. To avoid this, interlock handling is defined by
Enhanced Configuration option 76 as follows:
 If option 76 is set to 000, an open interlock is always reported as
fatal
 If option 76 is set to 001, the best overall status is reported. The
individual status is reported using DIGs ‘d’ and ‘e’ in response
to a Send Configuration command. For information on this
command, refer to the APTRA Advance NDC, Reference Manual.

Tamper Indication 5

As both cash handlers are reported to the host as a single logical

cash handler, some messages to the host can seem to be duplicated.
This may imply that tampering has occurred. If this is the case check
the journal trace, which includes information on the cash handler.
For example, if all cassettes are removed from CH0 and then all
cassettes are removed from CH1, the host message will suggest that
cassettes have been removed twice. However, the journal trace
prefixes this information with Cx., where x indicates the individual
cash handler.
For further information on tamper indication, refer to the APTRA
Advance NDC, Reference Manual.

An S2 currency dispenser contains a purge bin partitioned into three

S2 Media Dispenser units; retract bin, reject bin and single note divert (reject bin 2). The
Module 5
bins are categorized as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-297

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

 When the notes are presented but are not collected by customer,
they are moved to the retract bin.
 When the notes are picked from the cassette but not presented to
the customer due to device failure, they are moved to the reject
bin.
 When a pick failure occurs while picking the notes from the
cassette, they are moved to the single note divert bin.

Note 1: The user can configure to move the retracted notes into
the reject bin.

Note 2: The user can also configure the pick failure notes to be
moved into reject bin when the single note divert bin is full. This
is to ensure that the device remains in In‐Service for more time.

The purge bin is a single logical cash unit that can be represented
either as one or three physical cash units.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-298 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

The following table describes the registry entries for an S2 dispenser

in emulation mode or native mode:

Table 5-102
Dispenser Registry Entries
Registry Entry Type Description

HKLM\SOFTWARE\NCR\XFS MDM Service Provider\XFS-DeviceControl\MDM\Migration

cUnitIDs REG_DWORD The format used in the logical and physical cash
unit structure.
Valid values are as follows:
 0 ‐ The CDM SP format is used to represent
purge bin as a single logical cash unit.
(default)
 1 ‐ The GBRU/SDM/SCIM SP format is
used to represent purge bin as three
logical cash units.
PurgeBinReporting REG_DWORD Specifies if the purge bin is reported in one or
three physical cash units. This is reported only if
cUnitIDs is set to report CDM SP format.
Valid values are as follows:
 0 ‐ One physical cash unit is reported
(default).
 1 ‐ Three physical cash units are reported.

The Carriage Sweep functionality on an S2 dispenser provides a

Carriage Sweep 5

security feature in which carriage sweep is configured to be

executed prior to every dispense operation. This will clear the
transport and prevent fraudulent traps.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-299

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Carriage sweep for a dispense operation is enabled or disabled using

the following registry setting:

Table 5-103
Carriage Sweep Registry Entry
Name Type Description Possible Values

HKLM\SOFTWARE\NCR\APTRA Self-Service Support (NCR Features\ USBMediaDispenser\

Operational Parameters

Carriage Sweep REG_DWORD Whether the carriage path is 0

traversed and checked prior to Disables the carriage sweep.
each stack operation. This is the default value.

1
Enables the carriage sweep for
every stack operation.

Carriage Sweep can be performed as a Serial Carriage Sweep or as a

Parallel Carriage Sweep as explained in the following sections.

Serial Carriage Sweep 5

In a Serial Carriage Sweep, when Carriage Sweep is enabled, the

carriage moves and clears the transport when the Dispense
command is issued on the dispenser. After the Carriage Sweep is
completed successfully, the carriage moves to the stack position
ready to accept the notes. If Carriage Sweep is disabled, the carriage
moves to the stack position from the idle position.
If the dispense operation fails due to a jam or hardware issue while
performing a carriage sweep or while moving the carriage from the
idle position to the stack position, then the application sends a
solicited message to the host.

Parallel Carriage Sweep 5

Parallel Carriage Sweep is used on dispensers that have the

bPrepareDispense capability as it reduces the time of the dispense
operation. Parallel Carriage Sweep is achieved using the Prepare
Dispense feature.
For information on Prepare Dispense feature, see “Prepare
Dispense” on page 5‐300.

Note: Dual dispensers does not support Parallel Carriage Sweep.

Prepare Dispense feature helps to improve the time taken to

Prepare Dispense 5

dispense cash by moving the carriage to the stack position from the
default idle position before a dispense operation. If Carriage Sweep
is enabled, the carriage clears the transport and moves to the stack

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-300 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

position ready to accept the notes. After the dispense operation is

completed, the carriage moves to the Idle Position. If Carriage
Sweep is not enabled, the carriage is moved to the stack position
from the idle position without performing a carriage sweep.
The dispense preparation is terminated by the application by
executing the PREPARE_DISPENSE command in the Close State after
processing Card Eject for a successful/unsuccessful dispense
transaction. This is done only when the dispense preparation is
initiated as part of the transaction.
The dispense preparation fails and the carriage moves to the Idle
Position, if any execute command of the dispenser (except the
Denominate command) is used.

If a dispense preparation fails due to a jam or hardware issue, then

the application does not send any solicited or unsolicited messages
to the host. The carriage moves to the Idle Position after the error is
cleared through diagnostics.
The following registry is used to enable or disable Prepare Dispense
in card read states:

Table 5‐104
Prepare Dispense Registry Entry
Name Type Description Possible Values

HKLM\SOFTWARE\NCR\Advance NDC\Cash Handler

Prepare REG_DWORD Determines whether Prepare 0

Dispense On Dispense should be enabled This is the default value and
CardRead or disabled in Card Read disables the Prepare Dispense in Card Read
State A and Card Read ‐ PIN State A and Card Read ‐ PIN Entry Initiation
Entry Initiation State T State T.

1
Enables to Prepare Dispense when a card is
read successfully or when a cardless
transaction is initiated in Card Read State A
and Card Read ‐ PIN Entry Initiation State T.

If the value is missing or is any value other

than 0 and 1, the default is used.

Prepare dispense feature is available in Card Read State A and Card

Read ‐ PIN Entry Initiation State T. A separate state, Prepare
Dispense State z024 is also provided, which has to be configured by
the host in a transaction flow.
For information on the states, refer to sections, “A ‐ Card Read
State”, “T ‐ Card Read ‐ PIN Entry Initiation State” and “z024 ‐

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-301

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Prepare Dispense State” in Chapter 2, “State Tables” of the APTRA

Advance NDC, Reference Manual.

Card Read State A and Card Read ‐ PIN Entry Initiation

state T 5

When the card has been read successfully or a cardless transaction is

initiated either in Card Read state A and Card Read ‐ PIN Entry
Initiation state T, then the application performs the dispense
preparation.
To initiate the dispense preparation, Prepare Dispense On
CardRead must be set to 1 for the dispense preparation to start after
a successful card read or cardless transaction.

Prepare Dispense State z024 5

Prepare Dispense state is executed when the host knows that a

dispense transaction is going to take place. To initiate the dispense
preparation, Prepare Dispense On CardRead must be set to 0.
For example, if the card holder selects the Dispense transaction from
Four FDK Selection Function state, then this state can be executed
after Four FDK Selection Function state.
For chaining transactions support, use Prepare Dispense state.

Note: Prepare Dispense state will do nothing for dispensers that do

not have the bPrepareDispense capability, it will take Complete
Next State exit.
In Card Read State (A and T) and Prepare Dispense State (z024), if
the dispense preparation fails due to any error, a solicited message
with the mStatus of the failure is sent to the host when the dispense
command fails with WFS_ERR_CDM_NOTDISPENSABLE error.

Close State 5

After the dispense preparation is initiated from the above states, the
activated dispense preparation is stopped in the Close state.
In Close state, if the dispense preparation fails due to any error, a
solicited message with the mStatus of the failure is sent to the host
after the next dispense transaction is attempted and the dispense
command fails with WFS_ERR_CDM_NOTDISPENSABLE error.

In a dispense transaction, the notes that are not taken by the

Retract Options 5

consumer when presented are retracted to the retract bin by default.

However in S2 Dispensers and BRM devices, different retract
destinations can be configured for each dispense transaction so that
the bunch of notes retracted are identified by its dispense
transaction.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-302 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Advance NDC supports 1, 1.5, 2 and 2.5 retracts on an S2 dispenser

and a two stage retract on a BRM device based on the following
registry setting:

Table 5-105
Retract Options
Name Type Description Possible Values

HKLM\SOFTWARE\NCR\Advance NDC\CashHandler

Dispenser String Enables 1, 1.5, 2 or 2.5 0 ‐ Disabled

RetractOption and two stage Retract 1 ‐ Enables 1 Retract
option. 1.5 ‐ Enables 1.5 Retract
2 ‐ Enables 2 Retract
2.5 ‐ Enables 2.5 Retract
9 ‐ Enables two stage Retract
Valid values are 1, 1.5, 2, 2.5 and 9. Any other
value disables this feature and notes are retracted
to the retract bin.

1 Retract 5

The 1 Retract option separates the note bunch of a single retract

transaction. The notes of a retract operation for a particular
transaction are moved to the retract bin and further retract is
disabled until the device is cleared.

1.5 Retract 5

The 1.5 Retract option separates the note bunches between two
different transactions. The notes from the first retract operation for a
transaction move to the retract bin. The notes from the next retract
operation for another transaction move to the stacker and the device
goes to the fatal state. The device in fatal condition must be cleared
for further dispense.
2 Retract
The 2 Retract option separates the note bunches of two different
transactions. The notes of the first retract operation for a particular
transaction are moved to the retract bin. The notes from the next
retract operation are moved to the reject bin. After the second
retract, further retract is disabled until the device is cleared.

2.5 Retract 5

The 2.5 Retract option is similar to the 1.5 Retract option, here it
separates the note bunches between three different transactions. The
notes from the first retract operation for a transaction move to the
retract bin, the notes from the second retract operation move to the
reject bin, and the notes from the third retract operation move to the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-303

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

stacker and the device goes to the fatal state. The device in fatal
condition must be cleared for further dispense.

Two Stage Retract 5

When a two stage retract is enabled on a BRM device, the retract of

the notes happens in two stages.
In the first stage, the retracted notes pass through the bill validator
and then to the transport where the note categorization,
denomination, serial numbers and the number of notes retracted are
captured. Subsequently, a comparison is made between the
presented and the retracted notes and the following conditions are
validated:
 If there is any difference in the currency, denomination and/or
the number of notes presented and retracted.
 If there is any difference in the note categorization for the notes
presented and retracted.
 If there is any difference in the serial number of the notes
presented and retracted.
If any of the above conditions are true, the following occurs:
 The notes will remain in the transport.
 An unsolicited message is sent to the host with mStatus 04
marking the severity of the device as fatal.
 j0076 is the reserved screen, which logs the information that
there is a mismatch in the presented and retracted notes.
 j0077 and j0078 are the reserved screens that log the presented
notes.
 j0067 and j0068 are the reserved screens that log the retracted
notes.
 The device status is reported as fatal in fault display until it is
cleared by the Supervisor Test Cash option. For information on
how to clear the device, refer to section “Clearing the device”.
For information on logging the summary of presented and retracted
counts, refer to the section, “Presented and Retracted Counts” in
Chapter 7, “Error and Exception Reporting and Recovery” of the
APTRA Advance NDC, Supervisor’s Guide.
After the device is cleared, reconciliation of dispense and deposit
must be performed
If the first stage retract is successful and if none of the above
conditions are true, the second stage of retract starts and the
following occurs:
 The notes are retracted to the retract bin
 An unsolicited message is sent to the host.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-304 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

If the retract fails during first or second stage, an unsolicited status

message with mStatus about the retract failure, which is provided
by XFS is sent to the host. The second stage retract is not attempted
if the retract fails during the first stage.
To enable the functionality, set the registry key
DispenserRetractOption to 9 and the following registry to 1.

HKLM\SOFTWARE\NCR\XFS BRM Service

Provider\XFS-DeviceControl\BRM\Interoperability\
SerialNumberRead

For 1.5 and 2.5 retracts, when the notes are retracted to stacker, the
Advance NDC application marks the device as fatal until the
supervisor clears the device. An unsolicited message is sent to the
host marking the severity of the device as fatal. For information on
cash handler status, refer to the section “Cash Handler
(Solicited/Unsolicited)” in Chapter 9, “Terminal to Central
Messages” of the APTRA Advance NDC, Reference Manual.

Note: For information on how to clear the device, refer to section

“Clearing the device”.
The following registry settings obtain the 1, 1.5, 2 and 2.5 Retract
features on an S2 Dispenser:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-305

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Table 5-106
1, 1.5, 2 and 2.5 Retract on an S2
Dispenser
Name Description Value Possible Values

HKLM\SOFTWARE\NCR\APTRA Self Service Support(NCR Features)\USBMediaDispenser\

Operational Paramters

Number of retracts Number of retract operations 0 1 ‐ Default

allowed allowed from present 0 to 254 ‐ Range
position to the retract To separate note bunches
compartment of the bin between two different
between bin replenishment transactions.
cycles.

Retract to stack Retracts the notes to stacker 1 1 ‐ Default

enabled in the second retract 0 ‐ Disabled
operation. 1 ‐ Enabled

Half retract to retract Allows the media items to 1 0 ‐ Disabled

enabled move to the retract bin from 1 ‐ Enabled
half retract position (the This must be enabled if
stacker) while clearing the the consumer wants the
device. notes present in the
stacker to be moved to
the retract bin.

Half retract to reject Allow the media items to 1 0 ‐ Disabled

enabled move to the reject bin from 1 ‐ Enabled
half retract position (the This must be enabled if
stacker) while clearing the the consumer wants the
device. notes present in the
stacker to be moved to
the reject bin.

Note:

 If any of the required configuration is not applied at the driver

level, then application retracts the notes to the retract bin
always.
 A known limitation for 2.5 retract operation is that the notes can
get mixed up in the reject bin. For example, in a card before cash
dispense transaction, if a customer fails to take the card, then the
stacked notes move to the reject bin. In any dispense transaction
that follows, retracting the notes to the reject bin will mix up
notes in the reject bin.

Clearing the device 5

When the device is in the 1 or 2 Retract state and the notes are left at
the exit slot, then further retract operation is disabled. The device
must be cleared using Supervisor Test Cash option.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-306 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

When the device is in the 1.5, 2.5 Retract state or two stage retract
and in fatal condition, then further dispense is not possible. Hence
the supervisor must use the following steps to clear the dispenser
device for further transaction:
1 Collect the notes from the reject and retract bins.

2 Clear the device using the Test Cash option in Supervisor under
Replenish menu. The notes in the stacker or transport are
retracted to the retract bin. Also, the notes that are picked from
the cassettes during the Test Cash operation are moved to the
reject bin.
After the device is cleared, it will be available for further dispense
transaction.
If the device is in 1.5 or 2.5 retract state and if the supervisor enters
and exits the Supervisor menu without performing the above steps,
then the currency dispenser will not be cleared even though
Supervisor\ClearCashHandlerCmd is set to clear the device (see
“Cash Recycler: Registry Entries for User Update” on page 5‐318)
and the notes will remain in the stacker.

For an S2 Dispenser, which contain two reject bins and a retract bin,
Report Reject and Retract the following DWORD registry entry is used to display or print the
bins Physical Counts 5
individual reject and retract bin physical counts.
HKLM\SOFTWARE\NCR\Advance NDC\CashHandler\
ReportRejectAndRetractBinPhysicalCounts

Valid values are as follows:

0 ‐ Do not display and/or print reject and retract bin physical counts
(default)
1 ‐ Display and/or print reject and retract bin physical counts
For any other value or if the registry entry is missing, the default
value is used.
The counts can be checked using the Display Cash option and Print
Counters options on the Supervisor Replenish Menu.

Note:

 The reject bin physical counts will not match the actual counts of
notes in the reject bin after Test Cash is performed. This happens
because the Test Cash operation resets the purge bin tally count
to zero after moving few test notes to the reject bin. For example,
if four notes are moved to the reject bin as part of the Test Cash

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-307

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

operation, the physical reject bin count reported is zero as the

physical bin counts are cleared at the end of the Test Cash
operation.

The clearing of purge bin counts is enabled or disabled by the

following registry:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance
NDC\supervisor\ResetPurgeBinCountsOnTestCash

If the ResetPurgeBinCountsOnTestCash registry is set to 0, the

purge bin counts are not cleared as part of the Test Cash
operation and the physical reject bin counts are correctly
reported. Use the Clear Cash option to clear the purge bin
counts as the option clears the cash unit counts along with the
purge bin counts. If the ResetPurgeBinCountsOnTestCash
registry is set to 1 (default), the reject bin counts displayed on
the Reject/Retract Bin Counts screen will be zero after the Test
Cash operation as the purge bin counts are cleared though there
are notes in the reject bin.

However, the 1, 1.5, 2 and 2.5 retracts are not supported when
ResetPurgeBinCountsOnTestCash is disabled, as the clear
purge bins functionality is required to re‐enable retract
operations.

 The S2 dispenser does not report retract counts. Hence, the

retract bin count is always reported as zero.

In an S2 Dispenser, the purge bin is divided into three parts, a Reject

Tamper Indication on an bin, a Retract bin and a Single Note Divert (Reject Bin2) bin. The
S2 Dispenser 5
tamper information for these three bins are reported in Extended
Tamper Status field (‘C’) under the Cash Handler device identifier
of ‘d’ (for Cash Handler 0) and ‘e’ (for Cash Handler 1).

Journaling 5

When a retract or reject bin is inserted or removed, this is journaled

using reserved screen U0145, which records the status of bin
positions in the same format it goes to the host. The reserved screens
j0062 to j0065 are used to record individual changes in the physical
bin positions and are printed based on the Enhanced Configuration
Option 24 setting, and is printed before U0145 is printed. This
feature matches the behaviour of Tamper Indication support for the
Cash Dispenser.
The following reserved screens serve as journal record templates
and can be localised as necessary:
'j0062' REJECT BIN % INSERTED'
'j0063' REJECT BIN % REMOVED'
'j0064' RETRACT BIN INSERTED'

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-308 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

'j0065' RETRACT BIN REMOVED'

'U0145' '<ESC>(I
*<TSN%>*1*P*6<StatusData%>,M-<ESC>(1'

Where, the StatusData field contains the contents of Buffer C in the

Flexible TI/Sensors Unsolicited message. The TSN field contains the
last Transaction Serial Number or four space characters if not
available.
During Diagnostics, when a cassette or a bin is removed, a sensor
unsolicited message with the cassette sensor status is sent to the
Central. Sensor Data is journaled with its respective cassette or bin
reserved screen in the following format:
* *1*P* 0211011041111

For information on reserved screens and tamper data, refer to

“Appendix A ‐ Reserved Screens” and “Appendix E ‐ Device
Identifiers” of the APTRA Advance NDC, Reference Manual.

On a BRM device, when a dispense is attempted from a cassette and

Handling Incorrect a note with incorrect denomination is found, then the note is moved
Denomination and Short to the cassette configured for that denomination. During movement
Dispense 5 of the note, if the cassette becomes high, then an unsolicited
message (w0)is sent with the cassette status.
If none of the cassettes are configured for that denomination, then
the note is moved to the reject bin.
The above functionality can be enabled using the following
(DWORD) registry entry:
HKLM\SOFTWARE\NCR\XFS BRM Service
Provider\XFS-DeviceControl\BRM\Operations\ClearIncom
pleteStack

For example, a $10 denomination note is loaded in a cassette

configured for $20 denomination and when any dispense is
attempted, the $10 note is moved to the cassette configured for the
$10 note.

Note: The re‐stacking of the incorrect denomination notes to the

configured cassette is attempted for three times. After the three
attempts, the application reports an error.
The notes count is reported in Display Supplies Counters ‐ Cash
(DISP CASH) Supervisor option. The same counts are also printed
when the Print Supplies Counters (PRNT CNTRS) option is
executed. The j0085, j0086, j0087 and j0088 screens are displayed
only when NOTES PICKED or NOTES ADDED count is available.
When a dispense is attempted from a recycle cassette and that
cassette contains insufficient notes (short dispense) then the picked

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-309

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

notes are moved either to the same cassette from where notes were
picked or the reject bin as per the registry configuration.
During a dispense transaction, when notes are requested from a bill
cassette and if there are insufficient notes, then the picked notes are
moved to the reject bin irrespective of the registry setting.
The following table describes the registry with the name
ClearIncompleteStack:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-310 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Figure 5-80
BRM Registry Entry for Handling Incorrect
Denomination and Insufficient Dispense

Registry Entry Value Description

HKLM\SOFTWARE\NCR\XFS BRM Service Provider\XFS-DeviceControl\BRM\Operations

ClearIncompleteStack 2 Defines how the stack of notes (requested by the

consumer) which contains incorrect or
insufficient notes is handled. Possible values are
as follows:

0 ‐ Move all the incorrect denomination notes to

the cassette configured for that respective
denomination.

In a short dispense, notes are left in the stacker

and application moves the notes to the reject bin.
Also a WFS_EXEE_CDM_INCOMPLETEDISPENSE
event is received from the XFS platform.

1 ‐ Move all the incorrect denomination notes to

the cassette configured for that respective
denomination.

In a short dispense, move all the stacked notes to

the cassette from where it was picked; no
attempts are made to dispense the notes again
from the cassette.

Note: The notes may be removed from one or

more cassettes and then re‐inserted, so it may be
possible for a cassette to change state and return
to their original state. For example, before
initiating a dispense transaction, the cassette
status is empty. After the dispense transaction is
initiated, some notes may have been moved to the
cassette due to incorrect denomination, and the
cassette status changes to low. Similarly, the
cassette status can change from low to empty due
to movement of notes.

2 (default) ‐ Move all the incorrect denomination

notes to the reject bin.

In a short dispense, move the notes to the reject

bin.

Note: It is also possible that a single large stack

may fill the upper exception bin if configured as a
reject bin.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-311

Configuring Advance NDC and Associated Components
Configuring Cash Handlers

Journaling Moved Notes 5

During a dispense transaction, for incorrect denomination notes,

whenever the notes are moved to a configured cassette and the
NOTES PICKED or NOTES ADDED counts are updated, the following
message is journaled (reserved screen j0084):
WRONG NOTES DETECTED- MOVED TO CONFIGURED CASSETTES

Note: If same number of notes are picked and added to a cassette,

then the NOTES PICKED or NOTES ADDED counts are not updated and
message will not be journaled.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-312 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Configuring Cash Acceptors 5

This section describes the configuration options for cash acceptor

and recycling devices when used for the following types of
transaction:
 Cash deposit
 Cash deposit and dispense
 Recycling.
Cash acceptors (also known as BNAs and GBNAs) and recycling
units (also known as GBRUs and BRMs) are configured both by
updating registry keys and by editing CashInCustom.accfg. Where
configuration is done using the class configurator file, default
configuration settings are included in the CashInCustom.accfg file
installed with Advance NDC. For information on the
CashInCustom.accfg file see “.NET Class Configurator Files” on
page 5‐40.

Note: Any references to GBXX mean that the information can apply
to both recycling units and cash acceptors with configurable
cassettes.

The following registry entries are set during installation and must
Cash Acceptor Installation not be changed:
Settings 5

HKLM\SOFTWARE\NCR\Aptra Self-Service Support (NCR

Features)\R32BunchNoteAcceptor\Operational Parameters\
Disable Automatic Resets

HKLM\SOFTWARE\NCR\XFS CIM Service

Provider\XFS-DeviceControl\CIM\GENERAL_CONFIGS\
ResetActionOnInitialise

HKLM\SOFTWARE\NCR\XFS CIM Service Provider\XFS-Device

Control\CIM\Interoperability\
ExpandCIMRetractNoteList

HKLM\SOFTWARE\NCR\XFS CIM Service Provider\XFS-Device

Control\CIM\Interoperability\
IgnoreCashUnitNumberOnReset

HKLM\SOFTWARE\NCR\XFS CIM Service Provider\XFS-Device

Control\CIM\Interoperability\
ReportSeparateCashUnits

HKLM\SOFTWARE\NCR\GBRU-GBNA Service
Provider\XFS-DeviceControl\ GBRU-GBNA\Interoperability\
ChangeSoftwareErrorCIM

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-313

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Scalable Deposit Module 5

A cash acceptor that can accept either cash or cheques but not both
in a single transaction can be used as a scalable deposit module
(SDM). An SDM is an NCR device that can accept both notes and
cheques.
The following table describes the registry entries and the values that
are set to allow cash deposits:

Table 5-107
SDM Registry Entries

Registry Entry Value Description

HKLM\SOFTWARE\ActiveXFS\

CashInModule1 CashInModule1 Allows cash deposit transactions on SDMs

HKLM\SOFTWARE\NCR\XFS SDM Service Provider\XFS-DeviceControl\SDM\Interoperability\

ExpandCIMRetractNoteList 1 Retracted note counts for deposit transactions are

journaled
If set to 0, notes retracted during a deposit
transaction are not journaled

AlwaysAllowCapabilities 1 If no device is present, the Capabilities command

is successful
If set to 0, the Capabilities command is
unsuccessful when no device is present
For more information on the Capabilities
command, refer to the APTRA online
documentation under APTRA XFS |
Programmer’s Reference | XFS Service
Providers | XFS GBRU‐GBNA Service Provider
| CIM Class Capabilities

DepositMode 0 Accept only cash or cheques in a single

transaction
The depositing of both cash and cheques in a
single transaction (a value of 1) is not supported

HKLM\SOFTWARE\NDC\XFS SDM Service Provier\XFS-DeviceControl\SDM\Operations\

SuspendTimeout 900 Defines the time in seconds for which the device
is suspended when tampering by the consumer is
suspected

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-314 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Bunch Recycling Module 5

A recycler device that can accept or dispense notes as configured.

The following table describes the registry entries and the values that
are set to allow cash deposits:

Table 5-108
BRM Registry Entries

Registry Entry Value Description

HKLM\SOFTWARE\ActiveXFS\

CashInModule1 BRMAcceptor1 Allows cash deposit transactions on BRMs

HKLM\SOFTWARE\NCR\XFS BRM Service Provider\XFS-DeviceControl\BRM\Interoperability\

AlwaysAllowCapabilities 1 If no device is present, the Capabilities command

is successful.
If set to 0, the Capabilities command is
unsuccessful when no device is present

HKLM\SOFTWARE\NDC\XFS BRM Service Provier\XFS-DeviceControl\BRM\Operations\

SuspendTimeout 900 Defines the time in seconds for which the device
is suspended when tampering by the consumer is
suspected.

The following table describes the registry entries that can be

updated by the customer for cash deposit on BRM devices.

Table 5-109
BRM Registry Entry for User Update

Registry Entry Value Description

HKLM\SOFTWARE\NDC\XFS BRM Service Provier\XFS-DeviceControl\BRM\Operations\

P6Mode 0 Defines the mode of note categorisation. Valid

values are as follows:
0 ‐ All notes are identified as either category 1 or
category 4
1 ‐ Notes are identified as category 1, 2, 3 and 4
 Category 2 notes are stored in the cash unit
 Category 3 notes are returned to the card
holder
2 ‐ Notes are identified as category 1, 2, 3 and 4
 Category 2 and Category 3 notes are stored in
the cash unit.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-315

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Miscellaneous Configuration 5

To complete device configuration, the following tables define the

registry entries that must be updated to use the specified values. All
entries for GBxx and BRM are under the following registry key:
HKLM\Software\NCR\Advance NDC\

Table 5-110
Recycling Unit: GBxx Registry Entries Set
by Advance NDC
Registry Entry Description Update Value To..

Aliases\Cash Dispenser Specifies that the cash handler is a recycling BillDispenser1

unit
Aliases\Cash Dispenser Second The alias for whichever <Cash
Dispenser> is being used as a recycling
unit must be updated. Only one recycling
unit is supported on an SST.

CashRecycler\PhysicalCassettes\Top Defines the name of the physical cassette in Cassette 1

the top position

CashRecycler\PhysicalCassettes\Second Defines the name of the physical cassette in Cassette 2

the second position

CashRecycler\PhysicalCassettes\Third Defines the name of the physical cassette in Cassette 3

the third position

CashRecycler\PhysicalCassettes\Fourth Defines the name of the physical cassette in Cassette 4

the fourth position

CashRecycler\PhysicalCassettes\Reject Defines the name of the physical cassette in Reject bin

the reject bin position

Table 5-111
Recycling Unit: BRM Registry Entries set
by Advance NDC

Registry Entry Description Update Value To..

Aliases\Cash Dispenser Specifies that the cash handler is a recycling BRMDispenser1

unit
Aliases\Cash Dispenser Second The alias for whichever <Cash
Dispenser> is being used as a recycling
unit must be updated. Only one recycling
unit is supported on an SST.

CashRecycler\PhysicalCassettes\Top Defines the name of the physical cassette in Cassette 1

the top position

CashRecycler\PhysicalCassettes\Second Defines the name of the physical cassette in Cassette 2

the second position

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-316 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Registry Entry Description Update Value To..

CashRecycler\PhysicalCassettes\Third Defines the name of the physical cassette in Cassette 3

the third position

CashRecycler\PhysicalCassettes\Fourth Defines the name of the physical cassette in Cassette 4

the fourth position

CashRecycler\PhysicalCassettes\Reject Defines the name of the physical cassette in Lower

the reject bin position Exception Bin
Top

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-317

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Table 5-112
Cash Recycler: Registry Entries for
User Update
Registry Entry Description Update Value To..

supervisor\ClearCashHandlerCmd Ensures that the recycling unit is cleared 0x141

using a reset rather than a reject command
after the following:
 Suspend
 Exit from Supervisor
 Test Cash operation
 STD Cash operation

CurrencyTable Defines the Advance NDC Currency Types. Must match the
contents of the
GBRUConfig.xml
file for GBXX
devices and the
BRMConfig.XML
file for BRM
devices

CashRecycler\DispenseDisableThreshold Used when the recycling unit is in recycling Update as

mode. required
Defines the number of notes remaining in a
recycling cassette when the cassette is to be
reported as out of notes
The default value is 0. If the value is missing
or is greater than the
DispenseEnableThreshold value, the
default is used

CashRecycler\DispenseEnableThreshold Used when the recycling unit is in recycling Update as

mode. required
Defines the number of notes remaining in a
recycling cassette when the cassette is to be
reported as good having previously been
reported as being out of notes
The default value is 1. If the value is missing
or is less than the
DispenseDisableThreshold value, the
default is used

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-318 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

CashRecycler\ReportCDMRetractCounts Used to enable the storing, printing and If retract note

displaying of counts for notes retracted in counts, total
dispense operations when a recycling unit is retracted counts
present and Enhanced Configuration option and total rejected
45 has bits 3 and 6 set counts for
Along with the individual counts of notes dispense
retracted for each CDM NDC cassette type, operations are
the total retracted and total rejected counts required, set to 1
are also logged
Valid values are as follows:
 0 ‐ do not report retract note counts, total
retracted counts and total rejected
counts for dispense operations
 1 ‐ report retract note counts, total
retracted counts and total rejected
counts for dispense operations
The default value is 0, retract note counts,
total retracted counts and total rejected
counts for dispense operations will not be
reported. If the value is missing or is any
value other than 0 and 1, the default is used

CashRecycler\ClearRecycler Used to enable clearing of cash‐in error Update as

during the Test Cash operation and cash‐out required
error during the INIT BNA operation when
the device is a recycler
Valid values are as follows:
 0 ‐ Do not clear the cash‐in error during
the Test Cash operation and cash‐out
error during the INIT BNA operation
 1 ‐ Clear the cash‐in error during the
Test Cash operation and cash‐out error
during the INIT BNA operation

A cassette can be configured for deposit, recycling or dispense

transactions. To use cash‐in/cash‐out functionality on a recycling
unit, at least one physical cassette must be configured for depositing
notes and at least one must be configured for dispensing notes.
For GBxx, the reject bin contains three partitions, as follows:
 Reject area
 Retract area
 Counterfeit area.
For BRM, there are two lower exception bins and one optional
upper exception bin.
For information on mapping of physical bins to NDC cassette types,
refer to section “Mapping Physical Bins” in Chapter 7, “Status, Error
and Exception Reporting” of the APTRA Advance NDC Supervisorʹs
Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-319

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

In the Cash Accept state, you can use a dynamic text dictionary
Positioning the Reason for control sequence to define the reasons for refusing notes.
Note Refusal 5

The RefuseReasonMask property of the CashInCustom.accfg file is

used to position the text on the screen as follows:
<Property Name="RefuseReasonMask"
Value="Display Text {0:000}">

To use a screen other than the default Please Wait screen (reserved
Defining the Please Wait screen C20) during a cash deposit transaction, update the value of
screen 5
the WaitScreen property of the CashInCloseFlow Config class.
The default entry is as follows:
<Property Name="WaitScreen" Value="C20" />

The audio volume during a cash deposit transaction can be set using
Setting the Volume 5

the AudioVolume property of the NDCCashAcceptService class.

The range is from 1 to 1000, inclusive and the default entry is as
follows:
<Property Name="AudioVolume" Value="750" />

If a cash acceptor is part of a combined cash handler (a recycling

Combined Cash Handler 5

unit configured to use the CDM interface for dispensing cash and
the CIM interface to accept cash deposits) you can set the following
property of the CashInStatusHandler class to associate the cash
acceptor with a dispenser for tamper indication reporting:
<Property Name="CombinedDispenserNumber" Value="1" />

Valid values are 1 for the primary cash handler and 2 for the
secondary cash handler.

The number of bunches of notes that can be accepted in a single

Setting the Insertion Limit transaction is limited only by the maximum note limits of the
for Bunches of Notes 5
escrow or cassettes.
The number of bunches of notes can also be limited by setting an
explicit value in the AcceptedBunchLimit property of the
CashAcceptStateFlowConfig class. The default value means that
the limit is defined by the capabilities of the device as follows:
<Property Name="AcceptedBunchLimit" Value="0" />

If the insertion limit is reached, the option to add more notes is

disabled on the confirmation screen.
To apply a specific limit, update the value to the number of bunch
insertions to allow. For example, a value of ‘5’ allows up to five
bunches of notes to be inserted in a single transaction.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-320 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

The screen used to journal that the retry limit has been reached is
defined using the CashInJournalRecordMapping array, as
described in “Reserved Screen Mapping” on page 5‐382.

If all notes in a bunch are rejected, the consumer can repeat the
Setting the Retry Limit for attempt to insert the bunch until the configured limit of retries is
Note Insertion 5
reached.

Note: The retry limit applies to all failed attempts to insert bunches
of notes during a single transaction. This means that the limit can be
reached even if the failed attempts are not consecutive.

If repeated attempts to insert bunches of rejected notes fail and the

retry limit is reached, the notes are rejected and a prompt to remove
the notes is displayed. If the notes are removed, an unsolicited
message reports a consumer cancellation and the reason (the retry
limit was reached) is journaled. If the notes are not removed, the
notes are either retracted or left at the exit depending on the
behaviour defined by Enhanced Configuration option 45.
If the retry limit is reached and some notes have already been
accepted in previous bunches, the option to add more notes is
disabled on the confirmation screen in the following situations:
 The ECB 6 regulations are not being applied
 The ECB 6 regulations are being applied and notes identified as
counterfeit, suspect, or unrecognised have already been
inserted. If counterfeit notes are to be retained, the notes
retained screen is displayed before the confirmation screen
 Direct deposit is enabled.
The retry limit is configured using the RejectedBunchLimit
property of the CashAcceptStateFlowConfig class as follows:
<Property Name="RejectedBunchLimit" Value="0" />

The default value of ‘0’ means that no limit is applied to the

number of attempts that can be made to re‐insert bunches of notes.
To apply a limit, update the value to the number of attempts to
allow. For example, a value of ‘5’ permits five attempts to insert a
bunch of rejected notes.
The screen used to journal that the retry limit has been reached is
defined using the CashInJournalRecordMapping array, as
described in “Reserved Screen Mapping” on page 5‐382.

By default, the running total of all deposit transactions since the last
Transaction Request Clear BNA was performed (cumulative counts) are not reported in
Cumulative Counts 5
Transaction Request messages.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-321

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

To enable the reporting of cumulative counts, set the

ReportTRequestCumulativeCounts property of the
CashInStatusHandler class as follows:
<Property Name="ReportTRequestCumulativeCounts"
Value="true" />

The retract configuration is defined using the CashInCustom.accfg file

Configuring Note Retract as follows:
to the Escrow 5

 The RetractConfiguration property of the

ECB6CashAcceptService class defines the configuration to use.
The configuration is defined in the class with the same name as
the defined value. By default this is set to
RetractToStackerConfig
 The CounterName property of the RetractToStackerConfig
class defines the name of the counter used to persistently store
the number of retract operations that have been completed
 The NumberOfRetractCounts property of the
RetractToStackerConfig class defines the number of retracts
allowed.
The following extract shows the default entries for these properties
in the CashInCustom.accfg file:
<Class ID="ECB6CashAcceptService"
Name="NCR.APTRA.NDC.CashAcceptService.
ECB6CashAceptServiceCusomized"
Assembly="NCR.APTRA.NDC.CashAcceptService.dll">
<Interface>
<Property Name="RetractConfiguration"
Value="RetractToStackerConfig"/>
</Interface>
</Class>

<Class ID="RetractToStackerConfig"
Name="NCR.APTRA.CashAcceptService.
StdRetractConfiguration"
Assembly="NCR.APTRA.CashAcceptService.dll">
<Interface>
<Property Name="CounterName" Value="RetractCount"
/>
<!--Property Name="NumberOfRetractCounts" Value="2"
-->
</Interface>
</Class>

Enabling Retract to the Escrow 5

By default, the NumberOfRetractCounts property is commented

out in the CashInCustom.accfg file. This means that the default value
of 0 is used, giving infinite retract operations.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-322 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Uncommenting the NumberOfRetractCounts property enables

retract to the escrow (also known as the stacker). The value of 2
means that the first time notes are retracted, they are sent to the
retract area configured in “Error Recovery Modes” on page 5‐365.
The second time notes are retracted, they are sent to the escrow.
Setting the value to 1 means that the first time notes are retracted,
they are sent to the escrow.
If notes are retracted to the escrow, the cash acceptor is reported as
fatal until the notes are removed and either the Initialise BNA or the
Clear BNA Supervisor option has been performed. The notes
remain in the escrow whatever the setting of table entry 8 (BNA
Notes Return/Retain/Leave Flag) of extension state 1 in the Close
state.

Automatic Error Recovery 5

Automatic error recovery must be configured to leave notes in the

escrow (stacker). For further information, see “Error Recovery
Modes” on page 5‐365.

Journaling 5

The destination of the retracted notes is journaled as specified in

“Reporting the Retract Destination” on page 5‐382.

The RetainDestination property of the CashInCloseFlowConfig

Configuring the Retain class in the CashInCustom.accfg file is used to set the destination of
Destination for the notes to either retract bin or deposit cassettes when the notes are
Notes in Escrow 5 found in escrow and the Close state option is set to retain the notes.
The following extract shows the default entry of the property:
<Class ID="CashInCloseFlowConfig"
Name="NCR.APTRA.NDC.CashInFlows.CashInCloseFlowConfig"
Assembly="NCR.APTRA.NDC.CashInFlows.dll">
<Interface>
<!-- Acceptable values: Retract; Cassette -->
<Property Name="RetainDestination" Value="Cassette" />
</Interface>
</Class>

Valid values are as follows::

Retract Move the notes to retract bin

Cassette Move the notes to cassettes (default value)

Note: The cassette counts are updated in Display Counters

supervisor option and the retract counts are updated in Display

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-323

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

BNA Counts supervisor option when the notes are moved to the
retract bin.
The following message is journaled:

CLOSE STATE WITH NOTES PRESENT – ENCASH -<Destination%>

The destination for retained notes is journaled using the text defined
in the RetainDestinationArray array present in the
CashInCustom.accfg file, as follows:
<!-- local strings for CashIn close state Retain Destinations
-->
<Array ID=" RetainDestinationsArray ">
<Element Value="CASSETTES" />
<Element Value="RETRACT BIN" />
</Array>

In a direct deposit transaction, the notes are deposited to the

Enabling Direct Deposit 5

cassettes without being stored in the escrow. The Cash Accept state
defines whether the cash acceptor accepts direct deposits. For
details of the Cash Accept state, refer to Chapter 2, “State Tables” of
the APTRA Advance NDC, Reference Manual.

Note: To ensure that the notes can be successfully reported, bit 1 of

Enhanced Configuration Parameter option 45 must be set to 1 so
that the number of notes that can be accepted is more than 90.

Recycling units, cash acceptors with configurable cassettes (referred

to jointly as GBXX), and single‐note acceptors (SNAs) are capable of
direct deposits with the appropriate registry configuration, as
shown in the table on the next page.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-324 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Table 5-113
Enabling Direct Deposit

Hardware Registry Entry Description

GBXX HKLM\SOFTWARE\NCR\ Specifies the deposit mode.

GBRU-GBNA Service Provider\ Valid values are as follows:
XFS-DeviceControl\GBRU-GBNA\  1 ‐ Move items to the escrow
Interoperability\DepositMode (refundable deposit)
 2 ‐ Move items to the cassettes
(direct deposit).
The default) value is 1 and this allows
you to change the deposit mode from 1
to 2 dynamically.

Single note HKLM\SOFTWARE\NCR\ Specifies the deposit mode.

acceptor XFS SCIM Service Provider\ Valid values are as follows:
XFS-DeviceControl\SCIM\Interoperab  1 ‐ Move items to the escrow
ility\DepositMode (default)
 2 ‐ Move items to the cassettes
(direct deposit).
This must be set to 2 to enable direct
deposit.

Automatically Enabling Direct Deposits 5

The CashInAutoEnabled property of the

CashAcceptStateFlowConfig class determines whether deposits
are automatically enabled while the Confirmation screens are
displayed, as follows:
<Property Name="CashInAutoEnabled" Value="false" />

Valid values are as follows:

false ‐ The Add More FDK must be selected to deposit more
notes
true ‐ Notes can be deposited while the Confirmation screen is
displayed and the Add More FDK must be configured to
000.
For more information on the Confirmation screen, see
“Confirmation Screens During Cash Deposit” on page 5‐126.

Setting the Direct Deposit Limit 5

The number of notes accepted in a direct deposit transaction can be

defined in the following ways:
 Using the Direct Deposit Limit in the Cash Accept state
(extension 4, table entry 6). For details of the Cash Accept state,
refer to Chapter 2, “State Tables” in the APTRA Advance NDC,
Reference Manual

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-325

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 Using the CashInCustom.accfg file. This is used only if the Direct

Deposit Limit in the Cash Accept state uses the default value of
000 (accept the maximum number of notes for the hardware).
When the direct deposit limit is reached no further bunches are
accepted, however, the current bunch will be processed.
The value of the Direct Deposit Limit must prevent the number of
notes from exceeding both the message limit and the setting of
Enhanced Configuration Parameter option 45.
If the configuration is incorrect or the number of notes exceeds the
message limits the counts are reported as follows:
 The journal will be correct
 Messages to the host report the maximum supported by the
field. In this situation, reserved screen U0152 is journaled to
record that the number of deposited notes exceeds the message
field size.
Default Configuration The DefaultDirectDepositLimit 5

property of the CashAcceptStateFlowConfig class in

CashInCustom.accfg specifies the value as follows:
<Property Name="DefaultDirectDepositLimit" Value="700" />

This value means that the direct deposit limit is reached after 699
notes have been deposited in a transaction. As cash deposit is still
enabled, another bunch of up to 200 notes can be inserted.
Therefore, a maximum of 899 notes can be deposited in a single
transaction.

Reporting Direct Deposit Capability 5

The ReportExtendedHardwareConfiguration property of the

CashInStatusHandler class indicates whether to report the
additional four‐character hardware capabilities in the hardware
configuration terminal command response.
Valid values are as follows:
true — Report additional hardware capabilities (default)
false — Do not report additional hardware capabilities

The host application must be able to support both SSTs that include
the additional data and those that do not. For details of the
additional data returned in the command response, refer to the
APTRA Advance NDC Reference Manual.

Displaying Direct Deposit Error Messages 5

Advance NDC can be configured to display an error screen to the

consumer if an error occurs after some notes have been deposited in
a direct deposit transaction. In this situation, the Escrow Full screen

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-326 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

(Table Entry 6 in Extension 1 to State > — Cash Accept) is used so

that the Add More option is not available. The following screen
shows an example of the Escrow Full screen with an optional error
message:

Figure 5-81 CONFIRMATION

Direct Deposit Error Screen
REPORT HEADER
5 EUR X 1 = 5
10 EUR X 1 = 10
20 EUR X 1 = 20
50 EUR X 1 = 50
100 EUR X 3 = 300
200 EUR X 1 = 200
TOTAL = 585 EUR

AN ERROR HAS OCCURRED

PLEASE REVIEW YOUR NOTES

<<< DEPOSIT

To configure Advance NDC to display the confirmation screen and

an optional error message, edit CashInCustom.accfg as described
below. For details of the Escrow Full screen table entry, refer to
Chapter 2, “State Tables” of the APTRA Advance NDC Reference
Manual.
To display the confirmation screen, change the value of the
DisplayConfirmationScreenOnError property on the Cash
DepositHandlingStateFlow class to true:

Table 5-114
DisplayConfirmationScreenOnError
Property

Type Description Values

Boolean Enables the Escrow Full screen to be shown if an False

error occurs during a direct deposit transaction The Escrow Full screen is not displayed. If an
after some notes have already been deposited. error occurs, the hardware error screen is
This lets the consumer review the amounts before displayed and the Device Error exit is taken
proceeding. after the timer expires (default).

The Deposit FDK will be active. The Device Error True

exit will be taken on exit from the state, whether The Escrow Full screen is displayed with an
the Deposit FDK is pressed or the Time‐Out state optional error message (see Table 5‐115
times out. “ReportErrorMessage Property” on page 5‐328)
before taking the Device Error exit.

To configure the optional error message, edit the

ReportErrorMessage property on the DefaultConfirmation

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-327

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

ScreenFormatter class (or whichever additional Screen Formatter

classes have been configured) to include a string in the language
you require:

Table 5-115
ReportErrorMessage Property

Type Description Values

String A localised message which is shown when an Empty

error occurs after some notes have already No error message is displayed on the Escrow Full
been deposited in a direct deposit transaction. confirmation screen (default).

Example string:
"|SI|LEAN ERROR HAS OCCURRED|
SI|MDPLEASE REVIEW YOUR NOTES"

Advance NDC can be configured to reject the excess notes in GBXX

Setting the Transaction devices when the deposited notes are more than the deposit limit.
Cash‐In‐Limit 5
The deposit limit can either be the amount or the number of items or
both and is configured by the 5th extension state table entries of the
Cash Accept state. The reason for refusal of notes is displayed on the
screen.
For details of the Cash Accept state, refer to Chapter 2, “State
Tables” of the APTRA Advance NDC, Reference Manual.

Configuration 5

In the CashInCustom.accfg file, the values specified in the

CurrencyCodeMapping arrayID reads the value of the currency that
has the mapping for the currency code (ISO‐XXX format) to
currency ID. This mapping is used to get the currency ID for the
currency code given in the state parameter X of the extension state 5.
<!-- Currency Mapping for Set CashInLimit on Currency
type -->
<Array ID="CurrencyCodeMapping">
<!-- The equals sign is used as the separator -->
<Element Value="GBP=826" />
<Element Value="EUR=978" />
<Element Value="USD=840" />
<Element Value="GEM=276" />
</Array>

On a BRM device, in a deposit transaction, if both recycling and

Configuring Reject and/or cash‐in cassettes are full, bin overflow occurs. When there is a bin
Retract Bin for Depositing overflow and there are no other usable recycling and/or cash‐in
Notes 5 cassettes available, reject and/or retract bins can be configured to

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-328 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

accept the notes as part of the deposit transaction using the

following XFS registry entry:
HKLM\SOFTWARE\NCRNCR\XFS BRM Service Provider\
XFS-DeviceControl\BRM\Operations\BinOverflow

For details about the registry, refer to the APTRA on‐line

documentation under APTRA XFS | Programmer’s Reference |
XFS Service Providers | XFS BRM Service Providers |
Configurable Parameters | Operations.

Note: When both reject and retract bins are configured to accept the
notes, the reject bin takes priority.

When notes are moved to the reject bin as part of a deposit

transaction, the notes count is updated under the following:
 REJECT bin counts in DSP BNA CNTS
 ENCASHED and ESCRW DEPS counts in DISP CNTRS
 TOTAL REJECTED DURING DEPOSIT and REJECTED DURING
DEPOSIT COUNTS in PRN BNA TTLS

When notes are moved to the retract bin as part of a deposit

transaction, the notes count is updated under the following:
 RETRACT bin counts in DSP BNA CNTS
 ENCASHED and ESCRW DEPS counts in DISP CNTRS
 TOTAL REJECTED DURING DEPOSIT and REJECTED DURING
DEPOSIT COUNTS in PRN BNA TTLS

Note: As part of bin overflow, when notes are moved to the reject
bin/retract bin, the known limitations are as follows:

 The application journals this information as MISRECOGNITION

ERROR/NOTES IN REJECT BIN, though the notes are good and
properly recognized.
The notes count is updated under the NOTES IN TRANSPORT
counts in DISP CNTRS.

The Cash Deposit Handling state allows off‐line cash deposits to be

Off‐line Cash Deposit handled in a similar way to the Deposit Media and Refund Media
Handling 5
transaction reply functions used to complete a transaction where
notes have been accepted during the Cash Accept State.

Suppressing Messages 5

In the CashInCustom.accfg file, the SuppressMessages property of

the CashInStatusHandling class determines whether unsolicited
cash‐in status message (DIG ‘w’) are sent to the host, as follows:
<Property Name="SuppressMessages" Value="false" />

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-329

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Valid values are as follows:

false Send all status messages

true Suppress unsolicited status messages, either all

unsolicited messages or as defined in the Off‐line States
array

Receipt Service Provider 5

The ReceiptService property of the

CashDepositHandlingStateFlow class defines the service provider
for the receipt printer. The default entry is as follows:
<Property Name="ReceiptService" Value="NDCReceiptService"
IsLink="true" />

Off‐line States Array 5

This array in CashInCustom.accfg has an ID of OfflineStates and

specifies which NDC states are not to send unsolicited cash‐in status
messages (DIG ʹwʹ). It is used in conjunction with the
SuppressMessages property on the CashInStatusHandler. This
and the Cash Deposit Handling state allow cash deposits to be
handled without host control. Consequently, there may be a
requirement to suppress the sending of status messages. It also
allows other States such as the Cash Accept state to have their
messages suppressed. This may be required when other states are
used in conjunction with the offline Cash Deposit Handling state.
The array defines a list of state types which are to be considered
off‐line and therefore do not send unsolicited cash‐in status
messages (DIG ʹwʹ). The state types are entered in the form of
strings. The array accepts single‐character state types or extended
state types, that is, ʹzʹ followed by a three‐digit number, for example,
ʺz014ʺ.
For example, the following string values can be used to suppress
unsolicited messages for the respective states:

Table 5-116 String Value State

Examples of Strings for the Off-Line States
Array ʺ>ʺ Cash Accept state

ʺIʺ Transaction Request state

ʺJʺ Close state

ʺz014ʺ Cash Deposit Handling state

If the specified state value is not recognised, it is ignored.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-330 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

If all unsolicited cash‐in messages are to be suppressed, keep the

array empty, and set the SuppressMessages property in the
CashInStatusHandler to true.

Example of the Off‐line States Array The following example 5

suppresses unsolicited cash‐in status messages for the Cash Accept

and Cash Deposit Handling states:
<Array ID="OfflineStates"n >
<Element Value="z014" />
<Element Value=">" />
</Array>

Note: This does not affect solicited cash‐in status messages.

Due to the size of the signature data, the serial numbers of notes can
Reading, Journaling and only be journaled to the EJ if it is enabled.
Capturing Serial Numbers
of Notes 5
Reading the Serial Numbers 5

To read the serial numbers, the SST must have either a GBXX with a
dual‐camera bill validator or a BNA with an HBV (Revision H Bill
Validator), a BRM, or an SDM capable of reading serial numbers
installed.

Note: For the GBXX, BNA, BRM and SDM devices, no registry
settings are required to journal the serial number information of the
notes.

Along with the serial numbers of notes, the filename, location,

currency and denomination of the notes can also be journaled by
setting the properties under the SerialNumberJournalConfig
class in the CashInCustom.accfg file.
On a BRM device, the serial number information of deposited notes
is logged to the ECB6Log database file. This file is located in the
C:\Program Files\NCRAPTRA\AdvanceNDC\PersistedData\
ECB6Log folder.

Configuration for Journaling Serial Number

Information 5

Use this to format the output (journal) of serial number information

on EJ.
Name
NCR.APTRA.NDC.SerialNumberAndSignatureFormatter.
SerialNumberJournalConfig

Assembly
NCR.APTRA.NDC.SerialNumberAndSignatureFormatter.dll

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-331

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Table 5-117
Serial Number Journal Configuration
Properties
Property Name Type Description Possible values Default Value

CAT4Serial String Determines the Non‐empty string CAT4 SERIAL

NumberInfo header when serial NUMBERS:
Header number If empty then the header is not added
information of
Category 4 (good)
notes is journaled to
EJ

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-332 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Property Name Type Description Possible values Default Value

Cat4Serial String Determines the {CurrencyName} {SerialNumber}

NumberLayout layout of fields to {Denomination}{SerialNumber}
report the currency {FileName}{Location}
names,
denominations, Serial Number Information:
serial numbers, file  CurrencyName ‐ This is replaced
name and location, with the currency type of the note,
when serial number for example USD.
information of  Denomination ‐ This is replaced
category 4 notes is with the denomination of the note,
journaled to EJ. for example 100.
 SerialNumber ‐ This is replaced
Each field is defined
with the serial number of the note,
as {fieldname}
for example X81328508714.
 FileName ‐ This is replaced with
the name of the serial number
image file (applicable only for
deposit transactions)
 Location ‐ This is replaced with the
location of the note, for example
CASHUNIT
For information on possible values
of location, refer to Chapter 7,
“Journaling Serial Numbers and
Failed Reads in a Deposit
Transaction” in the APTRA
Advance NDC, Supervisor Guide.

The fields within the template are

interchangeable and user can remove
few fields. For example, if user wants
to journal only the serial number and
currency, then the template must be
defined as
{CurrencyName}{SerialNumber}

If the template is not defined

according to the format or if any field
name is mismatched, then that field is
ignored. See Note 1: for examples of
incorrect formats.

Note: Do not set this property to

empty. If empty, then Serial Number
Read (SNR) information is not logged
to the EJ.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-333

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Property Name Type Description Possible values Default Value

PrintCAT4 Boolean Determines  True: Log the category 4 serial True

SerialNumbers whether or not the number information to EJ
category 4 serial  False: Do not log the category 4
number serial number information to EJ
information must
be logged to EJ.
CAT3Serial String Determines the Non‐empty string CAT3 SERIAL
NumberInfoHea header when serial NUMBERS:
der number If empty then the header is not added
information of
Category 3
(suspect) notes is
journaled to EJ.
Cat3Serial String Determines the {CurrencyName} {SerialNumber}
NumberLayout layout of fields to {Denomination}
report the serial {SerialNumber}
numbers, location, {FileName}
{Location}
file name, currency
names and
denominations See “Serial Number Information:” on
when serial number page 5‐333 for detailed information on
information of the values
category 3 notes is
journaled to EJ. See Note 1: for examples of incorrect
format.
Each field is defined
as {fieldname}
PrintCAT3 Boolean Determines  True: Log the category 3 serial True
SerialNumbers whether or not the number information to EJ
serial number  False: Do not log the category 3
information of serial number information to EJ
category 3 notes
must be logged to
EJ.
CAT2Serial String Determines the Non‐empty string CAT2 SERIAL
NumberInfoHea header when serial NUMBERS:
der number If empty then the header is not added
information of
Category 2
(counterfeit) notes
is journaled to EJ

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-334 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Property Name Type Description Possible values Default Value

Cat2Serial String Determines the {CurrencyName} {SerialNumber}

NumberLayout layout of fields to {Denomination}
report the serial {SerialNumber}
numbers, location, {FileName}
{Location}
file name, currency
names and
denominations See “Serial Number Information:” on
when serial number page 5‐333 for information on the
information of values
category 2 notes is
journaled to EJ. See Note 1: for examples of incorrect
format.
Each field is defined
as {fieldname}
PrintCAT2 Boolean Determines  True: Log the category 2 serial True
SerialNumbers whether or not the number information to EJ
serial number  False: Do not log the category 2
information of serial number information to EJ
category 2 notes
must be logged
PrintCAT2 Boolean Determines  True: Logs the failed category 2 True
FailedSerial whether or not the serial number count to EJ
NumberCount count, location and  False: Do not log the failed
filename of the category 2 serial number count to
failed serial number EJ
reads of category 2
notes must be
See Note 2: for failed serial number
logged to EJ
reads format.
PrintCAT3 Boolean Determines  True: Logs the failed category 3 True
FailedSerial whether or not the serial number count to EJ
NumberCount count location and  False: Do not log the failed
filename of the category 3 serial number count to
failed serial number EJ
reads of category 3
notes must be
See Note 2: for failed serial number
logged to EJ
reads format.
PrintCAT4 Boolean Determines  True: Logs the failed category 4 True
FailedSerial whether or not the serial number count to EJ
NumberCount count location and  False: Do not log the failed
filename of the category 4 serial number count to
failed serial number EJ
reads of category 4
notes must be
See Note 2: for failed serial number
logged to EJ
reads format.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-335

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Property Name Type Description Possible values Default Value

CurrencyNames Array Specifies the array Any string referring to the currency CurrencyNames
of strings for name mapping array. Mapping
localization of
currency names If this is configured, the configured
data will be printed instead of
Format: {CurrencyName} field defined in the
currencyName=loc layout
alisedCurrency
Name
Example
USD=$
CZK=Kc

Where the equal

sign is used as the
separator

Note 1: Following are few examples which show the incorrect

formats of the template.
{CurrencyNameDenomination}{SerialNumber}

In the above format, braces are missing between the fields, so only
serial number is journaled
{Currency}{Denomination}{SerialNumber}

In the above format, Currency is not matching with CurrencyName,

so only denomination and serial number are journaled.

Note 2: For failed serial number reads, the filename and location of
the note are logged if they are included in the layout. The format
looks similar to the following:
FAILED SERIAL NUMBER READS:<NEW LINE CHARACTER> CAT4 NOTES:
<count><NEW LINE CHARACTER> Filenames <NEW LINE
CHARACTER><location> - <count><NEW LINE CHARACTER> CAT3 NOTES
: <count><<NEW LINE CHARACTER> Filenames <NEW LINE
CHARACTER><location> - <count><NEW LINE CHARACTER> CAT2
NOTES:<count><NEW LINE CHARACTER> Filenames <NEW LINE
CHARACTER><location> - <count>

For more information on journaling serial numbers, location and

filename, refer to Chapter 7, “Journaling Serial Numbers and Failed
Reads in a Deposit Transaction” in the APTRA Advance NDC,
Supervisor Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-336 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

The following example shows the default format in the

CashInCustom.accfg file:

<!-- Serial Number config for journal -->

<Class ID="SerialNumberEJConfig"
Name="NCR.APTRA.NDC.SerialNumberAndSignatureFormatter.SerialNumberJournalConfig"
Assembly="NCR.APTRA.NDC.SerialNumberAndSignatureFormatter.dll">
<Interface>
<PropertyName="CAT4SerialNumberInfoHeader" Value="CAT4 SERIAL NUMBERS:" />
<Property Name="CAT4SerialNumberLayout" Value="{SerialNumber}"/>
<Property Name="PrintCAT4SerialNumbers" Value="True" />
<Property Name="CAT3SerialNumberInfoHeader" Value="CAT3 SERIAL NUMBERS:" />
<Property Name="CAT3SerialNumberLayout" Value="{SerialNumber}"/>
<Property Name="PrintCAT3SerialNumbers" Value="True" />
<Property Name="CAT2SerialNumberInfoHeader" Value="CAT2 SERIAL NUMBERS:" />
<Property Name="CAT2SerialNumberLayout" Value="{SerialNumber}"/>
<Property Name="PrintCAT2SerialNumbers" Value="True" />
<Property Name="PrintCAT2FailedSerialNumberCount" Value="True" />
<Property Name="PrintCAT3FailedSerialNumberCount" Value="True" />
<Property Name="PrintCAT4FailedSerialNumberCount" Value="True" />
<Property Name="CurrencyNames" Value="CurrencyNamesMapping" IsArray="true" />
</Interface>
</Class>

Configuration for Printing Serial Number Information on

Receipt Use this to format the output (print) of serial number 5

information on receipt
Name
NCR.APTRA.NDC.SerialNumberAndSignatureFormatter.
SerialNumberReceiptConfig

Assembly
NCR.APTRA.NDC.SerialNumberAndSignatureFormatter.dll

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-337

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Table 5-118
Serial Number Receipt Configuration
Properties

Property Name Type Description Possible values Default Value

Cat4Serial String Determines the {CurrencyName} {SerialNumber}

NumberLayout layout of fields to {Denomination}{SerialNumber}
report the serial
numbers, currency Serial Number Information:
names and  CurrencyName ‐ This is replaced
denominations with the currency type of the note,
when serial number for example USD.
information of  Denomination ‐ This is replaced
category 4 notes is with the denomination of the note,
printed on receipt. for example 100.
 SerialNumber ‐ This is replaced
Each field is defined
with the serial number of the note,
as {fieldname}
for example X81328508714.

The fields within the template are

interchangeable and user can remove
few fields. For example, if user wants
to print only the serial number and
currency, then the template must be
defined as
{CurrencyName}{SerialNumber}

If the template is not defined

according to the format or if any field
name is mismatched, then that field is
ignored. See Note 1: for examples of
incorrect formats.

Note: Do not set this property to

empty. If empty, then Serial Number
Read (SNR) information is not printed
on the receipt.
PrintCAT4 Boolean Determines  True: Prints the category 4 serial False
SerialNumbers whether or not the number information on receipt
category 4 serial  False: Do not print the category 4
number serial number information on
information must receipt
be printed on
receipt.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-338 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Property Name Type Description Possible values Default Value

CAT3Serial String Determines the {CurrencyName} {SerialNumber}

NumberLayout layout of fields to {Denomination}
report the serial {SerialNumber}
numbers, currency
names and See “Serial Number Information:” on
denominations page 5‐338 for detailed information on
when serial number the values
information of
category 3 notes is
printed on receipt.

Each field is defined

as {fieldname}
PrintCat3 Boolean Determines  True: Prints the category 3 serial False
SerialNumbers whether or not the number information on receipt
serial number  False: Do not print the category 3
information of serial number information on
category 3 notes receipt
must be printed on
receipt.
Cat2Serial String Determines the {CurrencyName} {SerialNumber}
NumberLayout layout of fields to {Denomination}
report the serial {SerialNumber}
numbers, currency
names and See “Serial Number Information:” on
denominations page 5‐338 for detailed information on
when serial number the values
information of
category 2 notes is
printed on receipt.

Each field is defined

as {fieldname}
PrintCAT2 Boolean Determines  True: Prints the category 2 serial False
SerialNumbers whether or not the number information on receipt
serial number  False: Do not print the category 2
information of serial number information on
category 2 notes receipt
must be printed on
receipt
SerialNumber String Determines the , (Comma)
Separator delimiter character
OnReceipt between the serial
numbers that are
printed on receipt

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-339

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Property Name Type Description Possible values Default Value

PrintCAT2 Boolean Determines  True: Prints the failed category 2 False

FailedSerial whether or not the serial number count on receipt
NumberCount count of the failed  False: Do not print the failed
serial number reads category 2 serial number count on
of category 2 notes receipt
must be printed on
receipt
PrintCAT3 Boolean Determines  True: Prints the failed category 3 False
FailedSerial whether or not the serial number count on receipt
NumberCount count of the failed  False: Do not print the failed
serial number reads category 3 serial number count on
of category 2 notes receipt
must be printed on
receipt
PrintCAT4 Boolean Determines  True: Prints the failed category 4 False
FailedSerial whether or not the serial number count on receipt
NumberCount count of the failed  False: Do not print the failed
serial number reads category 4 serial number count on
of category 2 notes receipt
must be printed on
receipt
CurrencyNames Array Specifies the array Any string referring to the currency CurrencyNames
of strings for name mapping array. Mapping
localization of
currency names If this is configured, the configured
data will be printed instead of the
Format:: {CurrencyName} field defined in the
currencyName=loc layout
alisedCurrency
Name
Example
USD=$
CZK=Kc

Where the equal

sign is used as the
separator

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-340 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

The following example shows the default format in the

CashInCustom.accfg file:

<!-- Serial Number config for receipt -->

<Class ID="SerialNumberReceiptConfig"
Name="NCR.APTRA.NDC.SerialNumberAndSignatureFormatter.SerialNumberJournalConfig"
Assembly="NCR.APTRA.NDC.SerialNumberAndSignatureFormatter.dll">
<Interface>
<Property Name="CAT2SerialNumberLayout" Value="{SerialNumber}" />
<Property Name="CAT3SerialNumberLayout" Value="{SerialNumber}" />
<Property Name="CAT4SerialNumberLayout" Value="{SerialNumber}" />
<Property Name="PrintCAT2SerialNumbers" Value="False" />
<Property Name="PrintCAT3SerialNumbers" Value="False" />
<Property Name="PrintCAT4SerialNumbers" Value="False" />
<Property Name="PrintCAT2FailedSerialNumberCount" Value="False" />
<Property Name="PrintCAT3FailedSerialNumberCount" Value="False" />
<Property Name="PrintCAT4FailedSerialNumberCount" Value="False" />
<Property Name="SerialNumberSeparatorOnReceipt" Value="," />
<Property Name="CurrencyNames" Value="CurrencyNamesMapping" IsArray="true" />
</Interface>
</Class>

Capturing Serial Number Image 5

On a BRM device, the serial number image of a note inserted is

captured and saved to the configured destination. The filename of
the SNR image can also be journaled.
If ECB6 is enabled, the serial number images of good (category 4),
counterfeit (category 2) and suspect (category 3) notes are captured.
If ECB6 is not enabled, the serial number images of good (category
4) notes are captured whenever the notes pass the bill validator.
The serial number images are captured in the following scenarios:
Scenario 1: Deposit 5

In a deposit transaction, when the consumer inserts a note, after the

note validation, the serial number image is captured. For example,
the serial number image is captured with a name similar to
123456_1234_110918_124553_5678_DEP_001.JPG

Scenario 2: Retract 5

On the Confirmation screen in a deposit transaction, when the

consumer selects Refund FDK, the notes are refunded. If the returned
notes are not taken by the consumer, they are retracted and the
serial number images of the retracted notes are captured.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-341

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Any previously captured image of the same note is retained and the
image of the retracted notes is stored in the configured location with
a name similar to
123456_1234_110918_124553_5678_RET_001.JPG.

Scenario 3: Power‐fail 5

The application attempts recovery in the event of a power failure

after the notes are inserted. During recovery, if the notes are present
in the device and are successfully retracted, the serial number
images for all the retracted notes are captured.
Scenario 4: Hardware Error Recovery 5

If a hardware error occurs after the notes are inserted and during
the recovery (INIT BNA from supervisor is performed, supervisor
entry/exit or Close state), the serial number images for all the notes
that are successfully retracted as part of the recovery are captured.

Note: There could be a duplication of serial number images in the

retract and recovery scenarios
The following is the file format of a serial number image:
NNNNNN_TTTT_MMDDYY_HHMMSS_CCCC_OPERATION_XXX.JPG

Table 5-119 Variable Description

Serial Number Image Format
NNNNNN SST Machine Number

TTTT Transaction Serial number

MMDDYY Date in a format dependent on Enhanced

Configuration Option 3

HHMMSS Time in HHMMSS format

CCCC Last four digits of the consumer’s card

number

OPERATION DEP ‐ After the user inserts a note and the

validation is done
RET ‐ After notes are retracted and validation
is done
REC ‐ After notes are recovered and
validation is done during a reset operation
after power fail/jam

XXX A number in the range 001‐999 identifying

the sequence of the images if multiple images
are taken during a transaction

Note: Customers must ensure to clear the serial number image files
stored at the configured location.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-342 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

To capture the serial number image, configure the

CaptureSerialNumberImage property in the CashInCustom.accfg
file. To save the captured image of the serial number to a specific
location, configure the SerialNumberImageFilePath property in
the CashInCustom.accfg file. To journal the filename of the serial
number image to the EJ, configure the filename in
CashInCustom.accfg file. For information on how to configure the
filename, see the “Serial Number Journal Configuration Properties”
on page 5‐332.
The properties are described in the following table:

Table 5-120
ECB6CashAcceptService Properties
Property Type Description

CaptureSerialNumberImage Boolean Captures the serial number images of the notes.

If the value is set to True, the serial number image of the notes is
captured and stored in the specified file path.

If the value is set to False (default value), the serial number image
of the notes is not captured.

SerialNumberImageFile String Specifies the path to save the captured serial number image of the
Path notes.

The default path configured in CashInCustom.acccfg file is:

C:\Program Files\NCR APTRA\Advance NDC
\PersistedData\SerialNumberImageFiles.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-343

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

The following extract shows default entries for capturing the serial
number image and the path to store the image in the
CashInCustom.accfg file:

Figure 5-82
Capture Serial Number Image and Path
Extract
<Class ID="ECB6CashAcceptService"
Name="NCR.APTRA.NDC.CashAcceptService.ECB6CashAcceptServiceCustomized"
Assembly="NCR.APTRA.NDC.CashAcceptService.dll">
<Interface>
<!-- Name: CaptureSerialNumberImage
<!-- Type: boolean
<!-- Description: Determines whether Serial Number image will be captured or not.
<!-- Possible Values: True or False -->
<!-- When True Serial number images of the notes will be captured and stored in the
configured file path
<!-- When False Serial number images will not be captured -->
<!-- Default Value: false-->
<Property Name="CaptureSerialNumberImage" Value="false" />
<!-- Name: SerialNumberImageFilePath
<!-- Type: string
<!-- Description: This specifies the path name where Serial number images are saved
<!-- Possible Values: can be configured to the desired location
<!-- Default Value: "C:\Program Files\NCR APTRA\Advance NDC\Persisted
Data\SerialNumberImageFiles"-->
<Property Name="SerialNumberImageFilePath" Value="C:\Program Files\NCR APTRA\Advance
NDC\Persisted Data\SerialNumberImageFiles" />
</Interface>
</Class>

On a BRM device, during a deposit transaction, bunch camera,

Capturing Bunch Note present at the entry or exit slot, captures image of a bunch of notes
Image 5
in the following scenarios:
 When the shutter is closed after notes are inserted.
 Before the shutter is opened to return notes to the consumer.
 When the shutter is closed to retract or recover the notes present
in the pocket.
The above functionality can be enabled using the CaptureBunch
Images registry entry. For information on configuring the capturing
of bunch note image, see “Capturing Bunch Note Image” on
page 5‐289.
The following is a file format of a bunch note image:
NNNNNN_TTTT_MMDDYY_HHMMSS_CCCC_OPERATION.JPG

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-344 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Note: The bunch note image file format of a deposit transaction is

similar to a dispense transaction except the operation information.
For information about the bunch note image file format of a
dispense transaction, see Table 5‐100, “Bunch Note Image File
Format” on page 5‐289.

The operation information of the bunch note image file format of a

deposit transaction is as follows:
 DEP ‐ After notes are inserted
 REJ ‐ After notes are rejected
 REF ‐ When notes are refunded to the consumer
 RET ‐ After notes are retracted
 REC ‐ After notes are recovered during a reset operation after a
shutter jam
The captured bunch note images are stored in the below path:
C:\Program Files\NCR APTRA\Advance NDC\Persisted
Data\BunchImageFiles\Deposit

The bunch note images are captured in the following scenarios:

Scenario 1: Deposit 5

During a deposit transaction, when the consumer inserts notes, the

shutter is closed to process the notes and the bunch note image is
captured with a name similar to
123456__110918_124553_5678_DEP.JPG

Scenario 2: Reject 5

During a deposit transaction, when an invalid note is found, the

note is rejected and the shutter is opened to return the note to the
consumer. When the note is at the exit slot, and before the shutter is
opened to return the note, the bunch note image is captured with a
name similar to
123456__110918_124553_5678_REJ.JPG

Scenario 3: Refund 5

During a deposit transaction, on the Confirmation screen, when the

consumer selects Refund FDK, notes are refunded. When the notes
are at the exit slot and before the shutter is opened to return the
note, the bunch note image is captured with a name similar to
123456__110918_124553_5678_REF.JPG

If refund is initiated form the host, the bunch note image is captured
when the notes are at the exit slot, and before the shutter is opened
to return the notes to the consumer. The bunch note image is
captured for the refunded notes similar to

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-345

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

123456_1234_110918_124553_5678_REF.JPG

Scenario 4: Retract 5

During a deposit transaction, if notes are returned but the consumer

does not take the notes when presented are retracted after the
shutter is closed and the bunch note image is captured with a name
similar to
123456__110918_124553_5678_RET.JPG.

Scenario 5: Error Recovery 5

Hardware Error During a deposit transaction, on the 5

Confirmation screen, when the consumer selects Refund FDK, notes

are refunded. When the notes are at the exit slot and before the
shutter is opened to return the note, if a hardware error occurs, the
bunch note image is captured and error recovery is performed. The
bunch note image is captured with a name similar to
123456__110918_124553_5678_REF.JPG

During the error recovery, the shutter is closed and the bunch note
image is captured for the notes present in the exit slot with a name
similar to
123456__110918_124553_5678_REC.JPG.

The reconciliation list is produced by selecting either 48 DSP BNA

Reconciliation List RCNL or 49 PRN BNA RCNL on the Replenish menu in Supervisor.
Customisation 5
The information to be displayed or printed is created dynamically
using a Variable Operator Text worker.
You can use the entries under the following registry key to localise
the screen and print row headings:

HKLM\SOFTWARE\NCR\Advance NDC\BNA\Reconciliation

In the reconciliation list, the following conventions are used to

position counters and values:
 The counters column heading (CNTRS) occupies columns 18 to
22
 The values column heading (VALUE) occupies columns 25 to 31
 Data is right‐aligned, as follows:
— A 1‐digit counter starts at column 22
— A 3‐digit counter starts at column 20
— A 1‐digit value starts at column 31
— A 3‐digit value starts at column 29

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-346 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Note: If localising the reconciliation list, you must make sure that
the changes do not impinge on the positioning of the counters.

The default settings for the entries are as follows:

Table 5-121 Registry Entry Default Setting

Default Settings for Reconciliation List
RecListRetractedString RETRACT

RecListRetainedString RETAIN

RecListNotesString NOTES

RecListHeaderString BNA RECONCILIATION LIST

RecListDepositedString DEPOSIT

MultipleCurrencyReconSupp 0
Not supported

RecListTotalString TOTAL

Option 58 DSP BNA CNTS and Option 59 PRN BNA CNTS on the
Displaying and Printing Supervisor Replenish menu displays and prints the counts for the
BNA Counts 5
physical cassettes within the device respectively.
The following forms are used to print the counts, display status
messages and prompts on the screen:

Table 5-122
Forms Used for BNA Note Counts

Form Destination Form Location

CashInCountersRPTR.DEF Receipt printer C:\Program Files\NCR APTRA\Printing\Receipt\Forms

CashInCountersJPTR.DEF Journal printer C:\Program Files\NCR APTRA\Printing\Journal\Forms

CashInCountersTTU.frmttu Screen display C:\Program Files\NCR APTRA\Printing\TTU\Forms

Note: The option 58 DSP BNA CNTS uses the

CashInCountersTTU.frmttu form only.

Supervisor Counters Cassette Names Array 5

In the CashInCustom.accfg file, a mapping array is used to specify the

cassette names to be used when displaying or printing Supervisor
counts as follows:
<!-- Cassette Names Mapping for Cash In Supervisor Counters-->
<Array ID="SupCntrsCassetteNamesArray" >
<Element Value="Cassette1=CASS1" />
<Element Value="Cassette2=CASS2" />
<Element Value="Cassette3=CASS3" />

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-347

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<Element Value="Cassette4=CASS4" />

<Element Value="Cassette5=CASS5" />
<Element Value="Retract=RETRACT" />
<Element Value="Reject=REJECT" />
<Element Value="Counterfeit=CNTRFEIT" />
</Array>

The element values have the cassette name on the left of the =
separator and the output value on the right.

Cash‐in Supervisor Counters Configuration 5

The cash‐in Supervisor counters for displaying and printing BNA

counts are configured in the MaxRowsPerPage property of the
CashInSupCntrsConfig class in the CashInCustom.accfg file. By
default, each screen can show up to eight rows of denominations. If
the cassette has more than the maximum defined rows (eight), then
it will roll over to the next screen. If there is any screen that has no
counts or amounts to display, then the strings are configured to
display under the headings as follows:
<Property Name="NoCountsPerDenomString" Value="NO AMOUNTS
PER DENOMINATIONS" />
<Property Name="NoCountsPerCurrencyString" Value="NO
AMOUNTS PER CURRENCY" />
<Property Name="NoCountsForCassetteString" Value="NO
COUNTS FOR THESE CASSETTES" />
<Property Name="NoAmountsForCassetteString" Value="NO
AMOUNTS FOR THESE CASSETTES" />
<Property Name="UnknownDenomString" Value="UNKNOWN" />

Name
NCR.APTRA.NDC.CashInSupervisorTasks.CashInSupCntrsConfig

Assembly
NCR.APTRA.NDC.CashInSupervisorTasks.dll

The following tables describes the cash‐in Supervisor counters’

properties.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-348 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Table 5-123
Cash-In Supervisor Counters’ Properties

Property Name Type Description Possible values Default Value

MaxRowsPerPage Integer The number of Any unsigned integer 8

denominations to display or value. The range of the
print. value is 1 to 8.
NoCountsPer String This string is displayed Any appropriate string NO AMOUNTS PER
DenomString when there are no amounts that fits the screen. DENOMINATIONS
to display under screen
“TOTAL AMOUNTS PER
DENOM”.
NoCountsFor String This string is displayed Any appropriate string NO COUNTS FOR
CassetteString when there are no cassette that fits the screen. THESE CASSETTES
counts under screen “BNA
COUNTS PER
CASSETTES”.
NoAmountsFor String This string is displayed Any appropriate string NO AMOUNTS FOR
CassetteString when there are no amounts that fits the screen. THESE CASSETTES
to display under screen
“BNA AMOUNTS PER
CASSETTES”.
NoCountsPer String This string is displayed Any appropriate string NO AMOUNTS PER
CurrencyString when there are no amounts that fits the screen. CURRENCY
to displays under screen
“TOTAL AMOUNTS PER
DENOM”.
UnknownDenom String This string sets the text to be Any appropriate string UNKNOWN
String displayed or printed when that fits the screen.
there are unknown reject
counts available.

Options 58 DSP BNA CNTS and Option 59 PRN BNA CNTS on the
Printing BNA Totals, Supervisor Replenish menu displays and prints the counts for the
Displaying and physical cassettes within the device respectively. Option 60 PRN
Printing BNA Counts 5 BNA TTLS on the Supervisor Replenish menu prints note counts by
denomination and the total number of notes for different note
counts.

Currency Names Mapping Array 5

In the CashInCustom.accfg file, a mapping array is used to specify the

currency names to be used when printing or displaying Supervisor
counts, as follows:
<!-- Currency Mapping for Cash In journaling. -->
<Array ID="CurrencyNamesMapping" >

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-349

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<!-- The equals sign is used as the separator -->

<Element Value="USD=USD" />
<!-- Element Value="USD=$"/ -->
</Array>

The element values have the ISO currency code on the left of the =
separator and the output value on the right.
The element value with the ISO currency code and the currency
symbol is commented out by default.

Option 60 PRN BNA TTLS on the Supervisor Replenish menu prints

Printing BNA Totals 5

note counts by denomination and the total number of notes for

different note counts. The totals can be printed on any receipt
printer, journal printer or both depending on the selection made
using the SET PRINT option on the Configure menu in Supervisor.
The following forms are used to print the counts and display status
messages and prompts on the screen:

Table 5-124
Forms Used for BNA Note Counts

Form Destination Form Location

CashInPrintTotalsRPTR.DEF Receipt printer C:\Program Files\NCR APTRA\Printing\Receipt\Forms

CashInPrintTotalsJPTR.DEF Journal printer C:\Program Files\NCR APTRA\Printing\Journal\Forms

CashInPrintTotalsTTU.frmttu Screen display C:\Program Files\NCR APTRA\Printing\TTU\Forms

Counts Configuration Array 5

This mapping array in the CashInCustom.accfg file is used to specify

the counts to be used for the print operation. The default settings
provided with Advance NDC for option 60 PRN BNA TTLS on the
Supervisor Replenish menu are as follows:
<!-- CashIn Counters Configuration Array for the BNA Totals
Supervisor Task-->
<Array ID="CountsConfigurationArray">
<Element Value="DepositCounts"/>
<Element Value="RejectedDuringDepositCounts"/>
<Element Value="RetractCounts"/>
<Element Value="TotalDeposit"/>
<Element Value="TotalRejectedDuringDeposit"/>
<Element Value="TotalRetract"/>
<Element Value="TotalEscrow"/>
<Element Value="TotalRefund"/>
<Element Value="TotalReject"/>
<!--Element Value="CashInCassetteDepositCounts"/-->
<!--Element Value="RecycleCassetteDepositCounts"/-->
<!--Element Value="SuspectsNotAuthorisedDepositCounts"/-->
<!--Element Value="OfflineDepositCounts"/-->
<!--Element Value="RetractRecycleCounts"/-->
<!--Element Value="RetractNonRecycleCounts"/-->

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-350 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<!--Element Value="CounterfeitCounts"/-->
<!--Element Value="SuspectCounts"/-->
<!--Element Value="TotalCashInCassetteDeposit"/-->
<!--Element Value="TotalRecycleCassetteDeposit"/-->
<!--Element Value="TotalSuspectsNotAuthorisedDeposit"/-->
<!--Element Value="TotalOfflineDeposit"/-->
<!--Element Value="TotalRetractRecycle"/-->
<!--Element Value="TotalRetractNonRecycle"/-->
<!--Element Value="TotalCounterfeit"/-->
<!--Element Value="TotalSuspect"/-->
</Array>

The counts in bold are printed by default. The other counts can be
added to the report by uncommenting the entries in the array and
the counts for those note groups will be printed as individual counts
as well as in the main group to which they belong.The print order of
the counts follows the order of elements in the array.
The counts include notes not authorised by the host, that is, notes
that have been processed locally at the SST using the Cash Deposit
Handling state. For details, refer to Chapter 2, “State Tables” of the
APTRA Advance NDC Reference Manual.
Details of what each count contains are described in Table 5‐125,
“Counts for Note Groups” on page 5‐352.

Available Counts 5

What is printed for the Print BNA Totals option depends on the
configuration of the Counts Configuration Array. The main groups
are deposit and retract. Counterfeit notes are always reported
separately when ECB6 or P6 mode is enabled. The other counts are
subsets of deposit and retract.
Deposit Counts DEPOSIT COUNTS gives the number of notes 5

deposited since the counts were last cleared, and the sum of their
value, for each denomination, as follows:
 Notes deposited in or recovered to the cash‐in cassettes
 Notes deposited in the recycle cassettes
 Notes that are in the escrow before user confirmation and are
moved to the reject bin after deposit as the second validation
resulted in a misrecognition
 Notes jammed in the transport on their way to the cassettes after
deposit or for direct deposits, notes jammed in the transport after
insertion
 Notes retained in the Close state when the Close state option is
set to retain the notes

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-351

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 Notes identified as suspect (category 3) under the ECB 6

regulations and are one of the following:
— In the cash‐in cassettes
— Not encash authorised, that is, not authorised by the host
because the SST is configured to retain such notes on
insertion

If ECB 6 regulations are not enabled, suspect notes are returned

to the consumer as invalid and included in the rejected totals

 Notes that cannot be accepted to the correct cassette type because,

for example, the cassette for that denomination is full, and are
redirected to the reject bin after an encash operation. Such notes
are also known as excess notes.
Some counts appear in more than one group, which is indicated in
the table.
Retract Counts RETRACT COUNTS gives the number of notes 5

retracted since the counts were last cleared, and the sum of their
value, for each denomination, as follows:
 Notes in the recycle cassette
 Notes in the retract bin
 Notes retracted to the cash‐in cassette
CDI Stores CDI store IDs are also given for those counts that have 5

CDI stores. Some counts do not have CDI stores because the
information is obtained from internal data.

Table 5-125
Counts for Note Groups

Count Description

DEPOSIT (CDI stores 3164 to 3213)

COUNTS The number of notes of each denomination in the groups shown above with the sum of their
value, including the following subsets of counts:

CASH-IN CASSETTE For each denomination, the number of notes deposited in or

DEPOSIT COUNTS recovered to the cash‐in cassettes
(CDI store 5034)

RECYCLE CASSETTE For each denomination, the number of notes authorised by the
DEPOSIT COUNTS host and then encashed or recovered to the recycle cassette

SUSPECTS NOT For each denomination, the number of notes identified as

AUTHORISED DEPOSIT suspect (category 3) under ECB 6 regulations and retained
COUNTS without authorisation from the host.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-352 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Count Description

REJECTED DURING For each denomination, the number of rejected notes as follows:
DEPOSIT COUNTS  Notes in the escrow before user confirmation and moved to
the reject bin after deposit
 Excess notes redirected to the reject bin after an encash
operation
(CDI store 5051)

OFFLINE DEPOSIT For each denomination, the number of notes in the escrow and
COUNTS later authorised off‐line
(CDI store 5053)

SUSPECT COUNTS For each denomination, the number of notes identified as

suspect (category 3) under ECB 6 regulations and deposited in
any cash‐in or retract bin
(CDI store 5043)

RETRACT For each denomination, the number of retracted notes. This includes notes moved to the
COUNTS retract bin, the cash‐in cassettes or the recycle cassettes depending on Enhanced
Configuration Parameters option 74 (“Destination for Cash Deposit Retract”, described in
Chapter 7, “Configuration Parameters” of the APTRA Advance NDC Reference Manual)
(CDI stores 3292 ‐ 3341). This count includes the following subsets of counts:

RETRACT RECYCLE For each denomination, the number of notes retracted or

COUNTS recovered to the recycle cassette
(CDI store 5052)

RETRACT For each denomination, the number of notes:

NON-RECYCLE COUNTS  Recovered or retracted to the retract bin
 Retracted to the cash‐in cassette

COUNTERFEIT For each denomination, the number of notes identified as counterfeit (category 2) notes
COUNTS under ECB 6 regulations; if ECB 6 regulations are not enabled, such note are rejected as
invalid and included in the rejected totals
(CDI store 5042)

Totals Counts The following table gives the total counts for the 5

different groups of notes.

 The TOTAL DEPOSIT count gives the cumulative figures for the
same note groups moved to the cash‐in cassettes (Table 5‐125,
“Counts for Note Groups” on page 5‐352).
 The TOTAL RETRACT count gives the cumulative figures for
notes retracted to the recycle bin and the retract bin
 Other totals described in the table are as follows:
— If ECB 6 regulations are enabled, the total of counterfeit
notes
— The total of notes passing through escrow
— The total of all rejected notes
— The total of all notes refunded to the consumer

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-353

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Table 5-126
Counts for Note Totals

Count Description

TOTAL DEPOSIT The total number of notes, including the following subsets of total counts
(CDI store 3214)

TOTAL CASHIN The total number of notes deposited in or recovered to the

CASSETTE DEPOSIT cash‐in cassettes

TOTAL RECYCLE The total number of notes deposited in or recovered to the

CASSETTE DEPOSIT recycle cassettes

TOTAL SUSPECTS NOT The total number of notes retained in the cassettes but not
AUTHORISED DEPOSIT authorised.

TOTAL REJECTED The total number of notes containing:

DURING DEPOSIT  Notes that were in the escrow and were moved to the reject
bin after being vaulted
 Excess notes redirected to the reject bin after being vaulted
(CDI store 3347)

TOTAL OFFLINE The total number of notes that were in the escrow and later
DEPOSIT authorised off‐line
(CDI store 3776)

TOTAL SUSPECT The total number of notes identified as suspect (category 3

under ECB 6 regulations) and moved to any cash‐in cassette
or retract bin

TOTAL RETRACT The total number of notes moved to the retract bin or the cash‐in cassettes depending on
Enhanced Configuration Parameter option 74, described in Chapter 7, “Configuration
Parameters”, of the APTRA Advance NDC Reference Manual. This count includes the
following subsets of totals:
(CDI store 3765)

TOTAL RETRACT The total number of notes retracted to or recovered to the

RECYCLE recycle cassette

TOTAL RETRACT The total number of notes retracted to or recovered to the

NON-RECYCLE cash‐in cassettes or the retract bin

TOTAL The total number of notes identified as counterfeit (category 2) notes under ECB 6
COUNTERFEIT regulations; if ECB 6 regulations are not enabled, such note are rejected as invalid and
included in the total for rejected notes

TOTAL ESCROW The total number of notes accepted into the escrow
(CDI store 3216)

TOTAL REFUND The total number of notes returned to the refund slot from the escrow
(CDI store 3215)

TOTAL REJECT The number of notes returned during the Cash Accept state. A note is rejected when it
cannot be validated and is returned to the consumer.
(CDI store 3217)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-354 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Enhanced Cash‐in Formatter 5

Use this to format the output for the BNA counts

Name
NCR.APTRA.NDC.CashInFormattingCore.EnhancedCashInFormatter

Assembly
NCR.APTRA.NDC.CashInFormattingCore.dll

Table 5-127
Enhanced Cash-In Formatter Properties

Property Name Type Description Possible values Default Value

TotalString String The string to use when outputting Any string "TOTAL"
the Total amount
TemplateFor String The string template for the Any string "{0} {1} = {2,8}"
TotalLine Total line. The object list adhering to
contains the following: the .NET For example, one note of 20
0—Currency name Framework USD will be output as:
1—Total string (from the Composite
TotalString property) Formatting USD TOTAL = 20
2—Total value of the currency rules
3—Total number of notes for
the currency
TemplateFor String The string template for the Any string "{0, 3} {1, 6} X {2, 3}
ReportLine report line used when the adhering to = {3,8}"
report is formatted for each the .NET
denomination. The object list Framework For example, one note of 10
contains the following: Composite USD will be output as:
0 ‐ Currency name Formatting
1 ‐ Currency value rules USD 1 X 1 = 1
2 ‐ Number of notes
3 ‐ Total value of the currency
(the currency value times the
number of notes)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-355

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Property Name Type Description Possible values Default Value

Include Boolean Indicates whether to use a false false

GroupDigit comma as a digit group Comma will
separator (for example, 1,000) not be used.
while journaling any total
amount true
Comma will
be used.
CurrencyNames Array Specifies the strings to be used Any string CurrencyNamesMapping
for the localised currency equivalent Array
names representing
The string values have the the currency
following comma‐delimited name
format:
currencyName=
localisedCurrencyName,
for example:
{ "USD=$", "EUR=€" }

Print Cash‐in Totals 5

Use this to configure the following:

 Which counts are to be printed
 Duration of the error time‐out
 Whether zero counts are to be reported
 The formatter to be used
Name
NCR.APTRA.NDC.CashInSupervisorTasks.PrintCashInTotals

Assembly
NCR.APTRA.NDC.CashInSupervisorTasks.dll

Table 5-128
Print Cash-in Totals Properties

Property Name Type Description Possible values Default Value

ConfigureCounts Array By default, the elements Any string CountsConfiguration

TobePrinted shown in “Counts referring to an Array
Configuration Array” on array mapper
page 5-350 will be printed.
All other count elements are
commented out. To change
the default output, edit the file
to add or remove the comment
characters from the required
elements in the array

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-356 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Property Name Type Description Possible values Default Value

ErrorTimeout Int A general time-out used to Any unsigned 0

specify the amount of time an integer value. If a (The screen waits
error screen will be displayed time‐out is indefinitely and never
required, set the times out)
value to greater
than 0, for example,
5000 for 5 seconds.
ReportZero Boolean Specifies whether counts False False
Counts with zero values are to be Counts with zero
included in the print report values will not be
included.

True
Counts with zero
values will be
included.
Counters ICounters A cash‐in counters Any concrete class EnhancedCashIn
Formatter Formatter formatter. that implements Formatter
ICounters
Formatter

The reason for refusing a deposit is journaled. The text can be

Reason for Refusing a localised using the CashInCustom.accfg file.
Deposit 5

The default reasons are given in the extract of CashInCustom.accfg in

Figure 5‐83. These entries can be edited to localise the journaled text.

Figure 5-83
Default Input Rejected Reasons
<Array ID="MoneyRejectReasons"a>
<Element Value="CashUnitFull=CASH UNIT FULL" />
<Element Value="InvalidMedia=INVALID MEDIA" />
<Element Value="NoItems=NO ITEMS" />
<Element Value="DepositFailure=DEPOSIT FAILURE" />
<Element Value="ComponentFailure=COMPONENT FAILURE" />
<Element Value="EscrowFull=ESCROW FULL" />
<Element Value="ForeignItemsDetected=FOREIGN ITEMS DETECTED" />
<Element Value="BunchInvalid=BUNCH INVALID" />
<Element Value="CounterfeitItemsDetected=COUNTERFEIT ITEMS DETECTED" />
<Element Value="Jam=JAM" />
<Element Value="HardwareError=HARDWARE ERROR" />
<Element Value="TransactionDepositLimit=CASH IN LIMIT EXCEEDED" />
</Array>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-357

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

When a cash‐in cassette is inserted or removed, a message is

Tamper Indication journaled using the reserved screens U0143 and U0144. These
Journaling 5
reserved screens are used to record individual changes in the
physical bin positions. When a cassette is inserted or removed, a
flexible TI/Sensors unsolicited message is sent to the host with the
status of the cassette positions reported in Buffer C, field w. This
same message is journaled based on Enhanced Configuration
Option 24 setting and is printed before the reserved screen U0145 is
printed. This feature is similar to the journaling of tamper indication
for the cash dispenser cassette. For information on Tamper
Indication Journaling for a cash dispenser cassette, see “Tamper
Indication on an S2 Dispenser” on page 5‐308.
The following reserved screens serve as journal record templates
and can be localised as necessary:
'U0143' 'BNA <CassetteName%> INSERTED'
'U0144' 'BNA <CassetteName%> REMOVED'
'U0145' '<ESC>(I *<TSN%>*1*P*6<StatusData%>,M-<ESC>(1’

The cassette names can be localised using the CashInCustom.accfg

file.
The default cassette names are given in the extract of
CashInCustom.accfg in Figure 5‐85. These entries can be edited to
localise the journaled text.

Figure 5‐84
Default Cassette Names
<Array ID="CassetteNamesArray">
<Element Value="Cassette1=CASSETTE 1" />
<Element Value="Cassette2=CASSETTE 2" />
<Element Value="Cassette3=CASSETTE 3" />
<Element Value="Cassette4=CASSETTE 4" />
<Element Value="Cassette5=CASSETTE 5" />
<Element Value="Retract=RETRACT BIN" />
<Element Value="Reject=REJECT BIN" />
<Element Value="Counterfeit=COUNTERFEIT BIN" />
<Element Value="UnknownCassette=UNKNOWN CASSETTE" />
</Array>

When a cash‐in cassette is removed or inserted, along with the

tamper and sensor status reporting, a security trace message is
journaled before the reserved screens U0143 or U0144. Based on
Enhanced Configuration Option 24 setting, a security trace message
is also journaled before the reserved screen U0145. The security
trace message contains a header and is formatted as follows:
*NNN*XX/XX/XXXX*HH:MM*

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-358 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

For example,
 If option 24 is set to 000, the following is journaled when fourth
cassette is removed and inserted back:
*045*01/03/2019*12:10* BNA CASSETTE 4 REMOVED

ESC[020t*046*01/03/2019*12:10*
ESC[05pC1 FOURTH CASSETTE REMOVEDESC[00p
ESC(I * *1*P*1011110011010,M-ESC(1

ESC[020t*048*01/03/2019*12:10*
ESC[05pC1 FOURTH CASSETTE INSERTEDESC[00p
ESC(I * *1*P*1011110011011,M-ESC(1

 If option 24 is set to 002, the following is journaled when fourth

cassette is removed:
*129*01/04/2019*12:17* BNA CASSETTE 4 REMOVED

ESC (I
*1910*1*P*6D0*G00*P001001002001003001004001*d01100040010*
e01100041011*w03111041110*q0200,M- ESC(1ESC S

ESC[020t*130*01/04/2019*12:17*
ESC[05pC1 FOURTH CASSETTE REMOVEDESC[00p
ESC(I
*1910*1*P*6D0*G00*P001001002001003001004001*d01100040010*
e01100041011*w03111041110*q0200,M-ESC(1

*131*01/04/2019*12:17*
BNA CASSETTE 4 INSERTED

ESC(I
*1910*1*P*6D0*G00*P001001002001003001004001*d01100040011*
e01100041011*w03111041111*q0200,M-ESC(1ESCS

ESC[020t*132*01/04/2019*12:17*
ESC[05pC1 FOURTH CASSETTE INSERTED[00p
ESC(I
*1910*1*P*6D0*G00*P001001002001003001004001*d01100040011*
e01100041011*w03111041111*q0200,M-ESC(1

For more information on Security Trace Messages, refer to Chapter

7, “Security Trace Messages” in the APTRA Advance NDC, Supervisor
Guide.

When a cassette is inserted or removed, this is journaled using

Localising Tamper reserved screens U0143 and U0144 respectively.
Indication Journaling 5

The cassette names can be localised using the CashInCustom.accfg

file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-359

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

The default cassette names are given in the extract of

CashInCustom.accfg in Figure 5‐85. These entries can be edited to
localise the journaled text.

Figure 5-85
Default Cassette Names
<Array ID="CassetteNamesArray">
<Element Value="Cassette1=CASSETTE 1" />
<Element Value="Cassette2=CASSETTE 2" />
<Element Value="Cassette3=CASSETTE 3" />
<Element Value="Cassette4=CASSETTE 4" />
<Element Value="Cassette5=CASSETTE 5" />
<Element Value="Retract=RETRACT BIN" />
<Element Value="Reject=REJECT BIN" />
<Element Value="Counterfeit=COUNTERFEIT BIN" />
<Element Value="UnknownCassette=UNKNOWN CASSETTE" />
</Array>

By default, NDC note types are mapped automatically to the

Note Type Mapping 5

corresponding XFS note type. XFS note types are also mapped to the
corresponding NDC note types. This does not need to be changed
unless you want to change the way in which the mapping is done. A
sample file, CashInNoteMapping.XML, is created by the automatic
mapping and saved to C:\Program Files\NCR APTRA\Advance
NDC\Config\Samples. This file can be edited and is used if the
mapping method is changed to use the XML file.

Note: If the notes template is changed and automatic mapping is

used, clear all counts using the Supervisor options and restart the
SST.

The mapping method is configured using the CashInCustom.accfg

file.
The NoteTypesMapping property under the
NDCCashAcceptService class defines the method of mapping to
use, as follows:
<Property Name="NoteTypesMapping"
Value="AutomaticByNoteID" />

Valid values are as follows:

 AutomaticByNoteID. This automatically maps NDC note types
to XFS note types (default). The first NDC note type is associated
with the lowest XFS note type, the second NDC note type with
the second lowest XFS note type and so on until a maximum of
50 note types have been mapped. If any XFS note types are not
mapped to an NDC note type, they are inactive

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-360 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 AutomaticByDenom. This automatically maps note types by

grouping XFS note types of the same currency and
denomination. The first NDC note type is associated with the
lowest denomination grouping, the second NDC note type with
the second lowest denomination grouping and so on until a
maximum of 50 note types have been mapped. If any XFS note
types are not mapped to an NDC note type, they are inactive.
This method allows more than 50 note types to be used.
 XMLFile. This uses the XML file described in “Using the Note
Type Mapping XML File” below. This method allows a
one‐to‐one or one‐to‐many mapping of NDC note types to XFS
note types and the XFS note types can also be put into a specific
order in the host messages.

Using the Note Type Mapping XML File 5

If you have configured the mapping as XMLFile, you can edit the
CashInNoteMapping.XML file created by the automatic mapping and
save it to C:\Program Files\NCR APTRA\Advance NDC\Config. The
XML configuration file download is not used to install this file.
If this file is not present, it is not created by Advance NDC and a
fatal condition is reported to the host for the cash acceptor.
The file must conform to the structure given in Table 5‐129.

Table 5-129
Note Mapping XML Structure

Element Description

NDCCashDepositItemMapping The whole file is embedded within NDCCashDepositItemMapping

tags.

This is the root element.

Nested elements:
 CashItem

CashItem Optional

Maps an NDC note type to a XFS note type.

The XFSIdentifier attribute is the numeric identifier for the XFS note
type being mapped.

The NDCType attribute is the numeric identifier for the NDC note type
being mapped.

Example Note Mapping The XML example in Figure 5‐86, “Note 5

Mapping XML Extract” maps the note types as described in

Table 5‐130, “Example Note Mapping”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-361

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Table 5-130 XFS Note ID NDC Note Type

Example Note Mapping
1, 2 and 3 1

4 2

Figure 5-86 <NDCCashDepositItemMapping>

Note Mapping XML Extract <CashItem XFSIdentifier="1" NDCType="1"/>
<CashItem XFSIdentifier="2" NDCType="1"/>
<CashItem XFSIdentifier="3" NDCType="1"/>
<CashItem XFSIdentifier="4" NDCType="2"/>
</NDCCashDepositItemMapping>

If the configuration of the note types fails, reserved screen t34 is

Journaling Note used to journal the failure. The reason for the failure can be localised
Configuration Failures 5
using the NoteConfigFailedReasonsArray in the
CashInCustom.accfg file.
The default reasons, which can be edited as required, are as follows:
<Array ID="NoteConfigFailedReasonsArray">
<Element Value="000=EXCHANGE MODE" />
<Element Value="100=TIME_OUT" />
<Element Value="101=HARDWARE_ERROR" />
<Element Value="102=DEVICE_LOCKED" />
<Element Value="103=UNSUPPORTED METHOD" />
<Element Value="104=CANCELLED" />
<Element Value="105=UNSUPPORTED CATEGORY" />
<Element Value="106=CONNECTION_LOST" />
<Element Value="107=DEVICE NOT READY" />
<Element Value="108=UNSUPPORTED DATA" />
<Element Value="109=EXCEPTION OCCURRED" />
<Element Value="110=INVALID DATA" />
<Element Value="111=USER ERROR" />
<Element Value="999=SOFTWARE ERROR" />
<Element Value="Unknown=UNKNOWN ERROR" />
</Array>

If the validation of deposited notes fails, reserved screen t20 is used

Journaling Note Validation to journal the failure. The reason for the failure can be localised
Errors 5
using the NoteErrorReasonsArray in the CashInCustom.accfg file.
The default reasons, which can be edited as required, are as follows:
<Array ID="NoteErrorReasonsArray">
<Element Value="0=DOUBLE NOTES HAVE BEEN DETECTED" />
<Element Value="1=LONG NOTES HAVE BEEN DETECTED" />
<Element Value="2=SKEWED NOTE HAS BEEN DETECTED" />
<Element Value="3=ITEM COUNTING ERROR HAS OCCURRED" />
<Element Value="4=NOTES HAVE BEEN DETECTED AS
TOO CLOSE" />

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-362 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<Element Value="Unknown=UNKNOWN ERROR" />

</Array>

In a deposit transaction, the reserved screen u0183 is used to journal

Journaling the Count of the count of the notes that pass through the bill validator
Notes that Pass through irrespective of whether the notes are moved to escrow/cassette
the Bill Validator 5 based on the LogAndStoreValidatedNoteCounts property of the
NDCCashAcceptService class. The note counts are also populated
to CDI stores for customisations. When the recovery/reset is
successful, the LastCashInOperation CDI is set to Empty.
Valid values are as follows:
False (default)- The count of notes that pass through the
bill validator are neither journaled nor updated in the CDIs
True - The count of notes that pass through the bill validator
are journaled and also updated in the CDIs
The counts are journalled only if there is a hardware error/jam
during scenarios like:
 Deposit operation
 Retract operation
 Error recovery at start of day
 Error recovery in Close state
 INIT BNA Supervisor task
 Supervisor Entry/Exit

Note: The journaling doesn’t happen when a hardware jam occurs

during an encash operation as the note information is already
present after the notes were moved to escrow before the encash
operation.

For information on journaling, refer the “Count of the Notes that

Pass through the Bill Validator” section in Chapter 7, “Status, Error
and Exception Reporting” of the APTRA Advance NDC Supervisorʹs
Guide.

Reporting of M‐Status values differs for different devices. By

Device M‐Status Reporting 5

default, the device type is detected and reported accordingly. The

reporting of M‐Status values can be specifically configured to use
reporting used by BNA, GBXX or BRM devices, for example, to
report other vendors’ devices correctly. In general, other vendors’
devices use the same reporting as BNA devices and compound
devices use the same reporting as GBXX devices. The NCR SDM
uses the same reporting as BNA devices.The M‐Status reporting is
defined using the MStatusType property on the IMStatusMapper
class, the default entry in the CashInCustom.accfg file is as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-363

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<Property Name="MStatusType" Value="Default" />

Valid values are as follows:

 Default ‐ use the reporting for the device detected in the SST
 BNA ‐ use the same reporting as BNA devices
 GBXX ‐ use the same reporting as GBXX devices
 BRM ‐ use the same reporting as BRM devices.

You can choose whether to handle a Suspend condition as a fatal

Suspend Handling 5

condition or a Suspend condition. This is configured using the

CashInCustom.accfg file.
How to handle a Suspend condition on a cash acceptor is set using
the HandleSuspendAsFatal property under the
CashInStatusHandler class, as follows:
<Property Name="HandleSuspendAsFatal" Value="false" />

Valid values are as follows:

 true. This treats the cash acceptor as if it were in a fatal
condition. Automatic error recovery is run as normal.
 false (default). This treats the cash acceptor as if it were in
Suspend mode. For more information on the Suspend condition,
see “Configuring Suspend Timeout” on page 5‐100.

Note: Suspend condition handling is carried out before

automatic error recovery starts.

When an attempt is made to clear the Suspend condition, reserved

screen U0140 is journaled.

Error recovery attempts to clear cash acceptor device errors that

Error Recovery 5

have occurred following cash deposits at the following points:

 Start of Day
 After the device is reported fatal at the end of the Close state
 Initialise BNA option on the Supervisor Replenish menu
 Exiting Supervisor.
Automatic error recovery is configured using the
CashInCustom.accfg file.
The points listed above are configured using different classes, as
shown in Table 5‐131 “Error Recovery Configuration Classes” on
page 5‐365.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-364 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Table 5-131
Error Recovery Configuration Classes

Point Class

Start of day NCR.APTRA.NDC.CashInErrorRecovery.AutoRecoveryFlow

Close State NCR.APTRA.NDC.CashInErrorRecovery.AutoRecoveryFlow

INIT BNA NCR.APTRA.NDC.CashInErrorRecovery.SupervisorRecoveryFlow

Exiting Supervisor NCR.APTRA.NDC.CashInErrorRecovery.SupervisorRecoveryFlow

Error Recovery Modes 5

The error recovery mode is set using the RecoverMode property of

the AutoRecoveryFlow class, as follows:
<Property Name="RecoveryMode" Value="FullRecovery" />

Valid values are as follows:

 RecoveryDisabled
Automatic error recovery is off. No automatic error recovery is
performed. An operator must clear the device, for example by
running INIT BNA
 FullRecovery (default)
Automatic error recovery is performed. Any notes in the device,
including any at the throat, are retained in the destination
configured in the RecoveryDestination property as described
in “Recovery Destination” below
 LeaveNotesAtExitSlot
If notes are left at the throat, automatic error recovery starts only
after notes are removed or an operator clears the device
 LeaveNotesInStacker
If notes are left in the escrow for a reason other than a jam, a
retract operation or notes left in the Close state, automatic error
recovery starts only after notes are removed and an operator
clears the device
 LeaveNotesAtExitSlotOrInStacker
If notes are left at the throat or in the escrow for a reason other
than a jam, a retract operation or notes left in the Close state,
automatic error recovery starts only after notes are removed and
an operator clears the device.

Recovery Destination 5

The destination used when recovering notes is set using the

RecoveryDestination property of the AutoRecoveryFlow class, as
follows:
<Property Name="RecoveryDestination" Value="Automatic" />

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-365

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Valid values are as follows:

 Cassette
Notes are moved to the cassettes
 Retract
Notes are moved to the retract bin
 Automatic (default)
The destination is automatically selected based on money
ownership. Notes are moved to the cassettes if the money
belongs to the bank or to the retract bin if the money belongs to
the cardholder.

Note: When the Close state option is set to retain the notes and
a jam occurs in the Close state, the notes will be moved to retract
bin or cassettes based on the value configured in the
RetainDestination property. See “Configuring the Retain
Destination for the Notes in Escrow” on page 5‐323 for
configuration.

Note: On an SDM2 device, during a deposit transaction, if a

hardware error occurs, the device does not validate the notes during
the recovery. Hence, the note details are unknown and the notes are
moved to the retract bin irrespective of the destination set in the
RecoveryDestination property.

Reason for Failed Recovery 5

The reason given in reserved screen U0118 for a failed recovery

attempt can be described using the RecoveryFailedReasonsArray
in the CashInCustom.accfg file.
The default reasons are as follows:
<Array ID="RecoveryFailedReasonsArray">
<Element Value="Success=NO ERROR" />
<Element Value="Jammed=DEVICE JAMMED" />
<Element Value="RetractMissing=RETRACT BIN MISSING" />
<Element Value="CassettesMissing=CASSETTES REMOVED" />
<Element Value="CassettesFull=CASSETTES FULL" />
<Element Value="CombinedDeviceError=CASH OUT ERROR" />
<Element Value="HardwareError=HARDWARE ERROR" />
<Element Value="DeviceOffline=DEVICE OFFLINE" />
<Element Value="StartEndExchangeFailed=EXCHANGE FAILED" />
</Array>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-366 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Report Error Message 5

The ReportAutoErrorRecoveryUnsol property of the

CashInStatusHandler class determines whether an error message
(wF) is sent to the host when notes are captured to the cassettes
and/or bins if the automatic error recovery is successful in the Close
state, as follows.
<Property Name="ReportAutoErrorRecoveryUnsol" Value="true" />

Valid values are as follows:

true ‐ Report wF status message with the counts of captured
notes, which are included in the vaulted counts

false ‐ Do not report any message (default)

Article 6 of the Council Regulation (EC) No 1338/2001 of 28 June

ECB 6 Considerations 5

2001 lays down measures for protecting the euro against

counterfeiting. The Governing Council is part of the European
Central Bank (ECB), and these measures are collectively known as
ECB 6.
For more information about the ECB 6 regulations, see the European
Central Bank web site at www.ecb.int.

ECB 6 Note Categories 5

Four note categories are defined by ECB 6, as described in the

following table.

Table 5-132 Category Description

ECB 6 Note Categories
1 Either not a note or not recognised as a note. Category 1
notes are returned to the cardholder as unrecognised.

2 Counterfeit note. Counterfeit notes must be captured and

cannot be returned to the cardholder even if the
transaction is cancelled. The Supervisor option CREATE
SIGS asks the operator to insert a note in four directions
and captures the signatures onto removable media. The
Supervisor option EXTRACT SIGS asks for a start and
end date for the data to be extracted from the ECB 6
journal and a destination to copy the data to. Counterfeit
notes cannot be credited to the cardholder’s account but
the details are journaled.

Note: Information from these options must be removed

from the SST and compared to the journal to match a
cardholder to a transaction. The financial institution
must use information from Central to identify a
cardholder as the information in the ECB 6 journal is
masked

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-367

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Category Description

3 Suspect note. Suspect notes can be captured or returned

to the cardholder as unrecognised depending on the
financial institution. If captured, data can be extracted
from the ECB 6 journal, as described for counterfeit notes
above. Suspect notes may be credited to the cardholder’s
account; this decision is made by the financial institution.
Details of suspect notes are journaled.

4 Authenticated note. Authenticated notes have been

classified as genuine.

Note: Within ECB 6, authenticated notes can be further

categorised into fit and unfit notes. A fit note is
one that is suitable for circulation. Unfit notes are
damaged in such a way that they are unsuitable
for circulation. This categorisation only affects
devices used for recycling.

Counterfeit, Suspect and Good Notes 5

When a deposited note is identified as a counterfeit (category 2)

note, it must be captured, even if the cardholder subsequently
cancels the deposit.
When a deposited note is identified as a suspect (category 3) note
and ECB 6 mode 1 is configured, the note is either captured or
returned to the cardholder. For NCR SSTs, the action taken depends
on the setting of the Cat3rollback entry in the GBXX configuration
file. For details of the Cat3rollback entry, see “GBXX Cassette
Configuration” on page 5‐388. For other vendors, this is set using
the platform. If ECB 6 mode 2 is configured, the suspect note is
always returned to the cardholder as unrecognised. For details of
the ECB 6 modes, see “ECB 6 Modes” on page 5‐374.
If the reading of the note signature fails for suspect or counterfeit
notes, this is journaled using reserved screens U0124 and U0125.
Logging Good, Counterfeit and Suspect Notes The note 5

signatures for counterfeit, suspect and good notes are logged to the
ECB 6 database through the RecordCat3Signatures and
RecordCat4Signatures property of the
ECB6CashAcceptServiceCustomised class. The
RecordCat3Signatures property is set to true in the
CashInCore.accfg file. The RecordCat2Signatures property in the
code is also set to true. This ensures that the signatures retrieved
for counterfeit and suspect notes are always logged to the ECB 6
database regardless of the ECB 6 settings except for counterfeit
notes when both the following occur before a cash‐in transaction is
completed:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-368 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 Notes are left at the exit slot

 Power failure
The RecordCat4Signatures property is set to false in the
CashInCustom.accfg file. If you want to log the signatures of good
notes, set the property to True. The following extract in the
CashInCustom.accfg file shows the property set to True:
<Class ID="ECB6CashAcceptService"
Name="NCR.APTRA.NDC.CashAcceptService.ECB6CashAcceptSer
viceCustomized"
Assembly="NCR.APTRA.NDC.CashAcceptService.dll">
<Interface>
<!-- Description: This specifies whether Cat4
signatures need to logged to the database -->
<Property Name="RecordCat4Signatures"
Value="True" />
</Interface>
</Class>

The database structure is same as database structure for dispensed

notes except for the name of the database and an additional element
SerialNumber. See “Database Structure” on page 5‐292 for
information on the database elements.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-369

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Figure 5-87
Example Log Signatures (Deposit) Extract
<Journal>
<JournalRec>
<SysTime>2008-02-10T17:52:37.357+01:00</SysTime>
<SeqNum>578932</SeqNum>
<Content>
<DepositInfo>
<TransInfo>
<TransactionInfo>
<DisputeReference>7389256498</DisputeReference>
<TransactionTimeStamp>10/02/2008 5:52:00 PM </TransactionTimeStamp>
</IdentificationData>
</TransactionInfo>
</TransInfo>
<NoteInfo>
<BankNoteDetail>
<Currency>GBP</Currency>
<Denomination>10.00</Denomination>
<NoteID>21</NoteID>
<Category>4</Category>
<Orientation>2</Orientation>
<Signature>936b7e228f……….</Signature>
<SerialNumber>0090029296 </SerialNumber>
</BankNoteDetail>
</NoteInfo>
<NoteInfo>
<BankNoteDetail>
<Currency>GBP</Currency>
<Denomination>10.00</Denomination>
<NoteID>22</NoteID>
<Category>4</Category>
<Orientation>4</Orientation>
<Signature>7493085ef3……….</Signature>
<SerialNumber>0090029296 </SerialNumber>
</BankNoteDetail>
</NoteInfo>
</DepositInfo>
</Content>
</JournalRec>
</Journal>

Note: If you require to stop this logging to the ECB 6 database of

signatures for counterfeit and suspect notes, you will have to edit
CashInCore.accfg as follows:
1 Set the RecordCat3Signatures property of the
ECB6CashAcceptServiceCustomised class to false.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-370 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

2 Add a similar entry for the RecordCat2Signatures property,

also setting it to false.
Capturing Counterfeit and Suspect Notes When a note is 5

captured, the SST does the following:

1 Takes a single‐orientation note signature.
This is added to the ECB 6 database along with other details
such as the note type, ECB 6 note category, currency and time
stamp.

2 Captures the note.

Counterfeit notes are stored in the counterfeit bin. Suspect notes
are stored as specified in the Cat3StoragePolicy entry of the
GBXX configuration file or configured on the platform
depending on the SST. For details of the GBXX configuration
file, see “GBXX Cassette Configuration” on page 5‐388.

3 Journals the number of captured notes.

The operator must then use the following options on the Configure
menu in Supervisor:
1 Option 55 ‐ CREATE SIGS to take four orientations of a note and
copy the signatures to removable media. The operator must
remove the note and re‐insert it in each of the orientations.

2 Option 56 ‐ EXTRACT SIGS to take an extract from the ECB 6

database and copy it to a selected destination.
Note counts for suspect notes are included in the ‘ca3’ field of the
Transaction Request message. Note counts for counterfeit notes are
not included in the Transaction Request message.
Note counts for counterfeit notes are shown as totals and suspect
notes are included in the individual note type counts along with
good notes and shown as totals in following situations:
— When a confirmation screen is displayed, as described in
Chapter 5, “Application Programming Interfaces” of the
APTRA Advance NDC, Extending the Product publication
— When the following options are used on the Supervisor
Replenish menu:
3 DSP CNTS
4 PRNT CNTRS
53 CLR BNA
58 DSP BNA CNTS
59 PRN BNA CNTS.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-371

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Whether to report any detected counterfeit or suspect notes in an

unsolicited status message is configured using the
P6DetectedUnsol property of the CashInStatusHandler class.
The counts can be reported as either cumulative or counts per
operation which is explained in the following sections.
Valid values are as follows:
DoNotSend — Do not send an unsolicited message (default)
SendWithoutCardData — Send an unsolicited message, but do
not include any card data
SendWithCardData — Send an unsolicited message, and
include card data. If the card data is unavailable, the card
data fields are empty.
If the property is set to SendWithoutCardData or
SendWithCardData, a status message reporting counterfeit notes
begins with w? and a status message reporting suspect notes begins
with w@.
The CountsPerOperationInP6Unsols in the CashInCustom.accfg
file determines the counts populated in w? and w@ should be
cumulative or counts per operation.
True ‐ The unsolicited message will contain counts per operation.

False ‐ The unsolicited message will contain cumulative counts per

transaction (default).
The messages are sent only when counterfeit, suspect or both are
inserted or when the note category is changed to counterfeit or
suspect during the second bill validation on a GBNA/GBRU
machine.
The messages are not sent during a refund operation, if a hardware
error occurs during the transaction or during an error recovery.
<Class ID="CashInStatusHandler"
Name="NCR.APTRA.NDC.CashInStatusHandling.CashInStatusHa
ndler"
Assembly="NCR.APTRA.NDC.CashInStatusHandling.dll">
<Interface>
<!-- ============================================
-->
<!-- Name:
CountsPerOperationInP6Unsols -->
<!-- Type: Bool -->
<!-- Description: Defines Cumulative counts per
transaction or Counts -->
<!--per operation in the P6 unsol status
messages -->
<!-- Possible Values: True, False-->

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-372 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<!-- Default Value: False -->

<!--
============================================
-->
<Property Name="CountsPerOperationInP6Unsols"
Value="False"/>
</Interface>
</Class>

Example 1:
When the CountsPerOperationInP6Unsols is set to False,

1 Two counterfeit and three suspect notes are inserted, w?

message is sent with escrow count as 2 and w@ message is sent
with escrow count as 3.

2 If Add More is selected on the Confirmation screen, and three

counterfeit and four suspect notes are inserted, w? message is
sent with escrow count as 5 (cumulative count) and w@ message
is sent with escrow count as 7 (cumulative count).

3 If Add More is selected on the Confirmation screen and two

suspect notes are inserted, w? message is sent with escrow count
as 5 and w@ message is sent with escrow count as 9 (cumulative
count).

4 If Add More is selected on the Confirmation screen and two

good notes are inserted, and Deposit is selected on the
Confirmation screen, the notes are successfully deposited. w?
message is sent with vaulted count as 5 (cumulative count) and
w@ message is sent with vaulted count as 9 (cumulative count). If
refund is selected instead of Add more, w? message is sent with
vaulted count as 5 (cumulative count) and w@ message is sent
with vaulted count as 9 (cumulative count).

5 When two good notes are inserted, and if a good note is detected
as a counterfeit note during the second bill validation on a
GBNA/GBRU device, w? message is sent with vaulted count as
6. If the good note is detected as a suspect note, w@ message is
sent with vaulted count as 10.
Example 2:
When the CountsPerOperationInP6Unsols is set to True:

1 Two counterfeit and three suspect notes are inserted, w? message

is sent with escrow count as 2 and w@ message is sent with
escrow count as 3.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-373

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

2 If Add More is selected on the Confirmation screen, and three

counterfeit and four suspect notes are inserted, w? message is
sent with escrow count as 3 (counts per operation) and w@
message is sent with escrow count as 4 (counts per operation).

3 If Add More is selected on the Confirmation screen and two

suspect notes are inserted, w? message is not sent to the host and
w@ message is sent with escrow count as 2 (counts per
operation).

4 If Add More is selected on the Confirmation screen and two

good notes are inserted, and Deposit is selected on the
Confirmation screen. w? and w@ messages are not sent to the
host.

5 When two good notes are inserted, and if a good note is detected
as a counterfeit note during the second bill validation on a
GBNA/GBRU device, w? message is sent with vaulted count as
1. If the good note is detected as a suspect note, w@ message is
sent with vaulted count as 1.

Note: When CountsPerOperationInP6Unsols is set to True and

Cat3RollBack is set to 1 on a GBNA/GBRU device, if a suspect note
is detected as a counterfeit note during the second bill validation,
there will be a mismatch in the status reporting. The note is reported
in w@ status message when it is inserted, and the same note is
reported in w? as the note category has changed to counterfeit note.
The misrecognition error (screen U0126) is journaled if the note
category is changed during the second bill validation and the note is
moved to reject bin. If note category is changed to suspect or
counterfeit during the second bill validation, and the note is not
moved to reject bin, there will not be any misrecognition error.

Note 1: For a PA‐DSS compliant solution, the message must be sent

securely, for example, by using SSL to encrypt the message, if value
is set to SendWithCardData.

Note 2: If ECB 6 support is enabled, Enhanced Configuration

Parameter option 45 should be set to allow more than 90 notes.

ECB 6 Modes 5

The ECB 6 mode defines how notes are identified using the ECB 6
note categories. For GBXX devices, ECB 6 modes are defined using
the CatMode element of the GBXX Configuration file, as described in
“GBXX Cassette Configuration” on page 5‐388.
If the CatMode element of the GBXX configuration file is set to 2, the
CatMode property of the ECB6CashAcceptServiceCustomised

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-374 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

class in the CashInCustom.accfg file must also be set to 2 to guarantee

the suspect note count.
If the CatMode element of the GBXX configuration file is set to 1, the
CatMode property of the ECB6CashAcceptServiceCustomised
class in the CashInCustom.accfg file must also be set to 1.
By default, the value of the CatMode property of the
ECB6CashAcceptServiceCustomised class in the
CashInCustom.accfg file is 0.
The following sub‐sections describe the other registry values that
must be set according to your hardware and the CatMode value set
in the GBXX configuration file.
For further information on these registry entries, refer to the APTRA
on‐line documentation, under Self‐Service Support |
Programmer’s Reference | XFS Service Providers | XFS
GBNA‐GBRU Service Provider | Configurable Parameters.
Registry Entry for BNA Using ECB 6 Mode 1 If you are using a 5

BNA device and want to enable ECB 6 mode 1, you must set the
following registry entry to 1:

HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\
SERVICE_PROVIDERS\CIM\GENERAL_CONFIGS

Registry Entry for GBXX Using ECB 6 Modes 0 and 2 If you are 5

using ECB 6 mode 0 or 2 with a GBXX device, you must define the
destination for unfit authenticated notes by adding the following
registry entry:

HKLM\SOFTWARE\NCR\XFS GRBU-GBNA Service Provider\

XFS-DeviceControl\GBRU-GBNA\Interoperability\
NonECBUnfitDest

Valid values are as follows:

 1 ‐ unfit authenticated notes are deposited in cassette position 1
 2 ‐ deposit fit and unfit authenticated notes together.

BRM Device For a BRM device, ECB6 modes are defined using 5

the P6 mode element of the BRM Configuration file, as described in

“BRM Cassette Configuration” on page 5‐407.
If the P6Mode element of the BRM configuration file is set to 1 or 2,
the CatMode property of the ECB6CashAcceptServiceCustomised
class in the CashInCustom.accfg file must be set to 1.

Note: For a BRM device, Advance NDC supports ECB6 even when
the Upper Exception Bin is not present, however this requires
changes in the SP configuration. Refer to the documentation
provided by the Service Provider. For information on registry

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-375

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

settings for BRM, see“Bunch Recycling Module” on page 5‐315.

ECB 6 Database Support Utility 5

The ECB 6 database support utility is a component in the Advance

NDC aggregate. It is included so that the ECB 6 journal can store
signatures for the counterfeit and suspect notes in a deposit
transaction.

Note: On BNA devices, the Glory Database Generator must be

used. This is not supplied with Advance NDC, but can be obtained
from NCR Deposit Product Management.

For further information on the ECB 6 database support utility,

including the format of the file, refer to the APTRA on‐line
documentation under APTRA ECB6 Database Support.
ECB 6 Journal Format The ECB 6 journal is an XML file called 5

ECB6LOG.SDF. This file is located in the C:\Program Files\NCR

APTRA\Advance NDC\PersistedData\ECB6Log folder. It cannot be
viewed, unless the Extract Signature option on the Supervisor
Configure menu is used to copy an extract to removable media.
ECB 6 Journal Contents The ECB 6 journal contains the masked 5

card number, the time of the transaction, note ID, denomination,

whether the note was a counterfeit or suspect, and the orientation
and signature of the note. On a BRM device, along with the other
database elements, the serial number information of deposited notes
is also logged to the ECB6LOG database file. No information on
counterfeit or suspect notes is sent to the host in the Transaction
Request message, but note counts are included in the ca3 field.
Unsolicited status messages contain information on counterfeit and
suspect notes.

Note: The card number is masked in the database. If the card

number consists of only four digits, all are masked. If more than
four digits are included, all are masked except the last four. To track
a specific note or transaction to a cardholder, include reporting of
counterfeit and suspect notes in the status messages to allow the
host data to be used for tracking purposes.

For details of including counterfeit and suspect notes in the status

messages, see “Counterfeit, Suspect and Good Notes” on
page 5‐368. For information on using a PCI PA‐DSS compliant
solution, see Appendix E, “PCI DSS & PA‐DSS Compliance in
Advance NDC.”.
Duration of Stored Information According to ECB 6 regulations, 5

the maximum age of the stored information must be a minimum of

four weeks. Advance NDC will store information for 60 days. Any

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-376 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

records over the maximum age are automatically deleted from the
database.

The media entry indicator (MEI) on a BNA is used as defined in the

Media Entry Indicator for a following registry entry:
BNA 5

HKLM\SOFTWARE\NCR\XFS CIM Service Provider\

XFS-DeviceControl\CIM\Interoperability\
MiscIfMEI

For details of this registry entry, refer to the APTRA on‐line

documentation under APTRA XFS | Programmer’s Reference |
XFS Service Providers | XFS CIM Service Provider | Configurable
Parameters.

To improve performance, the transaction reply printer data can be

Encash, Print and Set Next sent to the printer at the same time as the encash operation is carried
State 5
out. This results in a parallel print and encash. The printing occurs
only if the encash operation is successful.
To enable parallel print and encash, the following registry entry
must be set to 1:
HKLM\SOFTWARE\NCR\Advance NDC\BNA\DoParallelEncashPrint

Valid values for this entry are as follows:

 0 to disable parallel print and encash (default).
 1 to enable parallel print and encash.

An XML file is used to log exceptions, retract operations and host

Cash Deposit Exception timeouts occurring during deposit transactions. Exception reporting
Reporting 5
is enabled and configured using properties in the
CashInCustom.accfg file as described in the following sections.
The log can be printed and cleared using options on the Supervisor
Replenish menu. The file can be archived and retrieved using
options on the Supervisor Configure menu. For details of the menu
options, refer to Chapter 3, “Replenish Menu” and Chapter 4,
“Configure Menu” in the APTRA Advance NDC, Supervisor’s Guide.

Enabling Exception Reporting for Cash Acceptors 5

The following shared property is used to enable exception reporting

for cash acceptors:
<SharedProperty Name="EnableExceptionReporting"
Value="false"/>

By default, exception reporting is disabled. To enable exception

reporting, update the value to "true".

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-377

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Configuring the Report Format 5

The formatter to use is set using the following property on the

PrintCashInExceptionReport class:
<Property Name="CountersFormatter"
Value="BasicCashInFormatter"/>

By default, the basic formatter is used. To use the enhanced

formatter, update the value to EnhancedCashInFormatter.
Basic Formatter When using the basic formatter, the number of 5

accepted notes for each denomination is reported as illustrated in

the following example:

DENOM:
EUR5-001,EUR20-017,
EUR50-018,EUR100-019

The number of columns to use when wrapping dynamic data can be

configured, as described in “Number of Columns” on page 5‐380.
Enhanced Formatter When using the enhanced formatter, the 5

number of accepted notes for each denomination is reported as

illustrated in the following example:

DENOM:
EUR 5 x 1 = 5
EUR 20 x 17 = 340
EUR 50 x 18 = 900
EUR 100 x 19 = 1900
EUR TOTAL = 3145

A separator can be configured to format numbers when the number

reaches a thousand as described in “Using a Separator” on
page 5‐381.
The test used for the total heading can be configured as described in
“Text Used for Total Heading” on page 5‐380.

Configuring the Statement Service 5

The statement service is configured through the

StatementServiceConfig.xml definition file.

Configuring the Receipt Service 5

Several properties in the CashInXFSReceiptSrv class can be used

to configure media and language for the receipt service, as
described in the following sections.
Media Definition The default formatting rules for the receipt 5

service are defined in the following property, which is available in

the CashInCore.accfg file:
<Property Name="ConfigContainer"

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-378 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Value="SupervisorReceiptConfigContainer"/>

The CEN‐XFS media definition defining the dimensions of the

paper used for printing is set using the following property:
<Property Name="Media" Value="Receipt1"/>

The value can be updated to reference any valid media definition

file.
Translation and Language The data translator associated with the 5

receipt service can be set using the following property:

<Property Name="Translator" Value="DataTranslator"/>

If the value is set to an empty string, no translation is carried out.

If a value is specified, the data records are translated to the language
specified in the Language property. The Language property defines
the two‐letter abbreviation that identifies the language to translate
the data records into as follows:
<Property Name="Language" Value="en"/>

The value must be the abbreviation for the desired language as

defined in ISO standard 639.

Printing Exception Reports 5

The following forms are used to print the exception report and
display status messages and prompts on the screen:

Table 5-133
Forms Used for Cash Deposit
Exception Reporting

Form Destination Form Location

CashInExceptionReportTasksJPTR.DEF Receipt printer C:\Program Files\NCR

APTRA\Printing\Receipt\Forms

CashInExceptionReportTasksRPTR.DEF Journal printer C:\Program Files\NCR

APTRA\Printing\Journal\Forms

CashInExceptionReportTasksTTU.frmttu Screen display C:\Program Files\NCR

APTRA\Printing\TTU\Forms

The format for cash acceptor journal entries can be configured using
Journal Formats 5

the CashInCustom.accfg file and screens in resrvd.def.

Example journal entries are described in Chapter 7, “Error Recovery
and Reporting” in the APTRA Advance NDC, Supervisor’s Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-379

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Class Configurator Configuration 5

The following sections describe the parts of the journal that can be
configured using the CashInCustom.accfg file. The examples from the
file provide the default settings. To change a setting, edit the value.
You can define whether to use the basic or enhanced formatter
using the DeviceStatusFormatter property of the CashInJrnlSrv
class, as follows:
<Property Name="DeviceStatusFormatter"
Value="BasicDeviceStatusFormatter" />
<Property Name="UnknownText" Value="UNKNOWN" />

To use the enhanced formatter, update the value to

EnhancedDeviceStatusFormatter. Table 5‐134, “BNA Journal
Format Properties”, shows which formatting properties use basic
formatting and which properties use enhanced formatting.

Table 5-134 Property Basic Enhanced

BNA Journal Format Properties
Number of Columns X

Text Used for Total Heading X

Using a Separator X

Denomination Names X

Currency Names X

Number of Columns The number of columns is set using the 5

NumberOfColumns property, under the BasicStatusFormatter

class, as follows:
<Property Name="NumberOfColumns" Value="22" />

If the number of columns is set to a value less than or equal to 20,

the default value (22) is used.
Text Used for Total Heading The text to use as the heading for 5

totals is set using the TotalString property, under the

EnhancedStatusFormatter class, as follows:
<Property Name="TotalString" Value="TOTAL" />

Text Used for Invalid Notes Heading The heading used for the 5

invalid note count is set using the CAT1H property, under the
CashInJrnlSrv class, as follows:
<Property Name="CAT1H" Value="CAT1:" />

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-380 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Text Used for Counterfeit Notes Heading The heading used for 5

the counterfeit note count is set using the CAT2H property, under the
CashInJrnlSrv class, as follows:
<Property Name="CAT2H" Value="CAT2:" />

Text Used for Suspect Notes Heading The heading used for the 5

suspect note count is set using the CAT3H property, under the
CashInJrnlSrv class, as follows:
<Property Name="CAT3H" Value="CAT3:" />

Text Used for Good Notes Heading The heading used for the 5

good note count is set using the CAT4H property, under the
CashInJrnlSrv class, as follows:
<Property Name="CAT4H" Value="CAT4:" />

Using a Separator Whether to use a separator is set using the 5

JournalGroupDigit property, under the

EnhancedStatusFormatter class, as follows:
<Property Name="JournalGroupDigit" Value="false" />

Valid values are as follows:

 true Use a separator
 false Do not use a separator.

The separator is used to format numbers, in the journaled totals the

separator is used when the number reaches a thousand. You must
change the value to true if you want to use a separator. For
example, to use 1,000 instead of 1000.
Reporting Zero Counts This is set using the ReportZeroCounts 5

property, under the CashInJrnlSrv class, as follows:

<Property Name="ReportZeroCounts" Value="true" />

Valid values are as follows:

 true Report counts with a value of zero
 false Do not report counts with a value of zero.

Serial Number Information 5

The format of the serial number information of Category 4 (Good),

Category 3 (Suspect) and Category 2 (Counterfeit) notes is set using
the properties under the class SerialNumberEJConfig. For
information on the properties, see “Reading, Journaling and
Capturing Serial Numbers of Notes” on page 5‐331.
Denomination Names These are set using the 5

DenominationNamesMapping array, as follows:

<Array ID="DenominationNamesMapping">
<Element Value="USD5=$5-" />

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-381

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

</Array>

Currency Names These are set using the CurrencyNamesMapping 5

array described in “Currency Names Mapping Array” on

page 5‐349.
Reporting the Retract Destination The destination of retracted 5

notes is journaled using the text defined in the RetractAreasArray

array, as follows:
<Array ID="RetractAreasArray">
<Element Value="CIM_TO_RETRACT=RETRACT BIN" />
<Element Value="CIM_TO_STACKER=STACKER" />
<Element Value="CIM_TO_CASSETTE=CASSETTES" />
<Element Value="CIM_TO_TRANSPORT=TRANSPORT"/>
</Array>

Reporting the Recovery Destination The destination for 5

recovered notes is journaled using the text defined in the

RecoveryDestinationsArray array, as follows:
<Array ID="RecoveryDestinationsArray">
<Element Value="RETRACT BIN" />
<Element Value="CASSETTES" />
</Array>

Reserved Screen Mapping The reserved screens used to journal 5

information for cash acceptors are mapped using the

CashInJournalRecordMapping array as follows:
<Array ID="CashInJournalRecordMapping">
<Element Value="CAS_CASH_IN_START_OK=j4018" />
<Element Value="CAS_SHUTTER_OPEN=j4019" />
<Element Value="CAS_NOTES_INSERTED=j4020" />
<Element Value="CAS_MONEY_REJECTED=j4021" />
<Element Value="CAS_NOTES_PRESENTED=j4022" />
<Element Value="CAS_NOTES_TAKEN=j4023" />
:
:
</Array>

Journaling a Customer Timeout The text used to journal that the 5

consumer has not responded within the allowed time limit is set
using the TCode1Timeout property, which is included under both
the BasicStatusFormatter and EnhancedStatusFormatter
classes, as follows:
<Property Name="TCode1Timeout" Value="CUSTOMER TIMEOUT" />

Transaction Code Mapping The messages used to journal 5

information for transaction codes are mapped using the

CashInJrnlTCodes array as follows:
<Array ID="CashInJrnlTCodes">

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-382 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<Element Value="0=OPERATION OK" />

<Element Value="1=CUSTOMER CANCEL" />
<Element Value="2=CASHIN CASSETTE FULL" />
<Element Value="3=DEVICE ERROR" />
<Element Value="4=BILLS AT EXIT" />
:
:
</Array>

If you use customised transaction error codes, this array must be

configured to match the new codes. For details of customised
transaction error codes, see “Legacy Software Transaction Error
Codes”, below.
Legacy Software Transaction Error Codes For regions that have 5

had to customise the transaction error codes, the

CashInStatusHandler component can be configured to use the
customised transaction error codes. This allows those regions to
maintain on‐going support on their host networks for the
customised status messages.
The TransactionErrorCodes property on the
CashInStatusHandler class is used to specify the transaction error
codes. This property is present in the CashInCustom.accfg file with an
example set of alternative error codes, but it is commented out by
default. When the TransactionErrorCodes property is used, the
CashInJrnITCodes array must also be configured to match the new
error codes.

Note: This setting is for legacy purposes only and must not be used
for future extensions. If you need to report different transaction
error codes, please contact NCR FSE Product Management.

Reserved Screen Configuration 5

The following sections describe the parts of the journal that can be
configured using the resrvd.def file.
If you do not require a journal entry for any of the following
situations, you can either remove all data from the appropriate
reserved screen, or remove the mention of the screen from the
JournalRecordMapping array in the CashInCustom.accfg file.

Inaccurate Counts If there is a device or platform limitation where 5

counts cannot be reported but notes have been detected during an

error recovery operation, the cash acceptor note counts may be
inaccurate at the following points:
 Whenever any of the following Supervisor functions are
selected:
— DISP CNTRS

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-383

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

— PRNT CNTRS
— DISP BNA RCVL
— PRN BNA RCNL
— DISP BNA CNTS
— PRN BNA CNTS
— PRN BNA TTLS.
 Following automatic error recovery.
That note counts may be inaccurate at any of the above points is
journaled using reserved screen U0116 and displayed on the Fault
Display using reserved screen U0151. The error (inaccurate counts)
can be cleared by running the Clear BNA Supervisor option.

Note: The journaling of inaccurate counts applies only when no

note counts are updated by the platform. If good notes (category 4)
are reported as unrecognised (category 1) under the ECB 6
regulations, details of retracted or recovered note types are not
reported. In this situation, only the retract totals will be updated but
note counts are not journaled as inaccurate.

Signatures of Good Notes If the recording of serial numbers is 5

configured under the ECB 6 regulations and the signature of good

notes is successfully read, it is journaled only on the EJ using
reserved screen U0119. If the EJ is not configured, no note signatures
are journaled.
For information on configuring the recording of serial numbers, see
“Reading, Journaling and Capturing Serial Numbers of Notes” on
page 5‐331.
Failed Serial Number Reads If the recording of serial numbers is 5

configured under the ECB 6 regulations, the number of good,

counterfeit and suspect notes serial numbers that cannot be read in
the current bunch is journaled using reserved screen U0120.
For information on configuring the recording of serial numbers, see
“Reading, Journaling and Capturing Serial Numbers of Notes” on
page 5‐331.
Failed Signature Reads If the signature of some notes identified 5

as good, counterfeit or suspect under the ECB 6 regulations cannot

be read, one of the following reserved screens are used to journal it:
 For counterfeit notes, reserved screen U0124
 For suspect notes, reserved screen U0125
 For good notes, reserved screen U0189
The number of notes for which the reading of the signature failed is
also journaled.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-384 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Reporting Account Numbers The masked account number is 5

supplied dynamically using the account number field of reserved

screen U0127. For information on the masking of the account
number, refer to Chapter 7, “Error and Exception Reporting and
Recovery” in the APTRA Advance NDC, Supervisor’s Guide.
Configuration properties are also provided as follows:
 The JournalCustomerData property of the
CashInStatusHandler class to determine whether to print
customer data
 The UnknownText property of the CashInJrnlSrv class
provides a method of customising the text used when the card
number is not available, for example in a cardless transaction.
This is set by default to UNKNOWN, but you can change this if
required.
Supplies and Severity Reporting By default, extended supplies 5

are always reported using reserved screen U0127.

You can configure reserved screen U0127 to always report extended
severity as well as supplies, or you can include supplies and
severity based on the setting of bit 3 of Enhanced Configuration
Parameter option 45.
To always report extended severity, add the SeverityEx% field to
the definition of screen U0127 in resrvd.def, as shown in the
following example:
’U0127’ ’*<TSN%>*<MessageClass%>*(Iw(1*<Transcode%>,
M-<DiagnosticData%>, R-<SuppliesEx%>’
’S-<SeverityEx%>’
’A/C<AccountNo%>’

To report supplies and severity based on the setting of bit 3 of

Enhanced Configuration Parameter option 45, add the Supplies%
and Severity% fields to the definition of screen U0127 in resrvd.def,
as shown in the following example:
’U0127’ ’*<TSN%>*<MessageClass%>*(Iw(1*<Transcode%>,
M-<DiagnosticData%>, R-<Supplies%>’
’S-<Severity%>’
’A/C<AccountNo%>’

Reporting Diagnostic Data The M‐Status diagnostic data is 5

supplied dynamically using the DiagnosticData field of reserved

screen U0127.
To exclude diagnostic data from the journal, edit the screen to
remove the field.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-385

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Text Used for Escrow Heading The heading used for the escrow 5

note count is defined using reserved screen U0127.

By default, this is ESC:
Text Used for Rejected Notes Heading The heading used for the 5

rejected note count is defined using reserved screen U0127.

By default, this is REJECTS:
Text Used for Returned Notes Heading The heading used for the 5

returned note count is defined using reserved screen U0127.

By default, this is REF:
Text Used for Vaulted Notes Heading The heading used for the 5

vaulted note count is defined using reserved screen U0127.

By default, this is VAL:
Reporting Notes at Exit During AER If notes are detected at the 5

exit during automatic error recovery, this is journaled using

reserved screen U0135.

Journaling Retract Counts 5

Retract counts are journaled after a retract operation. The format of

the journal entries are described in the APTRA Advance NDC,
Supervisor’s Guide.
On a GBXX, to display the list of note types, by default listed under
RECOGNIZED ITEMS, the SP must be configured to report the note
list on the retract bin by setting the following registry entry:
HKLM\SOFTWARE\NCR\XFS GBRU-GBNA Service Provider\
XFS-DeviceControl\GBRU-GBNA\Interoperability\
ExpandCIMRetractNoteList

To ensure that the retract serial number is correctly updated, the SP

must be configured to report retract operations by setting the
following registry entry:
HKLM\SOFTWARE\NCR\XFS GBRU-GBNA Service Provider\
XFS-DeviceControl\GBRU-GBNA\Interoperability\
ReportRetractOperations

Advance NDC can be configured to allow dynamic note sorting in

GBXX Dynamic Note GBXX devices when a cassette becomes nearly full (a high cassette
Sorting 5
event). This effectively increases the capacity of the device, as notes
can continue to be accepted.
After a high cassette event, a new cassette must be reconfigured to
accept the note types previously accepted by the nearly full cassette.
Advance NDC reconfigures the cassette during the Close state.
Following this reconfiguration, after the cassette becomes nearly

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-386 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

full, notes are automatically sorted to the newly reconfigured

cassette. The priority sequence is defined by the
CashInCassetteReconfigurePriority property of the
DynamicOverspill class. This property defines an array of the XFS
logical cassette IDs that can be reconfigured to accept other note
types. The order of the array defines the sequence in which the
cassettes are to be reconfigured.
To enable dynamic note sorting, the property in the
CashInCustom.accfg file must be as follows and the array must be
updated to list the cassettes to reconfigure:
<Class ID="DynamicOverspill"
Name="NCR.APTRA.NDC.CashInStatusHandling.DynamicOverspill
" Assembly="NCR.APTRA.NDC.CashInStatusHandling.dll">
<Interface>
<Property Name="CashInCassetteReconfigurePriority"
Value="CashInCassetteReconfigurePriorityArray"
IsArray="true" />
</Interface>
</Class>

To disable dynamic note sorting, the property in the

CashInCustom.accfg file must be commented out, as follows:
<Class ID="DynamicOverspill"
Name="NCR.APTRA.NDC.CashInStatusHandling.DynamicOverspill
" Assembly="NCR.APTRA.NDC.CashInStatusHandling.dll">
<Interface>
<!--Property Name="CashInCassetteReconfigurePriority"
Value="CashInCassetteReconfigurePriorityArray"
IsArray="true" />
</Interface>
</Class>

Note: In order to disable dynamic note sorting after it has been

enabled on the SST, use the Clear BNA option on the Supervisor
Config to reset the list of cassettes. If the list of cassettes is not reset,
dynamic note sorting remains enabled.

The following scenarios illustrate how the dynamic note sorting

occurs.

Note: As the reconfiguration occurs during the Close state, there

are some scenarios where the reconfiguration cannot take place. For
example, reconfiguration cannot take place if a cassette becomes
nearly full during a series of transactions.

In all of these scenarios, the desired priority is Cassette 1, Cassette 2,

Cassette 3, and Cassette 4, and the array is defined as follows:
<Array ID="CashInCassetteReconfigurePriorityArray">
<Element Value="CI1" />

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-387

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<Element Value="CI2" />

<Element Value="CI3" />
<Element Value="CI4" />
</Array>

Scenario 1: No All‐in Cassette Configured 5

The cassettes are configured as follows:

— Cassette 1 (CI1) accepts ten‐euro notes
— Cassette 2 (CI2) accepts twenty‐euro notes
— Cassette 3 (CI3) accepts fifty‐euro notes
— Cassette 4 (CI4) accepts one hundred‐euro notes
If Cassette 1 becomes nearly full, Cassette 2 will be dynamically
configured to accept ten‐euro notes. Cassette 2 is reconfigured as it
is the next cassette in the priority list.
If Cassette 1 is not high but Cassette 2 becomes nearly full, Cassette
1 will be dynamically configured to accept twenty‐euro notes. In
this case, Cassette 1 is reconfigured as it has the highest priority.

Scenario 2: All‐in Cassette Configured 5

All cassettes are configured as follows:

— Cassette 1 (CI1) accepts ten‐euro notes
— Cassette 2 (CI2) accepts twenty‐euro notes
— Cassette 3 (CI3) accepts fifty‐euro notes
— Cassette 4 (CI4) accepts all notes (this is the all‐in cassette)
If Cassette 1 becomes nearly full, notes will be sorted to Cassette 4
with no reconfiguration.
If Cassette 4 also becomes nearly full, Cassette 2 will be dynamically
configured to accept ten‐euro notes.

This section describes the configuration options for cassettes in cash

GBXX Cassette acceptors and recyclers as follows:
Configuration 5

 “Cassette Configuration Using Supervisor” describes how to

configure cassettes using Supervisor menu options
 “XML Schema” on page 5‐391 describes the schema used for the
GBXX configuration file on NCR SSTs
 “GBXX Configuration File” on page 5‐397 describes the GBXX
configuration file used for NCR SSTs
 “Registry Entries for Recycling Units” on page 5‐399 describes
the registry settings needed for recycling
 “Fixed Cassette Mapping for Recycling” on page 5‐404 describes
configuring a fixed mapping to report recycling cassettes

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-388 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 “Maximum Accepted Notes” on page 5‐405 describes

configuring the maximum threshold for accepted notes.
 “Automatic Cassette Mapping using PhysicalPositionMap
Property” on page 5‐406 describes how to configure cassettes
using PhyscialPostionMap property.

Cassette Configuration Using Supervisor 5

The following options on the Supervisor Configure menu that allow

cassettes to be configured:
 39 GBXX CONFIG
 82 BNA CASS CFG

Note: These configuration options can be used only with GBXX

devices, and are not applicable to BNA devices.

For details of these options, refer to Chapter 4, “Configure Menu” in

the APTRA Advance NDC, Supervisor’s Guide. The configuration for
these options is detailed below.
39 GBXX CONFIG Option This option is used to configure 5

cassettes for NCR GBXX devices only. Configuration will fail if the
configuration file does not exist, or does not conform to the
guidelines provided here.
To configure the cassettes for a GBRU or GBNA, you must use an
XML configuration file and associated XML schema as described in
“GBXX Configuration File” on page 5‐397 and “XML Schema” on
page 5‐391. The displays associated with this option are controlled
by forms in the CIMConfigTasksTTU.frmttu file. This file is located in
C:\Program Files\NCR APTRA\Printing\TTU\forms.
An example configuration file is given in “GBXX Configuration
File” on page 5‐397. The file can be created and edited in any text
editor. No template or sample file is supplied with Advance NDC.
Once created, the GBRUConfig.xml configuration file must be
installed to C:\Program Files\NCR APTRA\Advance NDC\Config
using your preferred method.
Whenever the GBXX cassette configuration task is executed, the
cassette configuration sets present in the GBRUConfig.xml file can be
displayed through the property DisplayConfigurations in
CashInCustom.accfg file. By default, the DisplayConfigurations
property is set to False. If you want to view and apply the desired
cassette configuration set present in the GBRUConfig.xml file, set the
property to True. The following example shows the default XML
entry in the CashInCustom.accfg file.
<Class ID="NDCConfigureGBRU"
Name="NCR.APTRA.NDCConfigureGBRUTask.NDCConfigureGBRU"
Assembly="NCR.APTRA.NDCConfigureGBRUTask.dll">

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-389

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<Interface>
<!-Displays the cassette configuration sets present in
GBRUConfig.xml file. Default value is False -->
<Property Name="DisplayConfigurations" Value="False"/>
</Interface>
</Class>

If no cassettes are configured as all‐in cassettes, or the all‐in

cassettes become full, good notes may be rejected. This occurs when
an individual bin becomes full but the GBXX is still in service. To
avoid this situation, either ensure that any all‐in cassettes are
replenished immediately, or use dynamic note sorting if no all‐in
cassettes are configured. For details of dynamic note sorting, see
“GBXX Dynamic Note Sorting” on page 5‐386.
You must create the configuration file, and include the following
information:
 Currency
 Denomination
 Initial counts

Note: The initial counts in the NoteCount element must be set

to 0. The counts are updated by the ADD CASH replenishment
option in Supervisor mode. Recycle cassettes must not contain
more than one denomination.

 Number of notes to accept before reporting the high threshold

 List of notes that can be deposited in particular cassettes
 Settings for the GBRUMode registry entry
 Settings for the ValidationMode registry entry.
If you use Enhanced Configuration Parameter option 45 to specify
when to report a full cassette, the cassettes must be configured as
follows:
 If option 45 is set to report when the first cassette is full, the
cassettes must be configured as individual cassettes. With this
setting, Central is informed when at least one Note Type can no
longer be accepted
 If option 45 is set to report when one retract bin or all cash‐in
cassettes are full, the cassettes must be configured as all‐in
cassettes. With this setting, Central is only informed when all
cassettes are full.
For further information on option 45, refer to Chapter 7,
“Configuration Parameters” of the APTRA Advance NDC, Reference
Manual.
82 BNA CASS CFG Option This option can be used to configure 5

all vendors’ SSTs with the following limitations:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-390 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 Only one cash acceptor can be configured for an SST

 Multiple currencies can only be configured to a single cassette if
the cassettes are configured using note IDs.
 Further vendor‐specific configuration may be required. The
GBRU and validation mode settings on NCR SSTs require
further configuration, for example, which can be achieved using
option 39 GBXX CONFIG or the XML configuration file.

XML Schema 5

The following schema must be referenced, as shown in “GBXX

Configuration File” on page 5‐397:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3org/2001/XMLSchema">
<xs:complexType name="NoteIDSType">
<xs:sequence>
<xs:element name="NoteID" type="xs:string" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="CassetteType">
<xs:sequence>
<xs:element name="CassetteID" type="xs:string"
minOccurs="1" maxOccurs="1"/>
<xs:element name="CurrencyType" type="xs:string
minOccurs="1" maxOccurs="1""/>
<xs:element name="CurrencyValue" type="xs:string"
minOccurs="1" maxOccurs="1"/>
<xs:element name="NoteCount" type="xs:string"
minOccurs="1" maxOccurs="1"/>
<xs:element name="NoteIDS" type="NoteIDSType"
minOccurs="1" maxOccurs="1"/>
<xs:element name="MaxCashInItems" type="xs:string"
minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ConfigDetailsType">
<xs:sequence>
<xs:element name="Cassette" type="CassetteType"
maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="ConfigID" type="xs:string"
use="required"/>
</xs:complexType>
<xs:complexType name="ActiveConfigType">
<xs:sequence>
<xs:element name="ActiveConfigID" type="xs:string"/>
<xs:element name="GBRUMode" type="xs:string"/>
<xs:element name="ValidationMode" type="xs:string"/>
<xs:element name="CatMode" type="xs:string"/>
<xs:element name="Cat3RollBack" type="xs:string"/>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-391

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

<xs:element name="Cat3StoragePolicy" type="xs:string"/>

<xs:element name="SuspectCassetteID" type="xs:string"/>
</xs:sequence>
</xs:complexType>
<xs:element name="GBRUConfig">
<xs:complexType>
<xs:sequence>
<xs:element name="ActiveConfig" type="ActiveConfigType"/>
<xs:element name="ConfigDetails" type="ConfigDetailsType"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>

Schema Elements The schema elements are described in the 5

following table.

Table 5-135
XML Schema Elements

Element Name Description

GBRUConfig The whole file is embedded within GBRUConfig tags.

This is the root element.

Nested elements:
 ActiveConfig
 ConfigDetails

ActiveConfig Mandatory.

Appears once only.

Defines the mode of operation and validation for a device. Defines the configuration to
use for the current device.

The mandatory GBRUNumber attribute identifies the device that is to be configured.

Nested elements:
 ActiveConfigID
 GBRUMode
 ValidationMode

ActiveConfigID Mandatory.

Identifies the configuration set to use when configuring the current device.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-392 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Element Name Description

GBRUMode Mandatory for a GBRU.

Ignored for a GBNA.

Identifies the mode in which a GBRU works.

Valid values are as follows:

0 ‐ Recycling mode. Cash can be deposited to and dispensed from the same recycling
cassette.

1 ‐ Cash Dispense mode. Cash can only be dispensed from a cash‐out cassette

2 ‐ Cash Deposit mode. Cash can only be deposited to cash‐in cassettes

3 ‐ Non‐recycling mode. Cash can be deposited to a cash‐in cassette, and dispensed from a
cash‐out cassette, but these must be separate cassettes

Note: If using the GBRU as a cash‐in/cash‐out device, this must be set to 3

ValidationMode Mandatory.

Identifies the currency validation mode of the device.

Valid values are as follows:

0 ‐ Actual notes

1 ‐ Test notes

CatMode Mandatory.
See Table Note 6
Defines the ECB 6 mode. For more information on ECB 6 modes and related settings, see
“ECB 6 Modes” on page 5‐374.

Valid values are as follows:

0 ‐ ECB 6 mode is disabled. All notes are identified as either category 1 or category 4

1 ‐ Full ECB 6 support. Provides standard ECB 6 note categorisation, as described in “ECB
6 Note Categories” on page 5‐367.

2 ‐ Notes are identified as unrecognised, counterfeit, or authenticated. Suspect notes are

treated as unrecognised.

3 ‐ Suspect and authenticated notes can be stored together.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-393

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Element Name Description

Cat3RollBack Only used when CatMode is set to 1.

Defines whether suspect notes are retained or returned to the cardholder.

Valid values are:

0 ‐ store suspect notes according to the Cat3StoragePolicy value (default).

1 ‐ return suspect notes to the cardholder if the transaction is cancelled or notes are
refunded.

Cat3StoragePolicy Only used when Cat3RollBack is set to 0.

Sets the destination for suspect notes.

Valid values are:

0 ‐ store suspect notes in an all‐in cassette (default).

1 ‐ store suspect notes only in position 1, as defined by the SuspectCassetteID

value.

SuspectCassetteID Only used if Cat3StoragePolicy is set to 1.

Identifies the cassette used for suspect notes.

Valid values are:

CIxx ‐ where xx is the magnetic setting on the designated cassette

ConfigDetails Mandatory.

Appears at least once.

Defines a complete set of configuration parameters to use when configuring a device.

Each ConfigDetails sub‐element is identified by a ConfigID attribute. This

ConfigID attribute is used by the ActiveConfig sub‐element to determine the
configuration to use.

The optional GBRUNumber attribute identifies the device that is to be configured.

Nested elements:
 Cassette
 ConfigID

ConfigID Mandatory.

Identifies a configuration set to be used for configuring the device.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-394 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Element Name Description

Cassette Mandatory.

Defines the configuration parameters for each cassette that is to be configured.

Nested elements:
 CassetteID
 CurrencyType
 CurrencyValue
 NoteCount
 MaxCashInItems
 NoteIDS

CassetteID Mandatory.

Identifies the cassette; for example CI15, RC10, or BC5.

Cassettes that are present in the SST and have corresponding entries in the XML file are
configured. No changes are made to the configuration of any cassette that is present in the
SST but does not have a corresponding entry in the XML file.

NCR recommends that entries are included for all cassettes currently present in the SST to
avoid possible conflicts when changing the configuration.

Entries can be included for cassettes not currently present in the SST to avoid reworking
the XML file in the future.

Note: If a recycling cassette is identified and the mode is changed such that recycling is
not supported, the CassetteID should be updated to identify a bill cassette. For example,
RC1 would be updated to BC1. All other configuration settings can remain the same.

CurrencyType Mandatory.

Identifies the currency to be accepted or dispensed by the cassette.

If CurrencyType is empty and NoteIDS is specified, the cassette is configured to accept

the specified note.

If CurrencyType is empty and NoteIDS is empty, the cassette is configured to accept all
notes.

CurrencyType uses the ISO‐4217 format.

Settings must not conflict with the Advance NDC cash dispenser mapping registry
entries.

Note: Only one CurrencyType can be specified. To accept multiple currency notes, use
all the individual NoteIDS.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-395

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Element Name Description

CurrencyValue Mandatory.

Identifies the value of the currency to be accepted or dispensed by the cassette.

If CurrencyValue is empty and CassetteID points to a cash‐in cassette, the cassette is

configured to accept all notes.

This value must be set to 0 or a single value for an individual type cassette.

NoteCount Mandatory.

Specifies the number of notes available in the cassette.

This value must initially be set to zero (0). Running ADD CASH in Supervisor mode
populates the counts.

NoteIDS Mandatory

Defines one or more note identifiers for the currency and value specified in
CurrencyType and CurrencyValue.

If multiple note identifiers are specified, the CurrencyType and CurrencyValue are
ignored.

Nested elements:
 NoteID

NoteID Optional.

Identifies a note ID for the currency and value specified in CurrencyType and
CurrencyValue.

Note ID values are vendor‐specific.

MaxCashInItems Optional.

Specifies the maximum number of notes that can be accepted before the SP reports a
cassette high threshold. If the MaxCashInItems element is present but empty, the
current setting is retained.

If the cassette is a bill cassette (type BC or CI), and the MaxCashInItems element is not
present, the default of 2000 is used

If the cassette is a retract, reject, or counterfeit bin, the following apply:

 When running the GBXX configuration file, only the MaxCashInItems element is
used
 If the MaxCashInItems element is not present, the default of 200 is used

Table Note 6: If the CatMode value is set to 1 or 2, the ECB 6

database support utility must be installed. See “ECB 6 Database
Support Utility” on page 5‐376.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-396 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

GBXX Configuration File 5

The following example of a GBXX configuration file defines the

following:
 The recycling unit can deposit cash to cash‐in cassettes and
dispense from cash‐out cassettes, but these must be separate
cassettes
 The GBXX is in the Test notes validation mode
 ECB 6 is fully supported, with suspect notes stored in cash‐in
cassette 1
 Configuration 1 is not used. This would configure cash‐in
cassettes 1 and 2 for any currency and denomination, cash‐in
cassette 3 for five‐euro notes (EUR), and cash‐in cassette 15 for
ten‐euro notes
 Configuration 2 is set as active and configures bill cassette 1 for
fifty‐euro notes, bill cassette 2 for one hundred‐euro notes, and
cash‐in cassette 3 is configured as an all‐in cassette.
The cassettes must contain the configured denominations.
<?xml version="1.0" encoding="utf-8"?>
<GBRUConfig
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="GBRUConfig.xsd">
<ActiveConfig>
<ActiveConfigID>2</ActiveConfigID>
<GBRUMode>3</GBRUMode>
<ValidationMode>1</ValidationMode>
<CatMode>1</CatMode>
<Cat3RollBack>1</Cat3RollBack>
<Cat3StoragePolicy>1</Cat3StoragePolicy>
<SuspectCassetteID>CI1</SuspectCassetteID>
</ActiveConfig>

<ConfigDetails ConfigID="1">
<Cassette>
<CassetteID>CI1</CassetteID>
<CurrencyType></CurrencyType>
<CurrencyValue></CurrencyValue>
<NoteCount>0</NoteCount>
<NoteIDS/>
</Cassette>
<Cassette>
<CassetteID>CI15</CassetteID>
<CurrencyType>EUR</CurrencyType>
<CurrencyValue>10</CurrencyValue>
<NoteCount>0</NoteCount>
<NoteIDS>
<NoteID>260</NoteID>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-397

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

</NoteIDS>
</Cassette>
<Cassette>
<CassetteID>CI3</CassetteID>
<CurrencyType>EUR</CurrencyType>
<CurrencyValue>5</CurrencyValue>
<NoteCount>0</NoteCount>
<NoteIDS>
<NoteID>259</NoteID>
</NoteIDS>
</Cassette>
<Cassette>
<CassetteID>CI2</CassetteID>
<CurrencyType></CurrencyType>
<CurrencyValue></CurrencyValue>
<NoteCount>0</NoteCount>
<NoteIDS></NoteIDS>
</Cassette>

</ConfigDetails>

<ConfigDetails ConfigID="2">
<Cassette>
<CassetteID>BC1</CassetteID>
<CurrencyType>EUR</CurrencyType>
<CurrencyValue>50</CurrencyValue>
<NoteCount>0</NoteCount>
<NoteIDS>
<NoteID>260</NoteID>
</NoteIDS>
</Cassette>
<Cassette>
<CassetteID>BC2</CassetteID>
<CurrencyType>EUR</CassetteType>
<CurrencyValue>100</CurrencyValue>
<NoteCount>0</NoteCount>
<NoteIDS>
<NoteID>261</NoteID>
</NoteIDS>
</Cassette>
<Cassette>
<CassetteID>CI3</CassetteID>
<CurrencyType></CurrencyType>
<CurrencyValue></CurrencyValue>
<NoteCount>0</NoteCount>
<NoteIDS></NoteIDS>
</Cassette>

</ConfigDetails>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-398 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

</GBRUConfig>

Registry Entries for Recycling Units 5

The following registry configuration is needed to support separate

cash‐in and cash‐out functions or full recycling functionality on a
recycling unit.

Note: To enable recycling, GBRUMode must be set to 0 using the

GBXX configuration file. For details, see “GBXX Cassette
Configuration” on page 5‐388. Recycling must also be enabled using
Enhanced Configuration option 45 as described in Chapter 7,
“Configuration Parameters” of the APTRA Advance NDC, Reference
Manual.

Table 5‐136, “Recycling Unit: Registry Entries Set by Advance

NDC” below, shows the entries set by Advance NDC, and
Table 5‐110, “Recycling Unit: GBxx Registry Entries Set by Advance
NDC” on page 5‐399, shows the entries that you must update to
complete the configuration.

Table 5-136
Recycling Unit: Registry Entries Set
by Advance NDC

Registry Entry Description Value

HKLM\Software\NCR\ Set at installation to set the recycling unit mode. 3

XFS GBRU‐GBNA Service Provider\ For details of the recycling unit modes see
XFS‐DeviceControl\GBRU‐GBNA\Operations\ Table 5‐135 on page 5‐392.
GBRUMode

HKLM\Software\NCR\ Set at installation to set the recycling unit suspend 900

XFS GBRU‐GBNA Service Provider\ timeout.
XFS‐DeviceControl\GBRU‐GBNA\Operations\ Advance NDC uses the maximum value to ensure
SuspendTimeout that it has control over the recycling unit timeouts.

HKLM\Software\NCR\XFS GBRU‐GBNA Set at installation to allow a reset command to be 1

Service Provider\ sent when the recycling unit is in suspend mode.
XFS‐DeviceControl\GBRU‐GBNA\
Interoperability\AllowResetDuringSuspend

HKLM\Software\NCR\ Set at installation to ensure that the MANIP status 1

XFS GBRU‐GBNA Service Provider\ is not reported when a cassette is inserted. The
XFS‐DeviceControl\ state is only reported for a short time and is
GBRU‐GBNA\Interoperability\ automatically cleared.
SuppressManipStatus For details of changing the default setting, see
or “Reporting the MANIP Status of GBRU Cassettes”
\GBRU‐GBNA2\Interoperability\ on page 5‐401
SuppressManipStatus

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-399

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Registry Entry Description Value

HKLM\Software\ Set at installation to prevent notes found in the 1

NCR\XFS GBRU‐GBNA Service Provider\ stacker when WFS_CMD_CDM_DISPENSE is
XFS‐DeviceControl\GBRU‐GBNA\ called from being automatically sent to the reject
Interoperability\NotRejectOnDispense area.

HKLM\Software\NCR\ Set at installation to prevent notes found in the 0

XFS GBRU‐GBNA Service Provider\ stacker when WFS_CMD_CIM_CASH_IN_START
XFS‐DeviceControl\GBRU‐GBNA\ is called from being automatically sent to the reject
Interoperability\RejectOnCashInStart area.

HKLM\Software\NCR\ Set at installation to prevent automatic error 1

APTRA Self‐Service Support (NCR Features)\ recovery when a hardware error occurs.
GBRU\Operational Parameters\
DisableAutoResetErrorRecovery This is to avoid the device performing automatic
error recovery in the middle of a cardholder
session, which would delay the transaction.

HKLM\Software\NCR\ Set at installation to ensure that notes are not 0

APTRA Self‐Service Support (NCR Features)\ cleared from the transport at startup.
GBRU\Operational Parameters\
ClearTransportOnStartUp

HKLM\Software\NCR\Advance NDC\ Set at runtime if the device is a recycling unit. 1

CashRecycler\BillDispenser

HKLM\Software\NCR\Advance NDC\ Set at runtime depending on the setting of

CashRecycler\CashRecyclerMapping Enhanced Configuration option 78.

If option 78 is 000 0

If option 78 is 001 1

HKLM\Software\NCR\Advance NDC\ Set at runtime to identify whether an error has

CashRecycler\ResetRequired occurred, and whether any error was on a cash‐in
or a cash‐out transaction.

If there was no error 0

If there was an error during a cash‐out transaction 1

If there was an error during a cash‐in transaction 2

HKLM\Software\NCR\Advance NDC\ Set at runtime to identify whether the last

CashRecycler\TransactionType transaction was a cash‐in or a cash‐out transaction.

If the last transaction was a cash‐out transaction 0

If the last transaction was a cash‐in transaction 1

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-400 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Registry Entry Description Value

HKLM\Software\NCR\Advance NDC\ Set at installation to clear the cash‐in error during

CashRecycler\ClearRecycler a Test Cash operation and cash‐out error during
INIT BNA operation when the device is a recycler
working in recycling mode

Do not clear the cash‐in error during a Test Cash 0

operation and cash‐out error during an INIT BNA
operation

Clear the cash‐in error during a Test Cash 1

operation and cash‐out error during an INIT BNA
operation

Reporting the MANIP Status of GBRU Cassettes 5

To enable or disable the reporting of the MANIP status for GBRU

cassettes, the SuppressManipStatus registry entry under the
following registry keys is used as appropriate for the primary and
secondary recycling units:
HKLM\Software\NCR\XFS GBRU-GBNA Service
Provider\XFS-DeviceControl\GBRU-GBNA\Interoperability

or
HKLM\Software\NCR\XFS GBRU-GBNA Service
Provider\XFS-DeviceControl\GBRU-GBNA2\Interoperability

Valid values for SuppressManipStatus are as follows:

0 = WFS_XXX_STATCUMANIP status is not cleared when the lower
transport or purge bin is inserted
1 = WFS_XXX_STATCUMANIP status is cleared when the lower
transport or purge bin is inserted (the default)
The variable XXX is either CDM or CIM.
When a physical cassette is inserted, the cassette status is set to
WFS_XXX_STATCUMANIP and a WFS_CMD_XXX_END_EXCHANGE
command is required to clear the status.
The value of SuppressManipStatus specifies whether
WFS_XXX_STATCUMANIP is automatically cleared by the service
provider when the lower transport or purge bin is re‐inserted.

Note: If the value is changed, the SST must be re‐booted for the
new setting to take effect.

CDM and CIM NDC Cassette Types 5

The cash recycler service providers (for example GBRU SP, BRM SP)
provide two device interfaces: a CDM XFS interface for performing
dispense operations and a CIM XFS interface for deposit operations.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-401

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

A mapping of XFS logical cash units (XFS Logical Types) to physical

cassettes for GBRU is created by the SP for both interfaces as shown
in the following example:

Figure 5-88 Cash In GBRU Cash Out

XFS Logical Cash Units to Physical
Cassettes
XFS Logical Type 1 DEPOSIT CASSETTE
ALL IN

XFS Logical Type 2 RECYCLING CASSETTE XFS Logical Type 1

10 EUR

XFS Logical Type 3 RECYCLING CASSETTE XFS Logical Type 2

20 EUR

XFS Logical Type 4 RECYCLING CASSETTE XFS Logical Type 3

100 EUR
CIM Interface for Physical Cassettes CDM Interface for
Deposit Operations Dispense Operations

Both CDM NDC cassette types and CIM NDC cassette types are
obtained by a mapping to the XFS Logical Types but the way in
which this is done is different.
CIM NDC Cassette Types The mapping of CIM NDC cassette 5

types to XFS CIM logical cash units is a simple one‐to‐one mapping

in which CIM NDC Cassette Type 1 maps directly to XFS Logical
Type 1 on the CIM interface, CIM NDC Cassette Type 2 maps
directly to XFS Logical Type 2 on the CIM interface and so on.
CDM NDC Cassette Types CDM NDC cassette types are defined 5

in the registry under the following registry entry:

HKLM\Software\NCR\Advance DC\CurrencyTable\
NDCTypeX

where X is a value in the range 1 to 7.

Example Cassette Mappings At Start of Day, the XFS logical 5

structure from the CDM XFS interfstace is obtained and the

mapping from CDM NDC cassette types to XFS CDM logical cash
unit is created. For example, with the following values defined in
the currency table:

NDCType1 10 EUR

NDCType2 20 EUR

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-402 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

NDCType3 50 EUR

NDCType4 100 EUR

the mappings for CIM NDC cassette types and CDM NDC cassette
types are the following:

Figure 5-89
NDC Types to XFS Logical Cash Units to
Physical Cassettes

Cash In GBRU Cash Out

NDC Type 1 XFS Logical Type 1 DEPOSIT CASSETTE NDC Type 1

ALL IN

NDC Type 2 XFS Logical Type 2 RECYCLING CASSETTE XFS Logical Type 1 NDC Type 2
10 EUR

NDC Type 3 XFS Logical Type 3 RECYCLING CASSETTE XFS Logical Type 2 NDC Type 3
20 EUR

NDC Type 4 XFS Logical Type 4 RECYCLING CASSETTE XFS Logical Type 3 NDC Type 4
100 EUR
CIM NDC CIM Interface for Physical Cassettes CDM Interface for CDM NDC
Cassette Type Deposit Operations Dispense Operations Cassette Type

The following table, Table 5‐137, “Example Mappings”, shows the

cassette type mappings for CIM and CDM for the configuration
given above during example deposit and dispense transactions.

Table 5-137
Example Mappings

XFS Logical Type

CIM NDC Cassette XFS Logical Type on CDM NDC Cassette
Transaction on the CDM
Type the CIM Interface Type
Interface

Deposit to 20 EUR cassette 3 3 2 2

Dispense from 10 EUR cassette 2 2 1 1

The CDM NDC Type 3 cassette has no mapping to an XFS CDM

logical cash unit as no cassette matches the denomination specified
in the Currency Table registry key.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-403

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Fixed Cassette Mapping for Recycling 5

By default, the NDC cassette type is mapped to the XFS logical cash
unit automatically. Defining a fixed cassette mapping means that
you can match the deposit cassette IDs with the dispense cassette
IDs.
A fixed mapping must be used when recycling is enabled and you
want to report fixed cassette types in a Ready ‘B’ or other status
message.
To configure fixed mapping, the following tasks must be completed:
 The CassetteFixedMappings property must be uncommented
in the CashInCustom.accfg file
 The CassetteFixedMappings array must be populated

Note: The GBRUMode registry entry must be present as described in

“Registry Entries for Recycling Units” on page 5‐399.

Uncommenting the Property The following section of the 5

CashInCustom.accfg file must be uncommented as shown below:

<Class ID="CassetteMapper"
Name="NCR.APTRA.NDC.CashAcceptService.GBxxCassetteMapper"
Assembly="NCR.APTRA.NDC.CashAcceptService.dll">
<Interface>
<Property Name="CassetteFixedMappings"
Value="CassetteFixedMappings" IsArray="true"/>
</Interface>
</Class>

Populating the Array The array must be populated with the 5

required mapping pairs using the following fomat:

Element Value ="<CassetteID>=<XFS logical cash unit>"

The following example array maps two recycling cassettes and one
cash‐in cassette:
<Array ID="CassetteFixedMappings">
<Element Value="RC1=1"/>
<Element Value="RC2=2"/>
<Element Value="CI15=3"/>
</Array>

The cassettes are reported using three digits, therefore, the cassette
defined in the first line of the above example would be reported as
‘001’.
For further information on the CassetteID element, see “GBXX
Cassette Configuration” on page 5‐388.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-404 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Valid values for the XFS logical cash unit are between 0 and 255. For
restrictions to this range, see “Reporting Missing or Invalid
Mappings” below.
Single to Multiple Mapping A single NDC cassette type must not 5

be mapped to more than one XFS logical cash unit unless the
network contains both GBNA and GBRU devices with recycling
enabled. In this situation, you can set up a single to multiple
mapping, but you must not insert the cassettes at the same time.
This allows a single CashInCustom.accfg file to be used on different
SSTs across the network. If the cassettes are inserted at the same
time and recycling is enabled, the recycling cassette is given
precedence over the cash‐in cassette. If this situation occurs,
Advance NDC adds 100 to the value reported by the service
provider. To avoid this situation, NCR recommends that the XFS
logical cash unit identifier is not duplicated.
Reporting Missing or Invalid Mappings If a mapping is not 5

found for a cassette or the mapping value is invalid, the cassettes are
reported as follows:
 For cash‐in cassettes Advance NDC adds 100 to the value
reported by the service provider
 For recycling cassettes Advance NDC adds 200 to the value
reported by the service provider.
Due to these adjustments, NCR recommends that no cassettes are
mapped to values in the following ranges:
 100 to 115
 200 to 215.

Maximum Accepted Notes 5

If Enhanced Configuration option 45 is used to limit the number of

accepted notes to 90 (default setting) and you also use any GBXX
units, you must reduce the number of notes accepted by the cash‐in
devices to 90.
To limit the number of accepted notes, update the
usmaxAcceptednote parameter in the GBRU_DP2_initial.ini file.
This parameter is set by default to 200.
The file is located in C:\Program Files\NCR APTRA\PcGBRU and
can be edited using a text editor.

Journaling Note Counts 5

During a deposit transaction, the count of the inserted notes that

pass through the note separator is logged to the journal printer and
the count of notes in the escrow is logged to EJ by using the reserved
screen U0147.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-405

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Automatic Cassette Mapping using

PhysicalPositionMap Property 5

The PhysicalPositionMap property under the GenericCassette

Mapper class can be used to overwrite the automatic mapping
configured by the GBXXCassetteMapper class.
The following format is used for the PhysicalPositionMap
property:
"Physical Position Name 1"-"Reporting Position
1"|"Physical Position Name 2"-Reporting Position 2"|
…|"Physical Position Name n"-"Reporting Position n"

Where the Physical Position Name is the actual physical position

reported by the device and Reporting Position is the NDC
physical cassette type.
To Use PhyscialPositionMap Property In the CashInCustom.accfg 5

file the following section must be commented out and the

GenericCassetteMapper information must be added:
<Class ID="CassetteMapper"
Name="NCR.APTRA.NDC.CashAcceptService.GBxxCassetteMapper"
Assembly="NCR.APTRA.NDC.CashAcceptService.dll">
<Interface>
<Property Name="" Value="CassetteFixedMappings"
IsArray="true"/>
</Interface>
</Class>

The following extract is an example of the GenericCassetteMapper

class in the CashInCustom.accfg file, which shows the Physical
PositionMap property configured for three physical cassettes,
retract, reject and counterfeit bins for a GBXX device:
<Class ID="CassetteMapper"
Name="NCR.APTRA.NDC.CashAcceptService.GenericCassetteMapper"
Assembly="NCR.APTRA.NDC.CashAcceptService.dll">
<Interface>
<Property Name="PhysicalPositionMap" Value="Cassette
1-Cassette1|Cassette 2-Cassette2|Cassette
3-Cassette3|Captured bin-Retract|Reject
bin-Reject|Counterfeit bin-Counterfeit"/>
</Interface>
</Class>

For example, if the above configuration is specified and cassette 4 is

inserted, the information related to Cassette 4 is not reported
anywhere in the application as it is not mapped to any of the NDC
physical casette type.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-406 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

GBXX Device with Cassettes Not Configured 5

When a GBXX device is configured in a recycle mode and any

cassette that are inserted during replenishment are not configured
using the GBXX config supervisor option, the application does not
perform the cash deposit or dispense transactions to that particular
cassette.
The supervisor options such as CLR BNA, INIT BNA, CLR CASH
and ADD CASH are performed successfully based on the value of
IgnoreUnconfiguredCUsDuringExchange registry only when the
fault display shows the following error:
CASH HANDLER CASSETTEx VALS ERROR (for CDM cassette)

BNA CASSETTEx FATAL for CIM cassette)

Table 5-138 Registry Entry Type Value

Registry Entry to ignore Casettes that are
not configured HKLM\SOFTWARE\NCR\Advance NDC\ REG_ 0 (Default)
CashRecycler\IgnoreUnconfigured 1
DWORD
CUsDuringExchange

If the registry value is set to 0, the supervisor options CLR BNA,

INIT BNA, CLR CASH, ADD CASH and GBXX Config fail.
If the registry value is set to 1, the supervisor options CLR BNA,
INIT BNA, CLR CASH and ADD CASH pass. However, the GBXX
Config supervisor option fail.

The BRMCassetteMapper class in the CashinCore.accfg file

Automatic Cassette automatically maps XFS physical cassettes with NDC physical
Mapping for a BRM Device 5
cassette types for a BRM device.

A device status of High is triggered when the service provider

Deposit Cassette reports a high status.
Maximum Threshold 5

For details of the service provider maximum settings, refer to the

APTRA on‐line documentation for ulMaximum under APTRA XFS
| Programmers Reference | XFS Service Providers.

The 83 BRM Cassette Configuration option on the Configure menu

BRM Cassette in Supervisor allows cassettes to be configured on a BRM device.
Configuration 5

For details of this option, refer to Chapter 4, “Configure Menu” in

the APTRA Advance NDC, Supervisor’s Guide. The configuration
for this option is detailed below.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-407

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

The displays associated with this option are controlled by forms in

the CIMConfigTasksTTU.frmttu file. This file is located in C:\Program
Files\NCR APTRA\Printing\TTU\forms.
To configure the cassettes for a BRM, you must use the
BRMConfig.xml configuration file and associated XML schema.
Configuration will fail if the configuration file does not exist or an
invalid XML is present.

BRM Configuration XML File 5

The BRMConfig.xml is used to configure the cassettes on a BRM

device. The BRMConfig.xml is stored in the following location:
C:\Program Files\NCR APTRA\Advance NDC\Config
XML Schema The schema, BRMConfig.xsd, defines the structure of 5

the configuration data for the cassettes as shown in “BRM

Configuration File Example” on page 5‐412. The order of the tags is
important in the XML configuration file as the supervisor task
validates the schema on the BRMConfig.xml file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-408 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Figure 5-90
BRM Configuration Schema
<?xml version="1.0" encoding="utf-8"?>
<xs:schema id="BRMConfig" xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
<xs:element name="BRMConfig" msdata:IsDataSet="true" msdata:UseCurrentLocale="true">
<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element name="Operations">
<xs:complexType>
<xs:sequence>
<xs:element name="DepositOnlyCassettes" type="xs:string" minOccurs="0" />
<xs:element name="DispenseOnlyCassettes" type="xs:string" minOccurs="0" />
<xs:element name="MaxDispenseItems" type="xs:string" minOccurs="0" />
<xs:element name="P6Mode" type="xs:string" minOccurs="0" />
<xs:element name="CassetteConfigSetID" type="xs:string" minOccurs="0" />
</xs:sequence>
<xs:element name="DepositOnlyCassettes" type="xs:string" minOccurs="0" />
<xs:element name="DispenseOnlyCassettes" type="xs:string" minOccurs="0" />
<xs:element name="MaxDispenseItems" type="xs:string" minOccurs="0" />
<xs:element name="P6Mode" type="xs:string" minOccurs="0" />
<xs:element name="CassetteConfigSetID" type="xs:string" minOccurs="0" />
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="CassetteConfig">
<xs:complexType>
<xs:sequence>
<xs:element name="Cassette" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="CassetteID" type="xs:string" minOccurs="0" />
<xs:element name="CurrencyType" type="xs:string" minOccurs="0" />
<xs:element name="CurrencyValue" type="xs:string" minOccurs="0" />
<xs:element name="MaximumLimit" type="xs:string" minOccurs="0" />
<xs:element name="NoteIDS" type="xs:string" minOccurs="0" />
<xs:element name="FwItemType" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="TypeAll" type="xs:boolean" minOccurs="1" />
<xs:element name="TypeUnFit" type="xs:boolean" minOccurs="1" />
<xs:element name="TypeIndividual" type="xs:boolean" minOccurs="1" />
<xs:element name="TypePLevel3" type="xs:boolean" minOccurs="1" />
<xs:element name="TypePLevel2" type="xs:boolean" minOccurs="1" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-409

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="setID" type="xs:string" />
</xs:complexType>
</xs:element>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>

Schema Elements The schema elements are described in the 5

following table:

Table 5-139
BRM Configuration XML Schema
Elements

Element Name Description

DepositOnlyCasse Mandatory for cash‐in cassettes.

ttes
Indicates which recycle cash units should be used for only deposit.

Valid values are a list of numbers between 1 and 15, which represents the number of the
physical recycle cash units that will be used for deposit.

A value of 0 is by default assigned as the Cassette 0 (CI0) is always a deposit cassette.

For example, a value of 1,5,7 sets the recycle cassettes, 1, 5, and 7 to be used for deposit
only operations.

The numbers in the list are reported through the CIM interface as
WFS_CDM_TYPECASHIN based on the cUnitID field.

DispenseOnlyCass Mandatory for bill cassettes.

ettes
Indicates which recycle cash units should be used for only dispense.

Valid values are a list of numbers between 1 and 15, which represents the number of the
physical recycle cash units that will be used for deposit.

For example, a value of 2,3,6 sets the recycle cassettes, 2, 3, and 6to be used for dispense
only operations.

The numbers in the list are reported through the CIM interface as
WFS_CDM_TYPEBILLCASSETTE based on the cUnitID field.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-410 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Element Name Description

MaxDispenseItem Optional.
s
Specifies the maximum number of notes that can be dispensed in one bunch. This value is
used to restrict the size of a bunch.

Valid value can be a number between 1 and the maximum number of notes that can be
dispensed using the device variant.

For a pocket variant, the maximum value is 300, which is the default value.

For a slot variant, the maximum value is 200, which is the default value.

P6Mode Optional.

Defines the mode of note categorisation. For information on P6 mode, see “BRM Registry
Entry for User Update” on page 5‐315

CassetteConfigSetI Mandatory.
D
Identifies the configuration set to use when configuring the device

FwItemType Optional

Specifies the FwItemType to be configured by the task for Cash‐In and Recycling
Cassettes

Nested Elements:
 TypeAll
 TypeUnfit
 TypeIndividual
 TypePLevel3
 TypePLevel2

If FWItemType is defined, all the nested elements must be defined.

TypeAll Mandatory.

Specifies that the cassette accepts all notes.

TypeUnFit Mandatory.
.
Specifies that the cassette accepts the unfit notes of the configured NoteIDs

TypeIndividual Mandatory.

Specifies that the cassette accepts individual Note IDs.

If this is set for a cash‐in cassette, the CurrencyType and CurrencyValue are mandatory.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-411

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Element Name Description

TypePLevel3 Mandatory.

Specifies that the cassette accepts the suspect notes of configured NoteIDs.

TypePLevel2 Mandatory.

Specifies that the cassette accepts the counterfeit notes of the configured NoteIDs.

CassetteID Mandatory.

Specifies the type of cassette; RC, CI and BC.

CurrencyType Mandatory.

Identifies the currency to be accepted or dispensed by the cassette, for example, EUR
(Euro).

CurrencyValue Mandatory.

Identifies the value of the currency to be accepted or dispensed by the cassette, for
example, 50, 100 or 500.

NoteIDS Optional.

Defines the set of NoteIDs that the cassette accepts. If there are multiple NoteIDs, they
should be separated by a comma.

If multiple NoteIDs are defined, the CurrencyValue must be set to 0

MaximumLimit Optional.

Specifies the maximum number of notes that can be accepted before the SP reports a
cassette high threshold.

Note: The configuration for Retract, Reject and Counterfeit is

optional. If the configuration is not defined, the application will use
the existing values.

Recycling Cassettes At the start of day, all the cassettes are 5

configured as recycling cassettes by default. The TypeIndividual

element of FwItemType must be set to 1 and the other nested
elements in the FwItemType element must be set to 0 for recycling
cassettes.

BRM Configuration File Example 5

The following example of a BRM Configuration file defines the

following:
 The first cassette is configured as a deposit cassette for five‐euro
notes (EUR)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-412 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 The second cassette is configured as a recycling cassette for

ten‐euro notes (EUR)

Figure 5-91
BRM Configuration Extract
<BRMConfig>
<Operations>
<DepositOnlyCassettes>1</DepositOnlyCassettes>
<DispenseOnlyCassettes></DispenseOnlyCassettes>
<MaxDispenseItems>200</MaxDispenseItems>
<P6Mode>0</P6Mode>
<CassetteConfigSetID>1</CassetteConfigSetID>
</Operations>
<CassetteConfig setID = "1">
<Cassette>
<CassetteID>CI1</CassetteID>
<CurrencyType>EUR</CurrencyType>
<CurrencyValue>5</CurrencyValue>
<MaximumLimit>100</MaximumLimit>
<NoteIDS>259</NoteIDS>
<FwItemType>
<TypeAll>0</TypeAll>
<TypeUnFit>0</TypeUnFit>
<TypeIndividual>1</TypeIndividual>
<TypePLevel3>0</TypePLevel3>
<TypePLevel2>0</TypePLevel2>
</Cassette>
<Cassette>
<CassetteID>RC2</CassetteID>
<CurrencyType>EUR</CurrencyType>
<CurrencyValue>10</CurrencyValue>
<NoteIDS>260</NoteIDS>
</Cassette>
</CassetteConfig>
</BRMConfig>

Fixed Cassette Mapping for BRM 5

By default, the NDC cassette type is mapped to the XFS logical cash
unit automatically. Defining a fixed cassette mapping means that
you can match the deposit cassette IDs with the dispense cassette
IDs.
A fixed mapping must be used when recycling is enabled and you
want to report fixed cassette types in a Ready ‘B’ or other status
message.
To configure fixed mapping, the following tasks must be completed:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-413

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 The CassetteMapperNCRBRM property must be uncommented in

the CashInCustom.accfg file
 The CassetteFixedMappings array must be populated
Uncommenting the Property The following section of the 5

CashInCustom.accfg file must be uncommented as shown below:

<Class ID="CassetteMapperNCRBRM"
Name="NCR.APTRA.NDC.CashAcceptService.BRMCassetteMapper"
Assembly="NCR.APTRA.NDC.CashAcceptService.dll">
<Interface>
<Property Name="CassetteFixedMappings"
Value="BRMCassetteFixedMappings" IsArray="true"/>
</Interface>
</Class>

Populating the Array The array must be populated with the 5

required mapping pairs using the following format:

Element Value ="<CassetteID>=<XFS logical cash unit>"

The following example array maps three recycling cassettes and two
cash‐in cassettes:
<Array ID="BRMCassetteFixedMappings">
<Element Value="CI0=1"/>
<Element Value="CI1=2"/>
<Element Value="RC2=3"/>
<Element Value="RC3=4"/>
<Element Value="RC4=5"/>
</Array>

The cassettes are reported using three digits, therefore, the cassette
defined in the first line of the above example would be reported as
‘001’.
For further information on the CassetteID element, see “BRM
Cassette Configuration” on page 5‐407.
For further information on fixed cassette mapping, see “Fixed
Cassette Mapping for Recycling” on page 5‐404.

By default, a BRM device is used as a recycler as there is no

Configuring a BRM device configuration available from XFS to use it as a deposit only or as a
as a Deposit only dispense only device. However, a user can configure the BRM
or a Dispense only 5 device to a deposit only or as a dispense only device by updating
the ANDCSST.xml file.
To configure a BRM device to a deposit only device, set the Cash
Dispenser registry to empty and CurrencyDispenser1 registry to
Not used in the following registry keys:
 HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\
Aliases\Cash Dispenser

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-414 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

 HKEY_LOCAL_MACHINE\SOFTWARE\ActiveXFS\
CurrencyDispenser1

To configure a BRM device to a dispense only device, set the Cash

Acceptor registry to empty and CashInModule1 registry to Not
used in the following registry keys:
 HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\
Aliases\Cash Acceptor
 HKEY_LOCAL_MACHINE\SOFTWARE\ActiveXFS\CashInModule1

An example to configure the BRM device as a deposit only device is

as follows:
<Configure actionlist ="Configure BRM as Deposit only"/>
….
<ActionList name=" Configure BRM as Deposit only ">
<Action Implements="registry" description="To configure
BRM as Deposit only ">
[HKEY_LOCAL_MACHINE\SOFTWARE\ActiveXFS]
"CurrencyDispenser1"="Not used"
[HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance
NDC\Aliases]
"Cash Dispenser"=""
</Action>
</ActionList>

BRM can be configured to swap the reject and retract bin. To

Configuring BRM to Swap configure, perform the following steps:
Reject and Retract Bin 5

1 Create a DWORD registry with the name BinConfiguration in

the following path:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\XFS BRM Service
Provider\XFS-DeviceControl\BRM\Operations

By default, the value of the registry is 0. Set the

BinConfiguration registry value to 1 to swap the reject and
retract bin.

2 Edit the ANDCSST.XML file as follows:

<provider name="BillDispenser1">
<!-- GBRU or GBXX-->
<HardwareName NameId="DEVNAME=NACC-01-GBRU">
<Configure actionlist ="GBRU Cassette Names
Recycler"/>
<Configure actionlist ="Unknown As
NotPresented"/>
</HardwareName>
<HardwareName
NameId="DEVNAME=NACC-01-USBBunchRecycler">
<!-- BRM-->
<Configure actionlist="Set BRMDispenser

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-415

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

AliasName"/>
<!--Configure actionlist ="BRM Cassette Names
Recycler"/-->
<Configure actionlist="CDM Physical Positions
Auto Detection" />
</HardwareName>
</provider>

3 Perform the supervisor option, option 94, Auto‐Configure

devices.

On a BRM device, when a Test Cash operation is performed for a

Validating the Incorrect cassette loaded with an incorrect denomination or a wrong
Denomination 5
denomination and if notes are picked from these cassette, the Test
Cash reports only the good cassette list and excludes the cassette
with incorrect denomination.
Advance NDC can be configured to validate the incorrect
denomination loaded in the cassettes when the Test Cash operation
is performed by using the following (DWORD) registry entry:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\AdvanceNDC\CashHandler\
ReportCassWithWrongDenomFatal.

The valid values are as follows:

 0 = Disabled (default)
 1 = Enabled
If the registry key is missing or any value other than 1 is used, the
default behaviour is applied.
When this option is enabled and the cassette is loaded with an
incorrect denomination, the Test Cash operation displays the list of
good cassettes. If only one cassette is present in the machine and the
same is incorrectly loaded, the Test Cash reports as No Good
Cassettes.

The incorrectly loaded cassette is marked as fatal and the fault

display shows X Cass Error, where X is the position of the
cassette that has the incorrect denomination. The same cassette is
reported as fatal in the terminal command response so that the host
can mark the cassette as unavailable and avoid any dispense from
that cassette.
If this option is disabled and the cassette is loaded with an incorrect
denomination, the Test Cash operation reports the status as good
and no error is sent to the host or reported on the fault display. In
case the notes are dispensed from this cassette, they are picked and
moved to the reject bin.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-416 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

When a logical cassette is mapped to more than one physical

cassette and if one of the physical cassettes is loaded with an
incorrect denomination, the status is reported as fatal for all the
physical cassettes that are mapped to that logical cassette. Following
are few examples:
Example 1 In a device that has four recycling cassettes, RC1, RC2, 5

RC3 and RC4 and all have one to one logical cassette mapping with
the following configuration:
RC1 = 5 ÔST
RC2 = 10 ÔST
RC3 = 20 ÔST
RC4 = 50 ÔST

NDCType Configuration under the registry key:

HKey_Local_Machine/Software/NCR/Advance NDC/Currency
Table
NDC Type1
Currency ID : ÔST
MediaType: 12
Value : 5
NDC Type2
Currency ID : ÔST
MediaType: 12
Value : 10
NDC Type3
Currency ID : ÔST
MediaType: 12
Value : 20
NDC Type4
Currency ID : ÔST
MediaType: 12
Value : 50

If RC1 has incorrect denomination, RC2, RC3, and RC4 have correct
denominations, the Test Cash report will have the following
message:
SECOND CASSETTE GOOD
THIRD CASSETTE GOOD
FOURTH CASSETTE GOOD

The fault display will show the following message:

TOP CASS ERROR

The respective logical cassettes will be reported as fatal in the

terminal command response.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-417

Configuring Advance NDC and Associated Components
Configuring Cash Acceptors

Example 2 In a device that has Cassette 1 and Cassette 2 mapped 5

to RC1, Cassette 3 and Cassette 4 are mapped to RC3 and RC4

respectively with the following configuration:
RC1 = 5 ÔST
RC3 = 20 ÔST
RC4 = 50 ÔST

NDCType Configuration under the registry key:

HKey_Local_Machine/Software/NCR/Advance NDC/Currency
Table
NDC Type1
Currency ID : ÔST
MediaType: 12
Value : 5
NDC Type3
Currency ID : ÔST
MediaType: 12
Value : 20
NDC Type4
Currency ID : ÔST
MediaType: 12
Value : 50

If Cassette 1 and Cassette 2 are configured to same denomination

but Cassette 1 is loaded with incorrect denomination, the Test Cash
report will have the following message:
THIRD CASSETTE GOOD
FOURTH CASSETTE GOOD

The fault display will show the following message:

TOP CASS ERROR
SECOND CASS ERROR

The logical cassette is reported as fatal in the terminal command

response.

Note: When the status of a cassette is reported as fatal in the

terminal response, the host has to ensure that no further dispense is
made from that cassette. In case of an attempt to dispense, the
transaction would fail as there are no valid notes in the cassette and
an unsolicited status message is reported with cassette severity as
fatal.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-418 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cheque Processors

Configuring Cheque Processors 5

This section describes the functionality that can be configured for

the Cheque Processors.

The SharedChequeDetail class in the AdvanceNDCCore.accfg file

Accessing Cheque Data 5

allows customisations to access cheque data. To avoid problems

with data access, you must not change the following text in the
AdvanceNDCCore.accfg file:

Figure 5-92
Example Shared Cheque Detailed Extract
<Class ID="SharedChequeDetail" Name="NCR.APTRA.NDC.Customisation.ChequeDetails.
SharedChequeDetail" Assembly="NCR.APTRA.NDC.Customisation.ChequeDetails.dll" Remoted="Any">
<Constructor>
<Argument Name="chequeAcceptServiceName" Value="_IChequeAcceptService" />
</Constructor>
</Class>

The object for the

NCR.APTRA.NDC.Customisation.ChequeDetails class is required
to access the cheque details and the
NCR.APTRA.NDC.CashInDataAccess.dll reference is required to
access the cash‐in CDI stores using script.
Dim chqDetails
Set chqDetails =
CreateObject("NCR.APTRA.NDC.Customisation.ChequeDetails.Chequ
eDetail")

The location of an image lifted by the cheque processing module

Cheque Processing (CPM) is set using the following registry key:
Module 5

HKLM\SOFTWARE\NCR\Advance NDC\CPM

The default path is C:\Program Files\NCR APTRA\Advance

NDC\ChequeImages.

Note: If your solution is to be PA‐DSS compliant, see “Cheque

Processing Solutions” on page E‐11, in Appendix E, “PCI DSS &
PA‐DSS Compliance in Advance NDC”.

If your printer can use the Epson Graphics format, you can print the
lifted image. The following registry entries provide the escape
sequence to allow printing of Epson Graphics:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Receipt\CHEQUE

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-419

Configuring Advance NDC and Associated Components
Configuring Cheque Processors

Note: USB receipt printers print cheque images regardless of

the value set here.

HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Journal\CHEQUE

If the value is empty, the escape sequence to print a cheque image is

ignored. For details of escape codes, refer to the APTRA Advance
NDC, Reference Manual or your printer’s documentation.
To rotate the lifted image anti‐clockwise by 90 degrees, set the
following registry entry to 1:

HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Receipt\
RotateChequeImage

The following entry is used to calculate the area used to mask the
codeline:

HKLM\SOFTWARE\NCR\Advance NDC\CPM\CodeLineHeight

The minimum value is 1 and the maximum is 40. The default is 40.
This value must be less than that defined by the
ChequeSizeRotated registry entry described in “Resizing the
Image” on page 5‐420.
If you are using a Branch Assist 18 SST, change the value of the
following registry entry from ChequeProcessor1 to
DocumentProcessor1:
HKLM\SOFTWARE\NCR\Advance NDC\Aliases\Cheque Processor

Cheque Images on Two‐Sided Thermal Printers 5

On two‐sided thermal printers, the following registry key allows

local configuration when printing cheque images on receipts:
HKLM\SOFTWARE\NCR\Advance NDC\CPM

The following entry controls whether the cheque image is printed

on the front or back:
AlwaysPrintChequesOnBack

By default, this entry is set to 0. This prints the cheque image as

specified in the escape sequence used in the message from Central.
If the entry is set to 1, the cheque image is always printed on the
back irrespective of the escape sequence in the message from
Central.

Resizing the Image 5

The cheque image can be resized by an amount specified in

millimetres; the DPI registry entry is used to convert the millimetre
setting for printing. The default DPI registry entry is 0, which is 150

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-420 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cheque Processors

DPI. To resize the lifted image, use the appropriate registry entry as
follows:
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Receipt\
ChequeSizeNormal

Use this entry when the RotateChequeImage registry entry is

set to 0 (default). The default value is 75, the minimum value is
10 and the maximum value is 75.
HKLM\SOFTWARE\NCR\Advance NDC\PRINTING\Receipt\
ChequeSizeRotated

Use this entry when the RotateChequeImage registry entry is

set to 1. The default value is 75, the minimum value is 10 and the
maximum value is 90.

Raw Data Printing For raw data printing, no additional lines are 5

inserted when a lifted image is printed. Also, the receipt length

defined by message mode option digit 6 is ignored to allow the
increased receipt length. You have to ensure that the total receipt
length for both text and image is not likely to result in a cardholder
trying to remove the receipt before printing has completed.
For details of the message mode option digits, refer to the APTRA
Advance NDC Supervisor’s Guide.

Form and Media Definitions 5

Default forms and media definitions are provided for cheque

endorsement, as described in Table 5‐140. These forms can be
modified to match the capabilities of the CPM. The default
installation locations are as follows:
 Forms
C:\Program Files\NCR APTRA\Printing\CPM\Forms
 Media definitions
C:\Program Files\NCR APTRA\Printing\CPM\Media.

Table 5-140 File Description

Cheque Endorsement Form & Media
Definitions LocalEndorse.def Used when a cheque is captured locally. The data
used to endorse the cheque is based on reserved
screen U0057. For details of this screen, refer to
the APTRA Advance NDC, Reference Manual

Endorse.def Used when the single‐line endorsement data sent

from the host does not start with the ‘?’ character

SpecialEndorse.def Used when the endorsement data sent from the

host starts with the ‘?’ character

CPMMedia.def Common media definition for all endorsing

operations

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-421

Configuring Advance NDC and Associated Components
Configuring Cheque Processors

Reserved screen U0057 contains the locally customisable string used

for endorsing a cheque. The default endorsement data is as follows:

<Machine Number> <Track 2 Data> CAPTURED <Date> <Time>

If the machine number is not defined, the endorsement data starts

with the track 2 data. The track 2 data is masked for security
reasons. The date format is dd/mm/yy. The time format is
hh:mm:ss.
For example, the default endorsement data could appear as follows:

012345 ;XXXXXXXXXXXXXXXXX0507 CAPTURED 24/09/10 14:05:20

Magnetic Ink Character Recognition (MICR) Option 5

By default, Advance NDC includes MICR reading when processing

cheques. To disable MICR reading, change the registry entry from 1
to 0 as in the following example:
HKLM\SOFTWARE\NCR\Advance NDC\CPM
"EnableMICR"=dword:00000000

You can configure a bunch cheque acceptor as follows:

Bunch Cheque Acceptor 5

 To configure the codeline for different fonts

 To suppress status messages in off‐line cheque deposit
transactions
 To accept cheques in a single orientation only
 To support a cheque validation service
 To retrieve the cheque image path
 To retrieve the setting of bit 4 of Enhanced Configuration
Parameter option 83.

Configuring the Codeline 5

As bunch cheque acceptors can support both the CMC7 MICR

barcode font and the E13B MICR font for automatic cheque
processing, the Bunch Cheque Accept Service has to be configured
for the required format through the Class Configurator.
To configure the required font, add a line for the CodeLineFormat
property in the AdvanceNDCCustom.accfg file and include the font
value, CMC7 or E13B, as shown in the following example for the
CMC7 font:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-422 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cheque Processors

Figure 5-93
Example Code Line Format Extract
<Class ID="IChequeAcceptService" Name="NCR.APTRA.BunchChqAccptSrv.
XFSBunchChequeAcceptService" Assembly="NCR.APTRA.BunchChqAccptSrv.dll">
<Property Name="MICRFormat" Value="NCRFormat"/>
</Class>
<Property Name="CodeLineFormat" Value="CMC7"/>

Suppressing Status Messages 5

In offline bunch cheque deposit transactions, the following registry

entry controls whether status messages are suppressed for the
bunch cheque acceptor:
HKLM\SOFTWARE\NCR\Advance NDC\CPM\
SuppressSCPMStatusMessages

Valid settings are as follows:

0 ‐ Send status messages (default)
1 ‐ Do not send status messages.

Note: The information is still journaled when this registry entry is

set to 1.

Accepting Cheques in a Single Orientation 5

You can accept cheques in one orientation only; you must disable
optical character recognition (OCR) on the PTR SP.
To disable OCR, set the following registry setting to 0:
%ULYBASEKEY%/USB Scalable Cheque Processing Module/
Operational Parameters/EnableOCR

Note: If your solution is to be PA‐DSS compliant, see “Cheque

Processing Solutions” on page E‐11, in Appendix E, “PCI DSS &
PA‐DSS Compliance in Advance NDC”.
Returning Invalid Cheques When the validation centre identifies 5

a cheque as invalid, the cheque is marked for return and returned

later in the transaction. For off‐line transactions, the cheques are
returned in Bunch Cheque Handling State. For host driven
transactions the cheques are either returned or moved to deposit
bin. This happens in line with cheque destination settings in the
transaction reply. This is a default setting which can be changed
through an XML configuration file available in C:\Program
Files\NCR APTRA\Advance NDC\Config.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-423

Configuring Advance NDC and Associated Components
Configuring Cheque Processors

To change the default behaviour, update the value of

"RefuseNonValidCheques" in AdvanceNDCCustom.accfg file as
shown below:

Figure 5-94
Example Refuse Invalid Cheques Extract
<Class ID="IChequeAcceptService" Name="NCR.APTRA.BunchChqAccptSrv.
XFSBunchChequeAcceptService" Assembly="NCR.APTRA.BunchChqAccptSrv.dll">
<Interface>
<Property Name="RefuseNonValidCheques" Value="TRUE"/>
</Interface>
</Class>

Caution For a Scalable Cheque Processing Module (SCPM) support, any

modifications to functionality or operation must be done through
Advance NDC state processing and off‐line processing. The on‐line
documentation for the .NET Bunch Cheque Acceptance Service is
provided for information on configuring and using the data
provided through this interface. Programming directly to the API is
not supported.

Note: This functionality currently does not support a Scalable

Deposit Module (SDM) if used as a bunch cheque acceptor as the
capabilities of an SDM and an SCPM are different.

Moving Returned Cheques to Retract Bin 5

When a returned cheque is not collected by the cardholder, the

cheque should be moved to the retract bin. The RejectBin
property’s value must be set accordingly. The following extract
shows an entry in AdvanceNDCCustom.accfg, which allows the
returned cheques (which are not collected) to move to the retract bin
on an SDM.

Figure 5-95
Example Moving Returned Cheque Extract
<Class ID="IChequeAcceptService" Name="NCR.APTRA.BunchChqAccptSrv.
XFSBunchChequeAcceptService" Assembly="NCR.APTRA.BunchChqAccptSrv.dll">
<Interface>
<Property Name="RejectBin" Value="2"/>
</Interface>
</Class>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-424 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cheque Processors

Supporting a Cheque Validation Service 5

The following extract shows an entry in AdvanceNDCCustom.accfg to

support a cheque validation service, which involves no NDC
configuration and can only be set using this file. If this were edited
by changing the LogInvalidCheques property to “True”, invalid
cheques would be logged.

Figure 5-96
Example Log Invalid Cheques Extract
<Class ID="IChequeValidation" Name="NCR.APTRA.CodelineChqValidator.CodelineValidator"
Assembly="NCR.APTRA.CodelineChqValidator.dll">
<Interface>
<!--Property Name="JournalService" Value="IJournalService"/-->
<Property Name="TerminalService" Value="ITerminalService"/>
<Property Name="TestDefinitionFile" Value="C:\Program Files\NCR APTRA\Advance
NDC\Config\NCRCVSCONFIG.XML"/>
<Property Name="LogValidCheques" Value="False"/>
<Property Name="LogInvalidCheques" Value="False"/>
</Interface>
</Class>

Retrieving the Cheque Image Path 5

The following extract shows an entry in AdvanceNDCCore.accfg to

retrieve the path used for cheque images from the registry:

Figure 5-97
Example Retrieving Cheque Image Path
Extract
<Property Name=”ImageCreationDir” Value=”C:\Program
Files\NCR APTRA\Advance NDC\ChequeImages”
DataDictionary=”AANDC Configuration”
DictionaryRecordType=”HKEY_LOCAL_MACHINE\SOFTWARE\NCR\
Advance NDC\CPM” DictionaryFieldName=”ImagePath”/>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-425

Configuring Advance NDC and Associated Components
Configuring Cheque Processors

Retrieving the Scan After Endorsement Setting 5

The following extract shows an entry in AdvanceNDCCore.accfg to

retrieve the setting of bit 4 of Enhanced Configuration Parameters
option 83 (scan after endorsing the cheque):

Figure 5-98
Example Retrieving Scan after
Endorsement Setting Extract
<Property Name=”ScanAfterEndorse” Value=”true”
DataDictionary=”NDC Configuration”
DictionaryRecordType=”Boolean”
DictionaryFieldName=”idOption83:2”/>

For details of the Enhanced Configuration Parameters, refer to

Chapter 7, “Configuration Parameters”, of the APTRA Advance
NDC, Reference Manual.

Endorsing Cheques Returned by the Host 5

If the cheque processor supports the endorsement of returned

cheques, any cheques returned by the host can be endorsed. If an
NCR bunch cheque acceptor is used, the XFS SCPM service
provider must be changed from IPM to PTR to configure the device
as a single cheque acceptor.
For details of configuring the bunch cheque acceptor for single
cheque acceptance, refer to the USB SCPM component release
bulletin.

Courtesy amount recognition (CAR) and legal amount recognition

Cheque Amount (LAR) can be implemented for cheque processing. To implement
Recognition 5
amount recognition, you must do the following:
 Contact NCR Financial Software Engineering for
implementation details and advice
 Purchase and configure a third‐party cheque validation engine,
such as those offered by A2iA or Parascript
 Implement and integrate the CAR/LAR support in Advance
NDC.

The ImageMark Passport ATM Image Agent, available from NCR,

ImageMark Passport ATM assists in the reconciliation of deposits. For details, contact your
Image Agent 5
local Payment and Imaging team representative.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-426 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cheque Processors

By default, support for the ImageMark Passport ATM Image Agent

is disabled in Advance NDC. To use this feature, change the value
of the following registry entry to 1 or 3:
HKLM\SOFTWARE\NCR\Advance NDC\CPM\ImageMark

Valid values for this entry are as follows:

0 to disable ImageMark Passport ATM Image Agent
1 to enable ImageMark Passport ATM Image Agent for
successful cheque deposits only
3 to enable ImageMark Passport ATM Image Agent for
successful cheque deposits and for the CLR DEPOS and CLR
BINS Replenish menu options in Supervisor.
The SST machine number is set using the Supervisor configuration
menu. The SST machine number is used to identify the source of the
transaction (see SourceId in “Transaction Data File: XML
Elements” on page 5‐430) and in the back‐office processing of the
cheques.
If cardless transactions are enabled, a method of identifying the
correct account must be provided. This allows the back‐end system
to determine the account number to post the deposit to and generate
any adjustments, such as an incorrectly entered cheque amount,
against. For further information, please contact your local Payment
and Imaging team representative.
The ImageMark Passport ATM Image Agent does the following:
 Defines the location of the upload directory. The path is
specified in the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\CPM\Path

If this registry entry does not exist, or does not contain a value,
or the specified path is invalid, the following path is assumed by
default:
C:\Program Files\NCR APTRA\Passport

Note: If your solution is to be PA‐DSS compliant, see “Cheque

Processing Solutions” on page E‐11, in Appendix E, “PCI DSS &
PA‐DSS Compliance in Advance NDC”.

 For each successful cheque deposit, the ImageMark Passport

ATM Image Agent completes the following steps:
1 Copies images lifted during cheque processing to the
specified path

2 Creates a temporary data file

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-427

Configuring Advance NDC and Associated Components
Configuring Cheque Processors

3 Renames the temporary file when all the data has been
written to the temporary data file, as required by the
Passport Agent. For details of the file see “Example
Transaction Data File” on page 5‐429.
 Creates an XML file when the CLR DEPOS or CLR BINS option
is selected from the Replenish menu in Supervisor. For details of
the file, see “Example Clear Option File” on page 5‐432.

Note: When the CLR BINS option is selected, the XML file is
created for each cleared bin on a CPM. On a bunch cheque acceptor,
an XML file is created only when the first bin with a non‐zero count
is cleared.

ImageMark Passport ATM Image Agent Filenames All files use 5

the following filename format:

<identifier><yyyymmdd>-<hhmmss>+<machine number>#
<transaction number><front/back><image number>.<extension>

The variables in the filename are described in the following table.

Table 5-141 Variable Description

Cheque Deposit Filename Variables
<identifier> Identifies whether the file was created for a
cheque deposit or clear option.
If a cheque deposit, this is TXN
If a clear option, this is BIN

<yyyymmdd> The date of the transaction in numeric year,

month, day format (yyyymmdd)

<hhmmss> The time of the transaction in numeric hour,

minute, second format (hhmmss)

<machine number> The machine number of the SST used for the
transaction

<transaction The number of the transaction

number>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-428 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cheque Processors

Variable Description

<front/back> Only used for front image or rear image files.

Identifies whether the image is of the front or
back of the cheque.
If the front, this is f
If the back, this is r

<image_number> Only used for front image or rear image files.

Identifies the number of the image and
matches the associated ItemId tag described in
Table 5‐142 on page 5‐429
For a CPM, this is always 01

<extension> The file extension.

If an image file, this is bmp
If a temporary file, this is tmp
If an XML file, this is xml

The following table provides example of filenames created

following successful cheque deposit and the selection of a CLR
DEPOS or CLR BINS option in Supervisor.

Table 5-142 Description Filename

Example Cheque Deposit Files
Front image TXN20071207‐091459+123456#1785f01.bmp
Rear image TXN20071207‐091459+123456#1785r01.bmp
Temporary data TXN20071207‐091459+123456#1785.tmp
Transaction data TXN20071207‐091459+123456#1785.xml
(renamed temporary
data file)

CLR DEPOS or CLR BIN20071207‐163459+12345#1945.xml

BINS options

Example Transaction Data File The transaction data file and front 5

and rear image files are created on a successful cheque deposit. The
cheque is considered to be successfully deposited when the
Transaction Reply message contains the Process Cheque function
identifier. If the cheque is ejected, or captured because the
cardholder has not taken the ejected cheque, the cheque is not
successfully deposited and no files are created. For details of the
Transaction Reply message, refer to the APTRA Advance NDC,
Reference Manual.
The transaction data file is an XML file with two sections:
transaction details and item details. For example, the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-429

Configuring Advance NDC and Associated Components
Configuring Cheque Processors

TXN20071207‐091459+123456#1785.xml file from the example above

would be as follows:

Figure 5-99
Example Transaction Data File Extract
<Tran>
<Version>2</Version>
<SourceId>123456</SourceId>
<TransactionId>1785</TransactionId>
<TranDate>20071207</TranDate>
<TranTime>091459</TranTime>
<PAN>5505123456789012</PAN>
<TansactionSource>ATM</TransactionSource>
<NumberOfItems>01</NumberOfItems>
<DepositAmount>10</DepositAmount>
<Item>
<ItemId>01</ItemId>
<ItemType>03</ItemType>
<MICR>:000067894: 87654321<2214</MICR>
<ItemAmount>10</ItemAmount>
</Item>
</Tran>

The file is populated by Advance NDC using the elements

described in Table 5‐143. For bunch cheque acceptors, the
information is provided by the ImageMark Deposit Recorder
component.

Table 5-143 XML Tag Description Populated With

Transaction Data File: XML Elements
Version The version of 2
XML used

SourceId The SST used for The machine number

the transaction

TransactionId Identifies the The NDC transaction

transaction sequence number

TranDate The date of the The date that the transaction

transaction occurred in yyyymmdd
format

TranTime The time of the The time that the transaction

transaction occurred in hhmmss format

PAN The primary The PAN read from the card

account number inserted for the transaction
of the card used in
the transaction

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-430 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cheque Processors

XML Tag Description Populated With

TransactionSource The type of device ATM

used for the
transaction

Source Location Describes the Source location identifier

location of the with a maximum of 20
source alphanumeric characters
Not supported for CPMs

NumberOfItems A count of the The number of cheques

number of <Item> deposited in this transaction.
tags included in For CPMs, this is always 1
the transaction

DepositAmount The amount being The total amount deposited

deposited Maximum of 30 numeric
characters
For CPMs, this is read from
the NDC Amount buffer
For bunch cheque acceptors,
the Cheque Detail Display
state allows the cardholder
to enter the amount. The
decimal point is not
exported, so any user of this
XML file, such as the
consolidation server, must
know how many decimal
points are used

ItemId Identifies the item Two digit count of the item.

in the transaction For the CPM, this is always
that the .bmp files 01
are associated
with

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-431

Configuring Advance NDC and Associated Components
Configuring Cheque Processors

XML Tag Description Populated With

ItemType Identifies the type 03

of deposit

MICR The codeline from The codeline read from the

the cheque being cheque.
deposited If the codeline validation
service is used and the
codeline cannot be read, this
tag is empty
If the codeline validation
service is not used, this tag
contains the codeline as it
has been read with question
marks (?) in the place of
characters that could not be
read
Codeline validation can only
be used on bunch cheque
acceptors

ItemAmount The amount of the The amount is calculated as

deposit described for the
DepositAmount element

Example Clear Option File The clear option file is an XML file 5

that records the clearing of the cheque bins. For example, the
BIN20071207‐163459+12345#1945.xml file from the example above
would be as follows:

Figure 5-100
Example Clear Option File Extract
<Tran>
<SourceId>123456</SourceId>
<TransactionId>1945</TransactionId>
<TranDate>20071207</TranDate>
<TranTime>163459</TranTime>
<LocalAmountTotal>00</LocalAmountTotal>
<LocalTotalCount>1</LocalTotalCount>
</Tran>

Note: The clear option file is not created if the counts are zero
before the cheque bins are cleared, even if the ImageMark Passport
ATM Image Agent is enabled.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-432 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Cheque Processors

The file is populated by Advance NDC using the elements

described in the following table:

Table 5-144 XML Tag Description Populated With

Check Bin Empty XML Tags
SourceId The machine used The SST machine
for the transaction number

TransactionId Identifies the The NDC transaction

transaction sequence number

TranDate The date of the The SST system date

transaction when the transaction
occurred

TranTime The time of the The SST system time

transaction when the transaction
occurred

LocalAmountTotal Total of the amount 00

deposited

LocalCountTotal Total number of The number of cheques

cheques deposited in that have been
the bins cleared by removed from the bin
the CLR DEPOS or
CLR BINS option If the CLR BINS option
is selected, only the
selected bin is cleared.
On a bunch cheque
acceptor, if the selected
bin has a zero count,
nothing is exported

If you want your application to emulate NDC+ behaviour for

Envelope Dispenser 5

envelope dispensing, you need to configure the following registry

setting:
HKLM\SOFTWARE\NCR\Advance NDC\
EmulateNDCPlusEnvDisp
The settings for this key are:
 DWORD value 0 or the key does not exist:

An envelope is dispensed during the Deposit and Print function

if the NDC State C (Envelope Dispenser State) has not been used
(current ANDC behaviour).

 DWORD value 1:

No envelope is dispensed during the Deposit and Print function.

(NDC+ behaviour).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-433

Configuring Advance NDC and Associated Components
Configuring Colored MEEI

Configuring Colored MEEI 5

This section describes how the color of a Card Reader’s MEEI can be
configured.
By default, the application uses Green color and Fast flash rate. The
flash rate for the Card Reader can be changed by using MSG MODE
(Option Digit 8) in Supervisor or Enhanced Configuration Option
25. For information on MSG MODE (Option Digit 8), refer to
section, “Option Digit ‐8” in Appendix A, “Option Digits Table” of
the APTRA Advance NDC, Supervisor Guide. For information on
Enhanced Configuration Option 25, refer to section, Option 25 –
Media Entry/Exit Indicators Flash Rate of the APTRA Advance
NDC, Reference Manual.
The Card Reader registry key in the DefaultMEEIValues registry
is used to set the default color and flashrate. The following table
provides the details of the keys in the Card Reader. The path is:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\
DefaultMEEIValues\Card Reader

Table 5-145
Default MEEI Registry Key Values
Name Type Description Possible values Default Value

Color Integer Color to be 1 ‐ Green 1

displayed 2 ‐ Red
3 ‐ Yellow
4 ‐ Blue
5 ‐ Cyan
6 ‐ Magneta
7 ‐ White
FlashRate Integer Sets the rate at the 1 ‐ Slow 3
which the MEEI 2 ‐ Medium
should flash 3 ‐ Quick
4 ‐ Continuous
FlashRate Integer Decides which 0 ‐ The flash rate set in the Enhanced 0
Precedence value should be Configuration Option 25 or Message
considered for Mode 8 will be used
flashing 1‐ The value provided in the API will
be used

If the value is missing or is any value other than the possible values,
or if the specified color is not supported by XFS platform, the
default is used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-434 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring Colored MEEI

The SetMEEIColorAndFlashRate and

SetDefaultMEEIColorAndFlashRate APIs are available for
customisations to change the color or flash rate of the device MEEI
respectively. For information on the APIs, refer to the section
“Changing the Color of an MEEI” in the APTRA Advance NDC,
Extending the Product.
The FlashRate registry value is used when FlashRatePrecedence
is set to 1 and one of the following conditions is true:
 Start of the day ‐ If the SetMEEIColorAndFlashRate API is
not called.
 If the SetDefaultMEEIColorAndFlashRate API is used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-435

Configuring Advance NDC and Associated Components
Configuring CRM Flowpoint State

Configuring CRM Flowpoint State 5

The CRM Flowpoint State calls the specified CRM flowpoint and
also updates the ConsumerID with the corresponding BufferID
based on the configuration defined in the CRMFlowpoints.xml file.
Once the configured flow point is called, the corresponding
campaigns are displayed.
The CRMFlowpoints.xml and CRMFlowpoints.xsd files are stored in the
following location:
C:\Program Files\NCR APTRA\Advance NDC\Config
For more information on CRM Flowpoint state, refer to section,
“z021 ‐ CRM Flowpoint State” in Chapter 2, “State Tables” of the
APTRA Advance NDC, Reference Manual.
The schema, CRMFlowpoints.xsd defines the structure of the
configuration data for the CRM flowpoint state. Figure 5‐101
provides a sample CRMFlowpoints.xsd schema.

Figure 5-101
CRM Flow Points Schema Extract
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns="http://www.ncr.com/APTRA/NDC/CRMFlowpoints"
attributeFormDefault="unqualified" elementFormDefault="qualified"
targetNamespace="http://www.ncr.com/APTRA/NDC/CRMFlowpoints"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="CRMFlowpointClass">
<xs:complexType>
<xs:sequence>
<xs:element name="CRMFlowpoints">
<xs:complexType>
<xs:sequence minOccurs="0">
<xs:element maxOccurs="unbounded" name="Flowpoint">
<xs:complexType mixed="true">
<xs:sequence minOccurs="0">
<xs:element name="Property">
<xs:complexType>
<xs:attribute name="Name" type="xs:string" use="optional" />
<xs:attribute name="StoreID" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="Index" type="xs:string" use="optional" />
<xs:attribute name="Name" type="xs:string" use="optional" />

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-436 1APTRA Advance NDC, Developer’s Guide

 Configuring Advance NDC and Associated Components
Configuring CRM Flowpoint State

</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>

The schema elements are described in the following table:

Table 5‐146
CRM Flowpoint XML Schema Elements
Element Description

CRMFlowpointClass This is the root element.

Nested element: CRMFlowpoints

CRMFlowpoints Defines the flowpoint that is used to locate the parameters of the CRM
flowpoint defined in the CRMFlowpoints.xml file.

Nested element: Flowpoint

Flowpoint Defines the flowpoint index.

This element includes attributes called Index and Name.

Nested element: Property

Index The Index number that matches to Flowpoint Index (state table entry 3) of
the CRM flowpoint state. The value is in the range 001‐255.

Name The name of the CRM flowpoint that is called when the Flowpoint Index
(state table entry 3) of the CRM flowpoint state matches with index in the
CRMFlowpoints.xml file.

Property The CRM property that has to be updated with the value of configured
StoreID.

This element includes attributes called Name and StoreID.

Name The name of the CRM property that is updated with the value of the buffer
mentioned in the StoreID attribute. Currently only one CRM Property is
supported, which is ConsumerID.

StoreID The StoreID value is a CDI buffer. For more information on CDI buffers,
see “Table C‐8 on page C‐12”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

1APTRA Advance NDC, Developer’s Guide 5-437

Configuring Advance NDC and Associated Components
Configuring CRM Flowpoint State

Note: The data in the ConsumerID property is not overwritten

when the StoreID attribute defined in the CRMFlowpoints.xml file has
an invalid value.

CRM Flowpoint XML 5

The following example shows an XML entry for CRM flowpoint:

Figure 5-102
CRM Flowpoint XML Extract
<?xml version="1.0" encoding="UTF-8"?>
<CRMFlowpointClass xmlns="http://www.ncr.com/APTRA/NDC/CRMFlowpoints"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ncr.com/APTRA/NDC/CRMFlowpoints CRMFlowpoints.xsd">
<CRMFlowpoints>
<Flowpoint Index="123" Name="Card Inserted">
<Property Name="ConsumerID" StoreID="BufferB"/>
</Flowpoint>
</CRMFlowpoints>
</CRMFlowpointClass>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

5-438 1APTRA Advance NDC, Developer’s Guide

 Table of Contents
Configuring Voice Guidance

Chapter 6
Configuring Voice Guidance

Overview 6‐1

Introducing Voice Guidance 6‐2

Support for Audio Messages 6‐2
Enabling Voice Guidance 6‐2
Voice Guidance with Multiple Languages 6‐2
Voice Guidance without Host Change 6‐2
Voice Guidance and Cardless Transactions 6‐3
Standard Audio Capabilities 6‐3
Voice Guidance and Cardless Transactions on an SST with
Standard Audio 6‐3
Enhanced Audio Capabilities 6‐4
Voice Guidance During a Transaction 6‐5

Configuring Voice Guidance 6‐7

Prompting for a Language 6‐7
Indicator Volume Control 6‐8
Automatic Language Selection 6‐8
Orientation Message 6‐8
Configuring the Enter Key to Initiate Cardless Transactions 6‐8
Enabling Voice Guidance Without Host Updates 6‐9
Dynamic Data 6‐9
Voice Out Entered Key 6‐10
Configuring the Idle Loop Audio 6‐10
Configuring Third‐Party TTS Software 6‐10
The Voice Guidance Voices Array 6‐11
Specifying the Character Encoding 6‐12
Audio Elements Required in the XML Configuration File 6‐12
Other XML Files Used in Voice Guidance 6‐12
Local XML Configuration File 6‐13
Voice Guidance Unavailable 6‐13

Advance NDC Voice Guidance and Other Applications 6‐14

Using Voice Guidance with Promote 6‐14
Using Voice Guidance with Display Manager 6‐15

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Configuring Voice Guidance

XML Schema 6‐16

Schema Elements 6‐24
Voicing the Multi‐Lingual Data Examples 6‐42
Encoding Formats for Voice Guidance 6‐43

Example XML Configuration File 6‐45

Voice‐Guided Sessions without Host Update 6‐50

No Host Update XML Elements 6‐50
Transaction Reply 6‐59
Screen Display Update Field 6‐59
Printer Data Field 6‐66
Interactive Transaction Response 6‐68
ITR Screen Data Fields 6‐68
ITR Screen Timer Field 6‐69
ITR Display Flag Field 6‐69
ITR Active Keys/Touch Areas Field 6‐69
Transaction Request General Purpose Buffer B field 6‐69
Example ITR Message Conversion 6‐69
Example 2 ITR Message Conversion 6‐71
Example 3 ITR Message Conversion 6‐72
Example 4 ITR Message Conversion 6‐76
Send Configuration Information 6‐79

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
F

Overview

Overview 6

This chapter describes how to configure Advance NDC to use voice

guidance.
Voice guidance in Advance NDC is controlled primarily by an XML
configuration file, as described under the following headings:
 “Introducing Voice Guidance”
 “Advance NDC Voice Guidance and Other Applications”
 “XML Schema”
 “Example XML Configuration File”
Some functionality, such as prompting for a language is configured
through the registry.If you have the Americas implementation, this
is still supported without change. For information on the formats
used, refer to the US documentation provided with the
implementation

Note: For voice‐guided transactions, NCR recommends you to use

version 11 of Windows Media Player to ensure efficient memory
handling.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-1

Configuring Voice Guidance
Introducing Voice Guidance

Introducing Voice Guidance 6

Voice guidance provides audio assistance to guide a

visually‐impaired consumer through a transaction.

To support voice guidance, two methods of providing audio

Support for Audio messages are supported in Advance NDC as follows:
Messages 6

 Voice recordings, which are provided in any file format that is

supported by Advance NDC. These files are referenced from the
XML configuration file for voice guidance
 Text messages voiced by any third‐party text‐to‐speech (TTS)
software for Windows, such as Vocalizer from Nuance
Communications Inc. It converts XML text messages to speech.

Note: Any TTS software must be purchased separately and

installed; however, Windows does provide Windows Media
Player and basic TTS software.

These methods can be used in any combination in the order defined

in the voice guidance XML configuration file.

To enable voice guidance on an SST, the following are required:

Enabling Voice Guidance 6

 A valid AudioGuidanceData.xml file in C:\Program Files\NCR

APTRA\Advance NDC\Config
 If you intend to use third‐party TTS software, it must be
installed on the SST
 If you intend to use audio files, they must be present on the SST
 Message mode option digit 1 must be set to enable voice
guidance. For details of Option Digit 1, refer to the APTRA
Advance NDC, Supervisor’s Guide.

Voice Guidance with Multiple Languages 6

To use different voices for multiple languages, you can edit the
AdvanceNDCCustom.accfg file to configure the TTS software. For
details, see “Configuring Third‐Party TTS Software” on page 6‐10.

Voice Guidance without Host Change 6

To use voice‐guided sessions without updating the host, the

NHCVGAudio.xml file must also be installed to C:\Program
Files\NCR APTRA\Advance NDC\Config using your preferred
method. This file defines the rules for parsing the Interactive
Transaction Response and the Transaction Reply messages and
includes the text for the data normally supplied by these messages

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-2 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Introducing Voice Guidance

Voice Guidance and Cardless Transactions 6

To use the Enter key or FDKs to initiate cardless transactions when

voice guidance is enabled, the following registry entries must be
configured:
 Active FDK Mask described in “Key Mask Definition” on page
5‐120
 Active PIN Pad Key Mask described in “Configuring the Enter
Key to Initiate Cardless Transactions” on page 6‐8.

On an SST that cannot detect when a headset is plugged into an

Standard Audio audio jack, a voice‐guided session can be initiated by the selection of
Capabilities 6
a defined key, or the selection of a defined language.
During the idle loop, the application monitors for a specific key
press to mark the beginning of a voice‐guided session. For cardless
transactions, the audio instruction for the idle loop in the XML file
has to explain to the consumer that either the Enter key or any
configured FDK can be used to trigger cardless transactions, along
with the key used to initialize voice guidance. The key used for
voice guidance is mapped based on the XML.
An audio message identifying the required selection plays in a
continuous loop until the selection is made to initiate the session. If
a key press is used to initiate voice guidance, the cardholder may
then be prompted to select a language to be used for the transaction.

Note: Advance NDC application will report the audio status as

fatal if the audio drivers or files such as sound card, the
text‐to‐speech engine, or Windows Media Player are not available
on the SST.

Voice Guidance and Cardless Transactions on an SST with

Standard Audio 6

The following table shows the actions for voice‐guided and cardless
transactions on an SST with standard audio enabled and both
Active FDK Mask and Active PIN Pad Key Mask entries configured
in the registry:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-3

Configuring Voice Guidance
Introducing Voice Guidance

Table 6‐1 Transaction Stage Action and Effect

Standard Audio SST: Voice Guidance and
Cardless Transactions Voice guidance and cardless Pressing a specified numeric key,
transactions are enabled but which is configured for voice
not initiated. guidance initiates a voice‐guided
transaction.
or
Pressing the Enter key or a
configured FDK initiates a cardless
transaction without voice guidance.
or
Inserting a card initiates a cardholder
transaction without voice guidance.

Voice guidance is enabled and Inserting a card at the prompt or after

initiated language selection initiates a
cardholder transaction and the
application goes to the next
configured state.
or
Pressing a configured FDK at the
prompt initiates a cardless
transaction

A voice‐guided transaction has The consumer is prompted audibly to

been successfully completed, press a configured key to initiate a
but the headset is left plugged voice‐guided transaction or, in
in. response to the on‐screen prompt, to
press any configured FDK, which
initiates a cardless transaction
without voice guidance.

On an SST that can detect when a headset is plugged into the audio
Enhanced Audio jack, this initiates a voice‐guided session.
Capabilities 6

If language options are available, the consumer is then prompted to

select a language to be used for the transaction.
Voice Guidance and Cardless Transactions with Enhanced
Audio
The following table shows the actions available for voice‐guided
and cardless transactions on an SST with enhanced audio enabled
and both the Active FDK Mask and the Active PIN Pad Key Mask
configured in the registry.

Table 6-2 Transaction Stage Action and Effect

Enhanced Audio SST: Voice Guidance
with Cardless Transactions Voice guidance and cardless Plugging in a headset initiates a
transactions are enabled but voice‐guided transaction.
not initiated.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-4 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Introducing Voice Guidance

Transaction Stage Action and Effect

Voice guidance is enabled and Inserting a card at the prompt or after

initiated language selection initiates a
cardholder transaction and the
application goes to the next
configured state.
or
Pressing any configured FDK
initiates a cardless transaction.

A voice‐guided transaction has The consumer is audibly prompted to

been successfully completed, press a configured numeric key to
but the headset is left plugged initiate a voice‐guided transaction or
in. prompted on screen to press any
configured FDK to initiate a cardless
transaction without voice guidance.

During the idle loop, voice guidance is initiated according to the

Voice Guidance During a audio capability of the SST, as described in the two previous
Transaction 6
sections.
Figure 6‐1 illustrates voice guidance during a transaction.

Figure 6-1
Voice Guidance During a Transaction

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-5

Configuring Voice Guidance
Introducing Voice Guidance

Note: If no AudioGuidanceData.xml file is present in the expected

location, the NoAudio.xml file defines a message to play when voice
guidance is unavailable. For more information, see “Voice Guidance
Unavailable” on page 6‐13.
According to the definitions in the XML file, the cardholder is then
prompted as follows:
1 To adjust the volume, which is increased or decreased by 10%
each time the defined key is pressed

Note: The volume can be adjusted by 25% at any time if the 00

key is configured for the platform.

2 To set the session preferences, as follows:

 To choose whether to hide the screen during the consumer
session. This selection applies throughout the session. If the
consumer chooses to hide the screen, a screen is displayed,
typically containing text identifying the current session as a
private audio session with an option to cancel the session.
 To choose whether to include advertisements during the
cardholder session. This selection is stored for use
throughout the session.

3 To choose whether to play the orientation script. The consumer

can choose to replay or stop the playback during the orientation
script.

4 To start the transaction.

Note 1: In a Card Read State, if the audio jack is removed during a

voice‐guided session, the transaction can be continued by providing
the input through Encrypting PIN Pad (EPP) or touch screen within
five seconds after the headset is unplugged from the audio jack, else
the session is timed out.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-6 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Configuring Voice Guidance

Configuring Voice Guidance 6

Voice guidance is configured using an XML file and registry entries.

The XML file is called AudioGuidanceData.xml and is downloaded
from Central using the XML Configuration Download message. For
details of this message, refer to the APTRA Advance NDC, Reference
Manual.
The XML file defines the following:
 Configuration parameters
 Keyboard layouts
 Audio messages
The XML configuration file must conform to and reference the XML
schema described in “XML Schema” on page 6‐16. An example
configuration file is given in “Example XML Configuration File” on
page 6‐45, but is not provided with Advance NDC. The file can be
created and edited in any text editor, and downloaded from Central.

Note: If the AudioGuidanceData.xml file is invalid, it is not deleted

whether downloaded or copied locally and a message defined in the
NoAudio.xml file is played to inform the cardholder that a
voice‐guided session is unavailable.
Registry entries are used for the following:
 Prevent the consumer being prompted for language selection
more than once during a voice‐guided session.
 Enable the Enter key or FDKs to be used to initiate a cardless
transaction when voice guidance is enabled.
 Enable the use of voice guidance without host updates.
 Voice out cumulative data or last entered key.

The following registry entry defines whether the consumer is

Prompting for a Language 6

prompted for a language selection once or more than once during a

voice guidance session:
HKLM\SOFTWARE\NCR\Advance NDC\VoiceGuidance\
SingleLanguageSelection

The default value is 1, meaning that the consumer is prompted for a

language selection only once in the session. This has the following
implications when a language is selected during a voice‐guided
initialisation sequence:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-7

Configuring Voice Guidance
Configuring Voice Guidance

 Language selection is skipped in the Eight FDK Selection

Function (‘Y’) and PIN and Language Select (‘m’) states. The
screen offset taken from the screenOffset element in the XML
file must match the offset specified in the state tables
 The language selected by the consumer for the voice‐guided
session takes precedence over the language selected in the
Language Select from Card (‘V’) state.
If the registry value is 0, the screen offset is reset when the
voice‐guided initialisation sequence has completed.

When a voice‐guided session is initiated on SelfServ SSTs, the sound

Indicator Volume Control 6

level for beeps is set to the value in the indicatorVolume element

in AudioGuidanceData.xml. This allows key‐press feedback and other
indicator beeps to be sounded at an appropriate volume for a
voice‐guided session. If a value is not defined, a default of 80 is
used.
When a session is initiated without voice guidance, the indicator
volume returns to 100 to allow indicator beeps to be sounded at the
platform volume.

If only a single language is supported on the SST and useLang is set

Automatic Language to false (do not use a language selection to trigger a voice‐guided
Selection 6
session), the language specified in LangOption is automatically
selected. For information on using these elements, see “XML
Schema” on page 6‐16.

Set the following registry to 1 to play the orientation messages

Orientation Message 6

without any interruption during a voice guidance session:

HKLM\SOFTWARE\NCR\Advance NDC\VoiceGuidance\
VGTimer00Multiplier

The default value is 0, which plays the orientation messages with

interruption during a voice guidance session.

To enable the Enter key to be used to initiate a cardless transaction

Configuring the Enter Key when voice guidance is enabled but not initiated, set the following
to Initiate Cardless registry entry:
Transactions 6

HKLM\SOFTWARE\NCR\Advance NDC\VoiceGuidance\
Active PIN Pad Mask

To enable the Enter key, set the entry to 0x400.

If any other value is used, including 0xFF to enable all numeric keys
on the PINpad, no PINpad key will be enabled to initiate cardless
transactions.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-8 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Configuring Voice Guidance

Note: When voice guidance and cardless transactions are both

enabled, do not configure the Enter key to initiate voice‐guided
transactions.

For the actions available to consumers when both voice guidance

and cardless transactions are enabled on SSTs with standard or
enhanced audio capabilities, see the following:
 “Standard Audio Capabilities” on page 6‐3
 “Enhanced Audio Capabilities” on page 6‐4
For details of configuring FDKs using the Active FDK Mask registry
entry, see “Key Mask Definition” on page 5‐120.

If you want to use voice guidance without updating the host, you
Enabling Voice Guidance must configure the NHCVGAudio.xml file. This functionality can be
Without Host Updates 6
enabled or disabled through option 89 - NO HOST CHG VG on the
Configure menu in Supervisor or by setting the following registry
entry:

HKLM\SOFTWARE\NCR\Advance NDC\NoHostChangeVG\Enable NHC VG

Valid values are as follows:

0 to disable voice guidance without updating the host
1 to enable voice guidance without updating the host.
For details of the Supervisor option, refer to the APTRA Advance
NDC, Supervisor Guide.
You must also create a NHCVGAudio.xml file that conforms to the
structure defined in the schema described in “Voice‐Guided
Sessions without Host Update” on page 6‐50. You must ensure that
the voice guidance configuration file, AudioGuidanceData.xml, is
present otherwise voice guidance will not be recognised.

Dynamic Data 6

For voice guidance without host update, any characters that are not
required for spoken text are removed from the dynamic data so that
consumers can hear all the required information without also
hearing unwanted data such as special characters, audio control
sequences, and the control sequences for the primary and secondary
character sets.
For information on audio control sequences and primary and
secondary character sets, refer to the following headings in section
“Formatting Rules for Cardholder Display Screens” in Chapter 3,
“Screen Data” of the APTRA Advance NDC, Reference Manual:
 “Digital Audio Control in Screen Display”
 “Select Primary Character Set”

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-9

Configuring Voice Guidance
Configuring Voice Guidance

 “Select Secondary Character Set”

In the Information Entry state, when the entry mode is configured to

Voice Out Entered Key 6

numeric key entry, the application can voice out either the entered
cumulative data or the last entered key. This functionality is
configured using the following registry entry:

HKEY_LOCAL_MACHINE\SOFTWARE\NCR\AdvanceNDC\Voice Guidance
\VoiceOutCumulativeText

Valid values are as follows:

 0 (default) = voice out last entered key
 1 = voice out cumulative data

On an SST with enhanced audio capabilities, the idle loop

Configuring the Idle Loop instructions can be voiced through speakers until a headset is
Audio 6
plugged into the audio jack on the SST. This is configured using the
following DWORD registry entry:

HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC
\VoiceGuidance\VoiceVGTriggerOverPublicAudio

Valid values are as follows:

 0 = Voice the idle loop and other voice guidance instructions
only when a headset is plugged into the audio jack. This is the
default value.
 1 = Voice the idle loop instructions through the speakers until a
headset is plugged into the audio jack.

The configuration of voices is optional and used only when multiple

Configuring Third‐Party voices for a transaction language have been installed and you want
TTS Software 6
to choose which language to use, as follows:
1 In Windows Control Panel, select Speech Recognition -> Text to
Speech.

2 In AdvanceNDCCustom.accfg. uncomment the DefaultVoices

property shown in Figure 6‐2,“Configuring Multiple Voices”.

Figure 6-2
Configuring Multiple Voices
<Class ID=”NDCVoiceGuidance” Name=”NCR.APTRA.NDC.VoiceGuidance.NDCVoiceGuidance”
Assembly=”NCR.APTRA.NDC.VoiceGuidance.dll”
<Interface>
<!--Property Name=”DefaultVoices” Value=”VoiceGuidanceVoices” IsArray=”true” /-->
</Interface>
</Class>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-10 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Configuring Voice Guidance

3 Complete the VoiceGuidanceVoices array with the languages

and voices you require using the format shown in the following
example:

Figure 6-3 <Array ID=”VoiceGuidanceVoices”>

Voice Guidance Voices Array <Element Value=”en=Microsoft Sam”/>
<Element Value=”<languagecode>=<voiceName>”/>
</Array>

Note: Adding one or more languages requires you to specify

the default language explicitly.

The Voice Guidance Voices Array 6

The VoiceGuidanceVoices array defines the association between

transaction languages and voices in the speech engine. The array
elements contain language/voice pairs separated by the equal
symbol (ʹ=ʹ), for example, for English, en=Microsoft Sam and for
Spanish, es=Paulina.
The default voice/language value is as follows and is used if nothing
is specified:
<Element Value="en=Microsoft Sam"/>

The default speed does not have to be specified.

Optionally, voice speed can be also specified following a semi‐colon
(;) in the range ‐10 (the slowest) to 10 (the fastest). The default value
is 2. For example, es=Paulina;-4 sets a slower speed for Paulina,
as shown in the following example together with the default
configuration for English:
<!-- Configuration of voices for Voice Guidance.
Define pairs of ISO language code and TTS voice name
separated by '=' -->
<Array ID="VoiceGuidanceVoices">
<Element Value="en=Microsoft Sam"/>
<Element Value="es=Paulina;-4"/>
</Array>

Note 1: If all you require are the default language (English), default
voice (Microsoft Anna on Windows 7, and Microsoft David Desktop
and Microsoft Zira Desktop for 64‐bit Windows 10), and the default
speed, you do not need to configure the array.

Note 2: If the VoiceGuidanceVoices array is not defined, a voice

matching the transaction language is automatically selected. If no
voice is available for the transaction language, no audio is played.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-11

Configuring Voice Guidance
Configuring Voice Guidance

To support languages with accented or special characters,

Specifying the Character AudioGuidanceData.xml specifies the character encoding to apply.
Encoding 6
Any dynamic voice data is interpreted as using the same encoding
as that specified in the XML preamble.
The following XML preamble specifies the use of Unicode
Transformation Format–8‐bit (utf-8) character encoding:
<?xml version="1.0" encoding="utf-8"?>

In a voice‐guided session, the cardholder is directed at various

Audio Elements Required points by messages defined by Audio elements (seeTable 6‐3,
in the XML Configuration “XML Schema Elements” on page 6‐24) associated with screens in
File 6 the XML file, as follows:
 If the SST has Standard Audio capability, run continuously
when the SST is In Service but not in a cardholder session. This
message provides instructions on starting a voice‐guided
session
 When a voice‐guided session is initiated, allow the cardholder to
do the following:
— Select a language for the session
— Adjust the volume
— Hide or display the screen
 Once the session preferences are set, ask the cardholder to enter
a card
 Allow the cardholder to select transaction options, such as
whether to withdraw cash or obtain a balance statement
 Inform the cardholder of the outcome of the transaction, such as
to ask the cardholder to take their cash, or to tell them their
balance
 Ask the cardholder to wait while the transaction processes
 Ask the cardholder if more time is required. This must be
defined with an audioID sub‐element of “0000”
 Define whether keyboard selections are to be echoed to the
cardholder using the keyText sub‐elements
 Inform the cardholder that the SST is out of service.

The following XML files can also be used in voice guidance, as

Other XML Files Used in follows:
Voice Guidance 6

 A local file is supported for the Americas implementation and

can be used in the following situations:
— When Central does not support the download of an XML file
— When the SST uses a different configuration to that
downloaded from Central.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-12 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Configuring Voice Guidance

For details of the local file, see “Local XML Configuration File”.

 When no valid AudioGuidanceData.xml file is present with audio

data, the NoAudio.xml file defines the message used to inform
the cardholder that a voice‐guided session is unavailable. For
details of this XML file, see “Voice Guidance Unavailable”.

Local XML Configuration File 6

The local XML configuration file must conform to and reference the
XML schema described in “XML Schema” on page 6‐16. An
example configuration file is given in “Example XML Configuration
File” on page 6‐45. The file can be created and edited in any text
editor. No local XML configuration file is provided with Advance
NDC.
The configuration file must be named AudioGuidanceDataLocal.xml,
and installed to C:\Program Files\NCR APTRA\Advance
NDC\Config using your preferred method.
The SST must be rebooted after a local configuration file is installed.
If this file is present, it is used instead of the AudioGuidanceData.xml
file when a voice‐guided session is requested.
Invalid Local XML File If AudioGuidanceDataLocal.xml is invalid, 6

no files are deleted and a message is played to indicate that voice

guidance is unavailable.

Voice Guidance Unavailable 6

The NoAudio.xml file is provided with Advance NDC and installed

to the following location on the SST:

C:\Program Files\NCR APTRA\Advance NDC\Config

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-13

Configuring Voice Guidance
Advance NDC Voice Guidance and Other Applications

Advance NDC Voice Guidance and

Other Applications 6

If using APTRA Promote and/or Display Manager on the SST with

Advance NDC, there may be restrictions or other considerations for
voice‐guided sessions. These are outlined in the following sections.
If using EMV Exits, refer to the EMV Integrated Circuit Card (ICC)
Reference Manual.

When a voice‐guided session is enabled on an SST with APTRA

Using Voice Guidance Promote, the following restrictions apply:
with Promote 6

 The Promote campaign must not have audio messages

associated with any flow‐point. Any audio messages in the
Promote campaign will be played at the same time as the
Advance NDC voice guidance audio messages. In a cardholder
session that is not an Advance NDC voice‐guided session, the
audio messages in the Promote campaign may be played
through the audio jack and not the speaker, and therefore not be
audible
 If the Promote campaign includes a screen displayed for a
defined period in the “Approving Transaction” flow point, the
previous audio message continues to play until the transaction
request is sent, “please wait” is then played while awaiting the
transaction reply
 If the Promote campaign has an “Attract” flow point, but no
“Card Inserted” flow point, the screen for the “Attract” flow
point is displayed briefly after the card is inserted before the
next Advance NDC screen is displayed
 If the cardholder has chosen to hide screens in a voice‐guided
session, the Promote screens are unaffected and are displayed as
usual.
 The following flow points must not be used:
— Card Inserted ‐ The “Please insert your card” message
continues playing after the card is inserted and while the
APTRA Promote screen is displayed
— PIN Acquired ‐ The “Please enter your PIN message
continues playing after the PIN is entered and while the
APTRA Promote screen is displayed
— Deposit (print receipt) ‐ The “Please insert your envelope”
message continues playing after the envelope is inserted and
while the APTRA Promote screen is displayed

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-14 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Advance NDC Voice Guidance and Other Applications

— Deposit (complete) ‐ The “Please insert your envelope”

message continues playing until after the envelope is
inserted and while the APTRA Promote screen is displayed
— Dispense (print receipt) ‐ The “Please take your cash”
message continues to play until after the cash is taken and
while the APTRA Promote
— screen is displayed
— Dispense (complete) ‐ The “Please take your cash” message
continues to play until after the cash is taken and while the
APTRA Promote screen is displayed.

The audio message associated with the previous screen can be

set to play continuously to avoid silence during the display of
the Promote screen.

Advance NDC calls the Display Manager and continues displaying

Using Voice Guidance HTML screens and playing the associated audio messages based on
with Display Manager 6
the value returned. For information, refer to the APTRA Advance
NDC User Guide for Display Manager.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-15

Configuring Voice Guidance
XML Schema

XML Schema 6

A schema, called ABMAudioGuidanceSchema.xsd, is provided with

Advance NDC and installed to C:\Program Files\NCR
APTRA\Advance NDC\Config. This schema must be referenced, as
shown in “Example XML Configuration File” on page 6‐45.
Figure 6‐4 provides a sample ABMAudioGuidanceSchema.xsd
schema.

Figure 6-4
Sample Voice Guidance XML Schema
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="urn:xsdNCRAudioGuidance"
xmlns:vt="urn:xsdNCRAudioGuidance">

<xsd:element name="NCRAudioGuidance">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Config" type="vt:ConfigTemplate"/>
<xsd:element name="Keyboard" type="vt:KeyboardTemplate"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="Audio" type="vt:AudioTemplate"
minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<!--
********* This is used by the host validation
********* groupID is not used on the SST
<xsd:unique name="UniqueConfigID">
<xsd:selector xpath="Config"/>
<xsd:field xpath="@groupID"/>
</xsd:unique>
<xsd:unique name="UniqueKeyboardID">
<xsd:selector xpath="Keyboard"/>
<xsd:field xpath"@keyboardID"/>
<xsd:field xpath="@groupID/>
</xsd:unique>
<xsd:unique name="UniqueAudioID">
<xsd:selector xpath="Audio"/>
<xsd:field xpath="@audioID"/>
<xsd:field xpath="@groupID"/>
</xsd:unique>
<xsd:keyref name="AudioMustExist"
refer="vt:UniqueAudioID">
<xsd:selector xpath=".//Link"/>
<xsd:field xpath="@audioID"/>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-16 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

<xsd:field xpath="@groupID"/>
</xsd:keyref>
-->
<xsd:unique name="UniqueKeyboardID">
<xsd:selector xpath="Keyboard"/>
<xsd:field xpath="@keyboardID"/>
</xsd:unique>
<xsd:unique name="UniqueAudioID">
<xsd:selector xpath="Audio"/>
<xsd:field xpath="@audioID"/>
</xsd:unique>
<xsd:keyref name="AudioMustExist"
refer="vt:UniqueAudioID">
<xsd:selector xpath=".//Link"/>
<xsd:field xpath="@audioID"/>
</xsd:keyref>
</xsd:element>

<xsd:annotation><xsd:documentation xml:lang="en">
=================================================
Audio Template declaration
=================================================
</xsd:documentation></xsd:annotation>

<xsd:complexType name="AudioTemplate">
<xsd:choice minOccurs="1" maxOccurs="unbounded">
<xsd:element name="Text" type="vt:TextCommand"/>
<xsd:element name="Recording" type="xsd:RecordingType"/>
<xsd:element name="Stream" type="vt:StreamCommand"/>
<xsd:element name="Loop" type="vt:LoopCommand"/>
</xsd:choice>
<xsd:attribute name="audioID" type="xsd:string"
use="required"/>
<xsd:attribute name="groupID" type="xsd:string"
use="optional"/>
<xsd:attribute name="keyboardID" type="xsd:string"
use="optional"/>
<xsd:attribute name="ad" type="xsd:boolean"
default="false"/>
<xsd:attribute name="repetitions" type="vt:LoopCount"
default="1"/>
<xsd:attribute name="ParamSourceID" type="xsd:string"
use="optional"/>
<xsd:attribute name="keyText" type="xsd:string"
use="optional"/>
</xsd:complexType>

<xsd:annotation><xsd:documentation xml:lang="en">
===================================================
Loop Command declaration

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-17

Configuring Voice Guidance
XML Schema

a LoopCount of 0 means infinite loop

===================================================
</xsd:documentation></xsd:annotation>

<xsd:complexType name="LoopCommand">
<xsd:choice minOccurs="1" maxOccurs="unbounded">
<xsd:element name="Text" type="vt:StreamCommand"/>
<xsd:element name="Stream" type="vt:TextCommand"/>
</xsd:choice>
<xsd:attribute name="count" type="vt:LoopCount"
use="required"/>
</xsd:complexType>

<xsd:annotation><xsd:documentation xml:lang="en">
====================================================
Play Text Command declaration
====================================================
</xsd:documentation></xsd:annotation>

<xsd:complexType name="TextCommand" mixed="true">

<xsd:group ref="vt:TextElements" minOccurs="0"
maxOccurs="unbounded"/>
<xsd: attribute name="lang" type="xsd:language"
default="en"/>
<xsd:attribute name="state" type="vt:AudioState"
default="private"/>
</xsd:complexType>

<xsd:group name="TextElements">
<xsd:choice>
<xsd:element name="Link" type="vt:LinkCommand"/>
<xsd:element name="Pause" type="vt:PauseCommand"/>
<xsd:element name="PlaceHolder" type="xsd:string"/>
<xsd:element name="Spell" type="xsd:string"/>
<xsd:element name="Pron" type="xsd:string"/>
</xsd:choice>
</xsd:group>

<xsd:annotation><xsd:documentation xml:lang="en">
===================================================
Play Stream Command declaration
===================================================
</xsd:documentation></xsd:annotation>

<xsd:complexType name="StreamCommand">
<xsd:group ref="vt:StreamElements" minOccurs="0"
maxOccurs="unbounded"/>
<xsd:attribute name="state" type="vt:AudioState"
use="required"/>
<xsd:attribute name="lang" type="xsd:language"

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-18 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

default="en"/>
</xsd:complexType>

<xsd:group name="StreamElements">
<xsd:choice>
<xsd:element name="Link" type="vt:LinkCommand"/>
<xsd:element name="Pause" type="vt:PauseCommand"/>
<xsd:element name="StreamURI" type="xsd:anyURI"/>
<xsd:element name="PlaceHolder" type="xsd:string"/>
</xsd:choice>
</xsd:group>

<xsd:annotation><xsd:documentation xml:lang="en">
===================================================
Pause Command declaration
PauseDuration unit is one tenth of a second
===================================================
</xsd:documentation></xsd:annotation>

<xsd:complexType name="PauseCommand">
<xsd:attribute name="duration" type="vt:PauseDuration"
use="required"/>
</xsd:complexType>

<xsd:annotation><xsd:documentation xml:lang="en">
===================================================
Configuration Related declaration
===================================================
</xsd:documentation></xsd:annotation>

<xsd:complexType name="ConfigTemplate">
<xsd:sequence>
<xsd:element name="afaTrigger" type="vt:AFATriggerDef"
minOccurs="1" maxOccurs="1"/>
<xsd:element name="afaLang" type="vt:AFALangDef"
minOccurs="1" maxOccurs="1"/>
<xsd:element name="audioVolume" type="vt:audioVolumeDef"
minOccurs="0" maxOccurs="1"/>
<xsd:element name="afaOption" type="vt:AFAOptionDef"
minOccurs="1" maxOccurs="4"/>
</xsd:sequence>
<xsd:attribute name="groupID" type="xsd:string"
use="optional"/>
<xsd:attribute name="restartKeyPos" type="vt:keyPosRange"
use="required"/>
<xsd:attribute name="repeatDelay" type="xsd:integer"
default="30"/>
<xsd:attribute name="configRetryCount" type="xsd:integer"
default="1"/>
<xsd:attribute name="timersAdjust" type="xsd:integer"

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-19

Configuring Voice Guidance
XML Schema

use="optional"/>
<xsd:attribute name="blankScreenID" type="xsd:integer"
use="required"/>
<xsd:attribute name="cardPromptScreen" type="xsd:integer"
use="required"/>
<xsd:attribute name="contactAndContactlessPromptScreen"
type="xsd:integer" use="optional"/>
<xsd:attribute name="contactlessPromptScreen"
type="xsd:integer" use="optional"/>
<xsd:attribute name="defaultVolume" type="xsd:integer"
default="50"/>
<xsd:attribute name="indicatorVolume" type="xsd:integer"
default="80" use="optional"/>
</xsd:complexType>

<xsd:complexType name="AFAOptionDef">
<xsd:attribute name="name" type="vt:AFAOptionNames"
use="required"/>
<xsd:attribute name="screen" type="xsd:integer"
use="required"/>
<xsd:attribute name="yesKeyPos" type="vt:keyPosRange"
use="required"/>
<xsd:attribute name="yesAudioID" type="xsd:string"
use="required"/>
<xsd:attribute name="noKeyPos" type="vt:keyPosRange"
use="required"/>
xsd:attribute name="noAudioID" type="xsd:string"
use="required"/>
xsd:attribute name="defaultResponse" type="xsd:boolean"
default="false"/>
</xsd:complexType>

<xsd:simpleType name="AFAOptionNames">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="blankScreen"/>
<xsd:enumeration value="ads"/>
<xsd:enumeration value="OrientationSkip"/>
<xsd:enumeration value="OrientationScript"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:complexType name="audioVolumeDef">
<xsd:attribute name="screen" type="xsd:integer"
use="required"/>
<xsd:attribute name="plusKeyPos" type="vt:keyPosRange"
use="required"/>
<xsd:attribute name="minusKeyPos" type="vt:keyPosRange"
use="required"/>
<xsd:attribute name="doneKeyPos" type="vt:keyPosRange"
use="required"/>
</xsd:complexType>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-20 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

<xsd:complexType name="AFATriggerDef">
<xsd:attribute name="useLang" type="xsd:boolean"
default="false"/>
<xsd:attribute name="triggerKeyPos" type="vt:keyPosRange"
use="required"/>
<xsd:attribute name="triggerKeyPos2" type="vt:keyPosRange"
use="optional"/>
<xsd:attribute name="confirmationKeyPos"
type="vt:keyPosRange" use="optional"/>
<xsd:attribute name="confirmationAudioID"
type="xsd:string" use="optional"/>
<xsd:attribute name="timeoutAudioID" type="xsd:string"
use="optional"/>
</xsd:complexType>

<xsd:complexType name="AFALangDef">
<xsd:sequence>
<xsd:element name="LangOption" type="vt:AFALangOptions"
minOccurs="1" maxOccurs="8"/>
</xsd:sequence>
<xsd:attribute name="screen" type="xsd:integer"
use="required"/>
<xsd:attribute name="opCodePos" type="vt:opCodePosRange"
use="optional"/>
</xsd:complexType>

<xsd:complexType name="AFALangOptions">
<xsd:attribute name="lang" type="xsd:language"
use="required"/>
<xsd:attribute name=keyPos" type="vt:keyPosRange"
use="required"/>
<xsd:attribute name="opCode" type="vt:opCodeRange"
use="optional"/>
<xsd:attribute name="opCodeNoALT" type="vt:opCodeRange"
use="optional"/>
<xsd:attribute name="screenOffset" type="xsd:integer"
default="0"/>
<xsd:attribute name="treqFieldID" type="xsd:string"
use="optional"/>
<xsd:attribute name="treqFieldLangData" type="xsd:string"
use="optional"/
</xsd:complexType>

<xsd:simpleType name="opCodeRange">
<xsd:restriction base="xsd:string">
<xsd:pattern value="[1-9A-Za-z]"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="opCodePosRange">

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-21

Configuring Voice Guidance
XML Schema

<xsd:restriction base="xsd:integer">
<xsd:minInclusive value="0"/>
<xsd:maxInclusive value="7"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:annotation><xsd:documentation xml:lang="en">
===================================================
Keyboard Related declaration
===================================================
</xsd:documentation></xsd:annotation>

<xsd:complexType name="KeyboardTemplate">
<xsd:sequence>
<xsd:element name="Key" type="vt:KeyDef" minOccurs="1"
maxOccurs="24"/>
</xsd:sequence>
<xsd:attribute name="keyboardID" type="vt:KeyboardNumber"
use="optional"/>
<xsd:attribute name:"groupID" type="xsd:string"
use="optional"/>
</xsd:complexType>

<xsd:complexType name="KeyDef">
<xsd:attribute name="pos" type="vt:keyPosRange"
use="required"/>
<xsd:attribute name="code" type="vt:keyCodeRange"
use="required"/>
</xsd:complexType>

<xsd:simpleType name="KeyboardNumber">
<xsd:restriction base="xsd:integer">
<xsd:minInclusive value="000"/>
<xsd:maxInclusive value="999"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="keyPosRange">
<xsd:restriction base="xsd:integer">
<xsd:minInclusive value="1"/>
<xsd:maxInclusive value="24"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="keyCodeRange">
<xsd:restriction base="xsd:string">
<xsd:pattern value="(3\d)|([fF][1-9aAfF])"/>
</xsd:restriction>
</xsd:simpleType>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-22 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

<xsd:annotation><xsd:documentation xml:lang="en">
===================================================
Misc Declaration
===================================================
</xsd:documentation></xsd:annotation>

<xsd:simpleType name="LoopCount">
<xsd:restriction base="xsd:integer">
<xsd:minInclusive value="0"/>
<xsd:maxInclusive value="9"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="PauseDuration">
<xsd:restriction base="xsd:integer">
<xsd:minInclusive value="1"/>
<xsd:maxInclusive value="999"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:simpleType name="AudioState">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="private"/>
<xsd:enumeration value="public"/>
</xsd:restriction>
</xsd:simpleType>

<xsd:complexType name="LinkCommand">
<xsd:attribute name="audioID" type="xsd:string"
use="required"/>
<xsd:attribute name="groupID" type="xsd:string"
use="required"/>
</xsd:complexType>

<xsd:complexType name="RecordingType
"> <xsd:attribute name="lang" type="xsd:language"/>
<xsd:attribute name="file" type="xsd:string"
use="required"/>
<xsd:attribute name="state" type="vt:AudioState"
default="private"/>
</xsd:complexType>

</xsd:schema>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-23

Configuring Voice Guidance
XML Schema

The schema elements are described in the following table.

Schema Elements 6

Table 6-3
XML Schema Elements

Element Name Description

Config Mandatory.

Appears once only.

Defines the parameters required to initialise a voice‐guided session.

Nested elements:
 groupID
 restartKeyPos
 repeatDelay
 configRetryCount
 timersAdjust
 blankScreenID
 cardPromptScreen
 contactAndContactlessPromptScreen
 contactlessPromptScreen
 defaultVolume
 indicatorVolume

groupID Optional.

Ignored by the SST.

Can be used by the host to categorise the Config sub‐elements for different
downloads.

restartKeyPos Mandatory.

Defines the key used to initiate a voice‐guided session.

This sub‐element must be present in the configuration file or the XML validation will
fail. However, it is ignored by voice guidance in Advance NDC.

repeatDelay Optional.

Defines the pause in tenths of a second between repeated messages. By default, this is
set to 30, giving a pause of 3 seconds.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-24 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Element Name Description

configRetryCount Optional.

Defines the number of times a cardholder is prompted to select voice guidance options
before the voice‐guided session is cancelled.

If this sub‐element is not present, or is set to zero, the voice‐guided session is cancelled
after the first prompt if the cardholder does not respond within the time allowed by
the adjusted timer. See timersAdjust for more information on the adjusted timers.

timersAdjust Optional.

Defines the time added to field ‘i’ of the Interactive Transaction Response message and
the following Advance NDC timers:
 Timer 00
 Timer 01
 Timer 04
 Timer 05
 Timer 07
 Timer 08
 Timer 09
 Timer 61
 Timer 77
 Timer 78
 Timer 87
 Timer 94
 Timer 95
 Timer 96
 Screen Timer defined in field ‘i’ of the Interactive Transaction Response message.

The integers values represent a count of 800 millisecond ticks. No adjusted timer can
exceed 255 ticks. If the adjustment results in a timer exceeding this limit, only 255 ticks
are used.

For details of the Interactive Transaction Response message and Advance NDC timers,
refer to the APTRA Advance NDC, Reference Manual.

blankScreenID Mandatory.

Defines the screen displayed during a voice‐guided session if the cardholder selects
the option to hide the screen for privacy.

If multiple languages are supported, a screen should be defined for each supported
language. Language screens must be numbered as defined in the ScreenOffset
sub‐element.

Ensure that no audio elements are defined for screens used in this situation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-25

Configuring Voice Guidance
XML Schema

Element Name Description

cardPromptScreen Mandatory.

Defines the screen displayed when the consumer is prompted to insert the contact
card. This screen is displayed when the contact card reader is the only card reader
available and active on the SST or both the contact and contactless card readers are
available but the contactless card reader is inoperative.

See Table Note 1 and Table Note 2.

contactAnd Optional.
ContactlessPrompt
Screen Defines the screen displayed when the consumer is prompted to insert the contact card
or tap the contactless card. This screen is displayed when both the contact and
contactless card readers are available and active on the SST.

See Table Note 1 and Table Note 2.

contactlessPrompt Optional.
Screen
Defines the screen displayed when the consumer is prompted to tap the contactless
card. This screen is displayed when the contactless card reader is only available and
active on the SST or both the contact and contactless card readers are available but the
contact card reader is inoperative.

See Table Note 1 and Table Note 2.

defaultVolume Optional.

Defines the default volume set at the start of each voice‐guided session.

If this sub‐element is not present, the default volume is set to 50. Valid values are
between 0, for the lowest volume setting, and 100, for the highest volume setting.

indicatorVolume Optional

For voice‐guided sessions, defines the percentage of the SST volume used for beeps to
indicate key presses and other indicator service feedback. It is set at the start of each
voice‐guided session.

Valid values are in the range 0 to 100.

If this attribute is not defined, the default indicator volume is set to 80 for the
voice‐guided session.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-26 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Element Name Description

afaTrigger Mandatory.

Defines how a voice‐guided session is triggered.

On SSTs with Standard Audio capabilities, this element is used when is In Service and
not in a cardholder session.

On SSTs with Enhanced Audio capabilities, this element is used when a headset
remains inserted after a cardholder session has concluded.

Nested elements:
 useLang
 triggerKeyPos
 triggerKeyPos2
 confirmationKeyPos
 confirmationAudioID
 timeoutAudioID

useLang Optional.

Defines whether language selection is used to trigger a voice‐guided session.

Valid values are as follows:

true – Use language selection to trigger a voice‐guided session
false – Do not use language selection to trigger a voice‐guided session

If this sub‐element is not present, language is not used to trigger a voice‐guided

session.

If this sub‐element is set to false or not present, the number of languages configured in
the XML is checked. If only a single language is present, the consumer is not asked to
select a language.

If set to true, the keys defined by the keyPos sub‐element are activated while the SST
is In Service and not in a cardholder session. Pressing an active key triggers a
voice‐guided session and selects the associated language. The triggerKeyPos and
triggerKeyPos2 sub‐elements are ignored.

If not present or set to false, the keys defined by the triggerKeyPos and
triggerKeyPos2 sub‐elements are used to trigger a voice‐guided session.

triggerKeyPos Mandatory.

Defines the key that triggers a voice‐guided session by its position. For details of the
key positions, see Table Note 3. If the triggerKeyPos2 sub‐element is defined, both
defined keys must be pressed to trigger a voice‐guided session.

This sub‐element must be present in the configuration file or the XML validation will
fail. However, it is ignored if the useLang sub‐element is set to true.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-27

Configuring Voice Guidance
XML Schema

Element Name Description

triggerKeyPos2 Optional.

Defines the key that triggers a voice‐guided session by its position. For details of the
key positions, see Table Note 3.

If this sub‐element is present, the cardholder must press two keys to trigger the
voice‐guided session. If the key defined by this sub‐element is not pressed within two
seconds of the key defined by the triggerKeyPos sub‐element, the voice‐guided
session is cancelled.

This sub‐element is ignored if the useLang sub‐element is set to true.

confirmationKeyPos Optional.

Defines the key used to confirm that a voice‐guided session is required. For details of
the key positions, see Table Note 3.

If set, the cardholder must press the key to confirm the voice‐guided session before
Timer 00 expires. If the cardholder does not press the defined key in this time, the
voice‐guided session is cancelled.

This sub‐element is ignored if the confirmationAudioID sub‐element is not set.

confirmationAudioID Optional.

Defines the audio to be played to request that the cardholder confirms that they
require a voice‐guided session.

This sub‐element is ignored if the confirmationKeyPos sub‐element is not set.

timeoutAudioID Optional.

Defines the audio to be played to inform the cardholder that a selection has not been
made within the allowed time.

afaLang Mandatory.

Defines the language and keys used in selecting a supported language.

Nested elements:
 screen
 opCodePos
 LangOption

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-28 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Element Name Description

screen Mandatory.

Defines the screen displayed when the cardholder is prompted to select the language
for a voice‐guided session.

An Audio element must be associated with the screen defined by this sub‐element.

This sub‐element is ignored if the useLang sub‐element is set to true.

opCodePos Optional.

Defines the language code position in field ‘j’ of the Transaction Request message.

See Table Note 4.

If this sub‐element is present, the opCode sub‐element is placed in the defined

position of field ‘j’ of the Transaction Request message for a voice‐guided session.

For details of the Transaction Request message, refer to the APTRA Advance NDC,
Reference Manual.

If using voice guidance with no host update, this sub‐element must not be present as
the field ‘j’ in the Transaction Request message is not used.

LangOption Mandatory.

Defines the following:

 Language
 Key position for selecting the language
 Optionally, the value defining the language in the Transaction Request message
 The screen offset for the voice guidance configuration screens.

At least one LangOption sub‐element must be defined in an afaLang element. A

maximum of eight LangOption sub‐elements can be defined in an afaLang
element.

Nested elements:
 lang
 keyPos
 opCode
 opCodeNoALT
 ScreenOffset
 treqFieldID
 treqFieldLangData

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-29

Configuring Voice Guidance
XML Schema

Element Name Description

lang Mandatory.

Defines the language used for the voice‐guided session.

Uses the ISO 639‐1 specification, which uses a two‐character code to represent each
language. See Table Note 4.

If TTS software is used and it does not support the defined language, this sub‐element
is ignored.

If the Text element contains messages in multiple languages, only the message in the
defined language is played. If the defined language does not match any languages
defined in the Text element, the message is played in all languages that are defined.

Before a voice‐guided session is triggered, the instructions are played in all defined
languages.

keyPos Mandatory.

Defines the key used to select a language. For details of the key positions, see Table
Note 3.

opCode Optional.

Defines the language using an alphanumeric character. The character is placed in the
position defined by the opCodePos sub‐element and used in the Transaction Request
message.

If using voice guidance with no host update, this sub‐element must not be present as
the field in the Transaction Request message is not used.

opCodeNoALT Optional.

Defines the language using an alphanumeric character. The character is placed in the
position defined by the opCodePos sub‐element and used in the Transaction Request
message.

Advance NDC does not support this sub‐element and it is ignored if present.

If using voice guidance with no host update, this sub‐element must not be present as
the field in the Transaction Request message is not used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-30 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Element Name Description

ScreenOffset Mandatory.

Defines which screen to display after a language is selected. The specified offset is
added to the screen number of the following screens:
 blankScreenID
 cardPromptScreen
 contactAndContactlessPromptScreen
 contactlessPromptScreen
 audioVolume
 blankScreen
 Ads
 OrientationSkip
 OrientationScript.

For example, if English is assigned an offset of 0 and Spanish an offset of 5, and the
cardholder selects Spanish, then 5 is added to the screen numbers and those screens
are displayed. Alternatively, you can use the same screen regardless of the selected
language by defining an offset of 0 for both English and Spanish. In this case, the
audioID sub‐element associated with each screen must contain both languages.

See Table Note 6 and Table Note 7

treqFieldID Optional.

Defines an additional field to include in the Transaction Request message to identify

the session as a voice‐guided session. The field identifier should be defined as ‘<’. As
this is a character with meaning within an XML file, it must be coded appropriately as
follows:

treqFieldID="&#60;"

This sub‐element can be used in addition to, or instead of the opCodePos and
opCode sub‐elements.

For details of the Transaction Request message, refer to the APTRA Advance NDC,
Reference Manual.

If using voice‐guided sessions with no host update, this sub‐element must not be
present as the field in the Transaction Request message is not used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-31

Configuring Voice Guidance
XML Schema

Element Name Description

treqFieldLangData Optional.

Defines the language to be included in the voice guidance buffer.

If this sub‐element is defined, the treqFieldID sub‐element must also be defined.

The language data is added to the transaction request message following the
additional field defined in the treqFieldID sub‐element.

For details of the Transaction Request message, refer to the APTRA Advance NDC,
Reference Manual.

audioVolume Optional.

Defines the keys used to adjust the audio volume and the screen displayed for the
volume adjustment option.

Nested elements:
 screen
 plusKeyPos
 minusKeyPos
 doneKeyPos

screen Mandatory.

Defines the screen to display during volume adjustment. If multiple languages are
supported, you can define a screen for each language. Screens should be numbered as
defined in the ScreenOffset sub‐element. Each screen must have an Audio
element defined.

plusKeyPos Mandatory.

Defines the key used to increase the volume. For details of the key positions, see Table
Note 3.

minusKeyPos Mandatory.

Defines the key used to decrease the volume. For details of the key positions, see Table
Note 3.

doneKeyPos Mandatory.

Defines the key used to finish adjusting the volume. For details of the key positions,
see Table Note 3.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-32 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Element Name Description

afaOption Mandatory.

Defines at least one and up to four cardholder options. Each option requires a choice of
two options (usually yes and no). If an option is not defined, the default is used.

Nested elements:
 name
 screen
 yesKeyPos
 yesAudioID
 noKeyPos
 noAudioID
 defaultResponse

name Mandatory.

Defines the cardholder option being defined in the afaOption element for a screen
with an Audio element as follows:
 blankScreen ‐ Asks whether the cardholder wants the screen to be hidden
during the voice‐guided session. Default is to hide the screen.
 Ads ‐ Asks whether the cardholder wants to hear advertisements during the
voice‐guided session. Default is to play advertisements.
 OrientationSkip ‐ Asks whether the cardholder wants to skip the orientation
information. This option must precede the OrientationScript option. If the
OrientationScript option is not defined, this option is ignored. Default is to play
the orientation information.
 OrientationScript ‐ Plays the orientation information. The cardholder can use
defined keys to play the information again or to skip the rest of the message. If the
cardholder inserts their card during the orientation information, the information
stops playing. If this element is not present, no orientation information is played.

screen Mandatory.

Defines the screen to display. If multiple languages are supported, you can define a
screen for each language. Screens should be numbered as defined in the
ScreenOffset sub‐element. Each screen must have an Audio element defined.

yesKeyPos Mandatory.

Defines the key used to accept the option. For details of the key positions, see Table
Note 3.

yesAudioID Mandatory.

Defines the Audio element played to confirm acceptance of the option.

noKeyPos Mandatory.

Defines the key used to refuse the option. For details of the key positions, see Table
Note 1.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-33

Configuring Voice Guidance
XML Schema

Element Name Description

noAudioID Mandatory.

Defines the Audio element played to confirm refusal of the option.

defaultResponse Optional.

Defines the default selection for occasions where the options are skipped, for example
by the cardholder inserting their card.

Valid values are as follows:

true ‐ accept the option
false ‐ refuse the option

If this sub‐element is not present, the options are refused by default.

Keyboard Mandatory.

Defines the layout of the numeric keyboard on the SST.

Nested elements:
 keyboardID
 groupID
 Key

keyboardID Mandatory.

Defines the Keyboard element. This can be used as a reference by any Audio
element.

Valid values are any unique integer between 100 and 999, inclusive.

groupID Optional.

Ignored by the SST.

Can be used by the host to categorise the Keyboard sub‐elements for different
downloads.

Key Mandatory.

Defines the keypad position and the code generated by that position.

At least one and up to 16 Key sub‐elements can be defined.

Only the numeric keys not in use by the state being executed can be defined. If any
keys already defined in the state table are defined in the XML file, the XML definition
is ignored

Nested elements:
 pos
 code

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-34 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Element Name Description

pos Mandatory.

Defines the key being defined in this Key sub‐element. For details of the key
positions, see Table Note 3.

code Mandatory.

Defines the code generated when the defined key is pressed. If the keyboard is not
referenced by an Audio element, the default keyboard layout us used. For details of
the default keyboard layout, refer to the APTRA Advance NDC, Reference Manual.

See Table Note 8

Audio Mandatory.

Defines a complete audio message.

Audio messages using Text elements are voiced by TTS software, and Recording
sub‐elements by recorded voice, for example .wav files. If both Text and Recording
sub‐elements are present, the application plays the voice in the order they are defined.

Nested elements:
 audioID
 groupID
 keyboardID
 ad
 repetitions
 ParamSourceID
 keyText

audioID Mandatory.

Defines the Audio element. Can be any alphanumeric data unless it is associated
with a screen when it must match the screen number.

This sub‐element is case‐sensitive. If the identifier contains alphabetic characters, the

same case must be used in any reference to the identifier or the reference will be
unsuccessful.
See Table Note 9

groupID Optional.

Ignored by the SST.

Can be used by the host to categorise the Audio sub‐elements for different
downloads.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-35

Configuring Voice Guidance
XML Schema

Element Name Description

keyboardID Optional.

References a Keyboard element. The value must match an existing keyboardID

sub‐element of the Keyboard element.

This sub‐element can be included in either base or nested screens, but not both.

ad Optional.

Defines whether the Audio element is an advertisement. This is used to suppress

advertisements if the cardholder has chosen not to listen to advertisements during the
voice‐guided session.

Valid values are as follows:

true ‐ This element is an advertisement
false ‐ This element is not an advertisement.

If this sub‐element is not present, it is assumed that the element is not an

advertisement.

repetitions Optional.

Defines the number of times this element is repeated. Valid values are between 0 and
9, inclusive. A value of 0 repeats the message indefinitely, or as long as the associated
screen is displayed.

If not present, the message is played only once.

ParamSourceID Optional.

Defines the screen number that contains the variable placeholder audio (the base
screen).

This sub‐element is used when you use a screen as a placeholder screen for variable
audio data sent in the screen update field of the Transaction Reply message. In this
situation, the host typically only updates the variable screen data. The
ParamSourceID element allows the production of voiced data to match the displayed
screen. This can be used in the following ways:
 The base screen includes a nested screen call to the transaction‐specific screen
containing the fixed screen display text. The audioID associated with the nested
screen contains this ParamSourceID element
 A transaction‐specific screen nests the updated base screen. The
transaction‐specific screen contains the ParamSourceID element

An audioID associated with the base screen must be defined, although the audio
text defined for this audioID will not be voiced. If you want to voice the selected key,
the keyText element must be defined in this audioID

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-36 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Element Name Description

keyText Optional.

Plays the message defined by the Audio elements with an audioID equal to the
four‐digit screen number followed by a dash (‐) and the value of the selected key (for
example C for Cancel). For example, the message can echo the key selection, “Three”,
or the meaning of the key selection, “Withdrawal”. A maximum of 15 seconds is
allowed for the message.

This sub‐element is only valid for use with the following states and when the FDKs are
mapped to the numeric keys of the keypad:
 Four FDK Selection Function State
 FDK Information Entry State
 Eight FDK Selection Function State

For details of these states, refer to the APTRA Advance NDC, Reference Manual.

This sub‐element must be included in the Audio element associated with the base
screen. It must not be used with nested screens.

Only the keys used by the screen must be defined. For example, if the screen activates
numeric keys 1, 2, and the Cancel key, only the audioID for <screen number>‐1,
<screen number>‐2 and <screen-number>‐C need to be defined for the screen.

Valid values are as follows:

true ‐ Play the message
false ‐ SST beeps to provide audio feedback for a key press.

If this sub‐element is not present, the SST beeps to provide audio feedback for a key
press.

Voicing the Clear Key Press

When the Clear key is pressed, the text defined in the Audio element is voiced. For
this, set the keyText attribute in the XML file to "true", and set the audioID
attribute to the four‐digit NDC screen number (1234) followed by a dash (‐) and then
“CLR” for the Clear key.

For example, if the keyText attribute is set to "true" for audioID “1234” and
“1234-CLR” is configured in XML file, the text associated with “1234-CLR” will be
voiced when the Clear key is pressed.

This feature is valid in the following states:

 PIN Entry
 Information Entry
 Amount entry
 Enhanced amount entry
 Note mix selection
 ITR

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-37

Configuring Voice Guidance
XML Schema

Element Name Description

Text Optional.

Defines the message to be spoken in a specified language by the TTS software and the
playing of recorded voice using .wav files. The message can be repeated. Pauses,
nested audio elements and recorded voice files can be included. The sequence is
controlled by Advance NDC.

Nested elements:
 lang
 state

Embedded elements:
 Pause
 Link
 PlaceHolder
 Recording

lang Optional.

Defines the language used by the TTS software.

If the TTS software does not support the defined language, the whole Text element
and all sub‐elements are ignored.

If this sub‐element is not present, the language is assumed to be English.

See Table Note 4

state Optional.

Defines the target device for the message.

Valid values are as follows:

public ‐ Play the message through the speaker
private ‐ Play the message through the audio jack.

This sub‐element is not supported by Advance NDC. The message is always played
through the audio jack.

Pause Optional.

Defines the duration of the pause in the playback.

The duration is defined in tenths of a second. Valid values are between 1 and 999,
inclusive. A duration of 10 causes a one second pause in the playback.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-38 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Element Name Description

Link Optional.

Specifies a nested audioID sub‐element to be included in the message.

This sub‐element include identifiers for both the audioID and groupID containing
the linked information. If the specified audioID does not exist, this sub‐element is
ignored. The specified audioID sub‐element must include only the Text
sub‐element.

This sub‐element is not needed if displaying a screen that includes nested screens with
their own audioID sub‐elements.

PlaceHolder Optional.

Specifies data to be substituted within the text.

The type of placeholder is implied by the content, as in the following examples:

 “$123” is currency and is played as “One hundred and twenty three Dollars”
 “1 2 3 4 5” are separate digits and are played as “One, Two, Three, Four, Five”
 “12345” is an amount and is played as “Twelve thousand, three hundred, forty
five”
 “savings” is a string and is played as “Savings”

The data cannot contain commas.

Nested Audio IDs have only one placeholder.

Recording Optional.

Specifies recorded voice in .wav files to be played with the text in a message.

This is usually used when the TTS software does not have support for a particular
language or for voicing dynamic text.

Nested elements:
 lang
 File
 state

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-39

Configuring Voice Guidance
XML Schema

Element Name Description

lang Optional.

Defines the language associated with the recording.

If this is specified, the Recording element is played only if the specified language
matches the language used in the current voice guided session.

If this is not specified, the Recording element is played as part of the audio element.

See Table Note 4.

File Mandatory.

Defines the name of the file containing the recorded voice.

If the file is copied to the C:\Program Files\NCR APTRA\Advance NDC\Media folder,

the path is not required, otherwise the full path and filename must be specified.

state Optional.

Defines the target device for the message.

Valid values are as follows:

public ‐ Play the message through the speaker
private ‐ Play the message through the audio jack.

This sub‐element is not supported by Advance NDC. The message is always played
through the audio jack.

Table Note 1: If multiple languages are supported, a screen must

be defined for each supported language. Language screens must be
numbered as defined in the ScreenOffset sub‐element.

Table Note 2 Ensure that no audio elements are defined for screens
used in a voice‐guided session with hidden screens used for
privacy.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-40 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Table Note 3 An integer value defines the position of a key as

illustrated in the following diagram. Shaded positions cannot be
defined in the XML configuration:

Figure 6-5
Key Positions FDK Left Numeric Keypad FDK Right

17 1 2 3 4 18

19 5 6 7 8 20

21 9 10 11 12 22

23 13 14 15 16 24

Table Note 4: The Spanish language has been coded as in some

legacy configurations. To support these configurations, this value is
automatically converted to the correct two‐character ISO code (es).

Table Note 5: The language code positions are defined as follows:

0 1 2 3 4 5 6 7

Table Note 6: If the PIN & Language Select State is used with voice
guidance, the screen offset defined in the XML file must match the
screen offset of the downloaded screens. For details of the PIN &
Language Select State, refer to the APTRA Advance NDC, Reference
Manual.

Table Note 7: The screen offset used in voice guidance screens is

different from that applied in Advance NDC where an offset of 5
would offset the screens by 5,000.

Table Note 8: Valid Tab: Valid codes that can be assigned in the
code sub‐element are given in Table 6‐4.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-41

Configuring Voice Guidance
XML Schema

Table 6-4 Code (Hex) Description

Codes for Defined Keys
30 ASCII ‘0’

31 ASCII ‘1’

32 ASCII ‘2’

33 ASCII ‘3’

34 ASCII ‘4’

35 ASCII ‘5’

36 ASCII ‘6’

37 ASCII ‘7’

38 ASCII ‘8’

39 ASCII ‘9’

F1 Enter

F2 Cancel

F3 FDK ‘D’

F4 FDK ‘C’

F5 FDK ‘B’

F6 FDK ‘A’

F7 FDK ‘F’

F8 FDK ‘G’

F9 FDK ‘H’

FA FDK ‘I’

FF Clear

Table Note 9 While voicing the multi‐lingual data for a screen

which is indicated in the state table, the AudioGuidanceData.xml file
needs to have separate audioID for each language screen with
language offset applied.

The following are few examples on the usage of Audio ID elements

Voicing the Multi‐Lingual for screens present in the state table and in the screens provided in
Data Examples 6
transaction reply.
To provide text for voicing screen 014 when the language offset is
500, there should be two audioIDs defined. For the first language
the audioID is 014 and for second language, the audioID is 514. The
details are:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-42 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
XML Schema

Figure 6-6
Example for two audioIDs
<Audio audioID="0014" groupID="0000" keyboardID="104" repetitions="0">
<Text lang="en" state="private">For Cash Withdrwal, press 1. For Account Inquiry,
press 2. For Settings press 3,For cancel press cancel button</Text>
</Audio>
<Audio audioID="0514" groupID="0000" keyboardID="104" repetitions="0">
<Text lang="ar" state="private">ARABIC 514 SCREEN data - For Cash Withdrwal,
press 1. For Account Inquiry, press 2. For Settings press 3,For cancel press
cancel button</Text>
</Audio>

Example of screen data provided in a transaction reply The 6

following is an example of screen data provided in a transaction

reply. In this case, the multi‐lingual screens need only one audioID
(of the base screen) and separate text elements within the same
audioID for voicing various languages.
The transaction reply for multiple languages will have the same
base screen number as follows.
4 <fs> <fs> <fs> 077 <fs> <fs> 1234 5 077 075
P0000;1;234\234003NDC DEMO NEXT STATE AND PRINT TEST

This reply needs the AudioGuidanceData.xml to have multiple text

elements in the same audioID as follows:

Figure 6-7
Example for one audioID
<Audio audioID="0075" groupID="0000" repetitions="1" keyboardID="102">
<Text lang="en" state="private">The actual balance in your account is
<PlaceHolder/><Pause duration ="5"/>Would you like to perform another
transaction. If yes, press 1. If no, press 2.</Text>
<Text lang="ar" state="private">ARABIC 075 SCREEN. The actual balance in your
account is <PlaceHolder/><Pause duration ="5"/>Would you like to perform another
transaction. If yes, press 1. If no, press 2.</Text>
</Audio>
<Audio audioID="0077" groupID="0000" repetitions="0" keyboardID="102">
<Text lang="en" state="private">Your transaction is completed, Would you like to
perform another transaction. If yes, press 1. If no, press 2.</Text>
<Text lang="ar" state="private">Your ARABIC transaction FOR SCREEN 077 is completed,
Would you like to perform another ARABIC transaction. If yes, press 1. If no, press
2.</Text>
</Audio>

The encoding formats used in AudioGuidanceData.xml can be

Encoding Formats for changed from ʺISO‐8859‐1ʺ to any other format such as ʺUTF‐8ʺ or
Voice Guidance 6
ʺUTF‐9ʺ, however, the file must be saved in the same format or it

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-43

Configuring Voice Guidance
XML Schema

will be invalid. In addition, the TTS software used must support the
specified encoding format or the audio message will not be played.
For information on changing the encoding format, see “Specifying
the Character Encoding” on page 6‐12.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-44 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Example XML Configuration File

Example XML Configuration File 6

The following example XML file references the schema described in

“XML Schema” on page 6‐16.

Figure 6-8
Example Voice Guidance XML File
<?xml version="1.0" encoding="ISO-8859-1"?>
<x:NCRAudioGuidance xmlns:x="urn:xsdNCRAudioGuidance">
<Config groupID="0000" restartKeyPos="6" repeatDelay="30" configRetryCount="2"
timersAdjust="45" blankScreenID="0196" cardPromptScreen="0197"
contactAndContactlessPromptScreen=”0198” contactlessPromptScreen=”0199” defaultVolume="50">
<afaTrigger useLang="false" triggerKeyPos="6" confirmationAudioID="confirm"
timeoutAudioID="timeOut"/>
<afaLang screen="0190" opCodePos="7">
<LangOption lang="en" keyPos="1" opCode="C" opCodeNoALT="A" screenOffset="0"
treqFieldID="&#60;"/>
<LangOption lang="sp" keyPos="2" opCode="D" opCodeNoALT="B" screenOffset="0"
treqFieldID="&#60;"/>
</afaLang>
<audioVolume screen="0191" plusKeyPos="1" minusKeyPos="2" doneKeyPos="4"/>
<!---1 to 4 question -->
<afaOption name="blankScreen" screen="0192" yesKeyPos="1" yesAudioID="blankYes"
noKeyPos="2" noAudioID="blankNo" defaultResponse="false"/>
<afaOption name="ads" screen="0193" yesKeyPos="1" yesAudioID="adsyes" noKeyPos="2"
noAudioID="adsNo" defaultResponse="true"/>
<afaOption name="OrientationSkip" screen="0194" yesKeyPos="1" yesAudioID="orientYes"
noKeyPos="2" noAudioID="orienNo"/>
<afaOption name="OrientationScript" screen="0195" yesKeyPos="1" yesAudioID="" noKeyPos="2"
noAudioID=""/>
</Config>
<!-- 2 FDK:FD -->
<Keyboard keyboardID="102">
<Key pos="1" code="F7"/>
<Key pos="2" code="F3"/>
</Keyboard>
<!-- 2 FDK:GC -->
<Keyboard keyboardID="110">
<Key pos="1" code="F8"/>
<Key pos="2" code="F4"/>
</Keyboard>
<!-- 2 FDK:AB -->
<Keyboard keyboardID="100">
<Key pos="1" code="F6"/>
<Key pos="2" code="F5"/>
</Keyboard>
<!-- 2 FDK:CD -->

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-45

Configuring Voice Guidance
Example XML Configuration File

<Keyboard keyboardID="103">
<Key pos="1" code="F4"/>
<Key pos="2" code="F3"/>
</Keyboard>
<!-- 3 FDK:ABC -->
<Keyboard keyboardID="105">
<Key pos="1" code="F6"/>
<Key pos="2" code="F5"/>
<Key pos="3" code="F4"/>
</Keyboard>
<!-- 4 FDK:ABCD -->
<Keyboard keyboardID="106">
<Key pos="1" code="F6"/>
<Key pos="2" code="F5"/>
<Key pos="3" code="F4"/>
<Key pos="5" code="F3"/>
</Keyboard>
<!-- 8 FDK:ABCDFGHI -->
<Keyboard keyboardID="113">
<Key pos="1" code="F6"/>
<Key pos="2" code="F5"/>
<Key pos="3" code="F4"/>
<Key pos="5" code="F3"/>
<Key pos="6" code="F7"/>
<Key pos="7" code="F8"/>
<Key pos="9" code="F9"/>
<Key pos="10" code="FA"/>
</Keyboard>

<!-- AFA Option messages -->

<Audio audioID="blankYes" groupID="0000">
<Text lang="en" state="private"> You have chosen to hide the screens. </Text>
</Audio>
<Audio audioID="blankNo" groupID="0000">
<Text lang="en" state="private"> You have chosen to display the screens. </Text>
</Audio>
<Audio audioID="adsYes" groupID="0000">
<Text lang="en" state="private"> You have chosen to hear the advertisements </Text>
</Audio>
<Audio audioID="adsNo" groupID="0000">
<Text lang="en" state="private"> You have chosen not to hear the advertisements. </Text>
</Audio>
<Audio audioID="orientNo" groupID="0000">
<Text lang="en" state="private"> You have chosen to listen to the orientation </Text>
</Audio>
<Audio audioID="orientYes" groupID="0000">
<Text lang="en" state="private"> You have chosen not to listen to the orientation. </Text>
</Audio>
<Audio audioID="timeOut" groupID="0000">

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-46 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Example XML Configuration File

<Text lang="en" state="private"> Time alloted to make a selection has expired. </Text>
<Recording file="timeout" state="private"/>
</Audio>
<Audio audioID="confirm" groupID="0000" repetitions="0" keyboardID="010">
<Text lang="en" state="private"> To confirm audio session activation, please press the 5 key
once more. </Text>
</Audio>
<Audio audioID="0190" groupID="0000" keyboardID="010" repetitions="0">
<Text lang="en" state="private"> Please choose a language. For English, press 1. For Spanish,
press 2. </Text>
</Audio>
<Audio audioID="0191" groupID="0000" repetitions="0" keyboardID="010">
<Text lang="en" state="private"> <Link audioID="Link0191" groupID="0000"/> <Pause
duration="20"/> To increase volume, please press 1. To decrease volume, please press 2. To
accept this volume, please press the Enter key. </Text>
</Audio>
<Audio audioID="Link0191">
<Text lang="en" state="private"> Welcome to the audio session. If you wish to use the default
settings, which consist of the current volume level and displaying the screens, please insert
your card. If you wish to customise the options, please continue with the selection menus.
Please note that you can press the Cancel key at any point during the selection setting to begin
again. </Text>
<Recording file="PlayWelcome" state="private"/>
</Audio>
<Audio audioID="0192" groupID="0000" repetitions="0" keyboardID="010">
<Text lang="en" state="private"> The audio session allows you to hide or display the SST
screen for privacy during your banking session. To hide the SST screens, please press 1. To
display SST screens, please press 2. </Text>
</Audio>
<Audio audioID="0193" groupID="0000" repetitions="0" keyboardID="010">
<Text lang="en" state="private"> The audio session allows you to skip any advertising
messages, please press 2. </Text>
</Audio>
<Audio audioID="0194" groupID="0000" repetitions="0" keyboardID="010">
<Text lang="en" state="private"> The audio session allows you to hear a short orientation
before starting your transaction. To skip the orientation, please press 1. To hear the
orientation, please press 2. </Text>
</Audio>
<Audio audioID="0195" groupID="0000" repetitions="1">
<Text lang="en" state="private"> Voice guidance allows a visually impaired individual to use
an SST. Choices are made using the 8-function display keys are reassigned to the numeric keypad.
Press 1 to listen to the orientation again. Press 2 to begin your transaction. </Text>
</Audio>
<Audio audioID="0197" groupID="0000" repetitions="0">
<Text lang="en" state="private"> Please insert your card. </Text>
<Audio audioID="0198" groupID="0000" repetitions="0">
<Text lang="en" state="private"> Please insert or tap the card. </Text>
<Audio audioID="0199" groupID="0000" repetitions="0">
<Text lang="en" state="private"> Please tap your card. </Text>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-47

Configuring Voice Guidance
Example XML Configuration File

</Audio>
<!-- English messages -->
<Audio audioID="0000" groupID="0000" keyboardID="100" repetitions="0" keyText="true">
<Text lang="en" state="private"> If you need more time, please press 1 for yes, press 2 for
no. </Text>
</Audio>
<Audio audioID="0000-1" groupID="0000">
<Text lang="en" state="private"> Yes </Text>
</Audio>
<Audio audioID="0000-2" groupID="0000">
<Text lang="en" state="private"> No </Text>
</Audio>
<Audio audioID="0000-C" groupID="0000">
<Text lang="en" state="private"> Cancel </Text>
</Audio>
<Audio audioID="0001" groupID="0000" repetitions="0">
<Text lang="en" state="private"> We’re sorry, this machine is currently unavailable. </Text>
</Audio>
<Audio audioID="0002" groupID="0000" repetitions="0">
<Text lang="en" state="private"> We’re sorry, this machine is currently unavailable. </Text>
</Audio>
<Audio audioID="0003" groupID="0000" repetitions="0">
<Text lang="en" state="private"> We’re sorry, this machine is currently unavailable. </Text>
</Audio>
<Audio audioID="0010" groupID="0000" repetitions="0" keyboardID="010">
<Text lang="en" state="private"> Welcome. To begin a voice-guided session please press the
5 key. </Text>
</Audio>
<!-- <Audio audioID="0102" groupID="0000" keyboardID="102" repetitions="0" keyText="true">
-->
<!-- English Translation flow screen messages -->
<Audio audioID="0012" groupID="0000" repetitions="1" keyText="true">
<Text lang="en" state="private"> Please enter your secret code, then press the Enter key
when you are finished. Press the Clear key if you wish to re-enter your secret code. </Text>
</Audio>
<Audio audioID="0012-CLR" groupID="0000">
<Text lang="en" state="private"> Cleared. Please re-enter your secret code. </Text>
</Audio>
<Audio audioID="0015" groupID="0000" repetitions="0" keyboardID="100" keyText="true">
<Text lang="en" state="private"> Please choose a transaction. To withdraw cash, press 1. To
check your balance, press 2. To cancel a transaction, press Cancel. </Text>
</Audio>
<Audio audioID="0015-1" groupID="0000">
<Text lang="en" state="private"> Withdrawal. </Text>
</Audio>
<Audio audioID="0015-2" groupID="0000">
<Text lang="en" state="private"> Balance. </Text>
</Audio>
<Audio audioID="0015-C" groupID="0000">
<Text lang="en" state="private"> Cancel. </Text>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-48 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Example XML Configuration File

</Audio>
<Audio audioID="0023" groupID="0000" repetitions="0">
<Text lang="en" state="private"> Key in the amount and press Enter. Press the Clear key if
you want to re-enter the amount. </Text>
</Audio>
<Audio audioID="0023-CLR " groupID="0000">
<Text lang="en" state="private"> Amount entered is cleared. Please re-enter the amount.
</Text>
</Audio>
<Audio audioID="0624" groupID="0000" repetitions="0">
<Text lang="en" state="private"> Please wait while your transaction is processing. </Text>
<Recording file="DAUDIA04.WAV" state="prvate"/>
</Audio>
<Audio audioID="0036" groupID="0000" repetitions="2">
<Text lang="en" state="private"> Please take your cash. </Text>
</Audio>
<Audio audioID="0050" groupID="0000" repetitions="0">
<Text lang="en" state="private"> Thank you for banking with us. Please take your receipt.
</Text>
</Audio>
<Audio audioID="0118" groupID="0000" repetitions="0" keyText="true">
<Text lang="en" state="private"> Key in your account number and press Enter. Press the Clear
key if you wish to re-enter the number. </Text>
</Audio>
<Audio audioID="0118-CLR" groupID="0000">
<Text lang="en" state="private"> Cleared. Please re-enter your account number </Text>
<!-- English reply message used in receipt data with Placeholder -->
<Audio audioID="0132" groupID="0000" repetitions="0">
<Text lang="en" state="private"> Your current balance is <PlaceHolder/>. </Text>
</Audio>

</x:NCRAudioGuidance>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-49

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Voice‐Guided Sessions without Host

Update 6

This section explains the structure of the XML file used to configure
voice‐guided sessions with no host update.
It also describes and illustrates how the Interactive Transaction
Response (ITR) and Transaction Reply messages are adjusted by the
XML file during a voice‐guided session without host update.
Finally, the section describes how the configuration information
sent in response to Send Configuration Information requests is
updated.

Although no schema file is provided with Advance NDC for

No Host Update XML voice‐guided sessions without host update, your XML file must
Elements 6
conform to the structure defined in the following table.
You must create your configuration file, called NHCVGAudio.xml,
and install it to the C:\Program Files\NCR APTRA\Advance
NDC\Config folder using your preferred method.
The no host update XML elements are described in the following
table.

Table 6-5
No Host Update XML Schema Elements

Element Name Description

NHCVGAudio Mandatory.

This is the root element.

The whole file is enclosed within NHCVGAudio tags.

Nested elements:
 ITRScreen
 ScreenUpdate
 PrintData

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-50 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

ITRScreen Mandatory.

Appears once only.

Defines the parsing rules for the Interactive Transaction Response message when
using voice guidance without host update.

Nested elements:
 Screen

Screen Mandatory.

Defines the information used to replace fields in an Interactive Transaction Response

message in a voice‐guided session. The formatting used for each attribute is the same
as that described for the associated field in the APTRA Advance NDC, Reference
Manual unless otherwise stated.

This element has the following attributes:

 Number. Mandatory. Identifies the data to be displayed on the cardholder screen
instead of using field ‘j’. This is either a four‐character string containing the
screen number (indirect audio text format) or blank (direct audio text format)
 timerValue. Optional. Identifies the timer value in ticks to use instead of using
field ‘i’
 repeatCount. Optional. Identifies the number of times to repeat the content of
the Text element. This is an integer between 0 and 9 to define the number of
times to repeat the text. If this is set to 0 or is blank, the text is only played once
and not repeated. If this is set to a number in the range 1 to 9, either the
repeatDelay or repeatDelayString attribute must also be defined
 repeatDelay. Optional. Defines the delay in tenths of a second between the
repeat of the content of the Text element
 repeatDelayString. Optional. Defines the control sequence used by the TTS
in use to add a delay between the repeat of the content of the Text element.
Not supported by Advance NDC
 displayFlag. Optional. Defines the masking of the cardholder display to apply
instead of using field ‘g’
 activeKeysMask. Optional. Defines the keys enabled instead of using field ‘h’
 enterKeyMap. Optional. Defines the key to use as the Enter key when
activeKeysMask is used
 cancelKeyMap. Optional. Defines the key to use as the Cancel key when
activeKeysMask is used
 appendScreenUpdateData. Optional. Defines the screen display data with or
without the audio data. If the value is set to 0 (default), the screen display data is
replaced with audio data only. If the value is set to 1, Screen Data Field will play
audio data and screen display data.
Nested elements:
 AudioData

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-51

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

AudioData Mandatory.

Defines the language used in a voice‐guided session without host update.

This element has the following attributes:

 lang. Mandatory. Identifies the language to use. The language selected by the
cardholder at the start of the voice‐guided session is matched with this attribute
to determine which AudioData element to use in the transaction. If there is no
match, no audio data is built. The two‐character string must comply with the ISO
639‐1 standard for codes representing the names of languages

Nested elements:
 DynamicTextDetails
 Text

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-52 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

DynamicTextDetails Mandatory.
Defines a specific piece of variable data. There can be one or more
DynamicTextDetails sub‐elements, which are used in sequential order. Any
spaces are automatically deleted from the dynamic data, and if only spaces are
included the dynamic data is considered to be “not found” unless the
dynDataDefault attribute is specified. As well as spaces, special characters, audio
control sequences, and the control sequences for the primary and secondary character
sets are also deleted from the dynamic data. See “Dynamic Data” on page 6‐9 for
more details.
This element has the following attributes:
 name. Mandatory. Identifies the dynamic data being searched for. This attribute
must be unique for each DynamicTextDetails sub‐element. It is used to reference
dynamic data in the Text and Criteria sub‐elements and is case sensitive.
 Numeric. Mandatory. Defines how the dynamic data is voiced. Valid values are
as follows:
— true The dynamic data must be voiced one digit or character at a time. Each
character of the dynamic data is modified so that it is separated by a space
character
— false The dynamic data is not modified or voiced one character at a time.
This is the default setting used if this attribute is blank or undefined
 Location. Mandatory. Defines where the dynamic data is located with regard to
the search string. Valid values are as follows:
— sameAs The dynamic data is the search string, if found. If any control
characters in the range hex 00 to hex 1F, and the control sequences for the
primary and secondary character sets are included in the dynamic data, they
are removed. If this is used, the dynDataDefault attribute must be blank or
undefined
— toRight The dynamic data is located to the right of the search string, if
found. All spaces and any characters from the beginning and end of the
string as defined in the StartPosition and EndPosition sub‐elements
are trimmed and either the ExtractCharsFromLast or
ExtractCharsFromStart sub‐elements are applied. This is the default
setting used if this attribute is blank or undefined
 dynDataDefault. Optional. Defines the variable‐length string to use as the
dynamic data if the search string is not found. If this is used, the dynamic data is
considered “found” when tested with the Criteria element. This must be
blank or undefined if the Location attribute is set to sameAs.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-53

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

 searchType. Mandatory. Defines where to start the search for the dynamic data.
Valid values are as follows:
— sequential The search begins at the point following the previous
successful search. If the previous successful search included the EndStr
element, the search starts from first character of the EndStr data. This is the
default setting used if this attribute is blank or undefined
startFromBeginning The dynamic data is HERE.
Nested elements:
 SearchStr
 EndStr
 StartPosition
 EndPosition
 ExtractCharsFromLast
 ExtractCharsFromStart

SearchStr Mandatory.

Defines the location at which to start the search of the variable data.

If the search string defined in the value element is not found, the dynamic data is
considered not found.

Nested elements:
 value

value Mandatory.

Defines the character string to be searched for when locating the start of the variable
data.

There can be one or more value elements within a SearchStr element, and each
defined string is searched for in turn.

Nested elements:
 hex

hex Optional.

Defines hexadecimal data or an XML special character within the search string. Each
hex element can only contain one hexadecimal or special character. If more than one
is required, you must use multiple hex elements.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-54 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

EndStr Optional.

Defines the location at which to end the search of the variable data when the
Location attribute of the DynamicTextDetails element is set to toRight. If the
Location attribute is set to sameAs, the EndStr element is ignored.

If the Location attribute of the DynamicTextDetails element is set to toRight

and the search string defined in the value element of the SearchStr element is
found, the EndStr element can be used as follows:

 If the value element of the EndStr element is defined, the data defined in the
value element of the EndStr is located and defines the end of the variable
data. If the search string defined in the value element is not found, the dynamic
data is considered not found
 If the value element of the EndStr element is not defined, the end of the
variable data is considered to be the end of the data to be searched.

Nested elements:
 value

value Optional.

Defines the character string to be searched for when locating the end of the variable
data.

There can be one or more value elements within an EndStr element, and each
defined string is searched for in turn.

Nested elements:
 hex

hex Optional.

Defines hexadecimal data or XML special characters within the search string. Each
hex element can only contain one hex or special character, if more than one hex or
special character is required, you must use multiple hex elements.

StartPosition Optional.

Defines the number of characters to skip after the search string defined in the
SearchStr element and after removing any leading spaces.

If this element is blank or undefined, no characters are skipped.

EndPosition Optional.

Defines the number of characters to skip backwards from the search string defined in
the EndStr element and after removing any trailing spaces.

If this element is blank or undefined, no characters are skipped.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-55

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

ExtractCharsFromLast Optional.

Defines the number of characters to extract from the end of the located string after
any adjustment as defined by the EndPosition element. This extracted set of
characters is used as the dynamic text for this DynamicTextDetails element.

If this element is used, the ExtractCharsFromLast element must be blank or

undefined.

ExtractCharsFromStart Optional.

Defines the number of characters to extract from the start of the located string after
any adjustment as defined by the StartPosition element. This extracted set of
characters is used as the dynamic text for this DynamicTextDetails element.

If this element is used, the ExtractCharsFromLast element must be blank or

undefined.

Text Mandatory

Defines the static and dynamic text to be passed to the TTS engine for this transaction
message using the language defined in the AudioData element.

Dynamic text is defined using the DynamicTextDetails element and its nested
elements. Dynamic data can be embedded into static text and can be tested using the
Criteria element to determine whether it has been found. You can include certain
text depending on the result of the Criteria test.

Nested elements:
 FreeText
 Criteria

FreeText Mandatory

Defines the text to be voiced along with any dynamic data, spaces and control
characters.

NCR recommends that the text for a given phrase or paragraph is defined on a single
line. Use multiple lines with separate FreeText elements to prevent control
characters from being voiced. Multiple consecutive lines must have a space at either
the end of the previous or the start of the next line of text.

Static text followed by dynamic data must have a space character included at the end
of the static text.

A space character is automatically inserted immediately after each piece of dynamic

data.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-56 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

Criteria Mandatory.

Tests whether the dynamic data is found or not. You can test multiple dynamic text
names within a single Criteria element using OR logic or use nested Criteria
elements to apply AND logic.

When testing the ITRScreen element, the following names can be used to test
whether any of the FDK, numeric or Cancel keys are active:

 ITR_FDK_A
 ITR_FDK_B
 ITR_FDK_C
 ITR_FDK_D
 ITR_FDK_F
 ITR_FDK_G
 ITR_FDK_H
 ITR_FDK_I
 ITR_Numerics
 ITR_Cancel
These names reflect the keys activated by the activeKeysMask parameter of the
Screen element if used, otherwise they reflect the keys activated by the ITR
message sent by the host.

ScreenUpdate Mandatory.

Appears once only.

Defines the parsing rules for the screens containing updated screen data in the
Transaction Reply message when using voice guidance without host update.

Nested elements:
 Screen

Screen Mandatory.

Defines the screen used to replace that given in field ‘n’ of a Transaction Reply
message in a voice‐guided session.

This element has the following attributes:

 Number. Mandatory. Identifies the four‐character screen number that identifies
the screen containing the updated screen data.

Nested elements:
 DynamicTextDetails

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-57

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

DynamicTextDetails For details, see DynamicTextDetails on 6-53

The dynamic text data located by the searches is passed as placeholder data in the
order that the data is found. If dynamic data is not found, it is not included in the list
of placeholder data. The placeholder data is referenced in the AudioGuidanceData.xml
file by the Audio element with an audioID matching the screen number of the
updated screen data. For details of the Audio element, see “XML Schema” on
page 6‐16.

PrintData Mandatory.

Appears once only.

Defines the parsing rules for the print data in the Transaction Reply message when
using voice guidance without host update.

Nested elements:
 TranReply

TranReply Mandatory.

Defines the print data parsing rules. There can be one or more TranReply
sub‐elements. This element has the following attributes:

 FuncId. Mandatory. Defines the Function ID that has to be matched with the
Function ID in field ‘l’ of the Transaction Reply message
 NextState. Mandatory. Defines the next state that has to be matched with the
field ‘f’ of the Transaction Reply message
 ScrToDisplay. Mandatory. Defines the screen number that has to be matched
with the screen number in field ‘m’ of the Transaction Reply message.

For details of the Transaction Reply message, refer to Chapter 10, “Central to
Terminal Messages”, in the APTRA Advance NDC, Reference Manual.

Nested elements:
 AudioData

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-58 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Element Name Description

AudioData Mandatory.

Defines the language used in a voice‐guided session without host update.

This element has the following attributes:

 lang. Mandatory. Identifies the language to use. The language selected by the
cardholder at the start of the voice‐guided session is matched with this attribute
to determine which AudioData element to use in the transaction. If there is no
match, no audio data is built. The two‐character string must comply with the ISO
639‐1 standard for codes representing the names of languages

Nested elements:
 DynamicTextDetails
 Text

The host can pass variable data that might require audio as part of
Transaction Reply 6

the Screen Display Update field or in the Printer Data field in the
Transaction Reply. Each method is discussed below.
For details of the Transaction Reply, refer to Chapter 10, “Central to
Terminal Messages”, in the APTRA Advance NDC Reference Manual.

Screen Display Update Field 6

The Screen element in the NHCVGAudio.xml file can be used to

replace information in field ‘n’ of the Transaction Reply.
If field ‘n’ contains a screen number, the Number parameter is
checked for a matching entry.
If a matching entry is located, placeholder data is built based on the
parsing rules. The audio escape sequence containing the
placeholder data is added to the beginning of the data in the
Transaction Reply following the screen number. No data is removed
from the message. However, if any audio escape sequences are
already present for use with a .wav file, these escape sequences are
removed.

Note: Support for .wav files is provided through the standard voice
guidance processing.

If no matching entry is located, one of the following occurs:

 If there are further screen numbers in field ‘n’, the Number
parameter is checked again for a matching entry
 If there are no further screen numbers in field ‘n’, the Print Data
field is used as described in “Example 2 Transaction Reply
Conversion” on page 6‐61.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-59

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

If no screen number is contained in field ‘j’, the rules associated with

the default screen number are used to parse and build the voice
data.
Example Transaction Reply Conversion The examples in this 6

section are as follows:

 Figure 6‐9 shows the original Transaction Reply sent by the host
 Figure 6‐10 shows an example of Voice Guidance XML Extract
from the AudioGuidanceData.xml file
 Figure 6‐11 shows an example of Screen Update XML Extract
from the NHCVGAudio.xml file
 Figure 6‐12 shows the Transaction Reply updated using the
XML elements.

Figure 6-9
Original Transaction Reply
4<fs><fs><fs>125<fs><fs>19365100134<ff><si>AA<so>125<si>DF $1.75<fs>000

Figure 6-10
Example Voice Guidance XML Extract
<Audio audioID="0134" groupID="0000" repetitions="0" keyboardID="100" keyText="true">
<Text lang="en" state="private"> A fee of <PlaceHolder/> will be charged for this transaction.
Do you accept this fee? To accept, press 1. To decline, press 2 or press the Cancel key.
</Text>
</Audio>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-60 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-11
Example Screen Update XML Extract
<NHCVGAudio>

<ScreenUpdate>
<Screen Number="0134">
<DynamicTextDetails name="PlaceholderSurcharge" numeric="false" Location="toRight"
dynDataDefault="" searchType="sequential">
<SearchStr>
<value><hex>0F</hex>D</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>1C</hex></value>
</EndStr>
<StartPosition>1</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
</Screen>
</ScreenUpdate>

</NHCVGAudio>

Figure 6-12
Updated Transaction Reply
4<fs><fs><fs>125<fs><fs>19365100134<sc>P0000;1;$1.75<esc>\<ff><si>AA<So>125<si>DF$
1.75<fs>000

Example 2 Transaction Reply Conversion The examples in this 6

section are as follows:

 Figure 6‐13 shows the original Transaction Reply sent by the
host
 Figure 6‐14 shows an example of Voice Guidance XML Extract
from the AudioGuidanceData.xml file
 Figure 6‐15 shows an example of Screen Update XML Extract
from the NHCVGAudio.xml file
 Figure 6‐16 shows the Transaction Reply updated using the
XML elements.

Figure 6-13
Original Transaction Reply
4<fs><fs><fs>050<fs>00000000<fs>71705068065<si>MF$ 10225.34 <fs>000

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-61

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-14
Example Voice Guidance XML Extract
<Audio audioID="0065" groupID="0000" repetitions="0" keyboardID="100"
keyText="true">
<Text lang="en" state="private"> Your available balance is <PlaceHolder/>. Would
you like to perform another transaction? If yes, press 1. If no, press 2 or press
the cancel key.
</Text>
</Audio>

Figure 6-15
Example Screen Update XML Extract
<ScreenUpdate>
<!--Example 2-->
<Screen Number="0065">
<DynamicTextDetails name="PlaceholderAvailBalAmt" numeric="false"
Location="toRight" dynDataDefault="" searchType="sequential">
<SearchStr>
<value><hex>0F</hex>MF</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>1C</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
</Screen>
</ScreenUpdate>

Figure 6-16
Updated Transaction Reply
4<fs><fs><fs>050<fs>00000000<fs>71705068065<esc>P0000;1;$ 10225.34
<esc>\<si>MF$ 10225.34 <fs>000

Example 3 Transaction Reply Conversion The examples in this 6

section are as follows:

 Figure 6‐17 shows the original Transaction Reply (for displaying
the balance) sent by the host
 Figure 6‐18 shows the original Transaction Reply (for printing
the balance) sent by the host
 Figure 6‐19 shows an example of Voice Guidance XML Extract
from the AudioGuidanceData.xml file

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-62 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

 Figure 6‐20 shows an example of Screen Update XML Extract

from the NHCVGAudio.xml file
 Figure 6‐21 shows the Transaction Reply (for displaying the
balance) updated using the XML elements.
 Figure 6‐21 shows the Transaction Reply (for printing the
balance) updated using the XML elements.

Figure 6-17
Original Transaction Reply Display
4<fs><fs><fs>120<fs><fs>18765100120<ff><si>BAYOUR BALANCE
IS<si>CCAVAILABLE<si>CN $450.83<si>DCBALANCE <si>DN
$485.75<si>GA<so>160<fs>001<journal data>

Figure 6-18
Original Transaction Reply Print
4<fs><fs><fs>120<fs><fs>18775100120<ff><si>BAYOUR BALANCE IS ON YOUR
RECEIPT<si>GA<so>160<fs>003<receipt and journal data>

Figure 6-19
Example Voice Guidance XML Extract
<Audio audioID="0120" groupID="0000" repetitions="0" keyboardID="100"
keyText="true">
<Text lang="en" state="private"> <PlaceHolder/> <PlaceHolder/> <PlaceHolder/>
<PlaceHolder/> <PlaceHolder/>. Would you like to perform another
transaction? If yes, press 1. If no, press 2 or press the cancel key.
</Text>
</Audio>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-63

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-20
Example Screen Update XML Extract
<ScreenUpdate>
<!--Example 3-->
<Screen Number="0120">
<DynamicTextDetails name="PlaceholderBalDesc" numeric="false"
Location="toRight" dynDataDefault="" searchType="sequential">
<SearchStr>
<value><hex>0F</hex>BA</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>1C</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="PlaceholderAvailBalDesc" numeric="false"
Location="toRight" dynDataDefault="" searchType="sequential">
<SearchStr>
<value><hex>0F</hex>CC</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>1C</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="PlaceholderAvailBalAmt" numeric="false"
Location="toRight" dynDataDefault="" searchType="sequential">
<SearchStr>
<value><hex>0F</hex>CN</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>1C</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-64 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

<DynamicTextDetails name="PlaceholderAcctBalDesc" numeric="false"

Location="toRight" dynDataDefault="" searchType="sequential">
<SearchStr>
<value><hex>0F</hex>DC</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>1C</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="PlaceholderAcctBalAmt" numeric="false"
Location="toRight" dynDataDefault="" searchType="sequential">
<SearchStr>
<value><hex>0F</hex>DN</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>1C</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
</Screen>
</ScreenUpdate>

Figure 6-21
Updated Transaction Reply Display
4<fs><fs><fs>120<fs><fs>18765100120<esc>P0000;1;YOUR BALANCE
IS;AVAILABLE;$450.83;BALANCE;$485.75<esc>\<ff><si>BAYOUR BALANCE
IS<si>CCAVAILABLE<si>CN $450.83<si>DCBALANCE <si>DN
$485.75<si>GA<so>160<fs>001<journal data>

Figure 6-22
Updated Transaction Reply Print
4<fs><fs><fs>120<fs><fs>18775100120<esc>P0000;1;YOUR BALANCE IS ON YOUR
RECEIPT<esc>\<ff><si> BAYOUR BALANCE IS ON YOUR RECEIPT
<si>GA<so>160<fs>003<receipt and journal data>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-65

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Printer Data Field 6

The PrintData element in the NHCVGAudio.xml file can be used to

replace information in fields ‘r’ of the Transaction Reply. If multiple
print groups are included in the Transaction Reply, all print groups
are included as one string for the parsing.
If there is no print data included in the Transaction Reply, the
processing for voice‐guided session without host update is
complete.
The parameters in the TranReply sub‐element must be set to
match the Transaction Reply as follows:
 The FuncId parameter must match with field ‘l’
 The NextState parameter must match with field ‘f’
 The ScrToDisplay parameter must match with field ‘m’.
If parsing rules are applied, the voice data is built based on these
rules and the ‘>’ printer flag followed by the built voice data within
double quotation marks is added to the Transaction Reply.
Example Transaction Reply Conversion The examples in this 6

section are as follows:

 Figure 6‐23 shows the original Transaction Reply sent by the
host
 Figure 6‐24 shows an example of Print Data XML Extract from
the NHCVGAudio.xml file
 Figure 6‐25 shows the Transaction Reply updated using the
XML elements.

Figure 6-23
Original Transaction Reply
4<fs><fs><fs>118<fs>0000<fs>00285123<fs>102YOUR BANK<lf><lf>2/21/09<so>511:11
AM<lf><so>:******0123<lf><so>:11-22-09<lf><lf><lf><lf>CHECKING<lf>BALANCE
$77273.54<lf><lf>00028<ff>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-66 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-24
Example Print Data XML Extract
<NHCVGAudio>
<PrintData>
<TranReply FuncId="5" NextState="118" ScrToDisplay="0123">
<AudioData lang="en">
<DynamicTextDetails name="DynamicChecking" numeric="false" Location="sameAs"
dynDataDefault="" searchType="sequential">
<SearchStr>
<value><hex>0A</hex><hex>0A</hex><hex>0A</hex>CHECKING</value>
</SearchStr>
<EndStr>
<value><hex>0A</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<Text>
<DynamicTextDetails name="DynamicAcctBal" numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0A</hex>BALANCE</value>
</SearchStr>
<EndStr>
<value><hex>0A</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<Criteria DynamicChecking="found">
<FreeText>Your new </FreeText>
<DynamicChecking/>
<FreeText> account balance is </FreeText>
</DynamicAcctBal/>
</Criteria>
</Text>
</AudioData>
</TranReply>
</PrintData>
</NHCVGAudio>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-67

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-25
Updated Transaction Reply
4<fs><fs><fs>118<fs>0000<fs>00285123<fs>102YOUR BANK<lf><lf>2/21/09<so>511:11
AM<lf><so>:******0123<lf><so>:11-22-09<lf><lf><lf><lf>CHECKING<lf>BALANCE
$77273.54<lf><lf>00028<ff><gs>>”Your new CHECKING account balance is $77273.54”

The ITR message is used to gather further information from the

Interactive Transaction cardholder, for example to identify the account to debit for a
Response 6
withdrawal. For details of the ITR message, refer to Chapter 10,
“Central to Terminal Messages”, in the APTRA Advance NDC
Reference Manual.
The Screen element in the NHCVGAudio.xml file is used to replace
information in some fields of the ITR and Transaction Request
messages, as described in the following sections.

ITR Screen Data Fields 6

The Screen Data Fields can be configured to display the screen data
or only the audio data by setting an attribute to the
appendScreenUpdateData, for details, see the Screen element in
Table 6‐5, “No Host Update XML Schema Elements” on
page 6-50.

Screen data can be provided using fields ʹj1ʹ and ʹj2ʹ of the ITR
message
Field ‘j1’ can contain a screen number. The screen number is
converted as follows:
 A three‐digit screen number, for example 123, is prefixed with
‘0’
 A four‐digit screen number enclosed in quotation marks, for
example “1234”, has the quotation marks removed
 A four‐digit screen number with prefixed with either ‘u’ or ‘l’,
for example u1234, has the prefix removed.
After the screen number has been converted, the Number parameter
is checked for a matching entry.

Note: If field ‘j1’ contains more than one screen number, the first
number is used.

If a matching entry is located, the associated rules are used to parse

and build the voice data for the current ITR message in Direct
Audio Text format.
If no matching entry is located, field ‘j1’ is not modified.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-68 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

If no screen number is contained in field ‘j1’, the rules associated

with the null screen number are used to parse and build the voice
data.
Field ʹj2ʹ, is only used in a voice‐guided session with data provided
by the host.

ITR Screen Timer Field 6

The timerValue parameter is used, if present, to define time‐out

intervals from the cardholder screen display. This replaces any
information supplied in field ‘i’ of the ITR.

ITR Display Flag Field 6

The displayFlag parameter is used, if present, to define how to

display cardholder keyboard entry on the screen. This replaces any
information supplied in field ‘g’ of the ITR.

ITR Active Keys/Touch Areas Field 6

The activeKeysMask parameter is used, if present, to active the

required keys or touch areas for cardholder responses. This replaces
any information supplied by field ‘h’ in the ITR.

Transaction Request General Purpose Buffer B field 6

The enterKeyMap or cancelKeyMap parameters are used, if present

and if the cardholder has selected the Enter or Cancel key, to update
field ‘m’ before the message is sent on to the host.
For example, this mapping is required if numeric keys are used for
numeric entry and FDKs are active to allow selection of the Enter or
Cancel keys.

Example ITR Message Conversion 6

The examples in this section are as follows:

 Figure 6‐26 shows the original ITR sent by the host
 Figure 6‐27 shows the Example XML Extract from the
NHCVGAudio.xml file
 Figure 6‐27 shows the ITR updated using the XML elements.
The message is updated, as follows:
 The Screen Timer Field is updated from a value of ‘080’ to a
value of ‘050’
 The audio data is provided.
The extract also shows that FDK C, FDK D and the Cancel key are
active.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-69

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-26
Original ITR Message
3<fs><fs><fs>20000111<fs>050<fs><ff><so>060<si>ABYOUR BANK <si>CB$1.00

Figure 6-27
Example XML Extract
<NHCVGAudio>
<ITRScreen>
<Screen Number="0060" timerValue="080" repeatCount="0" repeatDelay="" repeatDelayString=""
displayFlag="" activeKeysMask="" enterKeyMap="" cancelKeyMap="">
<AudioData lang="en">
<DynamicTextDetails name="DynamicText_BANK" Numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>AB</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicText_Fee" Numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>CB</value>
</SearchStr>
<EndStr>
</EndStr>
<StartPosition>0</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<Text>
<FreeText>For this transaction, </FreeText>
<DynamicText_BANK/>
<FreeText> will charge a fee of </FreeText>
<DynamicText_Fee/>
<FreeText>. This fee is in addition to any fees your </FreeText>
<FreeText>institution may charge you. If you accept this </FreeText>
<FreeText>fee and would like to continue with this </FreeText>
<FreeText>transaction, press 3. To decline this fee </FreeText>
<FreeText>and terminate this transaction, press 4, or </FreeText>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-70 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

<FreeText>press the cancel key.</FreeText>

</Text>
</AudioData>
</Screen>
</ITRScreen>
</NHCVGAudio>

Figure 6-28
Updated ITR Message
3<fs><fs><fs>20000111<fs>080<fs>For this transaction, YOUR BANK will charge a fee
of $1.00. This fee is in addition to any fees your institution may charge you. If
you accept this fee and would like to continue with this transaction, press 3. To
decline this fee and cancel this transaction, press 4 or the Cancel key.

Example 2 ITR Message Conversion 6

This is a multiple account example with three variable data

elements. The examples in this section are as follows:
 Figure 6‐29 shows the original ITR sent by the host
 Figure 6‐32 shows the Example XML Extract from the
NHCVGAudio.xml file
 Figure 6‐30 shows the ITR updated using the XML elements.
The message is updated, as follows:
 The Screen Timer Field is updated from a value of ‘080’ to a
value of ‘050’
 The audio data is repeated a second time, so the variable data
must be included in the voice data twice.
The extract also shows that Numerics, FDKs A,C,D,F & G and
Cancel Key are active.

Figure 6-29
Original ITR Message
3<fs><fs><fs>211101111100<fs>050<fs><ff><si>CC 1. PRIMARY SAVINGS<si>DC 2.
SECONDARY SAVINGS<si>EC 3. CHRISTMAS CLUB<so>090

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-71

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-30
Updated ITR Message
3<fs><fs><fs>211101111100<fs>080<fs>Please select the specific account you wish to
use. For your PRIMARY SAVINGS account, press 1 followed by the enter key. For your
SECONDARY SAVINGS account, press 2 followed by the enter key. For your CHRISTMAS
CLUB account, press 3 followed by the enter key. To cancel this transaction, press
the cancel key. [default RealSpeak 4-second delay sequence is inserted here] Please
select the specific account you wish to use. For your PRIMARY SAVINGS account,
press 1 followed by the enter key. For your SECONDARY SAVINGS account, press 2
followed by the enter key. For your CHRISTMAS CLUB account, press 3 followed by the
enter key. To cancel this transaction, press the cancel key.

Example 3 ITR Message Conversion 6

This is a multiple account example using the same screen number as

the above example but with two variable data elements. The
examples in this section are as follows:
 Figure 6‐31 shows the original ITR sent by the host
 Figure 6‐32 shows the Example XML Extract from the
NHCVGAudio.xml file
 Figure 6‐33 shows the ITR updated using the XML elements.
The message is updated, as follows:
 The Screen Timer Field is updated from a value of ‘080’ to a
value of ‘050’
 The audio data is repeated a second time, so the variable data
must be included in the voice data twice.
The extract also shows that Numerics, FDKs A,C,D,F & G and
Cancel Key are active.

Figure 6-31
Original ITR Message
3<fs><fs><fs>211101111100<fs>050<fs><ff><si>CC 1. PRIMARY SAVINGS<si>DC 2.
SECONDARY SAVINGS<so>090

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-72 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-32
Example XML Extract
<ITRScreen>
<!--Examples 2 & 3-->
<Screen Number="0090" timerValue="080" repeatCount="1" repeatDelay="40"repeatDelayString=""
displayFlag="" activeKeysMask="" enterKeyMap=""cancelKeyMap="">
<AudioData lang="en">
<DynamicTextDetails name="DynamicAcct1" Numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>CC</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>0E</hex></value>
</EndStr>
<StartPosition>4</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicAcct2" Numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>DC</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>0E</hex></value>
</EndStr>
<StartPosition>4</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicAcct3" Numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>EC</value>
</SearchStr>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-73

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

<EndStr>
<value><hex>0F</hex></value>
<value><hex>0E</hex></value>
</EndStr>
<StartPosition>4</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicAcct4" Numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>FC</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>0E</hex></value>
</EndStr>
<StartPosition>4</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicAcct5" Numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>GC</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>0E</hex></value>
</EndStr>
<StartPosition>4</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicAcct6" Numeric="false" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>HC</value>
</SearchStr>
<EndStr>
<value><hex>0F</hex></value>
<value><hex>0E</hex></value>
</EndStr>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-74 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

<StartPosition>4</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast></ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<Text>
<FreeText>Please select the specific account you wish to use. </FreeText>
<Criteria DynamicAcct1="found">
<FreeText>For your </FreeText>
<DynamicAcct1/>
<FreeText> account, press 1 followed by the enter key. </FreeText>
</Criteria>
<Criteria DynamicAcct2="found">
<FreeText>For your </FreeText>
<DynamicAcct2/>
<FreeText> account, press 2 followed by the enter key. </FreeText>
</Criteria>
<Criteria DynamicAcct3="found">
<FreeText>For your </FreeText>
<DynamicAcct3/>
<FreeText> account, press 3 followed by the enter key. </FreeText>
</Criteria>
<Criteria DynamicAcct4="found">
<FreeText>For your </FreeText>
<DynamicAcct4/>
<FreeText> account, press 4 followed by the enter key. </FreeText>
</Criteria>
<Criteria DynamicAcct5="found">
<FreeText>For your </FreeText>
<DynamicAcct5/>
<FreeText> account, press 5 followed by the enter key. </FreeText>
</Criteria>
<Criteria DynamicAcct6="found">
<FreeText>For your </FreeText>
<DynamicAcct6/>
<FreeText> account, press 6 followed by the enter key. </FreeText>
</Criteria>
<FreeText>To cancel this transaction, press the cancel key.</FreeText>
</Text>
</AudioData>
</Screen>
</ITRScreen>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-75

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-33
Updated ITR Message
3<fs><fs><fs>211101111100<fs>080<fs>Please select the specific account you wish to
use. For your PRIMARY SAVINGS account, press 1 followed by the enter key. For your
SECONDARY SAVINGS account, press 2 followed by the enter key. To cancel this
transaction, press the cancel key. [default RealSpeak 4-second delay sequence is
inserted here] Please select the specific account you wish to use. For your PRIMARY
SAVINGS account, press 1 followed by the enter key. For your SECONDARY SAVINGS
account, press 2 followed by the enter key. To cancel this transaction, press the
cancel key.

Example 4 ITR Message Conversion 6

This is a multiple account example with two variable data elements

without any base screen number. Only the last four digits of the
account numbers are voiced. The examples in this section are as
follows:
 Figure 6‐34 shows the original ITR sent by the host
 Figure 6‐35 shows the Example XML Extract from the
NHCVGAudio.xml file
 Figure 6‐36 shows the ITR updated using the XML elements.
The message is updated, as follows:
 The Screen Timer Field is updated from a value of ‘080’ to a
value of ‘050’
The extract also shows that FDK A, FDK B and the Cancel key are
active.

Figure 6-34
Original ITR Message
3<fs><fs><fs>200110010000<fs>050<fs><ff><si>BCPLEASE SELECT YOUR ACCOUNT<si>C@
<si>F38714990012--><si>I38712990014-->

Figure 6-35
Example XML Extract
<ITRScreen>
<!--Example 4-->
<Screen Number="" timerValue="080" repeatCount="1" repeatDelay="40"
repeatDelayString="" displayFlag="0" activeKeysMask="" enterKeyMap=""
cancelKeyMap="">
<AudioData lang="en">
<DynamicTextDetails name="DynamicTextAcct1" Numeric="true" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-76 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

<value><hex>0F</hex>F</value>
<value><hex>0E</hex></value>
</SearchStr>
<EndStr>
<value>--</value>
</EndStr>
<StartPosition>1</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast>4</ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicTextAcct2" Numeric="true" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>I</value>
</SearchStr>
<EndStr>
<value>--</value>
<value><hex>0E</hex></value>
</EndStr>
<StartPosition>1</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast>4</ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicTextAcct3" Numeric="true" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>L</value>
<value><hex>0E</hex></value>
</SearchStr>
<EndStr>
<value>--</value>
</EndStr>
<StartPosition>1</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast>4</ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<DynamicTextDetails name="DynamicTextAcct4" Numeric="true" Location="toRight"
dynDataDefault="" searchType=”sequential”>
<SearchStr>
<value><hex>0F</hex>O</value>
<value><hex>0E</hex></value>
</SearchStr>
<EndStr>
<value>--</value>
</EndStr>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-77

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

<StartPosition>1</StartPosition>
<EndPosition></EndPosition>
<ExtractCharsFromLast>4</ExtractCharsFromLast>
<ExtractCharsFromStart></ExtractCharsFromStart>
</DynamicTextDetails>
<Text>
<FreeText>Please select the specific account you wish to use. </FreeText>
<Criteria DynamicTextAcct1="found">
<Criteria ITR_FDK_A="active">
<FreeText>For your account ending with </FreeText>
<DynamicTextAcct1/>
<FreeText>, press 1. </FreeText>
</Criteria>
</Criteria>
<Criteria DynamicTextAcct2="found">
<Criteria ITR_FDK_B="active">
<FreeText>For your account ending with </FreeText>
<DynamicTextAcct2/>
<FreeText>, press 2. </FreeText>
</Criteria>
</Criteria>
<Criteria DynamicTextAcct3="found">
<Criteria ITR_FDK_C="active">
<FreeText>For your account ending with </FreeText>
<DynamicTextAcct3/>
<FreeText>, press 3. </FreeText>
</Criteria>
</Criteria>
<Criteria DynamicTextAcct4="found">
<Criteria ITR_FDK_D="active">
<FreeText>For your account ending with </FreeText>
<DynamicTextAcct4/>
<FreeText>, press 4. </FreeText>
</Criteria>
</Criteria>
<Criteria ITR_Cancel="active">
<FreeText>To cancel this transaction, press the cancel key.</FreeText>
</Criteria>
</Text>
</AudioData>
</Screen>
</ITRScreen>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-78 APTRA Advance NDC, Developer’s Guide

 Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Figure 6-36
Updated ITR Message
3<fs><fs><fs>200110010000<fs>080<fs>Please select the specific account you wish to
use. For your account ending with 0 0 1 2, press 1. For your account ending with 0
0 1 4, press 2. To cancel this transaction, press the cancel key. [default
RealSpeak 4-second delay sequence is inserted here] Please select the specific
account you wish to use. For your account ending with 0 0 1 2, press 1. For your
account ending with 0 0 1 4, press 2.
To cancel this transaction, press the cancel key.

When voice guidance is enabled using Supervisor message mode

Send Configuration option digit 1 and voice‐guided sessions without host update are
Information 6
being used, the host will not understand the hardware
configuration and fitness configuration information.
In this situation, the information about voice guidance is updated as
follows:
 Responses to Send Configuration Information command (code
ʹ7ʹ) and a command modifier of ‘6’ contain voice guidance
information in position 32 of fields ‘g3’ and ‘g4’. Field ‘g3’ is
updated to contain ‘0’ and field ‘g4’ is updated to contain ‘00’
 Responses to Send Configuration Information command (code
ʹ7ʹ) and a command modifier of ‘1’ contain voice guidance
information in field ‘g4’. The hardware configuration data
device identifier, ‘a’, and its associated value are removed from
field ‘g4’
 Responses to Send Configuration Information command (code
ʹ7ʹ) and a command modifier of ‘3’ contain voice guidance
information in field ‘g2’. The fitness data device identifier, ‘a’,
and its associated value are removed from field ‘g2’.
For details of Option Digit 1, refer to the APTRA Advance NDC,
Supervisor’s Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 6-79

Configuring Voice Guidance
Voice-Guided Sessions without Host Update

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

6-80 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Introducing the Advance NDC Authored Applications

Chapter 7
Introducing the Advance NDC
Authored Applications

Overview 7‐1

The APTRA Author 7‐2

Customisation Layer 7‐3

Customisation Layer Applications Catalog 7‐3
Cardholder Session 7‐5
Start from State 0 7‐6
NDC Processing State Executor 7‐6
AP Synch NDC State Processing ‐ Session 7‐7
State Types Catalog 7‐7
Card Read States 7‐7
Close State 7‐8
Suspend Mode 7‐8
Customisation Layer Catalog 7‐9
Transaction Reply Functions Catalog 7‐9
CDI ‐ <name> Catalog 7‐9
NDC Core Catalog 7‐9
NDC Transactions Catalog 7‐9
NDC Encryption Keys Catalog 7‐9
NDC Field Workers Catalog 7‐9

Application Core 7‐10

Application Core Project 7‐10
Start of Day 7‐12
Keymanager Init 7‐13
Initialise 7‐13
Start of Day Hook 7‐15
Mode Handler 7‐15
Application Core Catalog 7‐18
User Controls Catalog 7‐18
User Stores and Signals Catalog 7‐18
Synchronising with the Customisation Layer 7‐18
Session Releaser 7‐19

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Introducing the Advance NDC Authored Applications

Checking the Status of the Customisation Layer 7‐19

Mode Handling 7‐19
Message Handling 7‐21
Message Processing Director 7‐22
Message Handler 7‐24
Terminal Command Processing 7‐24
Customisation Data Processing 7‐26
Transaction Reply Command Processing 7‐27

Supervisor Mode 7‐29

Handle Switch Work Group 7‐30
Activating the Supervisor Application 7‐31
Supervisor Project 7‐31
Supervisor Mode Start‐Up 7‐33
Shared Stores 7‐34

Testing the Advance NDC Application 7‐35

Running in the PC Environment 7‐36
Generating Touch Events on a Development PC 7‐36
Running in the Author Environment 7‐37
SSDS DLL Interface 7‐37
Testing State Types and Transaction Reply Functions 7‐38
Using the XFS Simulator 7‐38
Preparing the XFS Simulator for Use 7‐38
Text Terminal Unit (TTU) 7‐38
Receipt Printer 7‐39
Simulated PINpad 7‐39
Card Reader 7‐40
Currency Dispenser 7‐40
Coin Dispenser 7‐40
Cash Acceptor 7‐41
Bunch Cheque Acceptor 7‐45
TCP/IP Configuration 7‐45
Simulating Communications 7‐45
Simulating a Passbook Printer 7‐45

Using the Command Line Utility 7‐47

The Customisation Data Database File 7‐47
Using the Custdat.exe Utility 7‐48
Exporting 7‐48
Importing 7‐49
Error Messages 7‐49

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Table of Contents
Introducing the Advance NDC Authored Applications

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Introducing the Advance NDC Authored Applications

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
G

Overview

Overview 7

Read this chapter if you want to familiarise yourself with the

Advance NDC application flow in the Author (the Customisation
Layer, Application Core and Supervisor applications).
“Supervisor Mode” on page 7‐29 also includes an overview of the
separate Supervisor application. Before Advance NDC 2.05, this
functionality was provided as part of the Application Core.
Information on how to test the applications on a development
system is provided in “Testing the Advance NDC Application” on
page 7‐35.
If you simply want to migrate your NDC+ application to Advance
NDC and use your existing (unchanged) NDC+ download, see
Chapter 3, “Migrating Existing NDC+ Applications to Advance
NDC”.
If you want to upgrade from a previous release of Advance NDC,
see Chapter 4, “Upgrading from Earlier Releases of Advance NDC”.
If you intend enhancing the Advance NDC applications, read this
chapter first, and then read Chapter 8, “Modifying the
Customisation Layer”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-1

Introducing the Advance NDC Authored Applications
The APTRA Author

The APTRA Author 7

As described in Chapter 1, “Introducing Advance NDC”, the

Application Core, Customisation Layer and Supervisor are three
projects in the Author. If you want to view or edit them, you need to
know how to use the APTRA Author. If you have the XFS Simulator
installed, you can use it to simulate devices on the development PC.
To learn how to use the Author and the XFS Simulator, refer to the
following:
 Author ‐ APTRA Author User’s Guide
 XFS Simulator ‐ APTRA Simulator, On‐line Documentation
To understand about the components, refer the On‐line Help in the
Author, which gives descriptions of the Components.

Note: On 32‐bit Windows 7 operating systems, you must install the

Windows Help program (WinHlp32.exe) as described at
http://www.microsoft.com/en‐us/download/details.aspx?id=91 to
view the on‐line help.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-2 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Customisation Layer

Customisation Layer 7

Before you can modify the Customisation Layer, you need to

understand how the application is structured.
The Customisation layer is modularised, separating the state types
and transaction reply functions into application DLLs, which are
identified and executed through application links configured in the
registry. This reduces the size of the Customisation Layer and
simplifies both maintenance and modification. The self‐contained
application DLLs can be loaded at start of day or when required.
The Customisation Layer is built as an application DLL driven by a
single executable, the Application Core.
The project file is named CustomisationLayer.mpj and can be found in
your <global>\final\support\user directory.
To access the supplied project file, start the Author and open the
CustomisationLayer.mpj project.
The project contains several catalogs (under File | Open Catalog...).
The main Advance NDC catalogs for transactions are as follows:
 Customisation Layer Applications
 Customisation Layer
 State Types (DLLs)
 Transaction Reply Functions (DLLs)
 User‐defined CDI stores (UCDIs).
Each of these catalogs is described in the following subsections.
Related catalogs are described on page 7‐9.

The Customisation Layer Applications catalog contains the

Customisation Layer Customisation Layer application, and the nested catalogs, State
Applications Catalog 7
Types, and Transaction Reply Functions, for easy reference. The
Customisation Layer application starts and finishes a session at
State 0, using the NDC Processing State Executor to load and
execute one state type internally (as a black box).
You can see the link build information for each application by
selecting an icon in the catalog, clicking right on Application
Settings and then double‐clicking Application Link Build
Information.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-3

Introducing the Advance NDC Authored Applications
Customisation Layer

The following screenshot shows the link and build information for
the Card Read States application:

Figure 7-1
Application Link Build Information

The fields have the following meaning:

Table 7-1 Field Description

Application Link and Build Information
ApplicationName The name of the application in the Author

ComponentId The unique identifier in the Author

Description A readable version of the application name

ApplicationLink The DLL name and the link name, in the registry
FileInfo under HKLM/SOFTWARE/NCR/Advance
NDC/Application Links

—DllName In the registry, the DLL name in Data value.

—LinkName In the registry, the application link in Name value

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-4 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Customisation Layer

Cardholder Session 7

In a cardholder session, every state can be executed. On completion

of a cardholder session, that is, State 0 has been reached again, the
Application Core can regain control.

Note: The Session Releaser is described in “Synchronising with the

Customisation Layer” on page 7‐18.

Before reading on, open a view of the Customisation Layer

application by doing the following:
1 Open the Customisation Layer Applications catalog.

2 Double‐click the Customisation Layer application.

3 Double‐click the Cardholder Session Director.

As well as browsing the application in the Author, you can also
browse the Component Descriptions and On‐line Help in the
Author.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-5

Introducing the Advance NDC Authored Applications
Customisation Layer

Look at the following diagram to familiarise yourself with the

Cardholder Session Director in the Customisation Layer
application:

Figure 7-2
Example of the Advance NDC Director in
the Customisation Layer

The work groups in the Cardholder Session Director perform the

following jobs:

Start from State 0 7

This work group sets the next state number to be executed by the
NDC Processing State Executor. The state processing loop is
performed until the next state number is 0, at which point the
cardholder session is complete and the application flow returns to
the Application Core.

NDC Processing State Executor 7

This worker executes a single NDC state and then signals Executed.
State Execution The NDC Processing State Executor worker loads 7

the State Type application DLL specified by the next state number.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-6 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Customisation Layer

If a Transaction Request State application DLL is loaded, it uses the

Transaction Request State worker to build and send a Transaction
Request message (such as, authorise a cash dispense) to the Central
application and receives a response (such as to dispense cash). It
then loads the appropriate Transaction Reply application DLL to
execute the function.
The Customisation Layer retains control until a Close state is
executed and the next state number is 0, at which point the
cardholder session is complete.

AP Synch NDC State Processing ‐ Session 7

If APTRA Promote is installed and Dialogs are enabled, this worker

provides an opportunity for the Presentation Client to synchronise
with the application flow.

Note: This worker is no longer required as APTRA Promote 4.0

must now be used and it does not use the Presentation Client.

This catalog contains applications for authored state type DLLs and
State Types Catalog 7

Suspend Mode. These applications use unconsumed signals to

indicate they have completed their operation and return control to
the NDC Processing State Executor. If you open one of the provided
state types and do a Signals Check, you can see these unconsumed
signals, with (Exit) attached to the end of the name.
The following subsections look at the functionality of three
applications you will find in the State Types catalog:
 Card Read States
 Close State
 Suspend Mode.

Card Read States 7

The Card Read States application DLL performs the Card Read ‘A’
state or Card Read PIN Entry Initiation ‘T’ state and completes the
following:
 Checks if the journal configuration has changed since the last
transaction. If it has changed, the appropriate journal
configuration is activated.
 Clears CDI data from the previous cardholder session.
 Enables the Card Reader device and prompts the cardholder to
enter a card.

While waiting for a card to be entered, a Session Releaser

worker monitors for mode changes (such as, go Out Of Service)
occurring in the Application Core. The Session Releaser is used
to give up control of the Customisation Layer to the Application

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-7

Introducing the Advance NDC Authored Applications
Customisation Layer

Core. However, control is only relinquished when the

cardholder session is either idle, waiting for card entry, or at
another suitable point in the application when it is safe to return
to Out Of Service Mode.

 If a cardholder session is initiated by a cardholder entering a

card into the reader, the card is read and a Financial Institution
Table (FIT) search is performed.

Any mode changes in the Application Core are delayed until the
current cardholder session is completed. The session is
completed when a Close state is executed and the next state
number is 0.
 If State ‘T’ is executed, attempts to read the card, and if
successful, prompts the cardholder to enter a Personal
Identification Number (PIN).

A cardless transaction prompts for a PIN, if track 2 data is

specified in the registry. For details, see Table 5‐39 “Cardless
Transaction Registry Entries” on page 5‐144.

 Performs any error recovery (for example, if the card read fails,
the card needs to be ejected/captured).
 Sends any unsolicited Device Fault Status messages to the
Central application.

Close State 7

This application DLL performs the following:

 Clears media from the Receipt Printer, BNA, CPM, Card Reader
and Statement Printer devices if required
 Sends any unsolicited Device Fault Status messages regarding
device activity, since completing the last transaction, to the
Central application
 Sets up the Next State Number to execute.

Suspend Mode 7

Although Suspend Mode is not a state type, it is included in the

State Types catalog for convenience. This support application DLL
performs the following:
 Handles any suspend condition which may arise with the
devices used by the terminal (for example, customer tampering).
This effectively puts the Customisation Layer out of service
before attempting to clear the suspend condition, ready for a
new cardholder session
 Displays the Out Of Service screen until either a Go In Service
command is received or five minutes have elapsed, after which
the suspend condition is cleared.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-8 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Customisation Layer

This catalog contains Advance NDC workers specific to the

Customisation Layer Customisation Layer and related DLLs.
Catalog 7

This catalog contains application DLLs for the 15 authored

Transaction Reply transaction reply functions. These applications use unconsumed
Functions Catalog 7
signals to return control to the authored flow.

The CDI ‐ <name> catalog contains Common Data Interface (CDI)

CDI ‐ <name> Catalog 7

stores. These stores represent items of data that Advance NDC

makes available as shared data (such as, configuration options and
transaction related buffers). For details of the CDI stores Advance
NDC provides, see Appendix C, “Common Data Interface Stores”.

This catalog contains all the Advance NDC workers common to

NDC Core Catalog 7

both the Customisation Layer and Application Core.

This catalog contains all authored functions for the Transaction

NDC Transactions Catalog 7

Request State and NDC Transaction Handler workers to execute a

Transaction Reply function.
The workers in this catalog are used in the Tr Reply Function work
group of the Transaction Request State and NDC Transaction
Handler workers. For details of the NDC Transaction Handler
worker, see “NDC Transaction Handler” on page 8‐20 and
Appendix B, “Advance NDC Workers Supplied”

This catalog contains the Encryption Keys used by Advance NDC

NDC Encryption Keys for Security purposes. These keys are used for PIN Verification and
Catalog 7
calculating the MAC (Message Authentication Code) in a message.

This catalog contains the NDC Field workers which are used to specify
NDC Field Workers the different optional fields that can be included in a Transaction
Catalog 7
Request message to Central. These workers would be included in
the NDC Field work group of an NDC Transaction Handler worker.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-9

Introducing the Advance NDC Authored Applications
Application Core

Application Core 7

The Application Core has three main purposes:

 To preserve the NDC message interface
 To separate the fixed part of Advance NDC (the Application
Core) from the customisable part (the Customisation Layer,
States and Screens)
 To drive the Customisation Layer (cardholder) and Supervisor
sessions.
The Application Core deals with the tasks of mode handling,
synchronising with Customisation Layer, and handling messages
from Central. The remaining sections in this chapter describe how
these functions are authored in the Advance NDC application.

Note: For details of the Supervisor Mode functionality, which is

provided in a separate Supervisor application DLL, see “Supervisor
Mode” on page 7‐29.

The sections are designed to be read in conjunction with the

Application Core project file we supply, ApplicationCore.mpj, located
in <global>\final\support\user.
First, open the ApplicationCore.mpj project in the Author.The main
Advance NDC catalogs relating to the functionality of the
Application Core are described in the following sections:
 Application Core Applications
 Application Core
 User Messages/Terminal Data Examples
 User Messages/Terminal Data Workers
 User Stores and Signals.

The Application Core Applications catalog contains the authored

Application Core Project 7

Application Core.
Open a view of the Application Core application as follows:
1 Open the Application Core Applications catalog.

2 Double‐click the Application Core application.

3 Double‐click the Application Core director and then the

AppCore director.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-10 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

Figure 7-3
Application Core Director

By browsing the application in the Author at the same time as

reading this section, you will make the most of the information. You
can also browse the Component Descriptions and On‐line Help in
the Author.
Open a view of the App Core director and familiarise yourself with
its contents in the Application Core application:

Figure 7-4
AppCore Work Group

The following sections describe the Start Of Day, Keymanager Init,

Initialise, Start Of Day Hook and Mode Handler work groups.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-11

Introducing the Advance NDC Authored Applications
Application Core

Start of Day 7

The following screenshot shows the Start of Day work group:

Figure 7-5
Start Of Day Work Group

The Start of Day Director and its subworkers perform the following
tasks:
 Initialise the Customisation Data work group:
— Put the In Service Indicators off
— Initialise or re‐load the customisation data from disk
according to the Config ID
 Configure the Journal:
— Check the printer status
— Configure the journal printer, including which mode of
journal printing is in operation
— Activate back up
 Initialise Promote:
— If APTRA Promote is installed, check whether Dialogs are
installed
— Hook for a Promote campaign
 Initialise the GBRU
— If a GBRU is installed, check each cash handler
— Reset if required
 Customisation Layer
— Check for installed devices and their status
— Configure the registry setting for the cash handler
Status Information Status information is logged for the following 7

devices: Statement Printer, Receipt Printer, Cash Handler, Envelope

Depository, Envelope Dispenser, Journal Printer, Encryptor, Card
Reader, Front Keyboard, Bunch Note Acceptor (BNA) and Cheque
Processing Module (CPM).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-12 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

Note: The receipt printer is initialised and prints a test receipt. This
pushes any receipt that has not been removed out. If the test receipt
is not removed, it will be retracted where the hardware has the
capability.
Journal Configuration Journal mode is persistent. At Start of Day, 7

the Configure Journal process checks whether a physical journal

printer is present or not. If a printer is found, the previous journal
mode is retrieved from persistent storage (pmdata file) and used. If a
printer is not found, persistent storage is checked for the previous
mode setting. If the previous mode was EJ, the journal mode is
configured for electronic journaling. If the previous mode was not
EJ, the journal mode is set to NONE.

Note: At initial boot‐up after installation of Advance NDC, the

journal mode is set to PAPER. If persistent storage is unavailable
(pmdata is corrupt or has been deleted), the journal mode will
default to PAPER or NONE depending on whether a journal printer
is present or not.

Keymanager Init 7

The Keymanager work group contains two workers: KeyManager

and OtherVendorInit.

Figure 7-6
Keymanager Work Group

KeyManager processes remote key management for NCR SSTs and

OtherVendorInit processes remote key management for other
vendors’ SSTs.

Initialise 7

The Initialise work group contains two workers: Initialise Mode and
AC Status Initialisation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-13

Introducing the Advance NDC Authored Applications
Application Core

The Initialise Mode Director performs the following initialisation

functions:

Figure 7-7
Initialisation Functions

 Check Boot Type:

— Initialisation of communications with Central (if the mode
switch is in the Normal position)
— Initialisation of printing on the journal depending on the
status of communications
 Determine Powerfail:
— System re‐initialisation based on the restart mode
— Send a Power Up message to Central
 Encryptor:
— Re‐initialisation of the encryptor if one is present
 Powerfail During Dispense:
— If Powerfail flag set, sets up note counts and performs
security trace on last dispense
 Setup no. of cassette types
— Check the value of option 76, Cash Handlers
— Set the number of cassette types for basic or enhanced cash
handling
 Initialise EJ Recurrence
— Start EJ recurrence
— Set the local EJ file size
 Initialise Web Exit
— Set up web exits
 Supervisor Mode:
— Check whether the Supervisor switch is in the Supervisor
position on start up
The AC Status Initialisation work group checks whether EJ or dual
mode is configured for the journal and enables the EJ.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-14 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

Start of Day Hook 7

This work group contains the following two hooks:

 Start Of Day Hook
 Mode Change Hook

Mode Handler 7

This work group performs the following:

 Handles changes in NDC+ modes (see below for more
information)
 Monitors and reports changes in the state of all Tamper
Indicating and Alarm sensors
 While the terminal is not in Supervisor Mode, it displays a
cycling list of the terminal’s current device‐related faults on the
Enhanced Operator Panel (if present).
The Mode Handler is authored as a Director with a fixed number of
work groups. Each work group is occupied by workers, typically in
sub‐Directors, to perform the functionality required of each of the
NDC+ modes. The work flows between the work groups are used to
handle the transitions that occur from mode to mode.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-15

Introducing the Advance NDC Authored Applications
Application Core

Figure 7-8
Mode Handler Director

Changes between modes are driven by the following factors:

 Terminal Commands (Go In Service, Go Out Of Service)
 Supervisor Mode Switch (Supervisor Entry, Supervisor Exit)
 Option digits, allowing the previous mode to be entered on
return from the current mode
 Suspend conditions being detected by the Customisation Layer
 Communications errors
 UPS signals.
Advance NDC will only enter modes based on valid transitions
from the current mode. For example, it is only possible to enter
Supervisor mode if the mode switch is moved to the Supervisor
position and the SST is idle, or the SST is Out of Service awaiting a
message.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-16 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

The following sections summarise the functionality of each of the

modes. For more information about synchronising the
Customisation Layer and Application Core, see “Synchronising with
the Customisation Layer” on page 7‐18. For more information about
mode and message handling, see “Mode Handling” on page 7‐19
and “Message Handling” on page 7‐21.
In Service Mode In Service Mode is authored as a Director, with 7

subworkers sequenced to perform the required functionality. This

worker and its subworkers perform the following:
 Correct handling of messages received with respect to mode of
operation
 Synchronisation with Customisation Layer cardholder session
activities.
Transitions can be made to the Supervisor Mode, Out Of Service
Mode, and Offline Mode work groups.
Out Of Service Mode The Out Of Service Mode is authored as a 7

Director, with subworkers sequenced to perform the required

functionality. This worker and its subworkers perform the correct
handling of messages received with respect to mode of operation.
Transitions are valid to the Supervisor Mode, Offline Mode and In
Service Mode work groups.
Offline Mode The Offline Mode is authored as a Director, with 7

subworkers sequenced to perform the required functionality for

Offline Mode. This worker and its subworkers return to correct
mode when communications are restored.
Transitions are valid to the Supervisor Mode, In Service Mode and
Out of Service Mode work groups.
Supervisor Mode This work group contains subworkers to 7

execute the Supervisor Mode of Advance NDC.

Supervisor mode is implemented in the same way as for NDC+ and
includes the following functionality:
 Activation of correct interface on entry to Supervisor Mode
 Correct handling of messages received with respect to mode of
operation
 Execution of operator selected Supervisor functions
 Return to correct mode on exit from Supervisor Mode.
Transitions are valid to the Out Of Service Mode, Offline Mode and
In Service Mode work groups.
For full details of Supervisor Mode, refer to the APTRA Advance
NDC, Supervisor’s Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-17

Introducing the Advance NDC Authored Applications
Application Core

This catalog contains Advance NDC workers specific to the

Application Core Catalog 7

Application Core.

This catalog contains the default versions of the ‘User Messages’

User Controls Catalog 7

and ‘User Terminal Data’ directors used in the Application Core.

This catalog contains the stores and signals (that is, Store workers
User Stores and Signals and Integer Signaller workers) that you are likely to need when
Catalog 7
updating User Messages or User Terminal Data. These stores and signals
should be shared from this catalog when using them in the authored
flow.
For details of the stores, see Appendix B, “Advance NDC Workers
Supplied”.
The values of the signals are important and must be maintained.

Table 7-2 Signal Value When should you use this signal?
Signal Values
Ready9 1 To return a Ready9 terminal state message.
Applies only to User Messages.

Reject 2 To return a Command Reject.

Applies to both the User Messages and User
Terminal Data.

Send Terminal 3 After setting up the Status Info CDI store with
State the terminal state message, use this signal to
send the message.
Applies only to User Messages.

Processing 4 To signal that no reply is to be sent to a new

Complete message (class or terminal command) received
from Central.
Typically used when storing a terminal
command.
Applies only to User Messages.

Send Message 5 To send a new message to Central, in response

to receiving a new message class.
Applies only to User Messages.

TC Processing 1 To send the terminal state message. Any

Complete additional data will have already been added
to the message.
Applies only to User Terminal Data.

When the Application Core activates the Customisation Layer work

Synchronising with the group, the Cardholder Session Application Link is activated. A
Customisation Layer 7
Session Releaser worker is used at various points to allow the
Application Core to regain control at appropriate times.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-18 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

Session Releaser 7

When the session is idle and awaiting card entry or in Suspend

mode, the Application Core can stop the current cardholder session
while the Session Releaser worker in the Customisation Layer is
active. In this case, the SST appears Out Of Service to the cardholder
until the Customisation Layer can be activated again.
The Session Releaser signals only when the Customisation Layer is
stopped by the Application Core if a mode change occurs (Mode
switch, OOS, Off‐line and so on).

Checking the Status of the Customisation Layer 7

The Application Core can query the status of the Customisation

Layer during a cardholder session by accessing a CDI Store worker
called Customisation Layer Status, found in the ʹCDI ‐ Transaction
Processing Flagsʹ catalog. This is used to determine if further
message processing can take place at various stages in the
application execution. This status information is not available to the
Customisation Layer directly as it is updated internally by Session
Releaser workers.
The table below shows the possible status values of the
Customisation Layer.

Table 7-3 Status Description

Customisation Layer Status Values
WAITING Waiting for a Request to be granted.

IDLE Waiting for a cardholder session to be initiated. The

Session Releaser worker is now active, allowing
control to be given up by the Customisation Layer.

PROCESSING Actually performing a cardholder session.

TRANSACTION Within the Transaction Request State; that is,

expecting a Transaction Reply or Interactive
Transaction Response (ITR) message. This value is
set by the Transaction Handler after a Transaction
Request has been sent to Central. It will be set to
PROCESSING when the Transaction Handler
completes.

The functionality that handles the changing of modes is called the

Mode Handling 7

‘Mode Handler’. The information provided in this section is for

information only. Do not modify the Mode Handler.
The way in which the Application Core transitions between modes
reflects the way in which NDC+ worked. Mode changes only occur
at specific points in the application, and the way in which a mode
change is initiated is similar for each mode.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-19

Introducing the Advance NDC Authored Applications
Application Core

Caller and Listener pairs are used to detect mode changes. The
mode to change to is assigned to the Mode Store and then the Mode
Changed Caller is activated. The Mode Changed Listener (below) is
concurrent with all activities in the current mode and so will signal
when the Mode Changed Caller is activated.
To display the following view from the Mode Handler, double‐click
Out Of Service | Out of Service (in OOS Mode) | Handle Messages..
(in OOS Mode) | Message Handler..| Check for Supervisor..(in
Receive Message) | Set Supervisor.. then Assign Return.. and Current
Mode...

Figure 7-9
Mode Handling

To display the following view from the Mode Handler, double‐click

Out Of Service | OOS Mode Change.

Figure 7-10
OOS Mode Change

The Validate Change work group contains Testers to check whether

the current mode change is valid. If it is, a Tester will signal and a

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-20 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

mode change will occur. Otherwise, no mode change occurs and the
Listener is activated to listen for another mode change. This
mechanism is used in each mode, allowing the exit to another mode
to be initiated from a single exit point.
When a valid mode change is called, all operations in the current
mode will be stopped and a mode change will occur. It is important
that a mode change should only be called when it is safe to do so. If
a mode change has to be delayed until an operation has finished, the
operation should be synchronised with the mode change. This will
ensure that the operation finishes before the current mode exits.

Note: Do not modify the Mode Handler functionality. To prevent

you from accidentally modifying the Mode Handler functionality,
its workers have been assigned to a different module from those
parts of the application you can modify. You can, however, view the
mode changes. A Mode Change Hook is called every time a mode
change occurs. There are eight Mode Change Hooks, one for each
mode.

Message handling occurs in each of the modes (except for the

Message Handling 7

Offline Mode). Message handling involves receiving a message,

processing it and then sending a response (a Ready9, Reject or
Terminal State message) to the message. The messages that can be
accepted in each mode are clearly defined and are therefore easily
processed within each mode. Any message received from Central is
processed based on the message class and current operating mode.
Message handling has been authored to allow you to extend the SST
to Central message interface to process new Message Classes and
add additional data to Terminal State messages.
To display the following view from the Mode Handler, double‐click
Out Of Service | Out of Service | Handle Messages..| Message
Handler...

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-21

Introducing the Advance NDC Authored Applications
Application Core

Figure 7-11
Message Handling

The Message Handler director handles any incoming messages received

from Central. It contains the following work groups:
 Process Pending TCs ‐ checks for pending Terminal Commands
stored in Supervisor and stores the pending commands in the
Host Message CDI store
 Message Processing ‐ processes messages from Central and
sends appropriate replies. This functionality is discussed in
more detail in the following section
 Process Pending EJ ‐ checks for pending EJ upload requests
stored in Supervisor and stores pending EJ uploads in the Host
Message CDI store
 Receive Message ‐ awaits an incoming message, while checking
for the mode switch being moved to the Supervisor position

Message Processing Director 7

The Message Processing Director processes messages from Central and

sends appropriate replies. It contains the following main work
groups:
 Process Message ‐ for the particular mode; the next section
discusses the work group for Out‐of‐Service (OOS) Messages as
an example
 Ready 9/B ‐ sends a Ready9/B message to Central
 Mode Change? ‐ checks if a mode change is required. If no
change is required, the flow goes on to wait for the next message
to be received in this mode
 Send Reject ‐ builds and sends a Command Reject or Specific
Command Reject Solicited Status Response message to Central,
and prints on the journal

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-22 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

 Send Terminal ‐ builds and sends a Terminal State Solicited

Status Response message to Central
 Send EJ Upload ‐ checks whether the electronic journal is
enabled and assesses the impact of the request before uploading
to Central
 Send EID Message ‐ builds and sends an Encryptor Initialisation
message to Central.
Note that the Message Processing Director is ‘shared’ in two work
groups. The first occurrence processes any pending Terminal
Commands, and the second processes other messages received until
the mode is exited.
Process Message The following diagram shows a view of the 7

Process Message workers for OOS Messages.

Figure 7-12
Process Message

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-23

Introducing the Advance NDC Authored Applications
Application Core

The message is processed by the appropriate work group as follows:

 Message Handler processes messages received from Central. For
details, see “Message Handler” on page 7‐24.
 Ready9, Send Reject or Send Terminal.. Pass‐thru workers ‐ when a
Ready9, Reject or Terminal State message is to be sent to Central,
a signal is sent from the Message Handler
 Mode Change ‐ work group that sets the values for the required
mode and sends a signal for a Ready9 message to be sent to
Central
 Send EJ Upload or Send EID Msg. Pass‐thru workers ‐ when the EJ
upload or an Encryptor Initialisation message is to be sent to
Central, a signal is sent from the Message Handler
 Continue Pass‐thru worker ‐ this signal is required for situations
where the Message Handler is not sending a reply to a message (for
example, exit execution).

The Message Handler functionality processes the following

Message Handler 7

messages from Central:

 Terminal Commands
 Customisation Data Commands
 Transaction Replies.
This section describes how the Message Handler processes these
messages.

Terminal Command Processing 7

Terminal Commands (Message Class 1) in Advance NDC are

processed based on the command code of the received message. The
range for the command code is 1 to ʹ?ʹ (ASCII 0x30 to 0x3F). Any
other command code outside this range is processed by the User
Messages director.

The table below shows how the Application Core responds to

Terminal Command messages, depending on the current mode. The
subsequent table defines the abbreviations used.

Table 7-4
Application Core Terminal Command
Responses

Command Power Up Out of Service Supervisor In Service Suspend

Go In Service P1 A1 A2 A S

Go Out of Service P1 A A2 A3 A

Config. ID Request P1 C C C C

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-24 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

Command Power Up Out of Service Supervisor In Service Suspend

Config. Info. Request. See Note 1: P1 D D D D

Counters Request P1 D P R R

Tallies Request P1 D P R R

Error Log Request P1 D P R R

Date/Time Request P1 D P R R

EKC Retrieve Hallmark Key. See Note 2: P1 D P R R

FREE JDATA Enable. See Note 2: P1 A A R R

Enable Image Dumping. See Note 2: P1 A A A A

Note 1: The information returned by a Config. Info. Request

depends on the Command Modifier that is used.

Note 2: These commands are not supported in Advance NDC.

Table 7-5 Ref. Response Description

Application Core Response Definitions
A Response is Ready 9 status.

A1 Change Mode to In Service. Response is Ready 9 status.

A2 Hold until Supervisor mode exited, then process. Response is

Ready 9 status. (If more than one command is received while in
Supervisor mode, only the last is recognised. The others are
dropped and no response is given.)

A3 Mode change to Out of Service when terminal is idle at the Card

Read State. Response is Ready 9 status.

C Response is a Terminal State Message containing the Config ID.

D Response is a Terminal State Message containing the requested

information.

P Hold until Supervisor mode exited and then process according to

mode entered.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-25

Introducing the Advance NDC Authored Applications
Application Core

Ref. Response Description

P1 Hold until Power Up mode exited and then process according to

mode entered. No check is made for pending messages on entry
to Supervisor or Offline modes, so the message will only be
processed on entry to Out of Service mode (unless overwritten by
a new request received in Supervisor mode).

R Response is Command Reject or Specific Command Reject. In

order to use these requests the terminal should be put Out of
Service. This is to avoid the information being updated by card
holder activity while the messages are being created.

S Hold until Suspend Mode exited and then process. Response is

Ready 9 status.

While in service, all Terminal Commands, (except for Config ID

requests) are held until the terminal is idle, and then processed.
Commands are not stacked and a new request overrides the
previous request to which no response is sent.
User Messages and User Terminal Data When the Message 7

Handler receives either an unknown message class or a request for

specific terminal state information, it sends a signal to activate the
appropriate User work group. This enables you to process new
Message Classes and add to existing Terminal State messages.

Customisation Data Processing 7

Customisation Data commands (Message Class 3, Sub‐class 1 or 3)

are processed in a similar way to Terminal Commands. The
commands are only accepted while the SST is Out Of Service or in
Supervisor mode.
Messages with sub‐class 2 are interactive transaction response (ITR)
messages. These are accepted by the terminal only in response to a
Transaction Request message, in order to obtain additional
information during a cardholder session. An ITR message received
while the terminal is in In Service mode and the Custom Layer
Status is TRANSACTION, is processed by a Transaction Handler.
The response will normally be another Transaction Request
message. Otherwise, the message is rejected (Specific Reject
Status/Qualifier ‘C04’). An ITR message received in Out of Service
or Supervisor Mode will be rejected (Specific Reject Status/Qualifier
‘C03’).
The table below shows how the Application Core responds to
Customisation Data Commands depending on the current mode.
The subsequent table defines the abbreviations used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-26 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Application Core

Table 7-6
Application Core Customisation Data
Command Responses

Command Power Up Out of Service Supervisor In Service Suspend

State Table Load ‐ A A R R

Screen/Keyboard Data Load ‐ A A R R

Config. Params Load ‐ A A R R

FIT Data Load ‐ A A R R

Encryption Key Change ‐ A A A R

Extended Encryption Key Change ‐ A A A R

Config ID Number Load ‐ A A R R

Enh. Config. Params Load ‐ A A R R

Diebold PIN Info Load ‐ A A R R

Date and Time Load ‐ A A R R

MAC Field Selection Load ‐ A A R R

Dispenser Currency Cassette Mapping Table ‐ A A R R

Override Reserved Screen ‐ A A R R

Interactive Transaction Response ‐ R R A1 A1

Table 7-7 Ref. Response Description

Application Core Response Definitions
A Accept for processing. Response is Ready 9 status.

A1 Accept for processing. Response is Transaction Request if the

Custom Layer status is ʹTransactionʹ, otherwise it is a Command
Reject or Specific Command Reject.

R Response is Command Reject or Specific Command Reject. In

order to use these requests the terminal should be put Out of
Service.

Transaction Reply Command Processing 7

Transaction Reply (Message Class 4) handling relies heavily on the

processing carried out in the Customisation Layer and should not
be altered. The complete Transaction Request/Reply mechanism is
encompassed within Transaction Handler workers to protect the
ordering of messages and their content from being erroneously
changed.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-27

Introducing the Advance NDC Authored Applications
Application Core

The first table below shows how the Application Core responds to
Transaction Reply Commands depending on the current mode. The
subsequent table defines the abbreviations used.

Table 7-8
Application Core Transaction Reply
Command Response

Command Power Up Out of Service Supervisor In Service (Tran. Req. State) In Service (not Tran. Req. State) Suspend

Print ‐ A A1 A R R
Immediate

Other ‐ R R A R R

Table 7-9 Ref. Response Description

Application Core Response Definitions
A Accept for processing. If completed successfully, response is
Ready 9 or Ready B status. If a device error occurs, response is a
device fault Solicited Status. If there is a message format error,
response is Command Reject or Specific Command Reject.

A1 If mode was entered from Out of Service, hold until Supervisor

mode exited (i.e. Out of Service mode re‐entered), then process
as A. Otherwise, the response is Command Reject or Specific
Command Reject.
If more than one command is received while in Supervisor
mode, only the last is recognised. The others are dropped, and
no response is given.

R Response is Command Reject or Specific Command Reject.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-28 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Supervisor Mode

Supervisor Mode 7

In Advance NDC 2.05, the Supervisor mode functions were moved

from the Application Core to a separate APTRA Author project
called Supervisor.mpj. The Application Core was thus reduced in
size, improving the performance of the Completeness Check and
Build Final operations.
From Advance NDC 3.03, Supervisor is an application DLL, driven
by the Application Core. When Supervisor Mode is activated, the
Application Core gives control to the Supervisor DLL.
Supervisor Common Data Interface (CDI) stores are listed in the
“Supervisor” section in Appendix C, “Common Data Interface
Stores”. Shared stores are listed under heading “Shared Stores” on
page 7‐34.
The next sections of this chapter should be read in conjunction with
the following project files:
 Supervisor.mpj
 ApplicationCore.mpj
These files are in <global>\final\support\user.
By browsing the application in the Author at the same time as
reading this section, you will make the most of the information. You
can also browse the Worker Class Help by right‐clicking on any
worker and selecting Help.
The following diagrams are for illustration purposes only; you will
gain a more complete and up‐to‐date understanding of the
provided Application Core and Supervisor projects by browsing
through them yourself.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-29

Introducing the Advance NDC Authored Applications
Supervisor Mode

The following diagram illustrates the Handle Switch work group in

Handle Switch Work the Application Core.
Group 7

Open the ApplicationCore.mpj project in the Author, then select

Advance NDC | Initialise Mode | Handle Switch.

Figure 7-13
Application Core Handle Switch

The Application Core activates a Supervisor session.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-30 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Supervisor Mode

The following diagram illustrates how the Supervisor Application is

Activating the Supervisor activated from the Application Core (App Core | Mode Handler |
Application 7
Supervisor | Supervisor Mode).

Figure 7-14
Activating the Supervisor Application

In activation of the Supervisor Application, notice that:

 Voice guidance is checked and enabled and then Supervisor
Mode is entered
 Message and Diagnostics handling are started concurrently with
Supervisor Session
 The Diagnostics Handler waits for diagnostics to be selected in
the Supervisor before acquiring diagnostics and releasing the
consumer resource. When diagnostics are complete, the
diagnostics are released and the consumer resource is
re‐acquired.

The following diagram illustrates the Supervisor Application

Supervisor Project 7

authored project.
Open the Supervisor.mpj project in the Author, and then a view of
the Supervisor Application.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-31

Introducing the Advance NDC Authored Applications
Supervisor Mode

Figure 7-15
Supervisor Project

In the Supervisor Application authored project, notice that:

 The Supervisor Application acknowledges to the Application
Core that it has started, using a Caller
 The Supervisor then performs any required initialisation, such
as setting up communications, and initialising CDI stores
 On Supervisor entry, Supervisor Mode is executed (see the
following Supervisor Mode Start‐Up sub‐section).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-32 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Supervisor Mode

Supervisor Mode Start‐Up 7

The following diagram illustrates the Menu Control in Supervisor

Mode Start‐Up:

Figure 7-16
Supervisor Mode Start-Up

In Menu Control, notice that:

 No message handling is performed
 Mode monitoring is performed here.
 The Mini Self‐Service Assistant (referred to as MAST) is run
here, providing access to vendor‐dependent mode (VDM)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-33

Introducing the Advance NDC Authored Applications
Supervisor Mode

To enable data to be shared between the Application Core and the

Shared Stores 7

Supervisor application, the following stores are shared stores:

Table 7-10
Shared Stores

Previous Previous Current Current Current

Store Name
Store Type Worker ID Store Type Worker ID Shared/CDI Store

Do Not Reset Comms Integer Store 2r2738r24 Sharable 6n2299dc125 Shared

Flag Integer Store

Supervisor Boot Integer Store 5r2301r22 Sharable 18n2299dc125 Shared

Integer Store

Offline Return Mode Integer Store 5s846g101 Sharable 20n2299dc125 Shared

Integer Store

Message Processing Flag Integer Store 2p8d1 Sharable 4r633ichl21 Shared

(renamed Supervisor Integer Store
Message Processing Flag)

Supervisor Entry Integer Store 0n622dc4 Common Data 28r633ichl21 CDI

Message (pending) String Store

Supervisor Exit Message Integer Store 5n578dc4 Common Data 31r633ichl21 CDI
(pending) String Store

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-34 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

Testing the Advance NDC

Application 7

Advance NDC in conjunction with the XFS Simulator allows

authored applications to be run in a simulated development
environment.
If you have the XFS Simulator installed, you can use it for testing on
a development PC. For example, if you want to run a test
application for the Customisation Layer from the
CustomisationLayer.mpj Author project, you can run the Application
Core, which runs the Customisation Layer and Supervisor
applications as DLLs.
You need to configure all the SST devices you want to simulate on
the PC. For details of configuring the communications connection,
see “Simulating Communications” on page 7‐45.
Advance NDC applications can be run on a development PC in two
ways:
 Running from within the Author using the Start command on an
application icon is called “running in the Author environment”.
The Author application controls the application context such as
path and exception handling.
 Starting the applications from Windows Explorer or a command
prompt is called “running in the PC environment”. The
application runs in the context of the development PC,
including path and exception handling.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-35

Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

Figure 7-17
Advance NDC Test Environment:
Directory Structure

There are two important environment variables:

%MAPS_GLOBAL% The directory where the development environment

is installed. This is set by the installer. The default is
\Nyctalopia.

%ANDC_PATH% The directory where the runtime application is

loaded when an application is executed outside the
author environment. The default is
%MAPS_GLOBAL%\final\XFS\dll.
This is embedded in the PATH environment
variable by the development environment installer.

In the PC environment, the applications can be run from Windows

Running in the PC Explorer or a command prompt. By default, the application
Environment 7
windows are full size and cannot be resized. To run the applications
in a smaller resizable window, create a system environment variable
APTRA_FINAL_RUNTEST=1. This will start the applications in a
smaller window and all NDC screen displays will be drawn in the
top left corner of the screen independently of the applications.
The DLL path used is %MAPS_GLOBAL%\final\XFS\Dll

Generating Touch Events on a Development PC 7

On a development PC, the ShowMousePointer registry entry can be

used to access touch‐screen keys. When Advance NDC is installed

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-36 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

on a development PC, touch‐screen key areas are enabled by default

(ShowMousePointer is set to 1) and they can be selected by clicking
on them using the mouse.
 On 32‐bit Windows 7, the ShowMousePointer registry entry is
under the HKLM\Software\NCR\Advance NDC\ScreenDisplay
 On 64‐bit Windows 7
HKLM\Software\Wow6432Node\NCR\Advance NDC\
ScreenDisplay registry keys.

On 64‐bit Windows 7
HKLM\Software\Wow6432Node\NCR\Advance NDC\
ScreenDisplay

The registry entry is installed by the Advance NDC Tools

component.

Testing within the Authored environment allows developers to ‘see’

Running in the Author the flow of execution of an application while developing it. The
Environment 7
Authored environment also gives extended error information and
access to help. The application windows can be resized to allow
easier access to other applications on the desktop. The Supervisor
project is too large to run in the Author environment but
Customisation Layer state types and transaction reply functions can
be tested.
To start an application in the Author:
1 Open the application from the catalog to create a new
workspace.

2 Select Options | Fast Start Enabled. If this is not selected, the

applications will not run in the test environment.

3 Right click on the blue application to select Start.

On initialisation, the application creates a resizable window.
Depending on what is being displayed in the workspace, red
hatching will indicate the currently active work group.

Note: If the application fails to run, a message prompts you to build

a worker factory as the application contains workers that are not
part of the default worker factory supplied.

For more information, refer to the APTRA Author User’s Guide.

The Author supports the test runtime environment only; the files
referenced are located in %MAPS_GLOBAL%\test\XFS\Dll, and
requires access to libraries in %MAPS_GLOBAL%\test\XFS\Lib
when building a worker factory.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-37

Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

SSDS DLL Interface 7

You can also use an SSDS DLL Interface worker to run the
applications within the test environment. This can help improve
performance if you want to simulate the entire product. Set the DLL
Name attribute of the SSDS DLL Interface worker to the final build
DLL of the application under test. For more information about the
SSDS DLL Interface worker, refer to the Author help.

Testing State Types and Transaction Reply Functions 7

To test an individual state type or transaction reply function in the

Author, create a test application in a new catalog using a
Customiser Data Initialiser worker as the first worker, and specify
the state parameters by setting the appropriate CDI State
Information as required. This lets the state type or transaction reply
function be tested as a unit.

The XFS Simulator provides full simulation of the service providers

Using the XFS Simulator 7

and hardware and does not require APTRA XFS to operate. It is

only accessible through the CEN‐XFS interface.

Preparing the XFS Simulator for Use 7

When the XFS Simulator is run for the first time, it prompts you to
import default ATM and Media definitions. After these have been
imported, some adjustments are required to simulate the
applications successfully.

Caution: Applications developed in the test environment must always be

tested fully on an SST before being used in a live environment.

Vendor‐Dependent Mode (VDM) VDM is not supported in the 7

XFS Simulator and Advance NDC will hang if option 7,

“Diagnostic”, is selected on the Supervisor Select menu.
To ensure that Advance NDC offers to close down the PC in this
situation, set the following registry entry to 1:
HKLM\SOFTWARE\NCR\Advance NDC\VDMSupported

If you select No when asked whether you want to close down the
PC, you are returned to the Select menu.

Text Terminal Unit (TTU) 7

To ensure the simulated TTU displays the Supervisor screens

correctly, set the “CR inserts NL” flag on. This setting can be found
in the TTU Simulated Device Editor (SDE) by selecting Capabilities
| Standard. The Simulated TTU service will hang if the Enter key is
pressed without entering any data. It is easier to use the front

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-38 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

interface on the development PC for Supervisor. In this case, do not

include the TTU in the simulated SST.
To set the forms path for TTU screens, select Capabilities |
Standard and browse to C:\Program Files\NCR
APTRA\Printing\TTU\Forms.

Receipt Printer 7

The receipt forms and media paths must be set to match the
Advance NDC installation location. To set the paths, complete the
following steps:
1 Open the SDE for the receipt printer and select Capabilities | Device
Capabilities

2 Select the Capabilities 2 tab to view the form and media files
section

3 Use the Browse buttons to set the paths as follows:

Forms:
C:\Program Files\NCR APTRA\Printing\Receipt\Forms
Media:
C:\Program Files\NCR APTRA\Printing\Receipt\Media

Simulated PINpad 7

The simulated PINpad must be set to report a different vendor, as

the default behaviour for NCR hardware requires further
configuration steps to be carried out, which are not required in the
simulated environment. Complete the following steps:
1 Open the SDE for the “Encrypting PINPad EPPB” (PINpad1)
and in the left‐hand pane, select Responses.

2 Open the response details for the

WFS_INF_PIN_CAPABILITIES command and select the
output button.

3 Change the Vendor key to the value Other or any value other
than NCR.

4 Change the Encryptor key value from EKC to BAPE.

5 On the Capabilities | Service Registration page, change the

“vendor name value” to Other or any value other than NCR.

6 Save the property values.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-39

Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

Ensure that for the PINpad device capabilities, the default encryptor
state is WFS_PIN_ENCREADY before simulation proceeds.
These updates will take effect when the simulation is closed, then
restarted.

Card Reader 7

The Card Reader may not be enabled due to a problem in the XFS
Simulator. This can be solved as follows:
1 Open the SDE for the card unit and select Device Capabilities | XFS
3.02 Caps/Dip Card Config to display the card configuration tab.

2 Deselect the bFluxSensorProgrammable checkbox.

3 Restart Advance NDC.

Currency Dispenser 7

The Advance NDC currency mapping table in the registry has to be

updated to reflect the default configuration in the XFS Simulator.
Updating the ‘CurrencyID’ field in each of the NDC Types to USD
ensures that money can be dispensed during the application
simulation. For more information, see “Configuring Cash
Handlers” on page 5‐267.
The alternative is to edit the Cash Units tab in the Currency
Dispenser Device Capabilities SDE and change the ‘cCurrency’ field
to GBP.

Coin Dispenser 7

The Simulator must be configured to emulate the coin dispenser, as

follows:
1 On the list of devices in the XFS Simulator, select RS232 coin
dispenser to include the device.

2 Open the SDE for the coin dispenser and select Device Capabilities |
Cash Units to see the current currency (cCurrencyID) and value
(ulValue) settings for a hopper (Chute).

3 Edit the fields as shown in Table 7‐11.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-40 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

Table 7-11 Chute cCurrencyID ulValues

Coin Dispenser Simulator Settings
1 USD 10

2 USD 20

3 USD 50

4 USD 100

5 USD 10

6 USD 20

7 USD 50

8 USD 100

4 From the Capabilities option on the Standard Capabilities tab, select

“bItemsTakenSensor” and edit “wMaxDispenseItems” by
entering the maximum dispense in the Unit Limits text box.
Set up the XFS Simulator to generate eight removal or insertion
events simultaneously with the RS232 coin dispenser device as
follows:
1 Open the Simulator Console, and select Scripting.

2 Select New and name the new script “Remove Canister” or

“Insert Canister” as appropriate.

3 Start recording and go to the coin dispenser IDE.

4 Select Device | Failures | Physical Cassette x ‐ Chute 1, and then

select the following:
— WFS_CDM_STATCUMISSING for removal
— WFS_CDM_STATCUOK for insertion.

Repeat this for each of the hoppers, replacing x with the hopper
type.

5 Stop recording.

6 Update the status of all hoppers from missing to low.

To simulate removal or insertion, click right on the appropriate
script, select Play with the ‘Zero all playback timing delays’
checkbox selected, and select OK.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-41

Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

Cash Acceptor 7

Set the value of the following registry entry as described in

Table 7‐12 “Logical Names for Cash Acceptors”:
HKLM\SOFTWARE\ActiveXFS\CashInModule1

Table 7-12 Device NCR Device Value Data (Logical Name)

Logical Names for Cash Acceptors
Cash acceptor BNA CashInModule1

Cash acceptor with GBNA BillAcceptor1

configurable cassettes

Recycling unit GBRU BillAcceptor1

Bunch Recycling BRM BRMAcceptor1

Module

The Simulator must be configured to emulate a cash acceptor. For

example, to configure the Simulator to emulate a BillAcceptor1,
complete the following steps:
1 Open the SDE and select Device Capabilities to see the current
settings.

2 Ensure that the fields from the Capabilities option on the Standard
Capabilities tab are as shown in Table 7‐13, “Cash Acceptor
Capability Settings” below.

Table 7-13 Capability Behaviour

Cash Acceptor Capability Settings
wClass WFS_SERVICE_CLASS_CIM

fwType WFS_CIM_SELFSERVICEBILL

wMaxCashInItems 100

bShutter TRUE

bShutterControl TRUE

bSafeDoorUSD FALSE

bCashBox FALSE

bRefill FALSE

fwMaxIntermediateStacker 100

bItemsTakenSensor TRUE

bItemsInsertedSensor TRUE

fwRetractTransportActions WFS_CIM_NOTSUPP

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-42 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

Capability Behaviour

wRetractStackerActions WFS_CIM_NOTSUPP

Shutter status reporting TRUE

Position status reporting TRUE

Transport status reporting TRUE

Transport items status reporting TRUE

Maximum notes per sub‐cashin 0

3 Select the Specials tab and check the settings as follows:

— To simulate support for the ECB 6 regulations, ensure that
the Categorisation Mode option is set to “1,2, 3 and 4”.
— If you do not require support for the ECB 6 regulations, set
this option to “1 and 4”.

4 Select Responses | Device Commands | WFS_INF_CIM_CAPABILITIES and

add a new response in the Output property. New responses are
added as vendor data strings. The settings are described in
Table 7‐14, “Cash Acceptors Output Settings” on page 7‐44.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-43

Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

Table 7-14
Cash Acceptors Output Settings

NCR Device Vendor Data String

GBRU
(recycling)

GBRU (deposits NUMDEVICES=1\00\DEVICE1=UID=120,DEVNAME=NACC‐01‐GRBU,DEVVAR=128\

or cash in/cash 00FirmwareVersion=AA55,TE0104\00\00
out )

GBXX2 NUMDEVICES=1\0DEVICE1=UID=120,DEVNAME=NACC‐01‐GBRU,DEVVAR=137,
DEVSN=010109061307\0FirmwareVersion=CC09,TE0908\0

GBNA NUMDEVICES=1\
00DEVICE1=UID=120,DEVNAME=NACC‐01‐GRBU,DEVVAR=9\
00FirmwareVersion=AA55,TE0104\00\00

BNA3 NUMDEVICES=1\
00DEVICE1=UID=166,DEVNAME=NACC‐01‐USBVUNCH,DEVVAR=1\
00FirmwareVersion=4,T003 ,G002,,,,\00\00

BNA2 NUMDEVICES=1\00DEVICE1=UID=100,DEVNAME=NACC‐01‐RS232Bunch,DEVVAR=1\
00FirmwareVersion=T027 ,CBV DSP:08H000000000000000000000\00\00

BNA1 NUMDEVICES=1\00DEVICE1=UID=100,DEVNAME=NACC‐01‐RS232Bunch,DEVVAR=1\
00FirmwareVersion=2, V003 ,003 ,E005 ,007 ,009 ,007 \00\00

SDM DEVICE=1=UID=173,DEVNAME=DPM_‐01‐USBScalableDeposit,DEVVAR=2\00\00

BRM (recycling) NUMDEVICES=1

DEVICE1=UID=194,DEVNAME=NACC‐01‐USBBunchRecycler,DEVVAR=0,
FirmwareVersion=U0725,L0725,C0630,C0630,C0630,C0630,C0630,D0717,990B,TST00009032,
0103,0000,990B,0102,000A,0108

To simulate support for the ECB 6 regulations, add an Output with

an additional key, “P6”, with one of the following values:

 If suspect notes are to be returned to the customer, “1”

 If suspect notes are to be handled as defined in the
Cat3StoragePolicy entry of the GBXX configuration file, “0”.
For details of the GBXX configuration file, see “GBXX Cassette
Configuration” on page 5‐388.

Note: The value must match the settings in the Cat 3 Storage Policy and
Category 3 Rollback properties on the Specials tab from Device Capabilities.

For example, for a GBRU configured for deposit or cash in/cash out
transactions, the Output is as follows:
P6=1\00NUMDEVICES=1\
00\DEVICE1=UID=120,DEVNAME=NACC-01-GBRU,DEVVAR=128\
00FirmawareVersion=AA55,TE0104\00\00

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-44 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

Bunch Cheque Acceptor 7

On the development PC, the logical name of the Item Processing

Module (IPM) in the APTRA Simulator must match the value
entered in the following registry setting:

HKLM\SOFTWARE\ActiveXFS\ItemProcessing1

TCP/IP Configuration 7

All forms have been moved to the C:\Program Files path. The forms
directory must be changed in the TTU SDE by selecting Device
Capabilities | Forms Directory and browsing to the C:\Program
Files\NCR APTRA\Printing\TTU\forms directory. After changing
this setting, the XFS Simulator must be restarted.

To simulate communications on a development PC, you need to

Simulating configure Advance NDC and the communications service for
Communications 7
TCP/IP. For details, see “Configuring Communications” on
page 5‐44.
Advance NDC provides an NDC Comms Connection ID worker,
which determines the communications used from the registry
settings.

Note: As PCCM is proprietary software of NCR, it is not supported

by the APTRA Simulator.

In the test environment, the application can be run in the

Application Core.

After you have developed an authored flow for a passbook printer,

Simulating a Passbook you can test your build in the XFS Simulator.
Printer 7

When preparing a test flow, ensure the flow starts with an assigner
in a work group of its own. Have the assigner call the external C
function, OOXFSInitialise(). This ensures the SP sessions are opened
and initialised properly.
The XFS Simulator must be configured as follows:
1 Ensure the PIN SP Encryptor value is configured as described in
“Simulated PINpad” on page 7‐39

2 For the passbook SP, set the following:

a On the second Capabilities screen, update the form and
media file paths as follows:
— C:\Program Files\NCR APTRA\Printing\Passbook\Forms
— C:\Program Files\NCR APTRA\Printing\Passbook\Media

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-45

Introducing the Advance NDC Authored Applications
Testing the Advance NDC Application

b In the Simulator DMC window, highlight passbook and

select the Media button on the menu bar. When the default
passbook definition is displayed, update it as shown in the
following screenshot.

Figure 7-18
Simulated Passbook Printer Setup

The Simulator Trace feature can help with the investigation of

problems. You can also use Debug Log, and the OOXFS window
provides a trace of the interaction with XFS.
For more information about the passbook printer worker classes,
refer to the worker class help in the Author.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-46 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Using the Command Line Utility

Using the Command Line Utility 7

Custdat.exe is a command line utility that allows access to the

customisation data database, which by default is custom.dat. The
customisation data database stores the download data sent from the
host.
You can use the custdat.exe utility to do the following:
 Export the custom.dat file

Once exported, the data can be viewed, analysed, or used in a

test environment.
 Import the custom.dat file

The data can be imported to modify the content of the custom.dat

file, for example, to set up test environments. Do not use the
import to adjust a live environment. Changes to a live
environment should be made using downloads or local
customisation data.

The custom.dat file is created by Advance NDC after the host sends
The Customisation Data the following in order:
Database File 7

1 Customisation data download

2 Send Configuration ID message

3 Go In Service command.
The custom.dat file contains the following:
 Screens and keyboards. This includes all screens and keyboards
downloaded by the host, including any downloaded reserved
screens.

Note 1: Reserved screens that are not downloaded by the host

are stored in the local resrvd.def file. The screens in the resrvd.def
file are not copied to the custom.dat file.

Note 2: Although keyboards can be downloaded by the host,

Advance NDC does not support these keyboards.

 States. This includes all state definitions downloaded from the

host.
 FITs. This includes all FIT definitions downloaded from the
host.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-47

Introducing the Advance NDC Authored Applications
Using the Command Line Utility

To start the custdat.exe utility, enter custdat, or custdat.exe at the

Using the Custdat.exe command line alone or with appropriate options, as described in
Utility 7
“Exporting” and “Importing”.
When the utility is run without an option or with the -help or -?
options, a help screen is displayed.

Exporting 7

The custom database file can be exported using the following

command:
custdat custom_file

This exports the custom database file, custom_file, to the standard

output. By default standard output is sent to the screen, but it can be
redirected to a specified file. For an example of redirecting the
standard output, see “Error Messages” on page 7‐49.
Further options can be used, as shown in Table 7‐15. If options are
used, the command is as follows:
custdat [options] custom_file

Table 7-15 Option Description

Custdat.exe Export Command Options
‐export The optional export command

custom_file The name of the custom database file to export.

The data is exported to standard output by default., to
redirect the data to a file, see “Error Messages” on
page 7‐49.

‐merge N The optional merge command to specify the number of

screens, states, or FITs to include in each message.
The default is 1, which means that each screen, state, or
FIT is transformed into a single message.
This option can be used with either format.

‐size S The optional size command to specify the message size.

The default size is 600 characters.
This option can only be used with the NDChost format.
The maximum message size supported by the ndchost
format is 9999 characters.

‐ndc Sets the export format to match that used by the host.
This is the default format.
The length of the line is not restricted when using this
format, so the -size option has no effect.
The exported data contains comment lines, which start
with the ‘#’ character.

‐ndchost Sets the export format to match that used by the

NDCHost Emulator tool, which is supplied with
Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-48 APTRA Advance NDC, Developer’s Guide

 Introducing the Advance NDC Authored Applications
Using the Command Line Utility

Importing 7

The file can be imported using the following command:

custdat -import import_file custom_file

This command imports the file called import_file to the custom

database file, custom_file.
Only the NDC format is supported when importing to the custom
database file.

Error messages are sent to the standard error stream. By default, this
Error Messages 7

is the screen.
If you want to capture error messages in a file along with the
standard output from an export, enter the following command:
custdat custom.dat >log.txt 2>&1

In this example, standard output is redirected from the screen

(using the ‘>’ command) to the log.txt file, and the error messages
(identified by the ‘2’) are also redirected (again using the ‘>’
command) to the log.txt file (identified by the ‘&1’).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 7-49

Introducing the Advance NDC Authored Applications
Using the Command Line Utility

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

7-50 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Modifying the Customisation Layer

Chapter 8
Modifying the Customisation Layer

Overview 8‐1

Modification Options 8‐2

Level 1 Customisation 8‐2
Level 2 Extensions and Enhancements 8‐3
Methods of Enhancing the Customisation Layer 8‐3

Before Modifying the Customisation Layer 8‐4

Customisation Guidelines 8‐4
Impact of Changing the Customisation Layer 8‐5
Compatibility Considerations 8‐5
Reserved screens 8‐5
User IDs 8‐6
Component IDs 8‐6
Documenting Changes 8‐6
Documenting Director Changes 8‐7
Documenting Signal Changes 8‐7
Preparation Guidelines 8‐7

Level 1 Modification Example 8‐10

Journal Level Trigger Value 8‐10
Journaling Examples 8‐11
Default Journaling Configuration 8‐11
Printing Only to the EJ 8‐12
Suppressing All Journal Data 8‐12

Level 2 Modification Examples 8‐13

Replacing State Types with Workers 8‐13
Exiting the State Executor 8‐14
Executing an Authored Exit 8‐15
Returning to State Execution 8‐15
Setting the CDI Stores Used in a Transaction Request 8‐15
Editing State Types Authored in Advance NDC 8‐16
Creating New State Types 8‐16

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Modifying the Customisation Layer

Transaction Request/Reply 8‐18

Before Modifying the Transaction Request/Reply 8‐18
Adding Data Fields to a Transaction Request 8‐18
New Function IDs in a Transaction Reply 8‐19
New Printer Flags in a Transaction Reply 8‐20
NDC Transaction Handler 8‐20
NDC Fields and CDI Stores 8‐20

Testing the Customisation Layer 8‐26

Extending the Runtime Application 8‐27

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
H

Overview

Overview 8

In Advance NDC, you can customise an Advance NDC application

by modifying the Customisation Layer, Supervisor and Application
Core applications.
This chapter describes how to:
 Make changes to the Customisation Layer. Remember that
making changes only to the Customisation Layer means that
your application will maintain compatibility with NDC
messages.
 Add new data fields to a Transaction Request, and process new
Function IDs and Printer Flags in a Transaction Reply; see
“Transaction Request/Reply” on page 8‐18.
Bear in mind that any enhancement or extension you make using
the Author will have to be reapplied to future releases of and service
pack updates for Advance NDC. Therefore, design your
implementation to have minimum impact on the supplied authored
application, and document your changes. For more information, see
“Impact of Changing the Customisation Layer” on page 8‐5.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-1

Modifying the Customisation Layer
Modification Options

Modification Options 8

Advance NDC uses both authored workers and NDC+ State Types
and screens and therefore the Customisation Layer can be modified
at two levels as follows:
 Level 1 ‐ Customisation using standard NDC+ State Types and
Screens download and modifying default values set in authored
workers
 Level 2 ‐ Extending and enhancing Advance NDC using Exits
and hooks.
The following diagram shows how these modification levels allow
you to evolve away from the NDC+ programming model of States
and Screens.

Figure 8-1
Modification Levels

If you want to use Level 1 modifications, for example to tailor the

Level 1 Customisation 8

user interface, use the NDC+ customisations such as screen

downloads. For more information on States and Screens, refer to the
APTRA Advance NDC, Reference Manual.
If you want to change the values set for a worker’s attributes in the
Author, see “Level 1 Modification Example” on page 8‐10, which
shows how to change the attribute values for Journal Page workers.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-2 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Modification Options

Use the Author to include Level 2 modifications, such as the

Level 2 Extensions and following:
Enhancements 8

 C Exits
 External C functions
 Exit hooks
 Web Exits
 Authored Exits.
For more information, see Appendix G, “User‐Configurable States”
and refer to the publication APTRA Advance NDC, Extending the
Product.

If you want to replace some of the State Types with Exits or workers
Methods of Enhancing the or add new authored transactions, modify the Customisation Layer.
Customisation Layer 8
If desired, you could replace all State Types in your Customisation
Layer with Exits or worker hierarchies.
Examples of changes you can make to the Customisation Layer are
provided in the “Level 2 Modification Examples” on page 8‐13.
These changes involve modifying the Customisation Layer project,
provided with Advance NDC, to create a customised application.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-3

Modifying the Customisation Layer
Before Modifying the Customisation Layer

Before Modifying the Customisation

Layer 8

This section provides important information that you should be

aware of before you enhance or extend the Customisation Layer
(level 2).

Your changes to the Customisation Layer must conform to the

Customisation Guidelines 8

requirements below, and follow the stages given in the Preparation

Guidelines section in this chapter.
The conformance requirements are as follows:
 Follow the protocol we have provided to synchronise the
Customisation Layer and Application Core applications; see
“Synchronising with the Customisation Layer” on page 7‐18.
 Save the Customisation Layer Author project
(CustomisationLayer.mpj) with a different name and back it up, so
as to avoid overwriting your changes when re‐installing
Advance NDC.
 Use a separate directory for each project being worked on, and
for each revision of each project. This enables previous revisions
to be used or tested if necessary.
 Clearly document the functionality provided in each revision.
 To avoid files being overwritten or deleted during installation of
a subsequent Advance NDC release, keep your files in your own
working directory, not in the global directory or its
subdirectories.
 Do not change or copy workers that synchronise the
applications (Caller workers), only share them.
 If you extend the NDC Message Interface by adding new data
fields to a Transaction Request or processing new Function IDs
and Printer Flags in a Transaction Reply, you need to contact
NCR to obtain unique message identifiers. For more details, see
“Compatibility Considerations” on page 8‐5.
 Any Transaction Reply Functions must finish immediately on
sending a solicited status message. This means that, after
sending the solicited status message, only flow control workers
should be used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-4 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Before Modifying the Customisation Layer

As long as you modify the Customisation Layer we provide

Impact of Changing the according to these guidelines, you can assume it will work with
Customisation Layer 8
subsequent releases of Advance NDC, but you will have to do one
of the following:
 Re‐apply your changes to the subsequent release of the
Customisation Layer
 Apply the changes required from the subsequent release of the
Customisation Layer to your Customisation Layer.
Reducing Future Work
To reduce the time you will have to spend in the future on
re‐applying your customisations, try the following:
 Develop your customisation as a separate application and call it
as a C Exit, a C function or a DLL Interface worker.
 For Authored State Types, copy the appropriate module and
apply your modification.
 Create catalogs for testing/development and workers.
 Make your work as modular as possible, with porting in mind.
 If you use an Authored Exit, refer to the publication APTRA
Advance NDC, Extending the Product for design
recommendations to help ensure portability of your Exit.

If you are extending the NDC Message Interface, you need to allow
Compatibility for future releases of Advance NDC, to remain as compatible with
Considerations 8
them as possible.
To ensure your extensions are compatible with Advance NDC,
contact NCR FSE Product Management to obtain unique message
identifiers. You need to obtain message identifiers for the following:
 Message Class
 Command Code
 Field in a message (such as a new data field in a Transaction
Request)
 Data Identifier in a message
 Function ID in a Transaction Reply
 Printer Flag in a Transaction Reply
 Device Identifier Graphic (DIG) for a new device.

Reserved screens 8

When you define additional reserved screens, remember that they

may be impacted by future Advance NDC developments.
Therefore, select numbers for them carefully.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-5

Modifying the Customisation Layer
Before Modifying the Customisation Layer

User IDs 8

User IDs form part of component IDs and must be unique.

Typically, they consist of at least 2 or 3 lower‐case letters identifying
the developer and 2 or 3 letters identifying the organization. When
using the Author, ensure that any user ID used to create new
workers is not in the list of NCR’s proprietary user IDs. For details,
refer to the APTRA Author, User’s Guide.

Note: Do not exceed 8 characters for a user ID and do not use

numeric characters or the list of restricted user IDs given in the
APTRA Author User’s Guide, Appendix E, “Reserved User IDs”.

Component IDs 8

Component IDs must be unique.

You can ensure that the component IDs remain unique as follows:
 Never share your user IDs
 Do not use any of the reserved user IDs listed in the APTRA
Author User’s Guide.

Ensure that changes are clearly documented. This facilitates easy

Documenting Changes review and comparison when making further changes or applying a
8

new release.
Always include a description of the worker. When dealing with
flags or stores, it is particularly important that you describe the
purpose, location(s) and the range of valid values. Use the
Description property of any catalogs, directors and other workers to
provide a summary of any update.
Ensure that further documentation includes at least a list of changed
workers, with the original component ID and worker name, and a
summary of the changes made. Select Components | Report to
generate a report of updated workers, catalogs, or components in
the project. You can export the resulting report into Excel and then
filter and sort on the time‐stamp and module. This lets you clearly
see all the components that have changed in a project during
particular sessions. You can also use this file to include additional
information to help document the changes.

Note: Including the worker name ensures that you can identify the
worker, even after a module copy assigns a new unique Component
ID.

NCR recommends that you also produce a document, using a

package such as Microsoft Word, to include the following:
 Application being modified

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-6 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Before Modifying the Customisation Layer

 Catalog being used

 Name and Component ID of the top worker
 Full description of the change and its purpose.
To help clearly communicate the changes in the document:

1 Take screen shots, using Alt+Print Screen

Note: Ensure that important component names are readable in

any screen shots and retain some context, such as the upper
level work groups.

2 Paste the screen shot into your document

3 Add callouts and annotations

Note: If you number the callouts, you can refer to the

illustrations in the description of the change.

Documenting Director Changes 8

Try to keep your changes within directors. This method uses the
director as a container for the update. You will also find that this
method simplifies the documentation as you only need to replace
the director.
Ensure that you include a statement covering whether the change
results in a new or updated director.

Documenting Signal Changes 8

If your changes require signals, ensure that you have identified all
that are required. After you have identified the signals, describe
them.
Try to use the logic of the containing director as much as possible to
reduce the signals required.

These guidelines assume you are familiar with using the Author,
Preparation Guidelines 8

and you have read the related documentation, and/or attended an

Advance NDC or Author course. As such they are not step‐by‐step
instructions, but stages to follow when you are preparing to make
the modifications you require. For details of the available related
documentation, see Appendix A, “Related Documentation”.
Before and during modifications, it is good practice to back up the
provided projects, and the projects you are working on.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-7

Modifying the Customisation Layer
Before Modifying the Customisation Layer

NCR recommends that you follow these guidelines when preparing

to modify elements of Customisation Layer:
1 With the required project file open, create a new module for
your development. Change the default module name you are
prompted with to an appropriate and meaningful (recognisable)
name, based on the customisation you are going to develop.

2 Set your created module as the default module. All workers and
catalogs created will be assigned to this module.

3 Create a new catalog ready for your applications, with a

meaningful name.

4 Create a new catalog ready to hold your workers, and workers

being changed, with another meaningful name.

Note: If your modifications require new worker class

definitions, you should create these in a separate module. This is
necessary as a module copy cannot copy a module containing
worker classes or literal type definitions.

5 Copy the application to be modified into your applications

catalog.

6 Open the application in your applications catalog to display its

top‐level picture.

7 Before changing a Director worker by adding a worker or work

group, share the original worker into your worker catalog. This
is useful for future releases or changes, enabling you to review
and compare changes.

8 Replace the top worker and any other Director workers you
wish to change, down to the required level. Make changes at the
Director level wherever possible, to enable easier re‐use of your
own changes, and for subsequent releases.

9 Ensure all the signals associated with the workers you have
changed are reconnected to the required workers.

10 Test the changes you have made in isolation as much as

possible, in a Unit test.

11 Perform a module copy on the catalogs containing tested

developer(s) changes into another fully functional ‘work in
progress’ application, as and when required.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-8 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Before Modifying the Customisation Layer

12 Share the top workers from the catalogs into the main flow.

Note: If changes are made to shared workers, you must ensure

that you identify all locations that use the shared workers.
Ensure that you have identified all instances of the shared
worker, even where the sharing occurs at a higher level.

13 All changes can then be tested in one or more Integration tests,

separately from a previously tested (known working)
application.

14 New functionality and updates can continue to be added in a

controlled manner, using these stage guidelines.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-9

Modifying the Customisation Layer
Level 1 Modification Example

Level 1 Modification Example 8

This section describes how to use an attribute in Journal Page

workers to restrict the amount of data that is printed to the journal
printer or EJ at different points in the application flow.

The Journal Page worker class has an attribute, Journal Level

Journal Level Trigger Trigger Value, which is used with the Journal Level and EJ Level
Value 8
values entered in Supervisor, option 35 on the Configure menu, to
provide an additional level of control on the data sent to the journal
printer or the EJ.
This attribute is an enumerated data type with the following values
a All Journal Levels
b Journal Levels 1, 2 and 3
c Journal Levels 2 and 3
d Journal Level 3
The default value is All Journal Levels, which allows all the data to
be journaled as specified by the Supervisor configuration. The other
levels progressively restrict the data to be printed. This means that
data will be journaled according to the value of the Journal Level
Trigger Value attribute. For examples of how this works, see
“Journaling Examples” on page 8‐11.
As you can set the value differently for each Journal Page worker
and the effect can be to suppress all data to the printer journal or EJ,
you have to determine the level of restriction, if any, to apply at each
place in the application flow, as follows:
1 Open a view of the Customisation Layer application, as
described in “Customisation Layer Applications Catalog” on
page 7‐3.

2 Navigate to the Journal Page worker whose attribute value you

want to change.

3 Change the value to the one you require, as shown in the table
“Data Journaling Control” on page 8‐11.

4 Save and build the application.

Note: The same procedure can be used for Journal Page workers in
the Supervisor and Application Core projects.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-10 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Level 1 Modification Example

Table “Data Journaling Control” shows what the Journal Page

worker journals, as determined by the following:
 The journal mode set in Supervisor
 The levels set in Supervisor for the journal printer and EJ
 The value of the Journal Level Trigger Value attribute.

Table 8-1
Data Journaling Control

Dual Mode JRNL Printer Only EJ Only

T JRNL Printer Level EJ Level JRNL Printer Level EJ Level JRNL Printer Level EJ Level

0 1 2 3 0 1 2 3 0 1 2 3 0 1 2 3 0 1 2 3 0 1 2 3

a J J J J J J J J J J J J J J J J

b J J J J J J J J J J J J

c J J J J J J J J

d J J J J

Table 8-2 Character Meaning

Data Journaling Table Key
T Journal Level Trigger Value (a to d as described in
“Journal Level Trigger Value” on page 8‐10)
J Journal the data (on the journal printer, to the EJ,
or both)
Empty cell Nothing is journaled

These examples show the effect of different combinations of

Journaling Examples 8

journaling values.

Default Journaling Configuration 8

This scenario has the default values for the Journal Level, EJ Level
and Journal Page worker attribute as follows:
 Journal Level = 0
 EJ Level = 0
 Journal Level Trigger Value = All Journal Levels
If f the journal mode is set to paper, journal data will be sent to the
journal printer. If the journal mode is set EJ only, journal data will
be sent to the EJ. If the journal mode is set to dual mode, the data
will be printed to both the journal printer and the EJ.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-11

Modifying the Customisation Layer
Level 1 Modification Example

Printing Only to the EJ 8

In this scenario, the values are set as follows:

 Journal Level = 1
 EJ Level = 3
 Journal Level Trigger Value = Journal Levels 2 and 3
Journal data will be printed only to the EJ. Even if the journal mode
is dual mode, nothing will be printed to the journal printer because
the journal level is lower than the value set in the Journal Level
Trigger Value attribute

Suppressing All Journal Data 8

In this scenario, the values are set as follows:

 Journal Level = 2
 EJ Level = 2
 Journal Level Trigger Value = Journal Level 3
No journal data will be sent to either the journal printer or the EJ,
irrespective of the journal mode because both levels are lower than
the value set for the ʹJournal Level Trigger Valueʹ attribute.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-12 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Level 2 Modification Examples

Level 2 Modification Examples 8

This section describes how to make the following changes to the

Customisation Layer:
 Replace NDC+ Data Entry State Types and Screens with Data
Entry and Screen workers to enhance the user interface
 Edit State Type application DLLs, such as the Card Read States,
in order to override downloaded customisation data
 Create new State Types.
Examples of how to make these changes are given in the following
sections.

You may want to replace NDC+ Data Entry State Types and Screens
Replacing State Types with with Data Entry and Screen workers (which have improved GUI
Workers 8
features) to enhance the user interface.
This is possible by exiting the State Executor based on a given State
Number and/or State Type, executing a worker hierarchy and then
returning to the State Execution based on the Next State Number.
How this is achieved is best explained with the aid of an example.
The Customisation Layer application contains an example of exiting
a State Flow to execute an authored State Type. All the state types
authored as DLLs can be seen in the State Types catalog, including
the following:
 PIN Entry States for:
— PIN Entry ‘B’
— Enhanced PIN Entry ‘M’
 Customer PIN Select ‘b’
 Cash Accept ‘>’
 MV Cheque Accept ‘w’.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-13

Modifying the Customisation Layer
Level 2 Modification Examples

Open a view of the Customisation Layer application, as described in

“Customisation Layer Applications Catalog” on page 7‐3. The
following diagram shows the NDC State Processing Executor:

Figure 8-2
NDC State Processing Executor

Exiting the State Executor 8

The NDC Processing State Executor worker executes one state and
can contain an Exit Condition Tester worker. These workers are
specific to Advance NDC and are described in Appendix B,
“Advance NDC Workers Supplied”.
An NDC Processing State Executor executes every NDC+ State Type
including State Number 0, the Card Read State, the Transaction
Request State and Close State. It has an ‘Exit condition’ work group,
which allows you to exit the State Executor based on a particular
State Number and/or State Type, checked for by adding an Exit
Condition Tester worker. The Exit Condition Tester has an Exit List
attribute to contain a list of comma separated State Numbers
followed by State Types (for example ʹ1,2,3,4,A,B,Cʹ). The following
dialog box shows an example Exit List attribute for use in the
Customisation Layer application.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-14 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Level 2 Modification Examples

Figure 8-3
Exit List Attribute for the Exit Condition
Tester

If a State Number/Type matches an entry in the Exit List attribute

(‘B’, ‘M’, ‘b’, ‘>’ or ‘w’ in the example), the Exit From Flow True
signal (which is tied to the SSDS States work flow in the application)
is produced by this Exit Condition Tester, to enable an exit to the
authored flow.

Executing an Authored Exit 8

After you have exited from the State Executor, you are responsible
for the behaviour and execution of your authored Exit.

Returning to State Execution 8

When control is passed back to the application, the NDC Processing

State Executor resumes executing NDC+ State Types, from the Next
State Number specified by the authored Exit.
If a Transaction Request is to be performed, the Transaction Request
State worker is signalled. This worker is described in Appendix B,
“Advance NDC Workers Supplied”.
If the Close State is executed, it sets up the next state number.

Setting the CDI Stores Used in a Transaction Request 8

When you enhance the Customisation Layer, by replacing NDC+

State Type Flows with Worker hierarchies, you need to write to the
correct CDI workers before using the Transaction Request State worker.
For details of CDI stores, see Appendix C, “Common Data Interface
Stores”.
If you replace all NDC+ State Types and Screens with Worker
hierarchies, you can still perform Transaction Requests. However,
you must use the NDC Transaction Handler worker to do Transaction
Requests/Replies, instead of the Transaction Request State.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-15

Modifying the Customisation Layer
Level 2 Modification Examples

For details of setting the optional NDC Fields used in the NDC
Transaction Handler worker, see “NDC Transaction Handler” on
page 8‐20.

You can use the Author to edit the State Types authored as
Editing State Types application DLLs for Advance NDC, such as the Card Read States,
Authored in Advance which is the authored version of the NDC+ Card Read State. It could
NDC 8 have been implemented as a worker class (C++ code) or an external
C function. Information, such as which tracks on the card are read,
is taken from the previously downloaded customisation data.
You can override downloaded customisation data by making
changes to the workers in the appropriate application DLL.

Note: To customise screens, use Display Manager. For details, refer

to the APTRA Advance NDC, User Guide for Display Manager.

Once you have finished your changes to a state type, complete the
following:
1 Rebuild the application DLL You can do this in one of the
following ways:
— On the Tools menu, select Build Application Links and select
the state type you have edited.
— Use the catalog pop‐up or workspace pop‐up window.

2 If you have changed the name or path of the DLL, update the
Application Links registry key. In a development environment,
you can edit the registry directly. For a runtime environment,
edit the application links in AdvanceNDC.reg to use your DLLs,
or write your own registry script to be run after AdvanceNDC.reg
during installation.

Note: NCR recommends you use your own DLL name and
build directory, to avoid overwriting the original files.

If editing an existing State Type in Advance NDC does not provide

Creating New State Types 8

the functionality you require, you may wish to create a new State
Type in Advance NDC.
If you decide you do need to create a new State Type in Advance
NDC, use the following guidelines:
1 Consider which State Types you need to add to Advance NDC,
and how they are best created/added. In particular, decide
whether they should be C Exits or Advance NDC authored State
Types. For an evaluation of each implementation method, refer
to the APTRA Advance NDC, Extending the Product publication.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-16 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Level 2 Modification Examples

2 Determine a new ‘z’ number, from 900 onwards, for your state
type.

3 Any new authored State Types should be defined as part of the

preparation in “Preparation Guidelines” on page 8‐7.

4 For an authored state type, build a new application link. You

will need an application name, an application link name and a
DLL name

5 Add the application link to the Applications Links registry key.

6 Edit the STCONT file to include your new state type, as

described in the APTRA Advance NDC, Extending the Product
publication.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-17

Modifying the Customisation Layer
Transaction Request/Reply

Transaction Request/Reply 8

In NDC+, the Transaction Request State sends a Transaction

Request message to Central, and executes the Transaction Reply
command received from Central. In Advance NDC, Transaction
Requests/Replies are performed by a Transaction Handler worker,
with each Transaction Reply Function authored as an application
DLL.
Advance NDC provides two versions of the Transaction Handler
worker:
 Transaction Request State ‐ performs the same functionality as the
NDC+ Transaction Request State
 NDC Transaction Handler ‐ allows you to specify the fields to include
in the Transaction Request message. You only need to use the
NDC Transaction Handler worker if you have replaced the NDC+
Transaction Request State with worker hierarchies. For more
details, see “NDC Transaction Handler” on page 8‐20.
Both Transaction Handler workers additionally allow you to add
new data fields to a Transaction Request, and process new Function
IDs and Printer Flags in a Transaction Reply. This involves
extending the NDC Message Interface. See the following sections for
details.
If you choose to enhance the Customisation Layer we provide, by
replacing NDC+ State Type Flows with worker hierarchies, you will
need to write to the correct CDI store workers before using the
Transaction Request/Reply mechanism. For details of CDI stores,
see Appendix C, “Common Data Interface Stores”.

If you intend extending the NDC Message Interface to add new data
Before Modifying the fields to a Transaction Request or process new Function IDs and
Transaction Request/Reply 8
Printer Flags in a Transaction Reply, remember it is important to
remain compatible with future releases of Advance NDC. For more
details, see “Compatibility Considerations” on page 8‐5.

To allow you to add new data fields to a Transaction Request

Adding Data Fields to a message, the Transaction Handler workers contain a work group
Transaction Request 8
called ‘User Data’. You can add new data fields by including String
Giver workers in this work group.

The data you supply will be inserted before any MAC (Message
Authentication Code) data. Advance NDC automatically precedes
the data with a Field Separator character, and each data string is
separated by a Group Separator.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-18 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Transaction Request/Reply

Note: The MAC Field Selection Load message has not been
expanded, so Selective MACing of the ʹUser Data’ fields is not
possible.

The Transaction Request Extension state can accommodate the

addition of new data fields to the Transaction Request message. For
details, refer to state table entry 6 in the APTRA Advance NDC,
Reference Manual.

Caution: Ensure you do not exceed the maximum length permitted for the
Transaction Request message. The maximum length will depend on
the communications protocol being used.

To allow you to process new Transaction Reply Functions in

New Function IDs in a Transaction Reply messages from Central, you need to author the
Transaction Reply 8
processing of the function in the work group of a Tr Reply Function
worker. Additionally, you need to specify the attributes for the Tr
Reply Function worker as follows:
 Tr Reply Function ID ‐ set this attribute to ʹUser Function IDʹ
when you are processing a new Transaction Reply Function
 User Function ID ‐ specify a unique Function ID for the new
function. The ID must be a single character
 Execute And Wait ‐ specify what the Transaction Handler
should do on receiving a Transaction Reply message. The
possible values for this attribute are:
— True ‐ executes the function and then waits in the
Transaction Handler for another Transaction Reply message
— False ‐ terminates the transaction.
When the Transaction Handler attempts to process the Function ID,
it checks its ‘Tr Reply Function’ work group to verify whether a
worker for this Function ID exists. If it does exist, the user function
is processed.
An example of when you may want to process a new Transaction
Reply Function is to support a third party device.
If, during a user function for a new device, a solicited/ unsolicited
status message is required for the device, you need to build and
send the status information. Typically the status information would
be retrieved using the ActiveX control for the new device.
If a user function sends a solicited status message to Central, then it
must set the Solicited Status Message Sent Flag CDI store. This is necessary
so as to inform the Transaction Handler that a solicited status
message has been sent. The Solicited Status Message Sent Flag CDI Store is
described in Appendix C, “Common Data Interface Stores”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-19

Modifying the Customisation Layer
Transaction Request/Reply

To allow you to add new printer flags to a Transaction Reply, any

New Printer Flags in a unrecognised printer flags and their associated data are placed in
Transaction Reply 8
CDI stores named:
PrinterFlag<ASCII character used for printer flag>

For example, if ʹ?ʹ were used as the printer flag, then the name of the
store would be PrinterFlag?.
When you want to print the data, you would access the appropriate
CDI store and print the data to the printer required.

You only need to use the NDC Transaction Handler worker if you have
NDC Transaction Handler 8

replaced the NDC+ Transaction Request State with worker

hierarchies.
The NDC Transaction Handler has an ‘NDC Field’ work group that is used
to specify which optional component fields are included in a
Transaction Request message. When you use this worker, it is your
responsibility to populate the ‘NDC Field’ work groups with the
CDI stores used in the Transaction Request message (for example,
Amount Buffer, Buffer A, Operation Code Buffer and Card Track 1
Data). All mandatory fields and Field/Group separators are
automatically included in the message.
We have provided a copy of the NDC Transaction Handler worker, in the
‘NDC Transactions’ catalog, which contains workers to execute all
NDC Transaction Reply functions. All you need to do is copy this
worker and specify which optional Transaction Request fields you
wish to include.
The following section details the relationship between the NDC Field
workers and the CDI stores.
For details of CDI stores, see Appendix C, “Common Data Interface
Stores”.

NDC Fields and CDI Stores 8

NDC Field workers are provided in the ‘NDC Field Workers’ catalog
for each of the optional fields that can be included in the Transaction
Request message.
To include non‐mandatory fields in the NDC Transaction Handler, place
the relevant NDC Field workers into the ‘NDC Field’ work group, in
any order. Before activating the NDC Transaction Handler, ensure that you
have written to the corresponding CDI store workers.
The NDC Transaction Handler will automatically ensure that all
mandatory fields are included, along with any Data Identifiers,
Field Separators and Group Separators. It will also include data for

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-20 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Transaction Request/Reply

the optional fields you have selected through using the NDC Field
workers.
The following table shows the relationship between NDC Field
workers and CDI stores by providing the following information:
 Field—Field in the Transaction Request message
 M/O—Whether the field is Mandatory/Optional
 NDC Field Worker—Name of the NDC Field worker
 Common Data Store—CDI store where data for the field is taken
from
 Catalog—Catalog where the CDI store worker is contained
 Field Description—Use of each field, and any other CDI stores
that influence whether a field is actually included or not.

Table 8-3
NDC Field Workers and CDI Stores

NDC Field
Field M/O Common Data Store Catalog Field Description
Worker

b M N/A Message Class. Value of ‘1’.

c M N/A Message Subclass. Value of ‘1’.

d M N/A Logical Unit CDI ‐ Terminal Logical Unit Number.

Number Configuration

MAC Machine CDI ‐ Security If the “MAC Machine Number” is not

Number six spaces, the data from this Common
String Store is included with the
Logical Unit Number as part of field
“d”.

e O Time Variant Time Variant Number. If this NDC

No. Field is specified, the Time Variant is
calculated at the time of sending the
Transaction Request, rather than
taking data from a Common Data
Store.

f M N/A Top of Receipt CDI ‐ Top of Receipt Flag.

Flag Transaction
Processing Flags

g M N/A Message Coordination Number. This

field is calculated at the time of
sending the Transaction Request,
rather than taking data from a
Common Data Store.

h O Track 2 Card Track 2 Data CDI ‐ Buffers

i O Track 3 Card Track 3 Data CDI ‐ Buffers

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-21

Modifying the Customisation Layer
Transaction Request/Reply

NDC Field
Field M/O Common Data Store Catalog Field Description
Worker

j O Op Code Operation Code CDI ‐ Buffers

Data Buffer

k O Amt. Entry Amount Buffer CDI ‐ Buffers

Field

l O Pin Buffer Buffer A CDI ‐ Buffers General Purpose Buffer A. If requested

(A) for inclusion, this Common String
Store should contain a 16 character
PIN, encrypted as specified in the FIT
table. The PIN Entry State writes to
this buffer. If the PIN Entry State is
not used, it is your responsibility to
write to this buffer.

m O GP Buffer (B) Buffer B CDI ‐ Buffers

n O GP Buffer (C) Buffer C CDI ‐ Buffers

o M N/A Data Identifier. This field will be a ‘1’ if

Track 1 Data is requested for inclusion
in the message.

p O Track 1 Card Track 1 Data CDI‐Buffers

q M N/A Data Identifier. This field will be a ‘2’ if

Transaction Status Data is requested
for inclusion in the message.

r O Transaction TSN CDI ‐ Security Last Transaction Status. If requested

Status for inclusion, this field is made up of
the data taken from all of the Common
Last Message CDI ‐ Security Data Stores indicated.
Status

Notes Last CDI ‐ Note

Dispensed Counters
Cassette 1 Count

Notes Last CDI ‐ Note

Dispensed Counters
Cassette 2 Count

Notes Last CDI ‐ Note

Dispensed Counters
Cassette 3 Count

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-22 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Transaction Request/Reply

NDC Field
Field M/O Common Data Store Catalog Field Description
Worker

Notes Last CDI ‐ Note When option 76 is set to the default

Dispensed Counters (000), the original format is used for
Cassette 4 Count Note Counts. This includes the counts
for cassettes 1 to 4 only. However,
when option 76 is set to support up to
seven cassettes (001), the counts for
cassette types 5, 6 and 7 are also
included.

Notes Last CDI ‐ Note

Dispensed Counters
Cassette 5 Count

Notes Last CDI ‐ Note

Dispensed Counters
Cassette 6 Count

Notes Last CDI ‐ Note

Dispensed Counters
Cassette 7 Count

Coins Last CDI ‐ Coin When Option 79 is set to the default

Dispensed counters (0), supporting four hopper types, this
Hopper 1 Count field reports the number of coins
dispensed from each hopper type.
However, when option 79 is set to
support more than four hopper types
(1), this field contains zeros and the
coin counts are reported using buffer
‘f’.

Coins Last CDI ‐ Coin

Dispensed counters
Hopper 2 Count

Coins Last CDI ‐ Coin

Dispensed counters
Hopper 3 Count

Coins Last CDI ‐ Coin

Dispensed counters
Hopper 4 Count

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-23

Modifying the Customisation Layer
Transaction Request/Reply

NDC Field
Field M/O Common Data Store Catalog Field Description
Worker

av O Confirmation New PIN Buffer 1 CDI ‐ Buffers CSP Data. If requested for inclusion,
CSP Present Flag the Data Identifier of “U” is included.
If the “New PIN Buffer 1 Present Flag”
is non‐zero, the data from “Customer
Selectable PIN Buffer 1” is also
included in the message.
The “Customer Selectable PIN Buffer
1” should contain a 16 character
encrypted PIN.

Customer CDI ‐ Buffers

Selectable PIN
Buffer 1

aw O Confirmation New PIN Buffer 2 CDI ‐ Buffers CSP Confirmation Data. If requested
CSP Present Flag for inclusion, the Data Identifier of “V”
is included. If the “New PIN Buffer 2
Present Flag” is non‐zero, the data
from “Customer Selectable PIN Buffer
2” is also included in the message.
The “Customer Selectable PIN Buffer
2” should contain a 16 character
encrypted PIN.

Customer CDI ‐ Buffers

Selectable PIN
Buffer 2

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-24 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Transaction Request/Reply

NDC Field
Field M/O Common Data Store Catalog Field Description
Worker

bd2 O N/A CAM Flag CDI ‐ Buffers This holds the Byte 2 of CAM flags,
and the bits are populated as
follows:
The value of bit 1 is set to 0 or 1 to
indicate whether the transaction was
performed using a contact or a
contactless card.
 Contact ‐ 0
 Contactless ‐ 1
If the transaction is performed using a
contactless card, the value of bit 2
is set to 0 or 1 to indicate the mode of
the transaction was a Magnetic
Stripe‐Like or an EMV‐Like.
 Magnetic Stripe‐Like ‐ 0
 EMV‐Like ‐ 1
If the transaction is performed using a
contactless card, the value of bit 3
is set to 1, and the 4 to 8 bits are set to
0.
When a transaction is performed using
a contact card, all the 8 bits are
set to 0.

Contactless EMV CDI ‐ Buffers This holds the EMV data of the smart
Data card used for contactless transactions.

ca O N/A Miscellaneous CDI ‐ BNA MISC Bunch Note Acceptor (BNA). If

requested for inclusion, this field is
made up of the data taken from the
Common Data Stores indicated and
from information provided by the NDC
CashAccept Service class.

cf O Buffer ‘f’ Buffer ‘f’ CDI ‐ Buffers Last Transaction Status if more than 4
coin hopper types are present. If
requested for inclusion, field ‘ce’ is
used instead of field ‘r’.
Included only if the last Transaction
Reply requested a coin dispense and
more than four hopper types are
present.
This field is repeated for each hopper
type specified within the Transaction
Reply.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-25

Modifying the Customisation Layer
Testing the Customisation Layer

Testing the Customisation Layer 8

If you have the XFS Simulator installed, you can test your changes
on the development PC. To test the applications, you need to
configure all the SST devices you want to simulate on the PC.
For details of how to configure devices, refer to the documentation
accompanying the XFS Simulator.
For details of how to configure the communications connection to
test the Advance NDC application, see “Simulating
Communications” on page 7‐45.
To simulate receiving messages from Central, you can enter all
messages into the host simulator (NDCHost Emulator) and assign
names to them. For example, you will need to enter Transaction
Reply messages to respond to the Transaction Request message sent
by the Customisation Layer.

Note: The host simulator can be used with both the IPv4 and IPv6
protocols.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-26 APTRA Advance NDC, Developer’s Guide

 Modifying the Customisation Layer
Extending the Runtime Application

Extending the Runtime Application 8

If you need to perform a task which cannot be implemented using

the Workers or NDC+ State Types we provide, there are other
programming tasks you can perform. The following table identifies
the various programming tasks available for extending the Advance
NDC runtime.

Table 8-4 If you want to.... Refer to ...

Extending the Advance NDC Runtime
Create an ActiveX Control APTRA Author User’s Guide
(B66038.pdf)

Write an external C function APTRA Advance ADE, Programmer’s Guide

or (B66042.pdf)
Create a new C++ Worker
Class

Configure new NDC+ State APTRA Advance NDC, Reference Manual

Types and Screens (B66180.pdf)

Create new Exits APTRA Advance NDC, Extending the

Product (B66926.pdf)

Migrate existing NDC+ APTRA Advance NDC, Extending the

Exits Product (B66926.pdf)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 8-27

Modifying the Customisation Layer
Extending the Runtime Application

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

8-28 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Enhancing the Application Core or Supervisor

Chapter 9
Enhancing the Application Core or
Supervisor

Overview 9‐1

Customising the Application Core 9‐2

Overview of User Messages/Terminal Data 9‐2

Before Modifying the Application Core 9‐4

Compatibility Considerations 9‐4
Preparation Guidelines 9‐4
Customisation Guidelines 9‐4

Processing a New Message Class 9‐5

Default User Messages Implementation 9‐5
Extract Message Class 9‐7
Message Selector 9‐7
Summary of Procedure 9‐7
Example User Messages Implementation 9‐8
Message Selector 9‐8
Unknown Command Code Director 9‐9
New Message Class 9‐9

Adding Additional Data to Terminal State Messages 9‐11

Default User Terminal Data Implementation 9‐11
Procedure for Adding User Terminal Data 9‐13
Example User Terminal Data Director 9‐13
Selector (Device 1) 9‐13

Processing new Enhanced Configuration Parameters 9‐15

Altering Modes 9‐16

Start of Day and Initialise Tasks 9‐16
In Service Mode 9‐17

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Enhancing the Application Core or Supervisor

Out Of Service Mode 9‐17

Offline Mode 9‐17
Supervisor Mode 9‐18

Enhancing the Supervisor Application 9‐19

Customisation without Using APTRA Author 9‐19
Customisation Using APTRA Author 9‐19

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
I

Overview

Overview 9

In NDC+, you could customise your self‐service application using

States/Screens. With Advance NDC, customisation can also be
performed by modifying the Customisation Layer, Application
Core or Supervisor.
This chapter describes how to modify the Application Core if you
want to do any of the following:
 Process new Message Classes
 Include additional data in Terminal State messages
 Process new Enhanced Configuration Parameters
 Add specific routines to the Application Core, such as the
following:
— Initialise Start Up
— Override configuration options/terminal commands

Note 1: If you plan to customise the Application Core, take into

consideration the following:

 Care must be taken to leave the core NDC+ functionality

(mode handling and existing messages) intact
 Any customisations you make will have to be re‐applied to
future service packs for and new releases of Advance NDC.

Note 2: Functionality for User Messages and User Terminal

Data is in the Application Core, not in separate ActiveX controls.

Note 3: To add a new Supervisor menu/function authored in

the APTRA Author, use the Supervisor application. For details,
see “Supervisor Mode” on page 7‐17.

If you intend modifying the Customisation Layer, see Chapter 8,

“Modifying the Customisation Layer”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-1

Enhancing the Application Core or Supervisor
Customising the Application Core

Customising the Application Core 9

The following table identifies parts of the Application Core you can
customise, and references sections for details of how to make the
changes.

Note: To accommodate some of these changes, the message

interface must be extended, requiring a change at Central.

Table 9-1
Customisable Parts of the Application Core

Customisation How?

Process a new Message Class or include additional Modify the authored flow for the Application Core
data in a Terminal State message author project for each mode as required.
See the following sections:
“Overview of User Messages/Terminal Data” on
page 9‐2,
“Before Modifying the Application Core” on page 9‐4,
“Processing a New Message Class” on page 9‐5,
“Adding Additional Data to Terminal State
Messages” on page 9‐11.

Processing new Enhanced Configuration Parameters Create and use User‐defined Common Data Interface
(UCDI) stores.
See “Processing new Enhanced Configuration
Parameters” on page 9‐15.

Add specific routines to the Application Core (for Modify the authored flow for the Application Core
example, to initialise Start Up, override configuration author project. This needs to be done with care.
options/terminal commands, or add a new Supervisor
menu/ function authored in the APTRA Author) For an example of adding a new Exit Supervisor menu
and authored Supervisor menu, see “Supervisor
Mode” on page 9‐18 and the APTRA Advance NDC,
Extending the Product publication.

The Message Handler, described in “Message Handling” on

Overview of User page 7‐21, processes the message class/terminal command. If the
Messages/Terminal Data 9
command code is outside the expected range, the Message Handler
sends an Unknown Message or Add Terminal State response to
activate the User Messages or User Terminal Data work group. The
User Messages and User Terminal Data directors handle messages
in a similar way.
Care needs to be taken to ensure you use the correct values for the
signals. The signals and their values are specified in “User Stores
and Signals Catalog” on page 7‐18.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-2 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Customising the Application Core

Note: When browsing the authored examples for User Messages and
User Terminal Data, notice how these signals are used. NCR
recommends you browse the authored examples in conjunction
with reading “Processing a New Message Class” on page 9‐5 and
“Adding Additional Data to Terminal State Messages” on
page 9‐11.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-3

Enhancing the Application Core or Supervisor
Before Modifying the Application Core

Before Modifying the Application

Core 9

This section provides important information that you should be

aware of before modifying the Application Core.

If you intend extending the NDC Message Interface to process a

Compatibility new Message Class or add additional data to Terminal State
Considerations 9
messages, your extensions must remain compatible with Advance
NDC. Therefore, you must contact NCR FSE Product Management
to obtain unique message identifiers. Examples of when you need to
obtain message identifiers are for a new:
 Message Class
 Command Code
 Field in a message (such as a new data field in a Transaction
Request)
 Data Identifier in a message
 Function ID in a Transaction Reply
 Printer Flag in a Transaction Reply
 DIG (Device Identifier Graphic) for a new device.

You must follow the general guidelines “Preparation Guidelines”

Preparation Guidelines 9

on page 8‐7 when preparing to modify the Application Core, as the

guidelines apply to any application before modification.
Before and during these guidelines, it is good practice to back up the
provided projects, and the projects you are working on.

When you make changes to the Application Core, you must save the
Customisation Guidelines 9

Application Core Author project (ApplicationCore.mpj) with a

different name and back it up, so as to avoid overwriting your
changes when re‐installing Advance NDC.
Remember: if you extend the NDC Message Interface, you need to
contact NCR to obtain unique message identifiers.
If you make changes to the Application Core, these changes will
have to be re‐applied when moving to subsequent releases of
Advance NDC, or installing service packs for Advance NDC. You
also run the risk of breaching the SST to Central message interface.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-4 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Processing a New Message Class

Processing a New Message Class 9

The User Messages director lets you add a new message class or
terminal command to the Application Core authored flow for each
mode. The User Messages director is supplied in the
ApplicationCore.mpj Author project. To find out where the User
Messages work group is used in the application flow, see “Message
Handling” on page 7‐21.
The following sections describe the default implementation of the
User Messages director in the Application Core, a summary of the
procedure for authoring a new Message Class, and an example
implementation of processing a new Message Class.

The User Messages authored flow extracts the message class from the
Default User Messages received message and processes the message accordingly. The
Implementation 9
default implementation is to reject an unknown message class or
terminal command.
The following diagram shows a view of the User Messages Director.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-5

Enhancing the Application Core or Supervisor
Processing a New Message Class

Figure 9-1
User Messages Director

To open a view of the default authored User Messages for the Out of Service
mode, do the following:

1 Open the Application Core Applications catalog and

double‐click the Application Core application.

2 Navigate to the OOS Message Handler (component ID 11l286b7)

3 Double‐click the User Messages Director.

Selector workers are used to decompose a message received from
Central. The general principle for decomposing a message is to first
look at the Message Class, followed by the Command Code,
followed by the Modifier.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-6 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Processing a New Message Class

Extract Message Class 9

Extracts the message class (the first byte of data) from the Central
message.

Message Selector 9

Activates the appropriate work group depending on whether a new

message class or a terminal command with a new command code is
to be processed.

Note: When a Selector is activated, it uses its Index work group to

decide which Doer work group to activate. For more information,
refer to the on‐line help.

The work groups are as follows:

 Convert Class ‐ Index to check whether a new message class or a
terminal command with a new command code is to be
processed. It does this by looking at the Class Range store and
comparing this with the contents of the Message Class store.

Note: To ensure that terminal commands with invalid

command codes are rejected, the value ʹ1ʹ (representing the
message class for a Terminal Command) must always be
included in the Class Range store as the first value.

 Unknown Command Code ‐ by default, this Director rejects a

terminal command with an unknown command code.
 New Message Class ‐ this Director is a placeholder for you to
author how to process a new message class.
 Invalid Class ‐ if the message class is not recognised, this
Director sets up the reject status and returns a reject signal. You
should not modify this functionality.
For an example implementation of the User Messages director, see
“Example User Messages Implementation” on page 9‐8.

To process a new message class/terminal command, complete the

Summary of Procedure 9

following:
1 Obtain the required Message Class number from NCR Financial
Software Engineering.

2 Append the class number to the Class Range store.

3 Author the relevant Director (New Message Class | Unknown Command

Code) to process the message for the required mode by adding
work groups and workers as required.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-7

Enhancing the Application Core or Supervisor
Processing a New Message Class

4 Include the Invalid Cmd Code work group, which is activated if

the command code is not recognised.

5 Whenever you want to send a reject signal, set the Reject Status
Value and Qualifier CDI store to the appropriate reject value (for
example, ‘C02’).

Note 1: If the message has to be processed differently in each mode

(for example, processed in In Service, rejected in Out Of Service, and
held for processing later in Supervisor), then the Current Mode CDI
store has to be checked and the relevant processing executed for
each mode.

Note 2: If you are processing an OOS mode message, put the

message in the Message For Host store. The format of this message is
entirely up to you provided Central can deal with the format.

NCR provides an example implementation of the User Messages

Example User Messages director to show how you could process a new message class from
Implementation 9
Central to the Terminal.
To open a view of the example implementation of the authored User
Messages, do the following:

1 Open the User Control Examples catalog.

2 Double‐click the User Messages Example.

3 Navigate down the worker hierarchy to view the Message Selector

worker.

Message Selector 9

As in the default implementation of the authored User Messages, the

Message Selector activates the appropriate work group depending on
whether a new message class or a terminal command with a new
command code is to be processed.
Here, the new message class is ‘9’ and the value of the Class Range
store is ‘19’, indicating the following:
 Terminal commands ‘1’, are processed
 A new message class of ‘9’ is processed using the second Doer
work group.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-8 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Processing a New Message Class

Unknown Command Code Director 9

Processes a new terminal command code. It contains two work

groups:
 Deformat Message ‐ breaks up the Terminal Command message
received from Central into its constituent parts for further
validation and processing. The significant fields are the
Command Code and Command Modifier
 Process Message ‐ processes the Terminal Command based on
its command code. This is discussed in the following section.
Process Message Contains three work groups: 9

 Index ‐ checks if a new terminal command code is to be

processed. It does this by looking at the Cmd Code Range store and
comparing this with the contents of the Command Code store. In
this example, the Cmd Code Range store indicates that command
codes of type ‘a’ are supported.
 Process a ‐ processes a command code of type ‘a’ based on the
current mode:
 Out Of Service ‐ fills the Status Info store with the status
information and generates a send terminal command signal
 Supervisor ‐ stores the terminal command for processing in
the next mode (that is, Out Of Service or In Service). The
terminal command is stored as follows:
— ‘Pending TC’ UCDI store is initialised
— Contents of the ‘Host Message’ UCDI store is copied to
the ‘Pending TC’ store
— ‘Pending TC Msg Flag’ is set to True to indicate there is a
pending terminal command
— ‘Stop Suspend’ Caller
— ‘Processing Complete’ signals to indicate that no reply is
to be sent to Central
 In Service ‐ stores the terminal command if a transaction is in
progress; otherwise the command is rejected
 Invalid Cmd Code ‐ if the command code is not recognised, this
work group is activated. It sets the reject code to ʹB04ʹ (Invalid
Command Code) and then returns a reject signal.

New Message Class 9

Processes messages with a Message Class of ‘9’. It contains two

work groups:
 Copy Mode to String ‐ uses an Assigner to convert the value of the
Current Mode CDI store from an integer to a local string store
named Copy of Mode

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-9

Enhancing the Application Core or Supervisor
Processing a New Message Class

 Mode Selector ‐ processes the Message Class based on the

current mode. The Convert Mode Integer Computer worker uses the
Copy of Mode local string store to select the ‘mode’ work group to
activate:
— Out Of Service: sends a new message to Central in reply to
the new message class.
— Supervisor: sends a Ready9 response to the new message
class
— In Service ‐ sends a reject response to the new message class.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-10 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Adding Additional Data to Terminal State Messages

Adding Additional Data to Terminal

State Messages 9

The User Terminal Data director lets you add additional terminal status
data to the following Terminal State Solicited Status Messages:
 Supply Counters
 Tally Information (See Note:)
 Error Log Information (See Note:)
 Hardware Configuration Data
 Supplies Data
 Fitness Data.

Note: As the sending of this information is not supported in

Advance NDC, a preconfigured default date and zero values are
returned.

The User Terminal Data director is used in the Application Core’s

authored flow for each mode. The User Terminal Data director is
supplied in the ApplicationCore.mpj Author project. To find out
where the director is used in the application flow, see “Message
Handling” on page 7‐21.
The following sections describe the default implementation of the
User Terminal Data director in the Application Core, a summary of the
procedure to add additional data to Terminal State messages and an
example implementation.

The default implementation of User Terminal Data returns a signal to the

Default User Terminal script host without adding to the Terminal State information.
Data Implementation 9

To open a view of the default version of the authored User Terminal Data
director for the Out of Service Mode, do the following:
1 Open the Application Core Applications catalog and
double‐click the Application Core application.

2 Navigate to the Message Handler (component ID 11l286b7).

3 Double‐click the User Terminal Data Director.

4 Double‐click Selector (Device 1).

The following diagram shows a view of the User Terminal Data Director.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-11

Enhancing the Application Core or Supervisor
Adding Additional Data to Terminal State Messages

Figure 9-2
User Terminal Data Director

The Status Info CDI store contains the Terminal State information (that
is, field ‘g’ of the Terminal State message). The first byte of this
information is the Message ID, which uniquely identifies the type of
status information: Counters (2), Tallies (3), Error (4), Hardware (H),
Supplies (I) and Fitness (J).
The User Terminal Data authored flow obtains the Message ID by
looking at the Status Info CDI store and comparing it with the Range
store. It then activates the appropriate work group:
 Add Counters ‐ by default, this Director simply continues
without adding any data to the terminal state message
 Add Tallies ‐ Reporting of tallies is not supported in Advance
NDC.
 Add Error Log ‐ Reporting of error logs is not supported in
Advance NDC.
 Add Hardware Config ‐ by default, this Director simply
continues without adding any data to the terminal state message
 Add Supplies ‐ by default, this Director simply continues
without adding any data to the terminal state message
 Add Fitness ‐ by default, this Director simply continues without
adding any data to the terminal state message
 Default ‐ this Director should never be needed.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-12 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Adding Additional Data to Terminal State Messages

If you want to add additional data to one or several of the Terminal

Procedure for Adding User State messages, you would author the appropriate Director to add
Terminal Data 9
the information to the Status Info store. For example, to add Fitness
Information for a new device, you would add a group separator and
then the Device ID and fitness data for the device to the end of the
Status Info store.
To add additional data to a Terminal State message, complete the
following:
1 Obtain a new identifier from NCR Financial Software
Engineering for any new device.

2 For the required mode, navigate down the worker hierarchy to

show the Selector (Device 1).

3 Author the relevant director (Add Counters, Add Hardware

Config, Add Supplies and/or Add Fitness) by adding work
groups and workers as required.

For example, to add Fitness data for a new device add a group
separator, device ID and the fitness data for the device to the
Fitness director. This is automatically added to the end of the
Status Info store.

4 If you have more than one new device, author a different

Selector to add terminal state data to each message.
For an example implementation of the User Terminal Data director, see
the next section.

The example implementation of the User Terminal Data director shows

Example User Terminal additional data to all Terminal State messages.
Data Director 9

To open a view of the example implementation of the authored User

Terminal Data director, do the following:

1 Open the User Control Examples catalog.

2 Double‐click the User Terminal Data Example application.

3 Navigate down the worker hierarchy to show the Selector (Device

1).

Selector (Device 1) 9

Like the default version of the User Terminal Data director, the Selector
(Device 1) obtains the Message ID by looking at the Status Info CDI store

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-13

Enhancing the Application Core or Supervisor
Adding Additional Data to Terminal State Messages

and comparing it with the Range store. It then activates the

appropriate work group:
 Add Counters ‐ appends additional Counter information to the
terminal state message
 Add Tallies ‐ not supported
 Add Error Log ‐ not supported
 Add Hardware Config ‐ appends additional hardware
configuration information to the hardware config terminal state
message
 Add Supplies ‐ appends additional supplies information to the
supplies terminal state message
 Add Fitness ‐ appends additional fitness information to the
fitness terminal state message.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-14 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Processing new Enhanced Configuration Parameters

Processing new Enhanced

Configuration Parameters 9

The Message Handler performs the standard processing for the

Enhanced Configuration Parameters Load message. All the
standard timers and options are processed.
If there are any new timers or options (not supported by the
standard NDC+ product) in the message, these will be put into
UCDI stores named Timer<Timer No> and Option<Option No> respectively.
You can access these stores via the Author by creating a CDI store
with its ‘Store ID’ attribute set to zero and its ‘Store Name’ set to
Timer<Timer No>/Option<Option No>.
For information on UCDI stores, see Chapter 10, “Using
User‐defined CDI Stores”.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-15

Enhancing the Application Core or Supervisor
Altering Modes

Altering Modes 9

As stated in “Mode Handling” on page 7‐19, you should not change

the Mode Handler functionality. To prevent you from accidentally
modifying the Mode Handler functionality, its workers have been
assigned to a different module from those parts of the application
you can modify.
It is possible to add functionality to each of the Modes contained
within the Mode Handler, but the utmost care needs to be taken
when making any changes.
For example, if a mode change is called while a concurrent
operation is running, the operation may not finish, thus leaving the
operation in an incomplete state. This could cause problems if the
application relies on the completion of this operation. It is therefore
important that changes introduced to a mode are done so in an
appropriate manner. This could mean inserting an operation
sequentially (with little impact) or adding a concurrent operation
that requires the overhead of synchronising with other concurrent
operations.

Note: Any changes made to a mode will need to be re‐applied

when re‐installing Advance NDC, or installing a subsequent release
or service pack.

Each of the modes follows roughly the same pattern:

 Initialisation
 Processing
 Mode change.
The easiest parts to modify, with the least impact, are at entry to and
at exit from a mode. This is because several concurrent activities
may be taking place during processing, and some method of
synchronisation is required, increasing the complexity of the
application. It is therefore recommended that changes should be
made on entry to and exit from a mode.

Any new activities added to the Start of Day or Initialise tasks must
Start of Day and Initialise synchronise their activities with the current task. Activities can
Tasks 9
either be inserted in the flow of the initialisation and executed
sequentially, or added concurrently, synchronising completion with
the main flow of the task. Inserting an activity into the flow is the
easiest to do, having the least impact on the mode.
You should determine the correct task to alter. Note that the
Initialise task checks the position of the mode switch before

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-16 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Altering Modes

progressing; also note that there is a potential for the Start of Day
and Initialise tasks to enter straight into a mode in the main Mode
Handler, based on the configuration and previous state of the SST.

In Service mode synchronises activities with the Customisation

In Service Mode 9

Layer. You should have a clear understanding of these interactions

and how any changes they make may affect this synchronisation.
There are five distinct parts to In Service mode:
1 Entry to the mode ‐ performs any initialisation and processing
of queued messages.

2 Initiating Customisation Layer synchronisation ‐ after the

Customisation Layer has started the SST can be thought of as
being ʹIn‐Serviceʹ.

3 Processing Terminal to Central Messages ‐ messages are

handled differently based on the message class and the status of
the Customisation Layer. Messages are generally processed
while the Customisation Layer is ʹIDLEʹ or ʹWAITINGʹ.

4 Suspended ‐ if Customer Tampering is detected, the

Customisation Layer will be deactivated and Suspend will be
entered.

5 Leaving the mode ‐ a mode change has occurred and the current
mode is being left. The Customisation Layer must be stopped
before the mode change can progress.
Changes can be made at any of these points with the most impact
occurring at points 3 and 4. Messages should be processed as
quickly as possible and holding up this process may affect the
running of the Customisation Layer. In Service mode is more
complicated than the others, as there are a lot of synchronisation
issues. NCR recommends that you add any In Service changes to the
Customisation Layer, as there is an already established mechanism
for the processing of a Cardholder Session.

The main activity in this mode is message processing. Configuration

Out Of Service Mode 9

Data Load and Terminal Commands can be processed, as well as

ʹPrint Immediateʹ Transaction Replies. Since you are protected from
altering the processing of these messages, any changes you make to
this mode should not interfere with these operations.

Offline mode simply waits for communications to be restored or

Offline Mode 9

Supervisor mode to be entered. As the restoration of

communications may occur at any time, any actions performed in

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-17

Enhancing the Application Core or Supervisor
Altering Modes

this mode should be synchronised with the restoration of

Communications.

Supervisor mode is your means of controlling the terminal by

Supervisor Mode 9

giving you access to a range of menus and options.

You can customise the Supervisor mode supplied with Advance
NDC either with or without the use of the APTRA Author.
Additional features are available when the Author is used. You can
incorporate additional menus (defined by user exit code or
authored additions), add new functions to existing menus, or
re‐implement functions provided.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-18 APTRA Advance NDC, Developer’s Guide

 Enhancing the Application Core or Supervisor
Enhancing the Supervisor Application

Enhancing the Supervisor

Application 9

You can modify the provided Supervisor application, or even

replace it completely by re‐authoring the application. However,
NCR recommends that where possible you customise Advance
NDC without using APTRA Author.
If using the Author is necessary, limit changes to those described
below. Other changes carry a risk of breaching the existing message
interface and mode transition protocol with the Application Core.

Text used for displaying menus and messages (acknowledgement,

Customisation without error, prompt, status and information) is contained in reserved
Using APTRA Author 9
screen groups A, E/e, I/i, M/m, P/p and S/s. You can modify this text
by editing the screen definitions in the reserved screen file, resrvd.def
(make a backup copy first), or by downloading new definitions for
the relevant reserved screens. Similarly, it is possible to modify the
text used for printing Security Trace Messages (screen group T). In
this way, you can localise text using the same methods as with
NDC+, without needing to use the APTRA Author.

If you plan to customise the Supervisor application, take into

Customisation Using consideration the following:
APTRA Author 9

 Any customisations you make will have to be re‐applied to

future service packs and updates for Advance NDC
 To maintain compatibility with NDC+, NCR recommends that
you do not modify, enhance or re‐implement existing menu
functions. In particular, you should avoid making changes to the
Select Menu Exit function, which interfaces with the Application
Core when causing a transition from Supervisor mode to
another mode.
Text from the reserved screen groups A, E/e, I/i, M/m, P/p and S/s
can be replaced by removing the Reserved Screen Retriever workers
and redefining the text in the authored application.
You can add new functions to the menus provided, by adding a
work group to the relevant Selector and placing a worker providing
the new function (typically a Director) in the appropriate work
group. The new function is normally placed in the penultimate
work group in the Selector, as the last one provides the default
functionality. When adding new functions, you should amend the
menu display text accordingly.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 9-19

Enhancing the Application Core or Supervisor
Enhancing the Supervisor Application

The menu function value is set before an Unsolicited Supervisor

Keys Status Message is sent to Central. If you wish to change the
value reported, you will have to set the new value explicitly.
You can define new menus in the same way as adding new
functions to existing menus. In turn, the new menus may have new
functions added to them.
As with adding a new Message Class or Terminal Command, you
should ensure that signals are correctly consumed by sharing the
relevant Pass‐thru worker, such as ʹTask Completeʹ.
If you use Operator Display workers and a Supervisor Data
Collector in the same work group, the Supervisor Data Collector
must be placed as the last worker to be activated. If the Supervisor
Data Collector is not the last worker, it blocks all Operator Display
operations that are activated later until the Supervisor Data
Collection is complete. This occurs because the Service Provider
processes WFS_CMD_TTU_READ and WFS_CMD_TTU_WRITE commands
sequentially.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

9-20 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Using User-defined CDI Stores

Chapter 10
Using User‐defined CDI Stores

Overview 10‐1

UCDI Service 10‐2

UCDI Initialisation File 10‐3

Persistence Levels 10‐4

Creating a UCDI Store 10‐5

Method 1 ‐ Using the UCDI Initialisation File and Stores 10‐5
Method 2 ‐ Using an Automation Object 10‐5
Method 3 ‐ Using the CreateObject Function 10‐6
APTRAUCDI Properties and Methods 10‐6

Accessing a CDI & UCDI Store 10‐9

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Using User-defined CDI Stores

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Using User-defined CDI StoresJ

Overview

Overview 10

As discussed in Chapter 1, “Introducing Advance NDC” under the

heading “User‐defined Common Data Interface” on page 1‐13, you
can create User‐defined Common Data Interface (UCDI) stores to
share data between the Customisation Layer and Application Core.
In the following sections we discuss:
 User‐defined Common Data Interface (UCDI) service
 UCDI initialisation file
 Persistence levels of CDI stores
 Creating a UCDI store.
You must ensure all UCDI stores are cleared, initialised and set by
your application, as required.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 10-1

Using User-defined CDI Stores
UCDI Service

UCDI Service 10

The UCDI is a service that automatically runs at system start‐up,

and implements new CDI stores ‐ which we refer to as User‐defined
CDI (UCDI) stores.
The UCDI service loads the UCDI initialisation file which initialises
the stores declared in the file. For details of the UCDI initialisation
file, see “UCDI Initialisation File” on page 10‐3.
The UCDI service contains an ActiveX class called ‘APTRAUCDI’,
which exposes a COM interface called ‘APTRAUSERCDI’. The class
enables access to UCDI data via an Active Script Host worker.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

10-2 APTRA Advance NDC, Developer’s Guide

 Using User-defined CDI Stores
UCDI Initialisation File

UCDI Initialisation File 10

The UCDI initialisation file is a text file named UCDIini.txt. It

contains details of all known UCDI stores and is loaded at system
start‐up.
All UCDI stores will be declared in this file as soon as they are
created (see “Creating a UCDI Store” on page 10‐5). The name, data
value and persistence indicator of the store is held in the file. The
required format for the file and an example of the file is shown
below.

Table 10-1 Format of Initialisation File Example of Initialisation File

UCDI Initialisation File Format
Name|Data|Persistence_Indicator BnaNoteCount1|32|1
Name|Data|Persistence_Indicator BnaLanguage|English|3
… SystemStartTime|07:02:12|1
… EmptyString||1
Name|Data|Persistence_Indicator

Note: Any lines in the file which do not conform to the required
format are ignored.

As the file is a standard ASCII text file, you can edit it with a text
editor thus enabling easy configuration of systems.
The ‘Name’ element represents the name of the store. Each name
element causes a new store with that name to be created. Any name
conflicts (where the name appears more than once) are resolved on
a first come first served basis.
The ‘Persistence_Indicator’ identifies the level of persistence of the
store. It can be 1 (Non‐persistent), 2 (Persistent and cannot be reset) or 3
(Persistent and can be reset). See “Persistence Levels” on page 10‐4 for
more details.

Note: Care must be taken when editing this file for persistent
stores. If you edit the data value for an existing persistent store (that
is, the store exists in persistent memory already), the value will not
be assigned to the store.

String stores can be initialised to contain an empty string.

For example, BnaLanguage||3.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 10-3

Using User-defined CDI Stores
Persistence Levels

Persistence Levels 10

Persistence of UCDI stores is maintained using a binary file named

UCDIpers.dat.
The UCDI initialisation file contains details of all known UCDI
stores, including the names and initial values of persistent UCDI
stores.

Table 10-2 Level of Persistence Behaviour

Persistence of UCDI Stores
1 Non‐persistent The store will maintain the last assigned
value as long as the UCDI service is
running. If the UCDI service is restarted,
the store will contain the value defined
by the initialisation file.

2 Persistent and cannot be The store will maintain the last assigned
reset value throughout system shutdown and
restart. The store cannot be reset to its
initial value by SST configuration
changes.

3 Persistent and can be The store will maintain the last assigned
reset value throughout system shutdown and
restart. The store may be reset to its
initial value by a call to the
ResetPersistentStores method.

If you need to reformat the terminal’s hard disk, first back up

UCDIpers.dat.
If you want to clear all persistent data, you can delete
UCDIpers.dat—it will be recreated on system start‐up. The persistent
stores will take on the values defined in the initialisation file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

10-4 APTRA Advance NDC, Developer’s Guide

 Using User-defined CDI Stores
Creating a UCDI Store

Creating a UCDI Store 10

UCDI stores must be created before they can be accessed. In the

following sections we discuss the three methods available for
creating a UCDI store:
 Method 1 ‐ Using the UCDI initialisation file and a Common
Store
 Method 2 ‐ Using an Automation Object
 Method 3 ‐ Using the CreateObject function.

Method 1 ‐ Using the UCDI Initialisation File and Stores 10

1 Specify the store in the initialisation file. For details of the format
of the initialisation file, see “UCDI Initialisation File” on
page 10‐3.

2 Re‐boot the system.

To access the UCDI store, use a Common Integer Store or Common
String Store worker with its ‘Store ID’ attribute set to zero and its
‘Store Name’ attribute set to the name of the UCDI store you
specified in the initialisation file.
If you attempt to create a UCDI store via a CDI worker without first
initialising the store in the initialisation file, then zero will be
returned for a Common Integer Store and null for a Common String
Store.
To allow for a successful completeness check of applications, the
name attribute for CDI store workers is set to an initial value of:
 ‘defaultInteger’ for Common Integer Stores
 ‘defaultString’ for Common String Stores.

Method 2 ‐ Using an Automation Object 10

1 In an Active Script Host worker, place an Automation Object in

its ‘Data Objects’ work group.

2 Set the Automation Object’s ‘Class Identifier’ attribute to

APTRAUSERCDI.APTRAUCDI.

This will expose the APTRAUCDI class interface; the methods of

which will be shown in the Script Editor, accessed via the Active
Script Host. For details of the methods of the APTRAUCDI class,
see “APTRAUCDI Properties and Methods” on page 10‐6.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 10-5

Using User-defined CDI Stores
Creating a UCDI Store

For an example implementation of this method, do the following:

1 Open the CustomisationLayer.mpj project.

2 Open the User Defined CDI catalog.

3 Double‐click the UCDI test application.

4 Double‐click the Active Script Host.

5 View the Automation Object attribute and the VBScript of the

Script Host.

Method 3 ‐ Using the CreateObject Function 10

In an Active Script Host worker, create an instance of the

APTRAUCDI class using the CreateObject function.
After created, the methods of APTRAUCDI class will be available.
For details of the methods, see the following section.
The following code sample demonstrates this method.

‘variable myCDI declared as global

Dim myUCDI

‘CreateObject used to assign a reference to ‘the

APTRAUCDI class
Set myUCDI = CreateObject("APTRAUSERCDI.APTRAUCDI")

‘can be any function within this Script Host ‘worker

Sub activate()

'data assigned to string store

UCDI.UCDIstring("GreetingMessage") = "Hello, Mr.
Customer"

'data retrieved from store

MsgBox myUCDI.UCDIstring("GreetingMessage") & ",
Welcome from NCR Bank"

MsgBox " Your fast-cash amount is £" &

myUCDI.UCDIinteger("CurrentCustFastCashAmount")

End Sub

APTRAUCDI Properties and Methods 10

The main properties and methods of the APTRAUCDI class are:

 UCDIstring(name) property
 UCDIinteger(name) property

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

10-6 APTRA Advance NDC, Developer’s Guide

 Using User-defined CDI Stores
Creating a UCDI Store

 newUCDIstore(name, initval, thetype) method

 ResetPersistentStores() method.
We describe these in the following tables.

Table 10-3 Parameters name ‐ String representing the Store Name of the
UCDIstring(name) Property target UCDI store.

Assign The store with Store Name of ʹnameʹ is assigned

expression=x the value of x; the value will be treated as a string.

Read The method will return the value stored in the

x=expression target UCDI store as a string.

Table 10-4 Parameters name ‐ String representing the Store Name of the
UCDIinteger(name) Property target UCDI store.

Assign The store with Store Name of ʹnameʹ is assigned

expression=x the value of x; the value will be treated as an
integer. Where x cannot be converted to an
integer, zero will be stored.

Read The method will return the value stored in the

x=expression target UCDI store as an integer. If the store
contains a string, an integer conversion will be
attempted. Zero will be returned if the
conversion fails.

Note: This property will cause an Invalid Argument Exception

(E_INVALIDARG) if the ‘name’ parameter is not recognised by the
UCDI. Use an ON ERROR statement to catch this error value if there
is a risk of using unknown names.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 10-7

Using User-defined CDI Stores
Creating a UCDI Store

Table 10-5 Description This method creates a new UCDI store with the
Boolean newUCDIstore(name, initval, name and initial value provided. The level of
thetype) Method persistence required is indicated by the ʹthetypeʹ
parameter.

This method can also be used to update the

default value of a store (but not a persistent
store). If the method is called with a name already
registered, but a different ʹinitvalʹ parameter, then
the ʹinitvalʹ value will become the new default
value of the store. If the ‘initval’ value is the same
as the current default value, the method will
return FALSE.

Parameters name ‐ String representing the Store Name of the

target UCDI store. The name must be less than 80
characters and must not contain a ʹ|ʹ (bar)
character.

initVal ‐ string containing the initial value of the

new store.

thetype ‐ string indicating the level of persistence

required. The string can be:
 1 ‐ “Normal”
 2 ‐ “Persistent”
 3 ‐ “Reset Persistent”
Return value A Boolean will be returned. The value of the
Boolean will be TRUE if the new store is
successfully created. The value FALSE is returned
if the store name already exists.

Table 10-6 Description This method will set all level 3 persistent stores
ResetPersistentStores() Method (that is, stores that can be reset) to their data
values defined in the current initialisation file.
The operation is reversible if you have made a
backup copy of the UCDIpers.dat file.

Parameters None

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

10-8 APTRA Advance NDC, Developer’s Guide

 Using User-defined CDI Stores
Accessing a CDI & UCDI Store

Accessing a CDI & UCDI Store 10

CDI stores are maintained to store the application specific data. A

few of the CDI stores are of an array type and are accessed with an
index value. For details of the CDI stores provided and their use, see
Appendix C, “Common Data Interface Stores”.
Advance NDC provides an option to create and maintain the UCDI
stores to store user specific data. These CDIs, CDI arrays and UCDIs
stores can be accessed to read and write via the
NDCCOMCDI.COMCDIDATA COM component.
The following functions are for reading and writing of CDIs and
UCDIs:

Table 10-7 Function Description

CDIs and UCDIs functions
comInteger This method is used to get or set
an integer value from a
CDI/UCDI store.

comString This method is used to get or set

a string value from a CDI/UCDI
store.

comInteger This method is used to get or

set an integer value from CDI
array.

The following example shows how to use

NDCCOMCDI.COMCDIDATA COM component in VBScript and
JScript

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 10-9

Using User-defined CDI Stores
Accessing a CDI & UCDI Store

Figure 10-1
COM component in VBScript and JScript
<!--VBSript for Object Creation/-->
dim cdiobject
set cdiobject
CreateObject(“NDCCOMCDI.COMCDIData”)
<!--JScript for Object Creation/-->
Var cdiobject
set cdiobject
ActiveXObject (“NDCCOMCDI.COMCDIData”)

‘Gets the cdi 1153 value

cdiobject.comInteger(1153)

‘sets 123 to the cdi 1153

cdiobject.comInteger (1153) = 123

‘Gets the UCDI Timer 68

cdiobject.comInteger (“Timer68”)

‘Set 2 to UCDU Timer 68

cdiobject.comInteger (“Timer68”) = 2

‘ Gets the UCDI DMITRData

cdiobject.comString("DMITRData")

‘ set “sample” to DMITRData

cdiobject.comString("DMITRData") = “Sample”

‘ Gets the Amount Buffer

cdiobject.comString(2000)

‘ Sets 12345678 to Amount buffer

cdiobject.comString(2000) = "12345678"

‘ gets the 0th index value of notesincassette cdi.

cdiobject.comIntegerArray(5010,0)

‘ sets the 0th index value of notesincassette cdi.

cdiobject.comIntegerArray(5010,0) = 1

set cdiobject = nothing

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

10-10 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Delivering an Advance NDC Aggregate to the SST

Chapter 11
Delivering an Advance NDC
Aggregate to the SST

Overview 11‐1

Advance NDC on Windows 7

64‐bit and Windows 10 64‐bit Systems 11‐2
32‐Bit to 64‐Bit Folder Mapping 11‐2
64‐Bit Folder Renaming 11‐2
Registry Entry Redirection 11‐3

Interactive Installation of Advance NDC 11‐4

Before You Start 11‐4
Installing Advance NDC on an SST 11‐5
Combined Installer 11‐5
Runtime Only Installer 11‐5
SST Directory Structure 11‐5
The pmdata File 11‐6
Clearing Persistent Memory (NVRAM) 11‐7
Starting the Advance NDC Application 11‐7

Including the Runtime Only Component in an Aggregate 11‐8

Creating a Runtime Only Aggregate 11‐8

Secure Initial Unattended Installation (IUI) 11‐9

Advance NDC and Security for APTRA 11‐9
Advance NDC Customisations and Security for APTRA 11‐9
Implementing Security for APTRA with Advance NDC 11‐9
Network Drives and Security for APTRA 11‐9

NCR Encryptor Configuration 11‐10

Registry Setting for EPP Devices 11‐10
Registry Setting for BAPE Devices 11‐11
Setting Basic or Enhanced Mode 11‐11
Key Names 11‐11

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Delivering an Advance NDC Aggregate to the SST

Key Manager Functionality 11‐11

Registry Settings for Key Manager 11‐11
Changing the Encryptor—Scenarios 11‐12
Changing from EPP to BAPE 11‐12
Changing from BAPE to EPP 11‐13
Retaining Encryption Keys 11‐13
BAPE 11‐14
Basic Security (DAPI1) 11‐14
International Security (DAPI7) 11‐14
Troubleshooting Key Manager 11‐15

Preparing a Modified Advance NDC Aggregate 11‐16

Creating Aggregate Subsets and Supersets 11‐16
Tools Component 11‐16
Windows 7 32‐bit 11‐17
Windows 7 64‐bit or Windows 10 64‐bit 11‐17
Extending the Supplied Application 11‐17
The Custom.ini File 11‐18
Installing the Aggregate 11‐19
De‐installing the Aggregate 11‐19
Post‐Installation Activities 11‐19
Using TCP/IP to communicate with Central 11‐20

De‐installing Advance NDC 11‐21

De‐installing .NET Assemblies 11‐22

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
K

Overview

Overview 11

This chapter describes the following:

 Support for Windows 7 64‐bit and Windows 10 64‐bit runtime
installations on NCR SSTs
 Including the runtime‐only component in an aggregate
 Configuring the encryptor
 Preparing modified applications, including migration from
NDC+, for installation
 De‐installing Advance NDC
 De‐installing .NET Assemblies.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-1

Delivering an Advance NDC Aggregate to the SST
Advance NDC on Windows 7 64-bit and Windows 10 64-bit Systems

Advance NDC on Windows 7

64‐bit and Windows 10 64‐bit
Systems 11

Advance NDC is a 32‐bit application that can be installed on NCR

SSTs running Windows 7 64‐bit and Windows 10 64‐bit (runtime
installations only). In Windows 7 64‐bit and Windows 10 64‐bit
installations, Microsoft installs applications as follows:

Table 11-1 Application Type 64-Bit Runtime Folder Locations

Application Installation Locations
32‐bit Program Files (x86)

64‐bit Program Files

Usually, the operating system is able to map all references from

32‐Bit to 64‐Bit Folder Program Files to Program Files (x86) for 32‐bit applications, but
Mapping 11
sometimes references in Advance NDC and its dependencies use
hard‐coded paths, which can mean the reference is not found. To
handle this, junction points are used for the Advance NDC
application and its dependencies requiring access to the Program
Files folder. These junction points are created by the Advance NDC
component installation. A 64bitWin7Support.vbs file is installed to
the Advance NDC\ in Runtime mode and NTGlobal\AANDCAPPS
in Development and Simulation mode and it can be reused if ever
the junction points are deleted and need to be reapplied.
Alternatively, the junction points can be applied manually by some
other script as required.
The junction points include the following:
 Program Files\NCR APTRA\Advance NDC
 Program Files\NCR APTRA\Printing
These junction points map to the corresponding Program Files (x86)
folders and must be left in place to ensure Advance NDC runs
correctly.

If the following folders exist at installation time, they are renamed

64‐Bit Folder Renaming 11

by appending _beforeANDCinstall to the filename during

installation. This allows the junction points with the same names to
be installed:
 C:\Program Files\NCR APTRA\Advance NDC
 C:\Program Files\NCR APTRA\Printing

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-2 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
Advance NDC on Windows 7 64-bit and Windows 10 64-bit Systems

Microsoft also uses redirection in the registry for 32‐bit applications

Registry Entry Redirection 11

running on Windows 7 64‐bit and Windows 10 64‐bit, under the

following registry key:
HKLM\Software

The Wow6432 subnode is used for the installation of 32‐bit

applications on 64‐bit Windows. Most of the registry entries for
NCR are under the following subkey:
HKLM\Software\NCR

Therefore, on 64‐bit Windows, these registry entries are installed to

HKLM\Software\Wow6432Node\NCR.

For more information on the handling of 32‐bit installations on

systems running 64‐bit Windows 7, refer to the following page on
the Microsoft web site:
http://msdn.microsoft.com/en‐us/library/windows/
desktop/aa384249(v=vs.85).aspx

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-3

Delivering an Advance NDC Aggregate to the SST
Interactive Installation of Advance NDC

Interactive Installation of Advance

NDC 11

To install Advance NDC interactively on an SST, complete the

following:
1 If you have an installed release of Advance NDC prior to ANDC
3.01, de‐install it before proceeding. For further information on
de‐installing Advance NDC, see “De‐installing Advance NDC”
on page 11‐21.

Caution: All installations of Advance NDC prior to version 3.01 and

associated components that have been installed separately must
be removed first. You do this using the Add or Remove
Programs option in the Windows control panel. In addition, if
you separately installed any of the other components supplied
with this package, remove them according to the instructions
supplied with that component.

2 Install Advance NDC as provided by NCR.

3 If you have any customisation to apply, install your

customisation.

4 Complete the post‐installation operations.

Note: Advance NDC supports the English version of the Windows

operating systems that it runs on.

There are two types of installer available in Advance NDC: the

combined installer, which contains all available Advance NDC
installation types, and the runtime‐only installer for installation on
an SST. For details, see “Combined Installer” and “Runtime Only
Installer” on page 11‐5.

The Advance NDC setup file, setup.exe, is in the root directory of the
Before You Start 11

APTRA Advance NDC Package CD‐ROM, along with the release

bulletin and the APTRA Advance NDC, Overview. To check you have
all the prerequisites to install the software, you can access the
overview document as follows:
1 If you have an installed release of Advance NDC prior to ANDC
3.01, de‐install any previous release of Advance NDC as
described in “De‐installing Advance NDC” on page 11‐21.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-4 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
Interactive Installation of Advance NDC

2 Insert the APTRA Advance NDC Package CD‐ROM in the

CD‐ROM drive of the SST.

3 Locate the file named APTRA Advance NDC Overview.pdf in the

root directory of the CD‐ROM and open it.

4 Ensure the prerequisite non‐NCR software is installed on the

SST. For details, refer to “Software Requirements” in Chapter 1
of the APTRA Advance NDC, Overview.

5 Also check the APTRA Advance NDC Package Release Bulletin for
the latest additional information.

As the size of the combined installer is over 75 MB, the runtime only
Installing Advance NDC installer is provided as a smaller alternative for SSTs. It has the same
on an SST 11
name as the combined installer and it is about 20 MB in size. To take
advantage of the smaller file size, you have to set up the runtime
installer to replace the combined installer.

Combined Installer 11

To install Advance NDC using the combined installer, select

setup.exe from the root directory of the APTRA Advance NDC
Package CD‐ROM. Follow the on‐screen instructions to choose the
installation type and complete the installation.

Runtime Only Installer 11

To set up the runtime component for the runtime‐only installation

perform the following steps:
1 Save a backup of all the files available in the comps/ANDC.54f
directory

2 The directory immediately below ANDC.54f contains

ANDC.msi: delete it and the other files, leaving only the
RuntimeOnly directory

3 Copy the contents of the RuntimeOnly directory up one level

After the installation, it is not possible to determine whether the
combined or runtime‐only installer was used to install the runtime
component. However, the method of de‐installation is unaffected as
it is not dependent on the installer file used.

The following table shows the directory structure created when you
SST Directory Structure 11

install Advance NDC, which is a 32‐bit application, on SSTs running

32‐bit Windows (7 or XP). For details of the file locations on SSTs
running 64‐bit Windows 7, see “Advance NDC on Windows 7 64‐bit

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-5

Delivering an Advance NDC Aggregate to the SST
Interactive Installation of Advance NDC

and Windows 10 64‐bit Systems” on page 11‐2.

Table 11-2
SST Directory Structure

Directory Description

C:\Program Files\NCR APTRA\Advance NDC\ Advance NDC base directory

Advance NDC component DLL files, user‐defined
DLL files and code page mapping files
application‐related files

Note: Due to the use of .NET binaries, the

ApplicationCore.exe file and any customisations
must be executed from the same directory.
C:\Program Files\NCR APTRA\Advance NDC\Media Media files, .jpg, and .wav files

C:\Program Files\NCR APTRA\Advance NDC\Config Configuration files: resrvd.def, AdvanceNDC.reg,

AdvanceNDC.accfg, AdvanceNDCCore.accfg,
AdvanceNDCCustom.accfg, CashInCore.accfg,
CashInCustom.accfg; XML files and related schemas

C:\Program Files\NCR APTRA\Advance NDC\Data Data files such as custom.dat and pmdata

C:\Program Files\NCR APTRA\Advance NDC\PD Problem Determination files such as makecab.exe

C:\Program Files\NCR APTRA\Advance NDC DisplayManager.exe and all files required by Display
Manager (for HTML screens)

Note: From Advance NDC 3.04 to 4.01, the DisplayManager

binaries are located in:
C:\Program Files\NCR APTRA\Advance NDC\DisplayManager

However, from Advance NDC 4.02, the DisplayManager binaries

are located in the Advance NDC folder. These files have been
relocated to facilitate accessing the application data, for example,
CDIs.

The pmdata File 11

An empty pmdata file is installed as part of the Advance NDC

installation. If a pmdata file is present on the machine from an earlier
installation, the empty pmdata file overwrites the existing file.

Note: This does not apply for Service Pack updates.

This approach avoids the need to manually delete the pmdata file
because of possible incompatible formats across versions of
Advance NDC.
If the pmdata file is to be deleted remotely using software
management, close the Advance NDC applications and stop the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-6 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
Interactive Installation of Advance NDC

APTRAUSERCDI service, to free the file for deletion. Advance NDC

will create a new empty pmdata file.

Clearing Persistent Memory (NVRAM) 11

To clear the persistent memory for a fresh start, you must delete the
following folders and their contents:
 C:\Program Files\NCR APTRA\Advance NDC\Data
 C:\Program Files\NCR APTRA\Advance NDC\PersistedData.

Note: It is a good practice to delete the ANDCConfig.NDC file

whenever the folders mentioned above are deleted. For information
on how to delete the ANDCConfig.NDC file, see “Supervisor Option
to Auto‐configure Devices” on page 5‐2.

To start the Advance NDC application, select

Starting the Advance NDC Start | Programs | NCR APTRA | Advance NDC | Start Advance
Application 11
NDC.
The Application Loader (AppLoader.exe) calls StartApps.vbs, which
checks that APTRA XFS is running and then loads the SST
configuration component, which completes the following:
1 Verifies whether configuration is required by checking for the
presence of the ANDCConfig.NDC file in C:\Program Files\NCR
APTRA\Advance NDC\Config\ and ensures that Advance NDC
is installed by reading the aggregate inventory.

2 Configures services and devices as required, restarting APTRA

XFS if necessary

3 Runs the application components in the Application Core

Between applications, there is a delay defined by the registry
entry HKLM\SOFTWARE\NCR\Advance NDC\SPStartPause
The default value is 30 seconds. This delay is required to allow
the applications to synchronise correctly at start‐up.

For details of component configuration on other vendors’ SSTs refer

to the APTRA Advance NDC Multi‐Vendor Support Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-7

Delivering an Advance NDC Aggregate to the SST
Including the Runtime Only Component in an Aggregate

Including the Runtime Only

Component in an Aggregate 11

This section describes the steps required to include the runtime‐only

component in an aggregate for interactive installation on an SST.

To include the runtime‐only component in your own aggregate

Creating a Runtime Only using the Aggregate Builder tool, perform the following steps:
Aggregate 11

1 Create a new archive

2 Import the Advance NDC aggregate into the archive

3 Import the component located in the ANDC.54f\RuntimeOnly

folder.

4 When prompted, replace the existing component in the archive.

Note: The method of de‐installation is unaffected as it is not

dependent on the installer used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-8 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
Secure Initial Unattended Installation (IUI)

Secure Initial Unattended Installation

(IUI) 11

This section discusses the considerations and preparation required

to install Advance NDC using NCR’s IUI on SSTs with Security for
APTRA already installed.

All files created at runtime, including the EJ and hardcopy backup

Advance NDC and files, are located in C:\Program Files\NCR APTRA\Advance
Security for APTRA 11
NDC\Data to allow read/write access under Security for APTRA.

Note: The c:\ssds path is not used for files, although it is still
available for backward compatibility with customer Exits. For more
information about affected files, see “Advance NDC and Updates
for Security for APTRA” on page 4‐7.

NCR recommends that the following are placed in or under the

Advance NDC C:\Program Files\NCR APTRA\Advance NDC\ directory.
Customisations and  All file references from authored applications
Security for APTRA 11

 Any executable files that need to be on the system path

 Any controls or object requiring registration.
All installation operations must be carried out under the
Administrator account.

Security for APTRA is supplied as a separate component on the

Implementing Security for Advance NDC CD‐ROM. To apply it to an SST, it must be added to
APTRA with Advance your super‐aggregate.
NDC 11

Caution It is not possible to update the Security for APTRA component on

an SST on which it is already installed. To install a newer version of
the Security for APTRA component the options are
disk‐replacement, disk‐imaging or Initial Unattended Installation.

Network Drives and Security for APTRA 11

When Security for APTRA is installed, network drive options will

not be available in Supervisor menus as the system lock‐down
policy prevents the use of network drives. For more information,
refer to the Security topic in the APTRA on‐line documentation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-9

Delivering an Advance NDC Aggregate to the SST
NCR Encryptor Configuration

NCR Encryptor Configuration 11

For the Advance NDC application, the following configuration is

required for the NCR encryptor on NCR SSTs:
 Registry setting for the Encrypting PIN Pad (EPP) or Basic
Alpha PIN pad and Encryptor (BAPE) device.

The setting must be updated manually if the device is changed

from EPP to BAPE or BAPE to EPP.

 Key names, which are automatically set up by the Key Manager

utility.
For information on the configuration required for other vendors’
encryptors, refer to Chapter 6, “Advance NDC on Specific Vendors’
SSTs” in the APTRA Advance NDC, Multi‐Vendor Support Reference
Manual.

If the NCR SST has an EPP device, the following registry entry is 1
Registry Setting for EPP to detect the EPP device before starting the PIN SP.
Devices 11

HKLM\SOFTWARE\Classes\XFS PIN Service Provider\

XFS-DeviceControl\PIN\GENERAL_CONFIGS\
EPPBTripleDESMode

When the PIN SP is started, it will change the other registry settings
and load the appropriate libraries for the EPP.
If you subsequently change the device from EPP to BAPE, you must
change this setting to 0.
If the EPP is not detected or is in fatal condition, the following
registry key is used to either stop or allow further transactions:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance
NDC\DisplayOOSWhenEPPFatal

0 ‐ When the EPP is fatal at the start of day or during a transaction,

the application allows further transactions. Advance NDC does not
put the SST into Out of Service mode. It is the responsibility of the
host and the host must be configured to do this if required.
1 (default) ‐ At the start of day, if EPP is fatal, after a go‐in‐service
(GIS) message is received, the application displays OOS screen.
During a transaction, if the EPP goes fatal, the application displays
OOS screen after the transaction is completed. The application
doesn’t allow further transactions.
For any other value or if the value is not present, the default value is
used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-10 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
NCR Encryptor Configuration

If the NCR SST has a BAPE device, the same registry entry is used as
Registry Setting for BAPE for an EPP device, but the value is 0 to detect the BAPE device
Devices 11
before starting the PIN SP.
If you subsequently change the device from BAPE to EPP, you must
change this setting to 1.

The PIN capabilities are used to distinguish between basic and

Setting Basic or Enhanced enhanced remote key loading. For further information, refer to the
Mode 11
APTRA Advance NDC, Reference Manual.
The following registry entry is used to select the remote key loading
type:
HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
PIN\GENERAL_CONFIGS\UseEnhRemoteKeyLoad

Valid values are as follows:

 0 to select basic remote key loading. This is the default
 1 to select enhanced remote key loading

As XFS requires keys to be created before loading them into the

Key Names 11

device, the NCR PIN SP provides registry settings for this purpose
on NCR SSTs. The registry setting to run the Key Manager utility is
automatically set when the application is first run, but it must be
updated manually thereafter if the device is changed.

Key Manager Functionality 11

When Advance NDC is first run after installation on an NCR SST,

the Key Manager utility detects the registry settings and initialises
the keys of the physical encryptor with the default registry values.
When the Key Entry Mode is changed, Advance NDC automatically
updates the registry settings and runs the Key Manager utility.
For other situations such as upgrading the software or changing the
encrypting device from BAPE to EPP, the registry settings have to
be checked and updated manually if required. See “Retaining
Encryption Keys” on page 11‐13 for details.

Note: If the registry setting is not correct for the device in use,
unpredictable behaviour will result. If this occurs, update the
registry with the correct setting and run the application again.

Registry Settings for Key Manager 11

The following registry key is used:

HKLM\SOFTWARE\NCR\Advance NDC\ENCRYPTORMODE

The ENCRYPTORMODE key has two entries, as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-11

Delivering an Advance NDC Aggregate to the SST
NCR Encryptor Configuration

 EncMode for encryptor key modes

 KeyMan for key management operations.

EncMode EncMode can have the following values: 11

Table 11-3 Value Meaning

EncMode Values
1 Run Key Manager for BAPE or EPP in single‐length mode

2 Run Key Manager for EPP in single‐length XOR mode

3 Run Key Manager for EPP in double‐length mode

4 Run Key Manager for EPP in restricted mode

The default value is 1.

All key modes (1 ‐ 4) are supported for non‐secure EPP on NCR and
other vendors’ machines. With secure EPP and International
Security (DAPI7) only key mode 4 is supported, if a key mode other
than 4 is entered, the key load will fail.

KeyMan KeyMan can have the following values: 11

Table 11-4 Value Meaning

KeyMan Values
0 Do not create the keys

1 Create the keys based on the value of EncMode.

Setting KeyMan to 1 deletes the keys from the krep.dat file

and reinitialises the encryptor based on the EncMode
registry setting.

2 Migrate keys from the previous versions

The default value is 2.

KeyMan is set to 0 after the Key Manager utility has successfully run.
This prevents the Key Manager utility from running each time you
start the application.

This section summarises the procedure for changing the encryptor

Changing the Encryptor— type. The following registry key is used to change the encryptor:
Scenarios 11
HKLM\SOFTWARE\Classes\WOSA/XFS_ROOT\SERVICE_PROVIDERS\
PIN\GENERAL_CONFIGS\

Changing from EPP to BAPE 11

1 Check that the EPPBTripleDESMode registry entry is set for the

BAPE encryptor, as follows:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-12 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
NCR Encryptor Configuration

EPPBTripleDESMode = 0

2 Set the Key Manager registry entry as follows:

EncMode = 1
KeyMan = 2

The Key Manager utility will start automatically while running the
application.

Changing from BAPE to EPP 11

1 Check the EPPBTripleDESMode registry entry is set for the EPP,

as follows:

EPPBTripleDESMode = 1

2 Set the registry entries for Key Manager as follows:

EncMode = 1
KeyMan = 2

Note: With International Security installed, Advance NDC

automatically sets EncMode to 4 regardless of the setting entered
here.

The Key Manager utility will start automatically while running the
application.

Wherever possible, Advance NDC will retain the encryption keys

Retaining Encryption Keys 11

used previously and use them in the new installation, or upgrade, of

Advance NDC.

Note 1: If the hard disk already has a krep.dat file that does not
match the Mode set in the registry, then the application will
generate an exception. In this case, delete krep.dat and krep.tmp as
described in “Troubleshooting Key Manager” on page 11‐15, and
run the applications again. This situation happens when the hard
disk has been used on another encryptor with a mode different from
the one selected.

Note 2: If the mode selected does not match the mode available in
the encryptor, atypical errors occur; for example, when performing
a key exchange operation, incorrect key data will be seen.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-13

Delivering an Advance NDC Aggregate to the SST
NCR Encryptor Configuration

BAPE 11

To retain keys for migrating a BAPE, or EPP in BAPE emulation

mode, do the following:
1 Set the XFS registry key, as described in “Registry Setting for
BAPE Devices” on page 11‐11.

2 In the registry, set the following values:

— EncMode = Previous mode (1 or 2), or leave unspecified. If
specified, the previous mode is retained. If the value is
unspecified, it is automatically set to 1 as default.
— KeyMan = Leave unspecified. If the value is unspecified, it is
automatically set to 2 as default. Setting KeyMan to 1 deletes
the keys from the krep.dat file and reinitialises the encryptor
based on the EncMode registry setting.

3 Either retain the krep.dat file, or install an empty krep.dat file.

Basic Security (DAPI1) 11

To retain keys for migrating an EPP with key modes 1, 2, or 3, do the

following:
1 Set the XFS registry key, as described in “Registry Setting for
EPP Devices” on page 11‐10.

2 In the registry, set the following values:

— EncMode = Previous mode (1, 2, or 3), or leave unspecified. If
the value is unspecified, it is automatically set to 1 as default.
— KeyMan = Leave unspecified. If the value is unspecified, it is
automatically set to 2 as default. Setting KeyMan to 1 deletes
the keys from the krep.dat file and reinitialises the encryptor
based on the EncMode registry setting.

3 Either retain the krep.dat file, or install an empty krep.dat file.

International Security (DAPI7) 11

Key mode 4 is for use with International Security. Therefore, this

section does not apply if you are migrating from an earlier release of
Advance NDC.
To retain keys for migrating an EPP in key mode 4, do the following:
1 Set the XFS registry key, as described in “Changing from BAPE
to EPP” on page 11‐13.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-14 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
NCR Encryptor Configuration

2 In the registry, set the following values:

— EncMode = 4. The mode cannot be retrieved from the
encryptor in secure mode and, therefore, must be specified
here.
— KeyMan = Leave unspecified. If the value is unspecified, it is
automatically set to 2 as default. Setting the KeyMan value to
1 deletes the keys from the krep.dat file and reinitialisaes the
encryptor.

3 Retain the krep.dat file.

If a power failure occurs while running Key Manager, or you

Troubleshooting Key encounter other problems with it, complete the following:
Manager 11

1 Close the Advance NDC application.

2 Delete the following files:

 krep.dat
 krep.bak

The default location for the krep.* files is C:\Program Files\NCR

APTRA\XFS PIN Service Provider. If the location is different, the
directory path is available in the Repository registry setting
under the following key:

HKLM\SOFTWARE\NCR\XFS PIN Service

Provider\XFS-DeviceControl\PIN\KEYLIB

3 Ensure the registry settings for the Key Manager are correct for
the attached BAPE or EPP device (see “Registry Settings for Key
Manager” on page 11‐11).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-15

Delivering an Advance NDC Aggregate to the SST
Preparing a Modified Advance NDC Aggregate

Preparing a Modified Advance NDC

Aggregate 11

Before modifying the installation in any way, ensure that you have
performed all the necessary changes, as discussed either in
“Changes Required” in Chapter 3, “Migrating Existing NDC+
Applications to Advance NDC” or in Chapter 4, “Upgrading from
Earlier Releases of Advance NDC”.
To re‐use the product components to create a subset or a superset
(including, for example, Security) of the supplied aggregate. See
“Creating Aggregate Subsets and Supersets” on page 11‐16.
You use the custom.ini file to include customised file, registry
settings and DLLs you have developed, such as worker class DLLs
or external C function DLLs, see “The Custom.ini File” on
page 11‐18.
To extend the product components with additional files and registry
settings, see “Extending the Supplied Application” on page 11‐17.

If you modify the Advance NDC application using the Author, you
Creating Aggregate use the Author to build the component, and the ABT to create and
Subsets and Supersets 11
export an installable aggregate.
The provided aggregate can be modified using the Aggregate
Builder Tool (ABT) on the development PC as follows:
1 On the development PC, create a new empty archive using
File | Select Archive.

2 To populate this archive, import the aggregate from the APTRA

Advance NDC Package CD using File | Import. You have only
to select the path where an aggregate or component is located.

3 Add, edit and remove components as required. For example,

you can import the SNMP aggregate and add the ‘Security for
APTRA’ component to the Advance NDC aggregate.

4 Save the archive and then perform an export to produce an

executable installable aggregate containing your changes, ready
for the SST.

The Tools component is not intended for installation in a runtime

Tools Component 11

environment on an SST. If you have a requirement to install the

Tools component on an SST, you can create a separate aggregate for

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-16 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
Preparing a Modified Advance NDC Aggregate

it. This aggregate has to be installed on the SST using the

Development and Simulation installation option.
The installation location for the Tools component depends on the
operating system type:

Windows 7 32‐bit 11

 C:\Program Files\NCR APTRA\Advance NDC\Tools

 C:\Program Files\NCR APTRA\Advance NDC\Tools
(Unsupported)

Windows 7 64‐bit or Windows 10 64‐bit 11

 C:\Program Files (x86)\NCR APTRA\Advance NDC\Tools

 C:\Program Files (x86)\NCR APTRA\Advance NDC\Tools
(Unsupported)
The Tools folder contains the following:
 DebugLog ‐ is a folder that contains the DebugLog.exe file. For
information on installing DebugLog, see “Installing and
Configuring DebugLog” on page 12‐16.
 InstallAANDCTools ‐ is a batch file, which calls the Tools batch
file.
 Tools ‐ is a batch file, which installs the NDCHost Emulator and
the Debuglog.

If you have new files or registry settings to update the supplied

Extending the Supplied application, use the custom.ini file to include them. All registry
Application 11
entries and source and target file names are held in the custom.ini
file. Refer to “The Custom.ini File” on page 11‐18 for details.
Complete the following steps:
1 Create a custom directory and copy the component files to it.
This folder can be created anywhere on your system, however, it
must contain the ANDC.msi and _comp.ini files. The ABT
recognises any folder containing _comp.ini as an APTRA
component folder.

Note: If you are updating a service pack, the custom directory

must contain the ANDCSP.msi file instead of the ANDC.msi file.

2 Create the custom.ini file, specifying the required registry and

file entries as shown in Appendix F, “Example Custom.ini
Files”, and save it to the custom directory.

3 Copy all the files referenced in the custom.ini file to the custom
directory.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-17

Delivering an Advance NDC Aggregate to the SST
Preparing a Modified Advance NDC Aggregate

4 Import the updated component to an archive. For information

on adding to an archive, see “Creating Aggregate Subsets and
Supersets” on page 11‐16. If you use an existing folder for the
archive, there may already be a component of the same name in
the folder. In this case, you must overwrite the existing
component.

5 Use the ABT to produce an installable aggregate. For details,

refer to the on‐line help provided with the tool.
If you use the aggregate to install the component separately to
Advance NDC, you must set the option to force installation
otherwise the installer will not overwrite the existing component.

The Custom.ini File 11

You must create a custom.ini file to specify the registry and file
entries for a modified component.
The registry and file entries in this file can be associated with a
particular configuration set, from which profiles are created in the
ABT. You must edit the custom.ini file directly to add a new
configuration set. This is because configuration sets cannot be
duplicated using the ABT as no configuration DLL is defined for
Advance NDC.
Specifying Files The files specified in the custom.ini file must be in 11

the component’s folder at installation. The default target path for a

file, if it is not specified, is [INSTALLDIR]. [INSTALLDIR] is the
directory chosen during installation as the target installation folder.
For SST installations, the default location is C:\Program Files\NCR
APTRA\Advance NDC\. For development installations, the default
is <drive>:\ntglobal, but this can be changed at installation.
To use another target path, include the full path, for example,
C:\MyFolder\File1.dll. To place a file in a subdirectory, specify the
full target path, for example, [INSTALLDIR]\MySubFolder\File2.dll,
or C:\MyFolder\MySubfolder\File3.dll.
Specifying Registry Entries A prefix must be used to specify the 11

data type when defining a registry value in the custom.ini file. String
values are the only exception. The data types and associated
prefixes are shown in Table 11‐5.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-18 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
Preparing a Modified Advance NDC Aggregate

Table 11-5
Registry Data Type Prefixes

Data Type Prefix Example

REG_SZ HKEY_LOCAL_MACHINE\Software\Subkey\StringValue1=MyString

REG_DWORD # HKEY_LOCAL_MACHINE\Software\Subkey\NumberValue1=#1

REG_BINARY #x HKEY_LOCAL_MACHINE\Software\Subkey\BinaryValue1=#x010203

REG_MULTI_SZ [~] HKEY_LOCAL_MACHINE\Software\Subkey\MultiStringValue1=[~]str1[~]str2

The aggregate can now be used in an installation. The following list

Installing the Aggregate 11

provides examples of installation methods:

 Interactively by running setup.exe, located in the exported
aggregates folder, and selecting the target type (Development
and Simulation or SST) and profile required
 Silently for the development target type and no profile. To do
this, run the following command line from the export
aggregate’s root directory:
setup.exe /u:s /t:devsim
 Silently for the SST target type and a named profile. To do this,
run the following command line from the export aggregate’s
root directory, in this example we are using a profile named
ProfileForSet1:
setup.exe /u:s /t:sst /f:"ProfileForSet1"

To deinstall the aggregate silently, run the following command line

De‐installing the from the aggregate installer’s installation folder:
Aggregate 11

setup.exe /d:"application name" "version number" /u:u

To deinstall the aggregate interactively, use the Add/Remove

Programs option in the Windows Control Panel.

To set up the SST, complete the following steps:

Post‐Installation Activities 11

1 If you modify the registry settings for customisations without

updating the custom.ini file, they will need to be manually reset.
Installing Advance NDC sets all registry keys to the default.

2 Start or activate the Advance NDC application as follows:

a Ensure the Supervisor Mode switch is set to Supervisor, to
enable all communications, keys, message mode and MAC
to be correctly set up before a connection to the host is
opened.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-19

Delivering an Advance NDC Aggregate to the SST
Preparing a Modified Advance NDC Aggregate

b Select Start | Programs | NCR APTRA | Advance NDC |

Start Advance NDC.

3 Complete the following in Supervisor before performing any

transactions:
a Enter the encryption keys.
b Clear and set the note counts.
c Configure communications.

For details of setting up an SST using Supervisor, refer to the

APTRA Advance NDC, Supervisor’s Guide , and if you are setting
up SSTs on other vendors’ SSTs, the APTRA Advance NDC,
Multi‐Vendor Support Reference Manual .

Using TCP/IP to communicate with Central 11

You must specify the IP addresses and port numbers using

Supervisor.

For details of the TCP/IP Configuration menu, refer to the APTRA

Advance NDC, Supervisor’s Guide.
For additional communications configuration, see “Configuring
Communications” on page 5‐44.
For details of the Communications Event Log, refer to the NCR
Self‐Service Support, System Application User Guide .

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-20 APTRA Advance NDC, Developer’s Guide

 Delivering an Advance NDC Aggregate to the SST
De-installing Advance NDC

De‐installing Advance NDC 11

If an SST has a version of Advance NDC prior to version 3.01 or you

want to re‐install Advance NDC, you must remove the existing
installation and any associated software that has been installed
separately before installing Advance NDC.
If you re‐install Advance NDC to the same location, it overwrites
most of the contents of the Advance NDC directories, so you need to
take copies of any files you wish to keep. Complete the following
steps:
1 Back up any electronic journal or hard copy backup logs in the
C:\Program Files\NCR APTRA\Advance NDC directory.

2 In the Windows Control Panel, use Add or Remove Programs to

first remove any Advance NDC service pack, then the Advance
NDC components. Files created after the installation of Advance
NDC, such as custom.dat, user ID files and CDI data files, will
not be deleted. It is up to you to keep or delete them.

Note: If you are de‐installing Advance NDC because the EJ Privacy

password needs to be reset, you must also delete the UCDI
persistent file. For further information, see “EJ Privacy” on
page 5‐180.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 11-21

Delivering an Advance NDC Aggregate to the SST
De-installing .NET Assemblies

De‐installing .NET Assemblies 11

You may need to update the .NET Assemblies component to a new

version in one of the following scenarios:
 New features
 Hotfixes
 Enhancements
To install a newer version of .NET Assemblies, you must de‐install
the current version. To achieve this, you need to build an aggregate
containing the required MSI component to de‐install .NET
Assemblies. Executing the aggregate on the SST ensures that there is
backup of configuration information for all the devices connected to
an SST.
For more information, see the following:
 “SST Configuration Component” on page 5‐2
 “De‐installing the Aggregate” on page 11‐19
During the de‐installation of .NET Assemblies, one of the following
occurs:
 If the ANDCConfig.NDC file is present, the aggregate renames
the ANDCConfig.NDC file as ANDCConfig.Uninstall, overwrites
any existing ANDCConfig.Uninstall file and the de‐installation is
completed.
 If the ANDCConfig.NDC file is not present, the de‐installation is
completed.

Note: To delete the ANDCConfig.NDC file without renaming it as

ANDCConfig.Uninstall, use the option 94, Auto‐Configure Device on
the Configure menu in Supervisor.
For more information on Auto‐Configure Devices, refer to Chapter
4, “Configure Menu” in the APTRA Advance NDC, Supervisor Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

11-22 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Installing and Configuring Troubleshooting Tools

Chapter 12
Installing and Configuring
Troubleshooting Tools

Overview 12‐1

Advance NDC Troubleshooting Utilities 12‐2

Selecting a Debugging Utility 12‐2
Problem Determination 12‐2
Silent Debug and DebugLog 12‐3

Event and Error Logs 12‐4

Advance NDC Trace Information 12‐5

Tracing from C++ Code 12‐6
Tracing in the Author 12‐6
Using the Debug Message Sender 12‐6
Using Active Script Hosts 12‐7

State Flow Tracing 12‐9

Enabling State Flow Tracing 12‐9
State Flow Trace Journaling 12‐9
Example Journal Entries 12‐9

Always On Tracing 12‐11

Installing and Configuring Silent Debug 12‐12

Silent Debug Installation 12‐12
Configuring Silent Debug 12‐13
Registry Entry for Silent Debug 12‐13
Silent Debug Configuration File 12‐13

Installing and Configuring DebugLog 12‐16

DebugLog Installation 12‐16

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Installing and Configuring Troubleshooting Tools

Configuring DebugLog 12‐16

Configuring Auto Save 12‐17
Changing the Save All Destination 12‐18

Using the Troubleshooting Tools 12‐19

Troubleshooting with Problem Determination 12‐19
Problem Determination Templates 12‐19
Managing Problem Determination Investigations 12‐19
Default Problem Determination Trace Settings 12‐20
Self‐Service Terminal Configuration Component 12‐21
Troubleshooting with Silent Debug 12‐22
Using the Command Line 12‐22
Starting the Silent Debug Service Remotely 12‐22
Silent Debug Log Files 12‐23
Troubleshooting with DebugLog 12‐25
Trace Stream Information 12‐26
Reflected Messages 12‐26
Invalid Screen Definitions 12‐26

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.
 Installing and Configuring Troubleshooting ToolsL

Overview

Overview 12

This chapter provides the following information on troubleshooting

with Advance NDC:
 An overview of the available troubleshooting tools and their
application
 An introduction to Problem Determination event and error logs
 Trace information and methods of introducing trace points in
Advance NDC
 Installing and configuring Silent Debug
 Installing and configuring DebugLog
 Using Silent Debug
 Using DebugLog.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-1

Installing and Configuring Troubleshooting Tools
Advance NDC Troubleshooting Utilities

Advance NDC Troubleshooting

Utilities 12

In Advance NDC the following troubleshooting utilities are

available:
 Problem Determination, including Always On tracing
 Silent Debug
 DebugLog.

Choosing the most suitable utility for your troubleshooting

Selecting a Debugging investigation depends on the level and type of problem that
Utility 12
requires investigation.

Problem Determination 12

Use Problem Determination (PD) if you need to analyse data

specified by a template. Templates are supplied with Problem
Determination and Advance NDC, or you can create your own.
You must use Problem Determination if you need to collect data for
a .NET component, such as the Cash‐In component or the .NET
Assemblies for Advance NDC component.
A template is provided with Advance NDC to collect data for the
.NET Assemblies for Advance NDC component. You can select the
template to use from the Supervisor options.
Problem Determination collects a large amount of data in a short
period of time. It is not suitable for collecting data over extended
periods because of the amount of data involved.
For more information about using Problem Determination with
Advance NDC see “Troubleshooting with Problem Determination”
on page 12‐19.
Details of PD templates are provided in the Problem Determination
Analysis On‐line Documentation.
Always On Tracing A feature of Problem Determination is 12

Always On tracing, which provides a level of PD tracing even when

there is no active PD investigation.
Advance NDC supports Always On tracing for .NET (C#) code.
Silent Debug and DebugLog, described in the next section, are used
to provide similar trace data for C++ and APTRA Author code.
Archive Manager is used to collect Always On traces.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-2 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Advance NDC Troubleshooting Utilities

Silent Debug and DebugLog 12

Silent Debug and DebugLog each log the same information, but are
designed for use in different environments as follows:
 Use Silent Debug in a runtime environment.
 Use DebugLog in a test environment.

Note: If you have both Silent Debug and DebugLog installed, they
cannot be run at the same time. If an attempt is made to run one
after the other has been started, a message will be logged in the
event log stating which one could not start.

Silent Debug saves the data to log files. DebugLog displays the
information on screen. DebugLog menu options can be used to save
the logs manually or it can be configured to save to log files
automatically.
The log files are significantly smaller than those collected by
Problem Determination allowing you to collect data over a much
longer period without file storage problems.
Silent Debug By default, in a runtime environment, Silent Debug 12

runs each time Advance NDC is started. This can be configured

through the registry. For details, see “Configuring Silent Debug” on
page 12‐13.
Archive Manager is used to collect Silent Debug logs.
DebugLog For DebugLog configuration, including configuring 12

automatic saves see “Configuring DebugLog” on page 12‐16.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-3

Installing and Configuring Troubleshooting Tools
Event and Error Logs

Event and Error Logs 12

For troubleshooting with Problem Determination, the following

Windows event logs are available:
 Application event log
 System event log
 Security event log
Almost all internal NCR APTRA XFS platform events are written to
the application event log.
Windows events are written to the system event log.
Saving Windows event logs is described in the Self‐Service Support,
System Application User Guide.
The Unhandled Exception Handler (UEH) provided with APTRA
XFS records the same exception information in both the Windows
application event log and the UEH log, but the entries in the UEH
log are easier to read.
The UEH log file (ueh.log) is located in <pathname>\system32> where
<pathname> is the installation directory for Exception Handling. The
last exception is always at the end of the file. The way to check the
UEH log file is to go to the end of the file and search backwards for
the word ʹexceptionʹ.
The APTRA XFS platform also provides a software log,
communications log and device log. The information in these logs is
also contained in the Windows application event log.
For details of the UEH refer to the APTRA on‐line documentation
under Exception Handling | About Exception Handling |
Exception Handling Functions | Unhandled Exception Handler.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-4 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Advance NDC Trace Information

Advance NDC Trace Information 12

For C++ and APTRA Author code, Advance NDC has tracing
functionality built into various points in the application (known as
trace points). You can add more trace points if necessary. When
Advance NDC reaches a trace point, it will send a trace output to
the active debug tool (Silent Debug or DebugLog).
The Advance NDC application is the sender (client) of the trace
information and Silent Debug or DebugLog is the receiver (server).
A timestamp is added to the logged trace information to help in
identifying what was happening when a problem occurred.
The trace information is categorised into named trace streams. The
default trace streams used by Advance NDC are described in the
following table:

Table 12-1 Trace Stream Name Description

Default Trace Stream Types
MESSAGEIN Logs all messages received by the SST
See Table Note 1

MESSAGEOUT Logs all messages sent from the SST

OOXFS Logs interaction between Advance NDC and the

CEN‐XFS sub‐system
See Table Note 1

DEBUG Logs the general trace stream, including the

timestamp and thread identifier from the trace points
in Advance NDC

STATEDATA Logs the NDC state flow and when a state DLL is
started or stopped

SECURITY Logs security‐related information

Table Note 1: For security, Advance NDC masks sensitive

customer data in the Message‐In window and does not log printer
data to the OOXFS window. Some of these settings can be changed
using the registry. For details of the registry configuration settings,
see “Example of Adding Flow Points” on page 5‐31.

You can add new trace streams if required, as described in the

following sections:
 “Tracing from C++ Code”.
 “Tracing in the Author”

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-5

Installing and Configuring Troubleshooting Tools
Advance NDC Trace Information

The state flow during a transaction can also be traced and written to
journal. For details, see “State Flow Tracing” on page 12‐9.

To trace information from C++ code, create an instance of the

Tracing from C++ Code 12

DebugOut class and use the debug() method.

The debug method accepts a variable number of parameters

organised in the printf() style. The code needs to include
debugout.h and link with DebugOut.lib. The pre‐processor symbol
DBON must be defined in the Visual C++ (IDE) project settings. This
dynamically loads ssdsDebugOut.dll at runtime.
To suppress debug messages, you can use the following macro:

DBG(dbg.debug(“Won’t Print Out Unless DBON is defined”);)

In Figure 12‐1, the “Hello World from NCR” message is traced. This
time, the company name is dynamically supplied as a parameter in
the debug() method using the printf() output formatting style.

#define DBON
Figure 12-1
#include “debugout.h”
Example Tracing Code
void HelloWorld()
{
char * CompanyName = “NCR”;
DebugOut dgb(“DEBUG”);
dgb.debug(“Hello World from %s”, CompanyName);
}

To implement tracing in the Author, edit the Author flow as

Tracing in the Author 12

described in the following sections:

 “Using the Debug Message Sender”
 “Using Active Script Hosts”.

Using the Debug Message Sender 12

To implement tracing in an authored application, the Debug

Message Sender worker is added to the Author flow as illustrated in
Figure 12‐2.
Trace information is specified in the DebugTextLine attribute. If the
text line contains an asterisk (‘*’), dynamic contents retrieved from
the worker’s workgroup are inserted in the text in that position. For
details of Message Sender worker refer to the worker class on‐line
help provided with the Author.
The name of the trace stream is specified in the worker settings
using the DebugOutput attribute.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-6 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Advance NDC Trace Information

In Figure 12‐2, the “Hello World from NCR” message is traced in

the DEBUG trace stream.

Figure 12-2
Tracing in the Author Flow

Using Active Script Hosts 12

To add debugging to a new or existing Active Script Host worker,

create an instance of the DebugMessage.DebugMessage object and
use the debug(String text) method.
In Figure 12‐4, the “Hello World from NCR” message is traced
using an Active Script Host worker.
The script illustrated in Figure 12‐3 is added to the Script attribute.

Set DGB = CreateObject(“DebugMessage.DebugMessage”)

Figure 12-3
Sub activate()
Example Tracing Script for the
Active Script Host Worker On Error Resume Next
Dim text
text = “Hello World from “ + CompanyName.Data
DBG.DebugOutput = “DEBUG”
DBG.debug(text)
ActiveWorkGroup.Index = 1

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-7

Installing and Configuring Troubleshooting Tools
Advance NDC Trace Information

Figure 12-4
Tracing with an Active Script Host Worker

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-8 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
State Flow Tracing

State Flow Tracing 12

State flow tracing provides troubleshooting information to help

resolve or characterise issues in cardholder transactions. It allows
the state numbers executed during a transaction to be printed to the
journal.
The information provided by state flow tracing applies only to
cardholder transactions.

State flow tracing is enabled using the following registry entry:

Enabling State Flow
Tracing 12
HKLM\SOFTWARE\NCR\Advance NDC\Extensions\Tracing\
State Flow Trace

By default, this value is set to 0, and state flow tracing is disabled.

To enable state flow tracing, set the value to 1. If the registry entry is
not present or has an invalid value, state flow tracing is disabled.
After changing this registry entry, the SST must be rebooted.

If state flow tracing is enabled, state numbers are recorded in the

State Flow Trace State Flow Sequence CDI store during every transaction and
Journaling 12
journaled during the Close state. The last recorded state numbers
are also journaled at Start of Day if the SST has a power interruption
or is restarted during a consumer transaction. After journaling, the
state numbers are cleared from the State Flow Sequence CDI store,
ready for the next transaction. For details of this CDI store, see
“Transaction Processing Flags” on page C‐53.
A time stamp in the format dd/mm/yy*HH:MM:SS precedes the
label (reserved screen t90) and state number information that is
journaled. For details of the reserved screen, refer to Appendix A,
“Reserved Screens” in the APTRA Advance NDC, Reference Manual.

Example Journal Entries 12

The following examples show the journal entry for a normal

cardholder transaction, and a following a power fail during a
transaction.
Typical Cardholder Transaction Figure 12‐5 illustrates the 12

journal entry following a cardholder transaction.

Figure 12-5 *10/10/10*08:43:22*

Example Transaction State Flow Journal LAST TRANSACTION FLOW
Entry 000 013 004 093 037 026 027

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-9

Installing and Configuring Troubleshooting Tools
State Flow Tracing

This example shows that the following state numbers have been
executed:
 000
 013
 004
 093
 037
 026
 027.
These state numbers can be compared to the state download to
identify the states that have been executed.
Power Failure During a Transaction Figure 12‐6 illustrates the 12

journal entry made at Start of Day following a cardholder

transaction when the SST experienced a power fail during the
execution of the last recorded state.

Figure 12-6 *10/10/10*08:56:42*

Example Transaction State Flow Journal LAST TRANSACTION FLOW
Entry 000 013 004 093 037

This example shows that the following state numbers have been
executed:
 000
 013
 004
 093
 037.
These state numbers can be compared to the state download to
identify the states that have been executed.

Note 1: No journal entry is made if a cardholder transaction is not

in progress when a power fail occurs.

Note 2: Alphanumeric state numbers are always journaled in upper

case.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-10 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Always On Tracing

Always On Tracing 12

The following messages are logged as part of Always On tracing

(which occurs whether or nor there is an active PD investigation):
 Messages sent to and received from the host
 Supervisor operations such as replenishment or clearing totals
 Start of day
 Data entered through .NET Supervisor tasks
 Start and finish of major functions such as Cash Unit
Configuration, Error Recovery and Start/End Exchange.
 Error events during transactions, such as cash /cheque deposit
failed, note/cheque rejected/retracted, or counterfeit/suspect
note detected; or while in Supervisor, such as note configuration
failure or thresholds reached
 NDC State and Transaction Reply start and finish, for example,
Cash Accept state, Bunch Cheque Accept state and Encash reply
 When an event is received in different components, for example,
a MoneyRejected event is received in CashInFlows,
NDCCashAcceptService, CashInStatusHandler and
CashInCounters, Always On tracing will be added in all the
components.
 Changes in the availability of devices or other services.
 Changes in configuration, for example, the start and finish of
GBXX configuration
 Journal points: information written to the journal is also traced
using the AlwaysOn method.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-11

Installing and Configuring Troubleshooting Tools
Installing and Configuring Silent Debug

Installing and Configuring Silent

Debug 12

This section describes the installation and configuration of the Silent

Debug tool for debugging in a live environment or a development
environment. For information on using Silent Debug, see
“Troubleshooting with Silent Debug” on page 12‐22.

Silent Debug is installed as part of the Advance NDC aggregate. In a

Silent Debug Installation 12

runtime environment, Silent Debug is set to run whenever Advance

NDC is started. In a development environment, Silent Debug is
started only if Silent Debug is already enabled.
For both environments, the Silent Debug files are installed to the
following locations:

Table 12-2
Silent Debug Installation Paths

File Path

NCRSilentDebug.exe C:\Program Files\NCR APTRA\Advance NDC\

SilentDebug.ini C:\Program Files\NCR APTRA\Advance NDC\Config

If the configuration file (SilentDebug.ini) is not present in this

directory the configuration is not recognised as valid, and the
following message is logged to the Windows Event Log:

The NDCSILENTDEBUG service configuration file is not

valid

When tracing in a live environment, Advance NDC installs Silent

Debug as an operating system service in Automatic Reset Mode.
This means that Silent Debug is automatically restarted following a
power failure. This can be changed to use Manual Reset Mode as
follows:
1 Select Start | Control Panel |Administrative Tools |Service.

2 Select NCRSilentDebug from the list of services.

3 Select Action | Properties.

4 Select Manual from the Startup type drop down list.

5 Select the OK button.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-12 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Installing and Configuring Silent Debug

After installation, the settings for Silent Debug can be changed

Configuring Silent Debug 12

through the registry entry for automatic start‐up and its

configuration file for parameters such as log names.

Registry Entry for Silent Debug 12

The default registry setting for Silent Debug is in the following

DWORD registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\
SilentDebugAutoTraceStart

Valid values are as follows:

Table 12-3 Registry

Description
Registry Entry for Silent Debug Start-up Value

0 Starts Silent Debug at application start‐up only if Silent

Debug is already enabled
This is the default in a development environment

1 Starts Silent Debug whenever Advance NDC is started but

DebugLog is not running.
This is the default in a runtime environment

For any other value or if the registry entry is missing, the default
value is used.
If Silent Debug is successfully started in a runtime environment, the
operator will be able to see in Supervisor the following status on the
Silent Debug submenu of the Troubleshooting menu:
SILENTDEBUG STARTED

Silent Debug Configuration File 12

The configuration settings for the Silent Debug can be edited in the
SilentDebug.ini file which is stored in the following location:

C:\Program Files\NCR APTRA\Advance NDC\Config

If the configuration parameters are not within the permitted ranges,

or the SilentDebug.ini file cannot be validated, Silent Debug will not
start logging.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-13

Installing and Configuring Troubleshooting Tools
Installing and Configuring Silent Debug

Configuration options in the SilentDebug.ini file are described in

Table 12‐4.

Table 12-4
Silent Debug Configuration Parameters

Parameter Description

MAXFILESIZE Defines the maximum permitted size of the log files in kilobytes (KB). The file is
overwritten from the beginning when the file size exceeds the specified value

The minimum setting is 1. If MAXFILESIZE is set to zero, Silent Debug will not start. By
default, MAXFILESIZE is set to 10 MB

A counter keeps track of the number of times the file is overwritten. The counter starts at
zero and increments by one each time the file starts to overwrite the log trace data. In
this way, old trace data will gradually be overwritten with new trace data.

An <END> marker is placed at the end of the last input of new trace data to the file.

If the counter indicates a high incidence of overwriting in a short space of time, increase
the value of MAXFILESIZE.

Sufficient disk space must be available for logging and for other purposes, such as EJ
backup files or PD investigations.

TRACE Defines the log names for each trace stream that is to be logged. The default log names
are listed in Table 12‐1 “Default Trace Stream Types” on page 12‐5.

Log names are separated by a comma.

MERGEDTRACE Defines whether trace information for each log name defined in the TRACE parameter is
captured in individual files, in a merged file, or both.

Valid values are as follows:

 0 ‐ an individual file is created for each log name

 1 ‐ an individual file is created for each log name and an additional file is created that
holds merged trace information for all of the log names.
 2 ‐ one file is created that holds merged trace information for all of the log names. This
is the default.

The merged trace file name will take the form MergedTrace.log or
MergedTrace_<dd>.log if daily files are specified.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-14 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Installing and Configuring Silent Debug

Parameter Description

LOGBYDAY Configures when new log files are created.

See Table Note 2 Valid values are as follows:
 0 ‐ the same log files are used until they reach the value specified by the MAXFILESIZE
parameter, after which the log files are overwritten
 1 ‐ a new log file is created for each specified trace as specified by the MERGEDTRACE
parameter on every day of the month that Silent Debug is running. This is the default

If configured to use daily log files, logging to the current files ends at 12 midnight.
Logging is then started to a new daily file, which is created in one of the following
ways:

 If no files exist for the date, new log files are created as defined in the
configuration
 If files exist for the date, the existing log files are overwritten. The wrap‐around
counter for the file will be zero.

Daily log files contain the trace data type and day of the month in their file name.
For example, if a trace log is created for the MESSAGEIN trace on the second day of
the month, the name of the log file is MESSAGEIN_02.log.

Table Note 2: If an exception occurs and Silent Debug is running, it

will restart automatically when the SST reboots. If Silent Debug
automatically restarts and LOGBYDAY is set to 1, logging will
continue as follows:

 If the date is the same as when the exception occurred,

logging continues in the same file
 If the exception occurs just before midnight and the SST
reboots after midnight, logging continues in a new log file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-15

Installing and Configuring Troubleshooting Tools
Installing and Configuring DebugLog

Installing and Configuring

DebugLog 12

This section describes how to install and configure the DebugLog

tool for debugging in a test environment. For information on using
DebugLog see “Troubleshooting with DebugLog” on page 12‐25

Note: The DebugLog tool is designed for use in a test environment

where a mouse and keyboard are available.

DebugLog is installed with the Advance NDC Tools component in

DebugLog Installation 12

the development environment. For information on installing the

Tools component on an SST see “Tools Component” on page 11‐16.

After installation, DebugLog can be configured using the registry.

Configuring DebugLog 12

The following registry entries are DWORD types.

Whether to log debug information is set using the following registry
entry:

HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\DebugLog

Valid values are as follows:

 0 ‐ no debug information is sent to DebugLog

 1 ‐ debug information is sent to DebugLog if the utility is
active. This is the default
The interaction between Advance NDC and CEN‐XFS can also be
traced. The level of detail is set using the following registry entry:

HKLM\SOFTWARE\NCR\Advance NDC\OOXFSDebugLevel

Valid values are as follows:

 0 ‐No trace enabled
 1 ‐Standard Trace. This logs XFS commands and events for
use in general troubleshooting.
 3 ‐Detailed This logs the XFS commands and events
provided by the Standard trace and includes additional data
that can be used to investigate low‐level issues. This is the
default.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-16 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Installing and Configuring DebugLog

Configuring Auto Save 12

By default DebugLog automatically saves data to log files for the

default trace streams. The files are saved to a directory called
AUTOSAVE created during the DebugLog installation.
The auto save function can be configured as follows:
1 Open the DebugLog application window.

2 Select Options | File Options. The DebugLog Application Properties

dialog box is displayed as illustrated in Figure 12‐7.

Figure 12-7
DebugLog Application Properties
Dialog Box

3 Select the checkbox to turn auto save on, or deselect it turn auto
save off.

4 You can specify a different location for the auto save log files
using one of the following methods:
— Type the required path in the AUTOSAVE text box.
— Select the Browse button at the right of the AUTOSAVE text
box, browse to the desired directory and select OK.

5 Select OK in the Debug Application Properties dialog box.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-17

Installing and Configuring Troubleshooting Tools
Installing and Configuring DebugLog

Changing the Save All Destination 12

By default, all trace data is saved to the LOG_DUMP directory when

Save All is selected from the DebugLog File menu. The destination can
be changed as follows:
1 Open the DebugLog application window.

2 Select Options | File Options. The DebugLog Application Properties

dialog box is displayed as illustrated in Figure 12‐7.

3 Specify a different location for the log files using one of the
following methods:
— Type the required path in the SAVE ALL text box.
— Select the Browse button at the right of the SAVE ALL text
box, browse to the desired directory and select OK.

4 Select OK in the Debug Application Properties dialog box.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-18 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Using the Troubleshooting Tools

Using the Troubleshooting Tools 12

This section provides an overview of Problem Determination,

information on using the Silent Debug and DebugLog tools and a
description of their log files.

The Problem Determination (PD) components, which are provided

Troubleshooting with as part of the Advance NDC aggregate, are as follows:
Problem Determination 12

 Problem Determination Analysis (PDA) must be installed on the

development PC.
 Problem Determination Collection (PDC) must be installed on
the SST.

Note: If an investigation has to be viewed on the SST, Problem

Determination Analysis, which does not require the use of
keyboard, must also be installed.

Problem Determination Templates 12

Advance NDC provides a default template file (filterset.txt) to help

with PD investigations. This template enables the tracing of the
streams listed in Table 12‐6 on page 12‐21. The default template and
the executable makecab.exe, which compresses the investigation files,
are automatically delivered when Advance NDC is installed on an
SST. If you modify or create a template, it must be configured as
described in the APTRA online documentation under Problem
Determination Analysis.

Note: The default location for the templates and the log file created
by an investigation is in the PD installation folder; for example, if
PD is installed on the C drive, the following are the default
locations:

 C:\Program Files\NCR APTRA\Problem Determination

Collection\Templates
 C:\Program Files\NCR APTRA\Problem Determination
Collection\Investigations
Makecab.exe is located in C:\Program Files\NCR APTRA\Advance
NDC\PD on the SST.

Managing Problem Determination Investigations 12

You can control the PD investigation using menu options on the

Configure menu in Supervisor mode. If using PD from Supervisor
mode, you must have PDInvTemplate installed and configured on
the SST. For information on the Supervisor options, refer to Chapter

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-19

Installing and Configuring Troubleshooting Tools
Using the Troubleshooting Tools

4, “Configure Menu” in the APTRA Advance NDC, Supervisor’s

Guide. The Supervisor options start the .NET PCD Support Tasks
described in Table 12‐5.

Table 12-5
.NET PCD Support Tasks

Task Description

Start Investigation This lists the templates currently stored on the SST. An investigation starts
when a template is selected from the list

Stop Investigation This stops the current investigation and leaves the investigation files
available for export

Export Investigation This lists the investigations currently stored on the SST. An investigation
is exported to the selected drive when selected from the list

Pause Investigation This pauses the current investigation whilst leaving it effectively
underway

Resume Investigation This resumes any currently paused investigation

Abandon Investigation This abandons the current investigation and deletes any files created as a
result of that investigation

Delete Investigation This lists the investigations currently stored on the SST. An investigation
is deleted when selected from the list

Import Template This imports templates to be used as the subject of an investigation

Delete Template This lists the templates currently stored on the SST. A template is deleted
when selected from the list

Investigation Status This displays the name and running time of the current investigation

For further information on these tasks, refer to the APTRA online

documentation under .NET PDC Support Tasks.
For further information on using Problem Determination Collection
and Problem Determination Analysis for troubleshooting refer to
the APTRA on‐line documentation under Problem Determination
Collection and Problem Determination Analysis.

Default Problem Determination Trace Settings 12

Table 12‐6 describes the default settings of the trace streams

included in the default template file (filterset.txt).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-20 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Using the Troubleshooting Tools

Table 12-6 Trace Stream Default Setting

Default Problem Determination Trace
Settings MESSAGEOUT Normal

MESSAGEIN Normal

OOXFS Normal

DEBUG(PD) Normal

DEBUG Normal

KEYBOARD Normal

STATEDATA Normal

BunchChqAccptSrv Normal

ImageMarkRecorder Normal

CodeLineValSrv Normal

ClassConfigurator Normal

VPITCPIP Normal

XFS SCPM Service Provider Minimum

See Table Note 3

AdvanceNDC.NCR.* Normal

CashAcceptService Normal

ECB6CashAcceptSrv Normal

ECB6CashAcceptService Normal

AXFS.XFSCashInResourceC3 Normal

Table Note 3: This includes information from the following:

 Interface entry
 Interface exit
 Event arrived
 Event fired
 General.

Self‐Service Terminal Configuration Component 12

The Self‐Service Terminal Configuration Component (SST

configuration component) uses Problem Determination tracing to
track the progress of the configuration of the identified XFS services.
If the SST is restarted after the SST configuration component has
completed to finalise successful configuration settings, events are
logged in the XP event log.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-21

Installing and Configuring Troubleshooting Tools
Using the Troubleshooting Tools

Silent Debug provides trace logging in a live or development

Troubleshooting with environment for C++ and APTRA Author code. When installed and
Silent Debug 12
started, it creates trace log files, depending on the configuration
settings in the SilentDebug.ini file, which is located in C:\Program
Files\NCR APTRA\Advance NDC\Config.
Installing and configuring Silent Debug is described on page 12‐12.
Silent Debug can be controlled in the following ways:
 Using the Configure menu in Supervisor as described in the
APTRA Advance NDC, Supervisor’s Guide.
 Using the command line
 Using a Windows script to start logging remotely.

Note: Windows .NET commands are not supported.

Using the Command Line 12

Silent Debug is run using the following command:

NCRSilentDebug [option]

The options that can be used with Silent Debug are described in
Table 12‐7.

Table 12-7
Silent Debug Commands

Option Description

‐i Installs Silent Debug as an operating system service and registers it with the Service Control
Manager.
This command installs the service in Automatic Restart Mode and in a stopped state.

‐u Uninstalls Silent Debug as an operating system service.

This command un‐registers the service with the Service Control Manager, but does not delete the
SilentDebug.ini or NCRSilentDebug.exe files.
Silent Debug must be stopped before running this command.

‐v Displays the version of Silent Debug.

‐r Starts Silent Debug

‐s Stops Silent Debug

‐vl Validates the SilentDebug.ini file

‐st Gets the current status of SilentDebug tracing

Starting the Silent Debug Service Remotely 12

Silent Debug can be started remotely using a Windows script that

changes the value of a CDI store (Store ID: 3348).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-22 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Using the Troubleshooting Tools

Figure 12‐8 is an example of a script used to start Silent Debug

remotely.

Dim objSilentDebugStore
Figure 12-8
Set objSilentDebugStore =
Example Script to Start Silent Debug
12

CreateObject(“COMCDISTORE.COMCDIimpl”)
On Error Resume Next
‘1 - Integer Type
If objSilentDebugStore.setStoreId (3348,1) = 0 then
objSilentDebugStore.Data = 1

Silent Debug Log Files 12

Silent Debug log files are created in the following location:

C:\Program Files\NCR APTRA\Advance NDC\Debug

The first line of the log file records the date in DD/MM/YYYY format,
the time in HH:MM:SS format, and how many times the file has been
overwritten as follows:

Trace Created 02/01/2006 15:06:44 Counter = 0

The counter indicates the number of times the file has been
overwritten from the beginning. When the counter reaches 99,999, it
is reset to 0 and the count starts again. If the file is being overwritten
too frequently, increase the configured file size.
A marker, <END>, is written to the file at the end of the trace stream
information. Any content appearing after the <END> marker is trace
stream information that exists from the last time the file was written
to.
For details of log file configuration, see “Configuring Silent Debug”
on page 12‐13.
Single Trace Stream Log Files Single trace stream log files record 12

information from one type of trace stream.

Figure 12‐9 is an example of a MESSAGEIN trace stream log file. Each
line uses the following format, as described in Table 12‐8:

HH:MM:SS.sss - DD/MM/YYYY #xxxx [xxxxxxxx]

Table 12-8 Format Description

MESSAGEIN Line Format
HH:MM:SS.sss Time of log entry in hours, minutes, seconds,
and milliseconds

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-23

Installing and Configuring Troubleshooting Tools
Using the Troubleshooting Tools

Format Description

DD/MM/YYYY Date of log entry

#xxxx Message sequence number
[xxxxxxxx] The message that has been received
For information on the message format, refer to
the APTRA Advance NDC, Reference Manual

Figure 12-9 Trace Created 06/03/2007 15:57:11 Counter

Example MESSAGEIN Log File 15:57:11.821 - 06/03/2007 #0001 [12000P21]
15:57:14.836 - 06/03/2007 #0002 [12000P21]
15:57:17.852 - 06/03/2007 #0003 [12000P21]
15:57:20.883 - 06/03/2007 #0004 [12000P21]
15:57:23.899 - 06/03/2007 #0005 [12000P21]
15:57:26.914 - 06/03/2007 #0006 [12000P21]
15:57:29.930 - 06/03/2007 #0007 [12000P21]
15:57:32.961 - 06/03/2007 #0008 [12000P21]
15:57:35.977 - 06/03/2007 #0009 [12000P21]
15:57:38.993 - 06/03/2007 #0010 [12000P21]
15:57:42.008 - 06/03/2007 #0011 [12000P21]
16:02:29.901 - 06/03/2007 #0012 [12000B0000]<END>

Merged Trace Stream Log Files Merged trace stream log files 12

record information from all of trace streams.

Each trace stream entry is identified by opening and closing tags,
indicating the type of trace stream content. For example, any
information from the MESSAGEOUT trace stream is enclosed in
<MESSAGEOUT> and </MESSAGEOUT> tags.
Figure 12‐10 is an example of a merged trace file which contains
trace stream information for DEBUG and MESSAGEOUT.
The DEBUG lines contain the following:
 Opening tag to identify trace stream <DEBUG>
 Current mode
 Date of log entry
 Time of log entry
 Description of activity
 The worker identifier contained in <wid> and </wid> tags. For
example, in Figure 12‐10 <wid>22v1823m34</wid> identifies
the Debug Message Sender worker.
 Closing tag to identify trace stream </DEBUG>.
The MESSAGEOUT lines contain the following:
 Opening tag to identify trace stream <MESSAGEOUT>

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-24 APTRA Advance NDC, Developer’s Guide

 Installing and Configuring Troubleshooting Tools
Using the Troubleshooting Tools

 Time of log entry

 Date of log entry
 Consecutive order of sent message
 The message details
 Closing tag to identify trace stream </MESSAGEOUT>.

Figure 12-10
Example Merged Trace File

Trace Created 06/03/2007 15:53:32 Counter = 0

<DEBUG>Supervi.. 06/03/2007 15:57:11.774 Activating Pending Supervisor
Entry Msg = 12000P21
Exit Msg = <wid>6r641ichl21</wid>
</DEBUG>
<DEBUG>Supervi.. 06/03/2007 15:57:11.774 Attempt to send Pending Supervisor Entry Message <wid>22v1823m34</wid>
</DEBUG>
<MESSAGEOUT>15:57:11.821 - 06/03/2007 #0001 [12000P21]</MESSAGEOUT>
<DEBUG>Supervi.. 06/03/2007 15:57:11.821 Supervisor Pending Complete <wid>25v1823m34</wid>
</DEBUG>
<DEBUG>Supervi.. 06/03/2007 15:57:14.821 Activating Pending Supervisor
Entry Msg = 12000P21
Exit Msg = <wid>6r641ichl21</wid>
</DEBUG>
<DEBUG>Supervi.. 06/03/2007 15:57:14.836 Attempt to send Pending Supervisor Entry Message <wid>22v1823m34</wid>
</DEBUG>
<MESSAGEOUT>15:57:14.836 - 06/03/2007 #0002 [12000P21]</MESSAGEOUT><END>

DebugLog provides trace stream logging in a test environment. The

Troubleshooting with trace information is displayed in windows and can be saved to file
DebugLog 12
automatically or manually. For information on installing and
configuring DebugLog, see “Installing and Configuring DebugLog”
on page 12‐16.
To start DebugLog select Start | All Programs | NCR APTRA |
Advance NDC | Tools | DebugLog.
The trace stream windows can be scrolled through, or saved. For
information on configuring save options, see “Configuring Auto
Save” on page 12‐17 and “Changing the Save All Destination” on
page 12‐18.

Caution: Do not re‐use filenames when saving the trace stream. Re‐using a
filename causes a sharing violation. If you save a DebugLog trace
with a specified name and continue tracing, when you save the trace
stream again you must use the Save As option and save the file
using a different filename.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 12-25

Installing and Configuring Troubleshooting Tools
Using the Troubleshooting Tools

Trace Stream Information 12

A window containing the trace stream messages for each trace

stream type is displayed in the DebugLog main window. To view
all trace stream windows simultaneously, select Tile from the
Window menu.

Reflected Messages 12

When a message is reflected (that is, the direction of the message is

changed) by a virtual controller, the message before reflection and
the message after reflection are recorded in the MESSAGEIN and
MESSAGEOUT trace streams of DebugLog. For more information on
the logging of reflected messages, refer to section, “Logging
Reflected Messages” in Chapter 9, “Developing Virtual Controllers”
of the APTRA Advance NDC, Extending the Product publication.

Note: Field separators can be displayed in various ways as they are

unprintable characters. For example, square boxes or ‘L’ shapes can
be used on‐screen and in files. In the APTRA Advance NDC, Reference
Manual, FS is used to represent field separators in Chapters 9 and
10, and a tilde (~) is used in Appendix D.

Invalid Screen Definitions 12

When an invalid screen definition is sent, the application accepts the

screen even though it has failed the validation. The application then
discards the screen, sends a Ready 9 message to the host, and
updates the date/time of custom.dat without saving the screen data
to it. The DebugLog trace stream messages do not include an entry
stating that a screen failed validation. The only indication of a
validation failure is a missing screen on the display.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

12-26 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Modifying the Advance NDC Applications

Chapter 13
Modifying the Advance NDC
Applications

Ways of Modifying Advance NDC 13‐2

Use an Existing Implementation 13‐2
Modify or Create an Implementation 13‐2

Programming Techniques 13‐4

C Exits 13‐4
Using the Author 13‐4
Script Host 13‐5
External C Function 13‐5
Web Exits 13‐6
New Worker Class 13‐6
Exposed Functions for PS Customisation 13‐6
Further Reading 13‐7

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Modifying the Advance NDC Applications

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Modifying the Advance NDC Applications
M

Overview

Overview 13

This chapter describes the various methods of modifying Advance

NDC. Which method you choose depends on the nature of the
change you plan to make, your experience and how much
re‐implementation will be required for future releases of Advance
NDC.
This chapter also considers whether development is necessary
For more information on modifying Advance NDC, refer to the
APTRA Advance NDC, Extending the Product publication.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 13-1

Modifying the Advance NDC Applications
Ways of Modifying Advance NDC

Ways of Modifying Advance NDC 13

Before starting to implement your particular modification to

Advance NDC, establish which of the following possible
approaches applies to you:
 Using an existing implementation
 Modifying an existing implementation
 Creating a new implementation.

If Advance NDC contains all the functionality required for a

Use an Existing particular customer environment, you can use Advance NDC as
Implementation 13
supplied by NCR. You will, however, still have to perform the usual
NDC+ modifications as follows:
 Define consumer transactions (create the appropriate states to
define the consumer flow, define consumer screens, FITs to
define card handling rules and so on)
 Define configuration parameters to control system behaviour
 Decide the configuration of the Supervisor when the application
is deployed and running.
These changes are regarded as customisations of Advance NDC and
are described in the APTRA Advance NDC Reference Manual and the
APTRA Advance NDC Supervisorʹs Guide. This type of modification is
not discussed in this chapter.

Modifying an existing implementation or creating a new

Modify or Create an implementation requires programming skills to modify an existing
Implementation 13
routine or write your own routine. These changes are regarded as
enhancing and extending Advance NDC.
For various enhancements or extensions to Advance NDC, different
programming techniques are available. They each require different
programming skills. Writing your own routine, called a C Exit,
requires knowledge of C or C++, but it can be used in future releases
of Advance NDC with no, or very little, re‐implementation.
Modifying the Advance NDC authored applications is easier but the
work will have to be re‐implemented when you move to a future
release of Advance NDC.

Note: Although it is possible to write C Exits using the APTRA

Author, NCR does not recommend it.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

13-2 APTRA Advance NDC, Developer’s Guide

 Modifying the Advance NDC Applications
Ways of Modifying Advance NDC

Before making programmatic changes consider the following:

 Will the functionality you want to add be available in a future
release of the product and in time for your requirements?
 Professional Services may have an implementation that could
meet your requirements.
 If you are a subscriber to the Advance NDC news group, you
can post a request for anyone who has implemented a similar, if
not identical, enhancement to send it to you. Even if it does not
provide exactly what you are looking for, it may be an excellent
starting point.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 13-3

Modifying the Advance NDC Applications
Programming Techniques

Programming Techniques 13

The two main techniques for enhancing or extending Advance NDC

are as follows:
 Writing C Exits (DLLs accessed through a specific exit interface)
 Using the APTRA Author to modify the authored flow using
one of various techniques, some of which will require less
re‐implementation in future releases of Advance NDC.

C Exits are called at predetermined points in the application flow. If

C Exits 13

these predetermined points are sufficiently flexible for your

modification, then a C Exit is likely to be the most appropriate
option.
Defining an Exit requires updates to one or more of the files that tell
Advance NDC which Supervisor functions or States are Advance
NDC standard, which are user written and where the user‐written
routines are to be found. For details of these control files, refer to the
APTRA Advance NDC, Extending the Product publication.
Configuration files allow you to link up the C Exits you have
developed with Advance NDC. There are a number of APIs
available for access to Advance NDC functionality.
If keyboard and screen handling are required, a C Exit can be
developed in the Author to take advantage of the support for
keyboards and screens and the predefined infrastructure.

The Author provides a graphical approach to software

Using the Author 13

development, with a diagrammatic representation of the application

flow.
Although using the Author can save time during the initial
implementation, a major disadvantage is the re‐implementation
effort required whenever you install service packs or move to a later
release of Advance NDC.
Various worker classes are provided to offer predefined
functionality and these can be used to create an application flow. A
list of workers classes developed for Advance NDC is given in
Appendix B, “Advance NDC Workers Supplied”. The worker class
help in the Author describes all workers. The APTRA Author User’s
Guide lists the workers supported in Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

13-4 APTRA Advance NDC, Developer’s Guide

 Modifying the Advance NDC Applications
Programming Techniques

There are different methods available to add missing functionality.

These methods can be considered implementation techniques in
their own right and are the following:
 Script host
 External C function
 New worker class
 Web exit

Script Host 13

You can use the Active Script Host worker class to make use of
COM objects and write VBScript to define the behaviour of the
Active Script Host worker.
As Active Script Host workers must be active to process events, care
is required when authoring a flow to ensure events are always
picked up and processed when they should be.
If your application flow will interface to a number of COM objects,
such as APTRA ActiveXFS objects, consider another
implementation technique rather than using Active Script Host
workers to drive the flow. For example, you can implement the
application flow, or a part of it, in Visual Basic (VB) and invoke the
VB COM object from a single Active Script Host worker containing
minimal VBScript.

Note: There is a limit on the amount of script data supported

within the Active Script Host, which may make this implementation
technique inappropriate for your development.
For more information about ActiveX exits, refer to the APTRA
Advance NDC, Extending the Product publication. For information about
ActiveX controls, refer to the APTRA Author User’s Guide.

External C Function 13

An external C function is different from a C Exit in the way it is

called. You use an Exit Condition Tester or an Assigner worker to
call the C function. The advantage is that a C function can be called
anywhere in the authored flow.
The C function can contain any code that can be written using the
Visual Studio 2005 compiler, provided the function is defined
within a DLL and invoked according to the C calling convention.

Note: The authored flow will need to be updated to call the new C
function, and if there is a change in the compiler and APIs used, the
C function will have to be re‐implemented.
If you have written a new State you can use STCONT to specify the
state, this means that you do not need to update the Customisation

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 13-5

Modifying the Advance NDC Applications
Programming Techniques

Layer for new releases as the state flow refers to the new state at
appropriate points. For information on STCONT, refer to the APTRA
Advance NDC, Extending the Product publication.

For more information, see Chapter 5, “Configuring Advance NDC

and Associated Components” and also refer to the APTRA ADE
Programmer’s Guide.

Note: The APTRA ADE Programmer’s Guide has not been updated for
the CEN‐XFS interface.

Web Exits 13

If you want to implement an HTML‐based flow, for example, for

transactions not available on the NDC host, use the Web Exit state
type for the call rather than the Web Page Loader. This will make for
easier migration in the future.
For keyboard and display separation, use the Display and Keyboard
hooks described in the APTRA Advance NDC, Extending the Product
publication.

New Worker Class 13

Developing a new worker class requires considerable effort and is

not recommended if there is a suitable alternative technique that can
be used instead. Consider whether you can combine existing
workers within a director to perform the required task, or write a C
Exit or external C function.
For more information, refer to the APTRA Author User’s Guide and the
APTRA ADE Programmer’s Guide.

Advance NDC provides few functions which can be accessed from

Exposed Functions for PS the customisations developed using Author Exits,
Customisation 13
C Exits and .Net Exits.

Table 13-1
External Functions exposed for
Customisation

Function Return Type Description

GetRetractCapability() Integer This function obtains the retract capability information of

Cash‐In devices.

Possible return values for this function are as follows:

 0 ‐ Device does not have retract capability.
 1 ‐ Device has retract capability.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

13-6 APTRA Advance NDC, Developer’s Guide

 Modifying the Advance NDC Applications
Programming Techniques

Function Return Type Description

GetEncashAuthorisationType() Integer This function obtains the encash authorisation type information
of Cash‐In devices.

Possible return values for this function are as follows:

 0 ‐ Cash deposit transaction is not authorised
 1 ‐ Cash deposit transaction is authorised online (encash
authorised by the host)
 2 ‐ Cash deposit transaction is authorised offline(offline
encash is in close state/Cash Deposit Handling state)

For the following information, refer to the APTRA Advance NDC,

Further Reading 13

Extending the Product publication:

 Benefits of the different types of exit and when to use them
 Impact of multi‐vendor functionality on C Exits.
For general guidelines on developing Author flows, refer to the
APTRA Author Userʹs Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide 13-7

Modifying the Advance NDC Applications
Programming Techniques

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

13-8 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Related Documentation

Appendix A
Related Documentation

Overview A‐1

Advance NDC Documentation A‐2

APTRA Author Documentation A‐4

NDC+ Documentation A‐6

Other NCR Documentation A‐7

CEN‐XFS Documentation A‐9

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Related Documentation

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Related Documentation
A

Overview

Overview A

This appendix lists the following documentation:

 Documentation provided with the Advance NDC CD‐ROM
 Documentation that is historically linked to Advance NDC, but
not provided on the Advance NDC CD‐ROM
 Documentation from other sources, such as optional
components and standards bodies. This documentation is not
provided on the Advance NDC CD‐ROM.
On a development system, the documentation can be installed alone
or installed with the Advance NDC software. The documentation is
not installed on a runtime system.
All APTRA product documentation is available under Start |
Programs | NCR APTRA | APTRA (TM) Documentation after the
relevant product has been installed.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide A-1

Related Documentation
Advance NDC Documentation

Advance NDC Documentation A

The following publications are provided on the Advance NDC

CD‐ROM. Printed versions can be ordered from the NCR
Publications web site.

Note: The Advance NDC Windows help files mentioned in

Appendix A are provided as part of the APTRA Author.

Table A-1
Advance NDC Documentation

Title Format Description

APTRA Advance NDC, Overview PDF/Paper Provides an introduction to Advance NDC,

B006‐6597 including overviews of the components contained
in the Advance NDC product and provided as
part of the ANDC Package on CD‐ROM.

APTRA Advance NDC, Developer’s Guide PDF/Paper Describes how to migrate to Advance NDC. It
B006‐6046 also identifies the functionality offered by
Advance NDC, and describes how to enhance it.

APTRA Advance NDC, Reference Manual PDF/Paper Provides application programmers with reference
B006‐6180 information for Advance NDC, including States,
Screens, and the message formats between
Central and the terminal.

APTRA Advance NDC, Multi‐Vendor PDF/Paper Provides users with information about running
Support Reference Manual the Advance NDC application on other vendors’
B006‐6344 SSTs, describing the differences between Advance
NDC on NCR SSTs and other vendors’ SSTs.

APTRA Advance NDC, Supervisor’s Guide PDF/Paper Describes the Supervisor interface, how to set up
B006‐6062 the terminal’s local configuration parameters, and
how to replenish the terminal.

APTRA Advance NDC, Extending the PDF/Paper Describes how to modify Advance NDC to ehance
Product or extend its functionality
B006‐6926

APTRA Advance NDC, User Guide for PDF/Paper Describes how to use the Display Manager for
Display Manager HTML pages to replace or overlay NDC screens.
B006‐6796

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

A-2 APTRA Advance NDC, Developer’s Guide

 Related Documentation
Advance NDC Documentation

Title Format Description

APTRA Advance NDC, Payment Application PDF Provides information on implementing an

Data Security Standard Advance NDC solution in compliance with PCI
Implementation Guide DSS
B006‐6861

NCR Security, Security on Windows NT, PDF/Paper Describes the installation and preconfiguration of
User’s Guide Security on an SST and development PC
B006‐6199

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide A-3

Related Documentation
APTRA Author Documentation

APTRA Author Documentation A

The APTRA Author is used in the development of Advance NDC

and can be used to modify the application.
The following titles are provided on the Advance NDC CD‐ROM to
support the use of the authoring environment. A printed version of
the PDF file can be ordered from the NCR Publications web site.

Table A-2
Provided Authoring Documentation

Title Format Description

APTRA Author, User’s Guide PDF/Paper Describes how to install and use the Author and Runtime
B006‐6038 Components to design, develop and maintain a self‐service
application.

APTRA Author Help Windows Context‐sensitive help for the Author user interface and
Help authoring errors.

Runtime Core Help Windows Context‐sensitive help for the Runtime Core Authoring
Help components and runtime errors, which are part of Advance
Core Self‐Service.

GUI Help Windows Context‐sensitive help for the GUI Authoring components,
Help which are part of Advance Core Self‐Service.

Self‐Service Core Help Windows Context‐sensitive help for the Self‐Service Core Authoring
Help components, which are part of Advance Core Self‐Service.

ActiveX™ Help Windows Context‐sensitive help for the ActiveX™ Authoring

Help components and runtime errors, which are part of Advance
Core Self‐Service.

Basic Self‐Service Help Windows Context‐sensitive help for the Authoring components and
Help runtime errors provided with Advance Basic Self‐Service.

ATM Help Windows Context‐sensitive help for the Authoring components and
Help runtime errors provided with Advance ATM.

Special Self‐Service Help Windows Context‐sensitive help for the Authoring components and
Help runtime errors provided with Advance Special Self‐Service.

Statement Printer Help Windows Context‐sensitive help for the Authoring components and
Help runtime errors provided with Advance Statement Printer.

Advance NDC Help Windows Context‐sensitive help for the Advance NDC Authoring
Help components (excluding Application Core components).

Advance NDC Application Windows Context‐sensitive help for the Application Core/Supervisor
Core Help Help Authoring components.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

A-4 APTRA Advance NDC, Developer’s Guide

 Related Documentation
APTRA Author Documentation

The PDF publications in Table A‐3 are not provided on the Advance
NDC CD‐ROM. These publications have not been updated, but may
be useful if you intend using the Author to extend Advance NDC.
Printed versions can be ordered from NCR Publications web site.

Note: NCR recommends the use of C Exits to extend Advance

NDC.

Table A-3
Additional Authoring Documentation

Title Format Description

APTRA Advance ADE, Programmer’s PDF/Paper Describes how application programmers should create
Guide their own C++ Worker Classes. It also contains
B006‐6042 information on using C routines to manipulate data.

APTRA Advance ADE, C++ Class PDF/Paper Provides application programmers with definitions for
Reference a number of C++ Runtime and Utility Worker Classes
B006‐6043 provided by NCR.

APTRA Advance ADE, Local Language PDF/Paper Describes how to customise the APTRA Advance ADE
Customisation Guide product into a local language.
B006‐6037

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide A-5

Related Documentation
NDC+ Documentation

NDC+ Documentation A

The publications in the following table are not provided on the

Advance NDC CD‐ROM but are listed here for reference. They are
available from NCR on request.

Table A-4
Additional NDC+ Documentation

Title Format Description

NDC, Programmer’s Overview PDF Provides an introduction to, and overview

B006‐2485 of, the NDC software.

NDC+, Programmer’s Reference Manual PDF/ Aimed at programmers who write host or
B006‐2486 Paper switch applications to support NDC+
terminals, or who create the terminal
configuration that customises NDC+.

NDC, Message Formats For Host Application PDF/ Designed for Central control application
Developers Paper developers working with NDC RMX,
B006‐4201 NDCxa or NDC+. Intended to help in
creating a control program that handles all
the NDC variants.

NDC+, Supervisor’s Reference Manual PDF/ Designed for those people who are
B006‐2487 Paper responsible for setting up the terminal’s
local configuration parameters, or for
routine replenishment of the terminal.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

A-6 APTRA Advance NDC, Developer’s Guide

 Related Documentation
Other NCR Documentation

Other NCR Documentation A

The publications in the following table are provided with the

software component to which they refer. Printed versions of the first
two titles can be ordered from the NCR Publications web site.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide A-7

Related Documentation
Other NCR Documentation

Table A-5
Other NCR Documentation

Product Title Format Description

APTRA XFS NCR Self‐Service Support, PDF/Paper Describes the functions that are used to perform
System Application User configuration and maintenance on an SST.
Guide
B006‐6167

APTRA Documentation HTML Help On‐line help for the Communications

CCM TCPIP (CHM) Connection Manager TCP/IP module.

APTRA Documentation HTML Help On‐line help for Communications Connection

CCM PCCM (CHM) Manager PCCM module.

APTRA Generic APTRA Communications PDF Describes how to use the Communications
Communications Feature, User’s Guide Feature software, which provides the files and
Release B006‐0012 registry settings required to run any PC
Communications Module (PCCM)
communications protocol on APTRA XFS.

APTRA SNMP APTRA SNMP Agent PDF/Paper Describes the management information exposed
Agent Reference Manual by the SNMP Agent: the NCR SST MIB, SNMP
B006‐6017 Traps, the Event Log Agent and SNMP Errors.

EMV/CAM2 EMV Integrated Circuit PDF/Paper Provides reference information for any APTRA
Exits for APTRA Card (ICC) Reference Advance NDC developer who wishes to add
Advance NDC Manual EMV Integrated Circuit Card (ICC) Card
B006‐6297 Authentication Method (CAM) functionality to
their Advance NDC application.

APTRA Promote User’s Guide PDF/Paper Describes how to use APTRA Promote, and lists
B006‐6309 the flow points supported for Advance NDC.

APTRA Relate APTRA Relate Overview PDF/Paper Provides an introduction to APTRA Relate.

ActiveXFS ActiveXFS Controls Microsoft Context‐sensitive help and reference for

Controls On‐line Documentation HTML Help ActiveXFS Controls
(CHM)

NCR XFS XFS Simulator HTML Help Context‐sensitive help for the XFS Simulator.
Simulator for
APTRA

If you are developing C Exits, the following PDF publication is

available for internal download from the NCR Publications web site:
Self‐Service Platform Software, C Programmer’s Reference Manual
B006‐4589‐A

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

A-8 APTRA Advance NDC, Developer’s Guide

 Related Documentation
CEN-XFS Documentation

CEN‐XFS Documentation A

For device access, Advance NDC supports release 3.0x (3.10 for
Item Processing Module) of the CEN‐XFS specification.
http://www.cen.eu/pages/default.aspx
More information about CEN‐XFS specifications is available at
http://www.cen.eu/pages/default.aspx.

Table A-6
CEN-XFS Documentation

Title Format Description

Extensions for Financial Services PDF or zipped PDF Provides reference information for
(XFS) interface specification CEN‐XFS specifications, release
(CWA 14050) 3.0x or 3.10.

XFS Clarifications for Device Class Word Provides additional information

Interfaces for the CEN‐XFS specifications

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide A-9

Related Documentation
CEN-XFS Documentation

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

A-10 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Advance NDC Workers Supplied

Appendix B
Advance NDC Workers Supplied

Overview B‐1

Customisation Layer Workers B‐2

NDC Core Workers B‐4

Application Core Workers B‐9

Passbook Printer Workers B‐12

Voice Guidance Workers B‐14

Miscellaneous Workers B‐15

Basic Self‐Service B‐15
Special Self‐Service B‐16
Self‐Service Core B‐16
MSSA Workers B‐16
Secure Workers B‐17
ATM B‐17

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Advance NDC Workers Supplied

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
B

Overview

Overview B

To enhance the provided Advance NDC application, you link

workers together in the APTRA Author GUI. Workers are the
components in an authored application. They are designed for
maximum re‐use, and so reduce the effort and time required to
develop your enhancements.
NDC‐specific workers are provided for the following authored
projects:
 CustomisationLayer.mpj
 ApplicationCore.mpj
 Supervisor.mpj.
Worker classes only are provided for the passbook printer, enabling
you to develop an authored flow for passbook transactions.
For detailed descriptions of all the provided workers, including
their attributes, signals, and work groups, refer to the on‐line help in
the APTRA Author.

For details of workers supported, modified and unsupported in

Advance NDC, refer to the APTRA Author, User’s Guide, Appendix
B, “Advance NDC Worker Support”.

Note: Additional Advance NDC worker classes (not listed here)

exist for inheritance purposes only. These worker classes are called
abstract classes; you cannot create an instance of an abstract class.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-1

Advance NDC Workers Supplied
Customisation Layer Workers

Customisation Layer Workers B

The Exit Condition Tester signals Exit From Flow True, when a
State Number/Type in its Exit List attribute matches the Common
Integer Store’s ‘Current State Number’ or ‘Current State Type’.
The NDC Close State Executor is used to execute an NDC+ State
Type Flow between the Close State and State Number 0. It offers a
choice of two methods to remove the last NDC+ screen, before
returning to the Author flow. It exits on a set of conditions checked
for by an Exit Condition Tester worker.
The NDC CRM Interface worker is used in customer relationship
management (Promote and Relate) to invoke a CRM flow point and
inform CRM of application events such as a campaign failure,
interruption or is cancellation. It can also be used to inform the NDC
CRM of readiness for a coupon to be printed.
The NDC Data Collector allows the front keyboard and front FDKs
to be enabled for data collection, and data to be echoed to the screen
during data entry.
The NDC Echo worker allows data to be displayed on the NDC
screen, and stored as a string on completion of data entry.

The NDC PIN Collector allows the customer to enter a Personal

Identification Number (PIN). It displays an NDC screen determined
by the state download for the state type, and waits until a PIN is
entered or a timeout occurs.
The NDC Print Coupon worker sends a coupon image file to the
USB receipt printer, using the specified BMP file name and XFS
form. For other image file formats, such as PFM, use a Variable
Graphics Paragraph worker.
The NDC Print Footer worker is used in the Close state to print any
remaining preprint information as a receipt footer and eject the
receipt.
The NDC Processing State Executor is used to execute NDC+ State
Types after a card has been entered, and signals when the next state
to be executed is a Transaction Request or Close State. It exits on a
set of conditions checked for by an Exit Condition Tester worker.
The NDC Timeout State Executor performs the same functionality
as the NDC+ Timeout State. Screen C00 is displayed, giving the
cardholder the option of selecting more time in the transaction, and

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-2 APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
Customisation Layer Workers

an intermittent beep is sounded. Whichever key is pressed, the beep

is stopped before signalling.
The PIN Retries Updater reads the integer data supplied by the
worker in its Retry Count work group, and uses it to update the
retry count data stores. This worker only updates the Retry Count
and Card Track Data Stores; the Card Track Data is not written to
the card.
The Random PAD Character worker supplies a random PAD
character in the range hex ‘0’ to ‘F’.

The Receipt Control worker captures the receipt currently at the

exit of the receipt printer. It can be used as follows:
 When a cut receipt has been printed but has to be captured; for
example, when the receipt printer is initialised at start of day
and a receipt is in the transport or at the exit.
 When a receipt has been ejected but not removed.
The Session Releaser worker, when active, allows the Application
Core to regain control of the cardholder session from the
Customisation Layer, by signalling when a mode change occurs.
The XFS Front FDK worker has the following two uses:
 If used within the NDC Data Collector worker, it provides the
key codes to use as part of the data input process.
 If used concurrently with an NDC Data Collector, detects key
presses based on the FDK Key Code attribute or Dynamic Key
Code work group.
The XFS Front Key worker can be used to enable and detect any key
or group of keys on the cardholder keyboard.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-3

Advance NDC Workers Supplied
NDC Core Workers

NDC Core Workers B

These workers may be used by one or more of the three APTRA

Author projects.
The Common Integer Store worker stores a piece of integer data,
enabling access to the data from within any authored application.
This worker class can be used anywhere an Integer Giver or Integer
Receiver can.
The Common Real Store worker stores a piece of real data, enabling
access to the data from within any authored application. This
worker class can be used anywhere a Real Giver or Real Receiver
can.
The Common String Store worker stores a piece of string data,
enabling access to the data from within any authored application.
This worker class can be used anywhere a String Giver or String
Receiver can.
The Configuration Data Saver worker processes data received in a
Configuration Parameters Load, Enhanced Configuration
Parameters Load, or MAC Field Selection Load message. It saves the
configuration data, specified by the String Giver worker in its
Config Data work group.
The Customisation Data Decomposer worker validates and stores
NDC+ customisation data, as specified by the String Giver in its
Custom Data work group.
It can handle data from the following messages:
 State Table Load
 Screen/keyboard Load
 FIT Data Load
 Override Reserved Screen Configuration.
The Customisation Data Initialiser worker initialises the Advance
NDC customisation data to default values, or to previously
downloaded and saved values, according to the Configuration ID.
A signal is produced on completion of the customisation data
initialisation.
The Customisation Data Saver worker saves the NDC+
Customisation Data, which includes the State Tables, Screen,
Keyboard and FIT customisation data, to disk. It ensures the data is
saved across any power failure, avoiding the need to download the
data from Central on power‐up.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-4 APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
NDC Core Workers

The Debug Message Sender worker allows application debug

messages to be sent to a server program (DebugLog) where they can
be displayed while the application runs.
The Disk Size Getter worker determines the size in bytes of the disk
specified by its Drive attribute.

The FIT Searcher worker is used to perform an NDC+ FIT match.

This worker searches the Financial Institution Table (FIT) for a valid
match, using information in tracks 1, 2 and 3. The search terminates
on the first match.
The Generic Exit Executor worker loads and executes the function
specified in the MISCONT control file. The Completed signal is
produced after this has been done. If the MISCONT control file does
not exist, this worker does nothing, and the Completed signal is
immediately produced.
The Integer Array Element worker provides access to one element
of a CDI array.

The Journal Security Trace Generator worker sequentially

generates and returns a new security trace number which is
required when printing status messages to the journal printer. This
worker is used within Journal Page workers, when Security Trace
Messages require printing within Advance NDC.
The Linked FIT Loader worker retrieves the next FIT Record from
the downloaded table of FIT Records. The selected FIT Record is
compared with the PIDDX, PFIID, PCKLN and PINDX fields to
determine whether it is a linked FIT Record.

Note: Linked FITs are not supported by Advance NDC.

The NDC Command Reject Message Builder worker builds a
Command Reject or Specific Command Reject Solicited Status
Message, in NDC+ defined format. The message is stored by a
String Receiver in the Message work group, before a Message Built
signal is produced. Send using an NDC Message Sender worker.
The NDC Comms Connection ID worker uses the APTRA Comms
Connection Manager (CCM) for communication with Central. By
default, it uses the connection name ʹTPA Connectionʹ, unless this is
overwritten by setting the Name attribute. There must be only one
instance of this worker for each connection.
The NDC Delete RSA Key worker extracts the key data and
signature from the Key Data work group. The data is decoded using
the Base 94 encoding method and used to delete the RSA public key
and signature in the encryptor.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-5

Advance NDC Workers Supplied
NDC Core Workers

The NDC Device Status Message Handler worker determines

which Device Fault Status messages need to be sent to Central, and
then builds and sends them.
This worker provides the option to send both Unsolicited and
Solicited messages, or only Unsolicited messages.
The NDC EPP Delete Key worker is used with the EPP to delete a
specified key and update its status in the encryptor.
The NDC EPP Initialiser worker is used only at Start Of Day to
initialise the encryptor in the EPP (Encrypting PIN Pad). It checks
the state of the Encryptor key spaces, and if required, initialises
them.
The NDC EPP Key Mode Initialiser worker is used with the EPP
after a key mode change has been confirmed, using the supervisor
Access menu function ʹ25 KEY ENTRYʹ. This worker determines
whether the requested EPP key mode is different from the current
mode held in the encryptor. If necessary, the key spaces are
initialised for the new mode.
The NDC EPP KVV Evaluator worker is used with the EPP to
generate the KVV (Key Verification Value) that confirms the correct
loading of a specified encryption key.
The NDC Export Encryptor Data worker checks the Data to Export
attribute to determine the data to retrieve from the encryptor (fixed
or variable serial number, remote key protocol, capabilities/status ,
certificate information or EPP attributes) and sends the command to
the encryptor. The retrieved data is stored in the Results work
group (fixed or variable serial number, EPP public key, EPP
capabilities, EPP attributes, ATM random number, or certificate
information) and the Signature work group (signature or status).
The EPP attributes can be returned to the host to determine whether
the EPP is PCI‐compliant.
The NDC Field worker is used in the NDC Field work group of an
NDC Transaction Handler worker, to signify the inclusion of a
specific optional field in a Transaction Request message. The NDC
Field ID attribute specifies the ID of the represented component
field.
The NDC Import RSA Key worker loads any type of RSA public
key (Host Public Key or NCR Sub Key) into the encryptor in the
Encrypting PIN Pad (EPP). The key data and signature are obtained
from the worker in its Key Data work group, The data is decoded
using the Base 94 encoding method, and then used to load the RSA
public key and signature into the encryptor.
The NDC Message Receiver worker receives a message from the
Virtual Message Buffer, or comms connection via the Virtual

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-6 APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
NDC Core Workers

Controller. The message is stored in a String Receiver in its Mailbox

work group. Since any virtual reply is stored in the Virtual Message
Buffer, it is used with an NDC Message Sender.
The NDC Message Sender worker sends a message to the Central
application or Virtual Controller. The message is specified and
stored using a String Giver worker in its Parcel work group. Since
any virtual reply is stored in the Virtual Message Buffer, this worker
must be used with the NDC Message Receiver worker.
The NDC Print Buffers worker processes and prints the data
received in the last Transaction Reply message, to the printer(s)
specified by its Print Flag attribute. The worker signals Complete
when printing of the required Print Buffers is complete.
The NDC Print Immediate Handler worker executes a Print
Immediate message, supplied by the String Receiver in the Message
work group. If a Transaction Reply message is successfully received
and validated in the Tr Reply Function work group, the relevant
Function is selected by its ID, and executed.
The NDC Printer Initialiser worker sends printer configuration
data to the associated printers. It signals Successful after the data
has been sent.
The NDC Ready 9/B Message Builder worker builds either a Ready
9 or Ready B Solicited Status Message. The default message type is
Ready 9; a Ready B message is only used within Advance NDC in
response to a Transaction Reply Message, if the relevant
configuration option has been set.
The NDC RSA Import DES Key worker loads one of the DES keys
(A Key, B Key or V Key) into the encryptor in the encrypting PIN
pad (EPP). The A, B or V Key to be loaded is specified in the
Destination work group, and the relevant key data and signature is
contained in the Key Data work group.
The NDC Screen Displayer worker enables the re‐use and display
of previously downloaded NDC+ screen definitions, in any
authored part of your Advance NDC application. You can specify
customised screens using the Screen Number work group, or
reserved screens using the Reserved Screen attribute.
The NDC Terminal State Message Builder worker is used to build
a Terminal State Solicited Status Message, and store it using a String
Receiver in its Message work group. The Status Information work
group uses a String Giver to hold data for inclusion in a Terminal
State Solicited Status Message. Send using an NDC Message Sender
worker.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-7

Advance NDC Workers Supplied
NDC Core Workers

The NDC Transaction Handler worker enables execution of the

complete Transaction Request/Reply sequence. It can be used as an
alternative to the Transaction Request State worker.
The Note Definitions Builder worker is used to buildand store a
definition of the notes which are to be accepted by the SST.

The Register Trace Generator worker configures the Journal

Configurator worker to generate a security trace header each time a
message is printed during a journal print backup operation.
The RSA Key worker uses the Key Name attribute to obtain the key
name or the signature key name of the RSA key to be imported or
deleted.
The Supervisor Exit Executor worker is used after each
menu/function selection, to implement the functionality in the Exit
function or .NET Supervisor task. If the control file specifies that a
defined supervisor function is supported by an Exit or .NET
Supervisor task, an Executed signal is produced; otherwise Not
Executed is signalled.
The TCP/IP Comms Connection ID worker is no longer supported,
but may remain referenced within any application, in the NDC
Comms Connection ID worker.
The Tr Reply Function worker executes a specific Transaction
Reply (for example, Card Before Cash). It is used within the Tr
Reply Function work group of an NDC Transaction Handler or Transaction
Request State worker.

The Track 1 Decomposer worker should only be used if you require

to decompose Track 1 data, and replace the provided NDC+ Card
Read State with your own card entry, read and FIT match. The
decomposed data is stored in workers in its work groups in the
appropriate format. Track 1 sentinels are ignored.
The Transaction Request State worker enables execution of the
Transaction Request State. It builds messages using the State Table
parameters for current State Number and Configuration
Parameters. It ensures that Unsolicited and Solicited Device Fault
Status messages are sent in the correct order.
The XML Config File Loader worker is used to load the XML
configuration file. It takes data from the Config Data work group
and loads it into an XML file, validates the data against a schema
and, if valid, saves the XML file to the hard disk.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-8 APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
Application Core Workers

Application Core Workers B

The Data Encoding Converter worker prepares key data in an

Encryption Key Change message to put into a Key Exchange
worker, or a VISA key table. It takes the data in the Data In work
group, converts it using the Input Encoding and Output Encoding
attributes, and stores the result in the Data Out work group. If the
data conversion is unsuccessful, the Error Code work group is
updated with a value indicating the reason for failure.
The NDC Application Terminator worker generates an mError. It
does not complete due to the mError terminating the application.
The Error Number work group contains an integer store which
specifies the type of mError.
The NDC Configuration Info Builder worker attempts to obtain
the terminal’s configuration information (hardware configuration,
fitness, supplies status and sensor states), and store it using the
String Receiver worker in its Status Information work group. This
information is used to build the Terminal State response message
for a ‘Send Configuration Information’ command.
The NDC Counters Builder worker obtains and stores the
terminal’s media count information using a String Receiver worker
in its Status Information work group.
This information can include counts of currency, coins, documents,
envelopes, camera film, captured cards and number of transactions.
This information is used to build the Terminal State response
message for a ‘Send Supply Counters’ command.
The NDC DES Loader worker provides the ability to load secret
keys from clear data, which is needed to emulate the NDC+
supervisor functions Write A, B and V keys. The worker places the
clear data supplied by the String Giver in its Data work group into
the Programmer/Secret Key or Initialisation Vector in the
Destination work group, packing the entered key according to
whether it is single or double length.
The NDC Dialup worker controls access to starting and stopping
sessions and transactions for dialup communications

The NDC Error Log Builder worker obtains error log information
for the log group specified in its Log Group work group, and stores
it using a String Receiver worker in its Status Information work
group. This information is used to build the Terminal State response
message for a ‘Send Error Log’ command.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-9

Advance NDC Workers Supplied
Application Core Workers

Note: Advance NDC 3.0 returns a preconfigured default date and

zero values.

The NDC Fitness Data Builder worker obtains fitness information

for the terminal devices and stores it using a String Receiver worker
in its Status Information work group. This information is used to
build the response message for a ‘Send Fitness Data’ command.
The NDC Hardware Config Builder worker obtains terminal
hardware configuration information and stores it using a String
Receiver worker in its Status Information work group. This
information is used to build the Terminal State response message
for a ‘Send Hardware Configuration Data’ command.
The NDC Message Validator worker validates the message format
of data held in its Message work group, which is typically a
complete NDC+ message from the host.
The process of validation depends on whether the message is a
Terminal Command, Configuration Data Load, Transaction Reply
or Virtual Controller message.
The NDC Sensors Status Builder worker obtains information on
the state of terminal sensors and tamper indicating devices, and
stores it in a String Receiver in its Status Information work group.
This information is used to build the Terminal State response
message for a ‘Send Tamper and Sensor Status Data’ command.
The NDC Supplies Data Builder worker obtains the terminal’s
media supplies information, and stores it using the String Receiver
worker in its Status Information work group. This information is
used to build the Terminal State response message for a ‘Send
Supplies Data’ command.
The NDC Tally Builder worker obtains tally information for the
device specified in its Device work group, and stores it using the
String Receiver worker in its Status Information work group. This
information is used to build the Terminal State response message
for a ‘Send Tallies’ command.

Note: Advance NDC 3.0 returns a preconfigured date and zero

values.

The Reserved Screen Retriever worker returns the specified NDC

Reserved Screen data, taken from the RESRVD.DEF file.
You would typically use this worker in Supervisor Mode to retrieve
data for display or printing.
The Resource Status Checker worker reports the status of all
devices in the Resources to Report work group. It produces a
multi‐line customisable report, using the Fault Display reserved

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-10 APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
Application Core Workers

screens. The status always reports error status messages and can be
configured to report good status messages.
The Supplies Data Formatter worker builds a string containing a
description of any replenishable Self‐Service Terminal devices
currently requiring attention.
It is used only during execution of the ʹDisplay Supplies and ʹPrint
Suppliesʹ Supervisor functions.
If all the device supplies are good, this worker returns a string
indicating ʹALL SUPPLIES GOODʹ.
The UPS worker is used for an uninterruptible power supply (UPS)
device, enabling the SST to complete a transaction on battery power
if the mains supply fails before going out of service, or shut down in
a controlled manner. When activated with a state, this worker
generates a detected signal if the state matches the actual UPS
device state.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-11

Advance NDC Workers Supplied
Passbook Printer Workers

Passbook Printer Workers B

The following worker classes are available in Advance NDC for the
development of an authored flow to support passbook transactions.
The Line Number Store worker stores the line number of the next
available line for printing, letting you specify the line number on
which printing is to start.
The Page Number Store worker stores the number of the page at
which the passbook is currently opened. A value of 0 indicates that
the page number cannot be determined.
The Passbook Acceptor worker looks for a form definition file
corresponding to the passbook ID and, if successful, lets a passbook
into the passbook printer. Once successfully accepted, the passbook
magnetic stripe is read and stored for later use.
The Passbook Capture worker attempts to capture the passbook.

The Passbook Definer worker contains a set of valid passbook

definitions, which it updates before the main transaction loop is
entered.
The Passbook Definition worker contains the attributes which
make up the passbook definition.
A default passbook definition is provided, which is returned if no
other form definition is found.
The Passbook Ejector worker attempts to eject the passbook.

The Passbook Page Turner worker turns the number of specified

pages. If the number is positive, the pages are turned forwards; if
negative, the pages are turned backwards.
The Passbook Printer worker prints one or more lines of data on the
passbook. After printing, this worker updates the Line Number
(used by the Line Number Store worker) with the number of the
next line to print on. If a new page is required, the number equals 1.
The Passbook Printer Checker worker determines the type of
passbook printer installed on the terminal, and can be used where
both page turning and non‐page turning printers are installed, so
that a single application can handle both types of printer.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-12 APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
Passbook Printer Workers

The Passbook Reader worker returns the passbook magnetic stripe

data read by the Passbook Acceptor worker on entry of the
passbook.
The Passbook Resource ID worker can be used in any work group
that accepts Resource ID workers. This allows the Fitness Getter and
Resource Initialiser workers to be used for a passbook printer.
The Passbook Writer worker writes data to the passbook magnetic
stripe.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-13

Advance NDC Workers Supplied
Voice Guidance Workers

Voice Guidance Workers B

The following workers are available in Advance NDC for the

development of an authored flow to support voice guidance
sessions.
The Audio Jack Detector worker signals when the audio jack status
matches the State attribute.

The Audio Resource ID worker retrieves the fitness or variant of

the audio device.

The Audio Speaker worker plays the audio for either the specified
Recorded Voice file (*.wav) or the text to be played by the Text To
Speech (TTS) software.

The NDC Audio Speaker worker plays the audio for a specified
audio ID in the voice guidance XML configuration file.

The Volume Adjuster worker can either set or obtain the audio
volume for a voice guidance session.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-14 APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
Miscellaneous Workers

Miscellaneous Workers B

The following lists some of the workers in other Catalogs used in

the Advance NDC authored flows.
For detailed descriptions of all the workers, including their
attributes, signals, and work groups, refer to the on‐line help in the
APTRA Author.

Basic Self‐Service B

The Card ATR Reader, used for a DASH reader, gets the Answer to
Reset from the chip on the card and stores it.

The Cheque Acceptor worker enables the CPM for cheque

acceptance, reads and stores the codeline from the cheque and scans
an image of the front and/or back of the cheque in BMP format to
specified files.
The Cheque Capture worker captures a cheque and prints any
required data on the back of the cheque before depositing the
cheque in the specified bin.
The Cheque Ejector worker ejects cheques, while displaying a
prompt to the card holder. If the cheque is not taken, it is left or
retracted depending on the CPM variant.
The CPM Initialise worker sends the Reset command to the CPM,
attempting to clear the device fault and return the CPM to a known
good state and available for use.
The CPM Resource ID worker is used to determine whether either a
CPM or a bunch cheque acceptor is present. It also enables the
fitness of the cheque processor to be checked when used in the
Fitness Getter worker.
The CPM TI (Cheque Processing Module Tamper Indication)
worker is used to detect the removal or insertion of a CPM bin.

The Resource Initialiser worker checks the type of reset required

for the devices included in its Resources to Check workgroup and
sends the appropriate XFS reset or 24‐volt reset command to SST
devices that indicate a reset is required to recover from an error
situation.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-15

Advance NDC Workers Supplied
Miscellaneous Workers

The Secure Encryption Key Collector collects the encryption key

data securely from the keyboard, and returns the KVV value for the
entered key.
This allows manual entry of a full‐length, symmetric encryption key
part directly into the PIN Pad, without it being exposed outside the
PIN Pad.
The Variable Graphics Paragraph worker specifies a variable
graphics file, for example a coupon, to the printer coordinator. For a
fixed graphic, the Graphics Print Paragraph worker is used. For
USB receipt printers, Advance NDC uses the NDC Print Coupon
worker.

Special Self‐Service B

The Barcode Reader worker is used to read barcode information.

After the barcode has been read by the device the worker stores the
result and produces a success signal. If there is any problem with
the device the worker produces a failed signal.
The Barcode Reader Resource ID worker is used with resource
management classes to provide management for the Barcode
Reader device. This worker class can be used in any work group
that accepts Resource Identifier workers.

Self‐Service Core B

The Cancel Collector signals Complete if the Cancel key is pressed,

to indicate that data collection is complete.

The SMS Data Collector supports SMS‐style input in the

Supervisor application, on either the consumer interface or the
EOP/GOP. It also supports PC keyboard input, if one is available,
and can be configured through the SupervisorKeyboard.xml file,
which is described in “Supervisor Keyboard XML Configuration
File” on page 5‐106.
The Supervisor Task Executor allows a specified .NET Supervisor
task to be executed anywhere in the application flow. It configures
the .NET Supervisor task by specifying the current operator
interface and printer to be used.

MSSA Workers B

Mini Self‐Service Assistant (MSSA) workers are provided for an

on‐screen short‐cut for entering vendor‐dependent mode (VDM).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-16 APTRA Advance NDC, Developer’s Guide

 Advance NDC Workers Supplied
Miscellaneous Workers

The Supervisor Mast Host worker displays an icon on the front

interface while the Supervisor Select menu is displayed on the front
interface. On a touch screen, the icon can be pressed, otherwise it is
aligned to FDK C.
The VDM Entry Listener waits for a request to enter Vendor
Dependent Mode (VDM) and signals either that it is safe to enter
Diagnostics or that another task is currently running.
The VDM Negotiator checks the current status of VDM and signal
immediately VDM is inactive.
The VDM resource ID worker is used to report the status of the
VDM Entry request. This worker class can be used in any work
group that accepts Resource Identifier workers.

Secure Workers B

Workers in the Secure Workers catalog are used to hold sensitive

data, as defined by the Payment Card Industry Data Security
Standard (PCI DSS). They ensure that memory is automatically
cleared after the data is processed.
The Secure Authenticator validates logon credentials (user name
and password) against the Windows User Account database.

The Secure Password Changer allows a user’s password to be

changed if the user is in the Windows User Account database; for
example, if the password has expired.
The Secure String Store worker stores sensitive data entered by the
user.

ATM B

The Cash Taken worker indicates when the cardholder has taken
the cash from either the primary or secondary cash handler,
whether or not the retract capability has been enabled.
The Coin Dispenser worker is used in coin dispensing operations
from one or more coin hopper types.

The Extended Cash Stacker worker stacks a specified number of

notes from each cassette type in preparation for presenting them to
the cardholder.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide B-17

Advance NDC Workers Supplied
Miscellaneous Workers

The First Cash Handler Resource ID worker is a Cash Handler

Resource ID for use with a dual cash handler, and returns
information about the first dispenser.
The Second Cash Handler Resource ID worker is a Cash Handler
Resource ID for use with a dual cash handler, and returns
information about the second dispenser.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

B-18 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Common Data Interface Stores

Appendix C
Common Data Interface Stores

Overview C‐1

Barcode C‐3

BNA Accepted Denomination Counts C‐4

BNA Active Banknotes C‐5

BNA Counters C‐6

BNA Denomination Configuration C‐8

BNA Deposited Denomination Counts C‐9

BNA MISC C‐10

Buffers C‐12

Coin Counters C‐14

CPM C‐15

CPM MISC C‐16

Dial up C‐17

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Common Data Interface Stores

EJ Upload C‐19

EMV C‐20

Encryptor Variant C‐21

Error Processing C‐22

Exit Migration C‐23

FIT Data C‐25

Key Entry Mode C‐29

Misc Counters C‐30

Note Counters C‐31

Option Digit Stores C‐34

Printing C‐35

Screen Display C‐37

Security C‐38

State Information C‐41

Supervisor C‐44

Terminal Configuration C‐47

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Table of Contents
Common Data Interface Stores

Timers C‐51

Transaction Processing Flags C‐53

UCDI Stores C‐55

Voice Guidance Stores C‐56

Miscellaneous CDIs C‐57

Accessing CDI Store Values C‐58

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Common Data Interface Stores

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
C

Overview

Overview C

As discussed in Chapter 1, “Introducing Advance NDC”, under the

heading “Common Data Interface” on page 1‐11, the Common Data
Interface (CDI) and User‐defined Common Data Interface (UCDI)
consist of stores representing all of the data used throughout the
Advance NDC application. There are several hundred CDI store
workers, one for each piece of data.
The CDI stores are grouped into the following “CDI ‐ <name>”
catalogs:
 CDI ‐ Barcode
 CDI ‐ BNA Accepted Denomination Counts
 CDI ‐ BNA Active Banknotes
 CDI ‐ BNA Denomination Configuration
 CDI ‐ BNA Deposited Denomination Counts
 CDI ‐ BNA MISC
 CDI ‐ Buffers
 CDI ‐ Coin Counters
 CDI ‐ CPM
 CDI ‐ CPM MISC
 CDI ‐ Dial up
 CDI ‐ EJ Upload
 CDI ‐ EMV
 CDI ‐ Encryptor Variant
 CDI ‐ Error Processing
 CDI ‐ Exit Migration
 CDI ‐ FIT Data
 CDI ‐ Key Entry Mode
 CDI ‐ Misc Counters
 CDI ‐ Note Counters
 CDI ‐ Option Digits
 CDI ‐ Printing
 CDI ‐ Screen Display
 CDI ‐ Security
 CDI ‐ State Information
 CDI ‐ Supervisor
 CDI ‐ Terminal Configuration
 CDI ‐ Timers
 CDI ‐ Transaction Processing Flags.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-1

Common Data Interface Stores
Overview

Note: There is also a CDI ‐ Document Processing catalog. This

catalog contains data related to the Document Processing Module
(DPM), which is unsupported in Advance NDC.

There are also CDIs, used by cash acceptors and recycling units, that
are outside of catalogs.
The following sections give brief descriptions of all the CDI stores
and UCDI stores provided with Advance NDC.

Note: All CDIs related to counts, fitness or device variant

information supplied by the XFS service providers are read‐only.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-2 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Barcode

Barcode C

Table C-1
Barcode

CDI Store Worker Description

Barcode Buffer This holds the barcode that has been read

Barcode Format This holds the format of the barcode

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-3

Common Data Interface Stores
BNA Accepted Denomination Counts

BNA Accepted Denomination

Counts C

The counts in the following integer CDIs are read‐only.

Table C-2
BNA Accepted Denomination Counts

CDI Store Worker

Description
(Index)

Accept Count 1 This is used to hold the number of notes accepted for note type 1.
(3225)

Accept Count 2 This is used to hold the number of notes accepted for note type 2.
(3226)

... ...

Accept Count 50 This is used to hold the number of notes accepted for note type 50.
(3274)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-4 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
BNA Active Banknotes

BNA Active Banknotes C

The following integer CDIs are read‐only.

Table C-3
BNA Active Banknotes

CDI Store Worker

Description
(Index)

Note 1 Active This specifies whether denomination type 1 is active.

(1266)

Note 2 Active This specifies whether denomination type 2 is active.

(1267)

... ...

Note 50 Active This specifies whether denomination type 50 is active.

(1315)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-5

Common Data Interface Stores
BNA Counters

BNA Counters C

Table C-4
BNA Counters

CDI Store Worker

Description
(Index)

Total Notes Encashed Total cumulative count of all vaulted notes

(3214)

Total Notes Refunded Total cumulative count of all refunded good notes
(3215)

Total Notes to Escrow Total cumulative count of notes that have been in escrow, whether later
(3216) vaulted or refunded

Total Notes Rejected Total cumulative count of all rejected notes

(3217)

BNA Retract Count Total Total notes retracted during a deposit transaction
(3765)

Reject Bin Total Reports the Notes in Transport field in the Display Counters Supervisor
(3347) option
Contains the cumulative count of notes moved to the reject bin on cash
acceptors

Cash‐In Retract Operations Holds the number of cash‐in retract operations

(1371)

Offline Encash Total Holds the total count of offline encash operations
(3776)

Last Transaction Notes Refunded Holds the total number of notes refunded in the last deposit transaction

Last Transaction Notes Rejected Holds the total number of notes rejected in the last deposit transaction

Last Transaction Notes Encashed Holds the total number of notes encashed in the last deposit transaction

Retract Count Denom 1 Holds the count of retracted notes of note type 1 that is considered to be
(3292) consumer’s money

... ...

Retract Count Denom 50 Holds the count of retracted notes of note type 50 that is considered to
(3341) be consumer’s money

Cassette 1 Count Denom 1 Holds the count of note type 1 in physical cassette 1
(3501)

... ...

Cassette 1 Count Denom 50 Holds the count of note type 50 in physical cassette 1
(3550)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-6 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
BNA Counters

CDI Store Worker

Description
(Index)

Cassette 2 Count Denom 1 Holds the count of note type 1 in physical cassette 2

... ...

Cassette 2 Count Denom 50 Holds the count of note type 50 in physical cassette 2

Cassette 3 Count Denom 1 Holds the count of note type 1 in physical cassette 3

... ...

Cassette 3 Count Denom 50 Holds the count of note type 50 in physical cassette 3

Cassette 4 Count Denom 1 Holds the count of note type 1 in physical cassette 4

... ...

Cassette 4 Count Denom 50 Holds the count of note type 50 in physical cassette 4

Cassette 5 Count By Denom An array which holds the counts of 50 note types in physical cassette 5
(5057)

Reject Count Denom 1 Holds the count of rejected notes of note type 1

... ...

Reject Count Denom 50 Holds the count of rejected notes of note type 50

Per Transaction Category 2 Holds the counterfeit note counts for each transaction for all 50 note
types

Per Transaction Category 3 Holds the suspect note counts for each transaction for all 50 note types

Accumulated Category 2 Holds the cumulative counterfeit note counts for all 50 note types
This is reset when the Clear BNA Supervisor option is selected

Accumulated Category 3 Holds the cumulative suspect note counts for all 50 note types
This is reset when the Clear BNA Supervisor option is selected

BNA Retract Bin Counts Holds the rejected note counts for all 50 note types

Recycle Cassette Deposit Count by This holds the recycle cassette note count for all note types.
Note ID The count is reset when the Clear BNA Supervisor option is executed
(5043)

Retract Recycle Counts Holds the retracted note counts for all 50 note types

BNA Reject Encash Count Array Holds the rejected note counts for all 50 note types for notes rejected
during an encash operation

Offline Encash Counts Holds the offline encash counts for all 50 note types

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-7

Common Data Interface Stores
BNA Denomination Configuration

BNA Denomination Configuration C

The following string CDIs are read‐only.

Table C-5
BNA Denomination Configuration

CDI Store Worker

Description
(Index)

DenomConfig Type 1 This holds the currency name and value for NDC note type 1.
(2090) For example, for the currency name EUR with the value of five, this
holds the value EUR5-
The trailing dash (‐) is always present.
If an NDC note type is not defined, the value is an empty string.

DenomConfig Type 2 This holds the currency name and value for NDC note type 2.
(2091)

... ...

DenomConfig Type 50 This holds the currency name and value for NDC note type 50.
(2139)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-8 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
BNA Deposited Denomination Counts

BNA Deposited Denomination

Counts C

The counts in the following integer CDIs are read‐write.

Table C-6
BNA Deposited Denomination Counts

CDI Store Worker

Description
(Index)

Denomination Type 1 This holds the cumulative deposit count for NDC note type 1.
(3164)

Denomination Type 2 This holds the cumulative deposit count for NDC note type 2.
(3165)

... ...

Denomination Type 50 This holds the cumulative deposit count for NDC note type 50.
(3213)

Total Notes to Escrow This holds the cumulative total number of notes moved to the escrow.
(3216)

Total Notes Rejected This holds the cumulative total number of notes rejected by the BNA.
(3217)

Total Notes Refunded This holds the cumulative total number of notes refunded to the
(3215) cardholder.

Total Notes Encashed This holds the cumulative total number of deposited notes.
(3214)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-9

Common Data Interface Stores
BNA MISC

BNA MISC C

Table C-7
BNA Misc

CDI Store Worker

Description
(Index)

BNA Denoms Clrd Date & Time This string holds the date and time the BNA counters were last cleared.
(4035)

BNA Fitness Status This holds the overall fitness of the cash acceptor device, as follows:
(3219)  ‐1 device not present
 0 device is in a good condition, configured and usable
 3 device is in a suspend condition
 4 device is in a fatal condition
This CDI is read‐only

BNA Supplies Status No longer supported

(1261)

Last Deposit Direction This holds the direction of the last transaction completed by the BNA.
(3224) Valid values are as follows:
 0 ‐ Not a deposit transaction
 1 ‐ Vaulted
 2 ‐ Refunded

Programmed Currency Count This holds the total number of NDC note types configured for the BNA
(1316) device.
This CDI is read‐only

Cash‐In Device Variant This matches the variant number as reported in the Configuration
(1368) terminal command.
This CDI is read‐only

Cash‐In Notes Present Indicates whether notes are present in the device.
(1373) This CDI is read‐only

Solicited Status Message Sent Flag Communicates to the Transaction Handler that a Solicited Status
(1317) message has been sent to Central.

Cash‐In Deposit Note Number Holds the maximum number of notes that can be deposited during a
Limit (1377) transaction, set using buffer ‘d’ of the Transaction Reply command. This
limit applies to all currencies that can be accepted by the SST during
transactions.

Cash‐In Deposit Amount Limit Holds the maximum value of the specified currency that can be
(2168) deposited during a transaction, set using buffer ʹdʹ of the Transaction
Reply command. If two or more currencies are set, there is a group
separator between them, for example, EUR200<GS>GBP50. This limit
applies only to the named currency. Other currencies are not affected.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-10 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
BNA MISC

CDI Store Worker

Description
(Index)

LastCashInOperation In a deposit transaction, holds the last operation type when the last
(4063) operation has failed due to a hardware error, as follows:
 DEPOSIT
 RETRACT
 RECOVER

See Note 1:

CashInUnknownRejectCount Holds the number of invalid notes that are moved to reject bin and are
(3778) updated under XFS note ID 0.

ValidatedCat1NoteCount In a deposit transaction, holds the number of Cat 1 of the notes that
(3779) passed through the bill validator during a hardware error.

See Note 2:

ValidatedCat2NoteCounts In a deposit transaction, holds the number of Cat 2 (50 Note types) of the
(5066) notes that passed through the bill validator during a hardware error.

See Note 2:

ValidatedCat3NoteCounts In a deposit transaction, holds the number of Cat 3 (50 Note types) of the
(5067) notes that passed through the bill validator during a hardware error.

See Note 2:

ValidatedCat4NoteCounts In a deposit transaction, holds the number of Cat 4 (50 Note types) of the
(5068) notes that passed through the bill validator during a hardware error.

See Note 2:

Note 1: The CDI will be reset to empty when the hardware error is
cleared during recovery or reset.

Note 2: Read this CDI only when the LastCashInOperation is not

empty.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-11

Common Data Interface Stores
Buffers

Buffers C

Table C-8
Buffers

CDI Store Worker Description

Decimal Character Code This is set to ‘.’ in the Card Read initialisation. It is possible to be set by
the Amount Entry and the Enhanced Amount Entry. It is covered under
the International Currency in screen handling.

FDK Keycode Buffer This holds the FDK Keycode buffer, and is used in several of the State
Types.

New PIN Buffer 1 Present Flag This is used in the Transaction Request/Reply. If ‘av’ is required, then
add in the Data Id ‘U’. If this flag is TRUE, then include data from the
Customer Selectable PIN Buffer 1 CDI in the Transaction Request
message.

New PIN Buffer 2 Present Flag This is used in the Transaction Request/Reply. If ‘aw’ is required, then
add in the Data Id ‘V’. If this flag is TRUE, then include data from the
Customer Selectable PIN Buffer 2 CDI in the Transaction Request
message as well.

Current Screen Number This holds the Transaction Reply field ‘m’, which is the screen to be
displayed during the Function Execution. Set to 0 when the Transaction
Reply is received, then set to the correct value if field ‘m’ is included. If
the screen number is non‐zero, the screen will be displayed during the
Function Execution.

Buffer B Decimal Point This holds the decimal point position in the B Buffer and is set to 2 in the
Card Read initialisation. It is used in the Amount Entry State and
Amount Check State.

Buffer C Decimal Point This holds the decimal point position in the C Buffer and is set to 2 in
the Card Read initialisation. It is used in the Amount Entry State and
Amount Check State.

Amount Buffer Decimal Point This holds the decimal point position in the Amount Buffer and is set to
2 in the Card Read initialisation. It is used in the Amount Entry State
and Amount Check State.

Amount Buffer This holds data for the Transaction Request field ‘k’, which is the
Amount Buffer.

Buffer A This holds data for the Transaction Request field ‘l’, which is Buffer A.

Buffer B This holds data for the Transaction Request field ‘m’, which is Buffer B.

Buffer C This holds data for the Transaction Request field ‘n’, which is Buffer C.

Buffer f This holds data for the Transaction Request fields ‘ce1’ to ‘ce<n+1>’,
which is Buffer f. This is used only with a coin dispenser using more
than four hopper types.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-12 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Buffers

CDI Store Worker Description

Operation Code Buffer This holds data for the Transaction Request field ‘j’.

Customer Selectable PIN Buffer 1 This holds data for the Transaction Request field ‘av2’. It is the first
entry of a new PIN when doing a PIN change.

Customer Selectable PIN Buffer 2 This holds data for the Transaction Request field ‘aw2’. It is the second
entry of a new PIN when doing a PIN change.

Card Track 1 Data This holds data in the Transaction Request field ‘p’ and Transaction
Reply field ‘ak2’, from or for Track 1 of a card.

Card Track 2 Data This holds data in the Transaction Request field ‘h’ and Transaction
Reply field ‘al2’, from or for Track 2 of a card.

Card Track 3 Data This holds data in the Transaction Request field ‘i’ and Transaction
Reply field ‘x’, from or for Track 3 of a card.

Virtual Message Buffer This is used to store a message reply created by the virtual controller,
rather than passing it to Central and waiting for a reply.

Terminal Status Buffer This is used to store the status information field of a terminal status
message, prior to the assembly of the message.

Device Fault Status Buffer This is used to store status fields of a device fault message, prior to the
assembly of the message.

Transaction Request Field Array This is used to hold data written to it by the transaction request builder,
after it has calculated which fields are to be included in the message. It is
also used to add the MAC to the message after the virtual controller has
completed processing.

Amount Buffer Length If it is set to TRUE the Amount Buffer length is 12 instead of 8. This CDI
holds the value of the Configuration Parameter or Enhanced
Configuration Parameter (Part of Option 1).

Amount Read These are not used in Advance NDC.

CAV Amount Entry Buffer
CIM Verify Buffer
CIM Verify Code

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-13

Common Data Interface Stores
Coin Counters

Coin Counters C

Table C-9
Coin Counters

CDI Store Worker Description

Coins Remaining Hopper x Count This holds the remaining coin counts for hopper type x
An instance of this worker must exist for each hopper type

Coins Remaining Hopper x This holds the backup for the remaining coin counts for hopper type x
Backup Count An instance of this worker must exist for each hopper type

Coins Dispensed Hopper x Count This holds the dispensed coin counts for hopper type x
An instance of this worker must exist for each hopper type

Coins Dispensed Hopper x This holds the backup for the dispensed coin counts for hopper type x
Backup Count An instance of this worker must exist for each hopper type

Coins Currently Dispensed This array holds the number of coins dispensed in the current dispense
Hopper x Count operation from hopper type x. It is not specific to host‐controlled and is
updated when the coins are dispensed irrespective of the source of
update.

Coins Last Dispensed Hopper x This holds the number of coins dispensed in the last host‐controlled
Count dispense operation from hopper type x
An instance of this worker must exist for each hopper type

Standard Coin Count Hopper x This holds the standard number of coins to be used for hopper type x
during replenishment using the STD COINS Supervisor option
An instance of this worker must exist for each hopper type

Coin Count Last Cleared Date This holds the timestamp of the last coin counters clearing operation
using the CLR COINS Supervisor option

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-14 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
CPM

CPM C

Table C-10
CPM

CDI Store Worker Description

Cheque Present This indicates whether a cheque is present at the CPM

CPM Buffer a This is used to store the codeline unique to each cheque, so that it can be
used for identification purposes within the Transaction Request.

CPM Cheque Destination This specifies the pocket in which to deposit/capture a cheque.

CPM Configuration This is used to store the configuration of the CPM device at Start of Day.

CPM Endorse Flag This holds the flag used to determine whether or not a cheque has been
endorsed, so that the position of the cheque can be reported should an
error condition occur.

CPM Pocket 1 Count This holds the number of cheques deposited into Pocket 1.

CPM Pocket 2 Count This holds the number of cheques deposited into Pocket 2.

CPM Pocket 3 Count This holds the number of cheques deposited into Pocket 3.

CPM Print Data This holds the data to print on the cheque, as specified by the
Transaction Reply.

CPM Print on Reverse Flag This holds the flag used to determine whether or not to print on the
reverse of the cheque.

CPM Stamp Flag This holds the flag used to determine whether to stamp the cheque after
it has been deposited, as specified by the Transaction Reply.

MICR Detected This holds the flag used to determine if the codeline from the cheque has
been detected.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-15

Common Data Interface Stores
CPM MISC

CPM MISC C

Table C-11
CPM Misc

CDI Store Worker Description

CPM Fitness Status This holds the fitness of the CPM device.

CPM Pocket Count This holds the total number of pockets associated with the CPM device.

CPM Pocket 1 Clr Date & Time This holds the date and time of the last clearing action for Pocket 1.

CPM Pocket 2 Clr Date & Time This holds the date and time of the last clearing action for Pocket 2.

CPM Pocket 3 Clr Date & Time This holds the date and time of the last clearing action for Pocket 3.

CPM Pocket 1 Count This holds the number of cheques deposited into Pocket 1.

CPM Pocket 2 Count This holds the number of cheques deposited into Pocket 2.

CPM Pocket 3 Count This holds the number of cheques deposited into Pocket 3.

CPM Last Deposited TSN This holds the Transaction Serial Number (TSN) of the last deposited
cheque.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-16 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Dial up

Dial up C

Table C-12
Dial up CDI Store Workers

CDI Store Worker Description

Dial Up Enable Flag to indicate whether the environment is a dial up environment

Dial Up Activity Timer Number of 1‐second units the application will wait before redialing and
sending an Iʹm Alive message, after the connection has been dropped.
The range is 0 ‐ 25,500 seconds.

Dial Up Error Redial Timer Number of 1‐second units to wait before attempting to redial after a
connection failure, a host timeout, or a failure to send the Iʹm Alive
message or the Power‐Up message. The range is range 0 ‐ 2,500.

Dial Up Host Msg Pending Flag indicating whether the host has messages to send, as follows:
1: host messages pending
0: no host messages pending

Dial Up Host Header Enabled Flag indicating whether there will be a header to messages from the host,
as follows:
1: host header expected
0: no host header expected

Dial Up Message Suppression Flag to suppress SST to Central messages for Alarms and Supervisor key
presses; journal update messages will still be sent.

Dial Up Msg Completion Option Flag to indicate whether to send a transaction complete message to the
host, as follows:
1: Message Type indicates that the SST will send a Transaction
Completion message to the host.
0: Message Type indicates that the SST will not send a Transaction
Completion message to the host.

Dial Up CP Message Timer Number of 1‐second units the application will wait for an additional
message after sending a CP (or an EP) message to the host. The range is
range 0 ‐ 255.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-17

Common Data Interface Stores
Dial up

CDI Store Worker Description

Dial Up Transaction Completion Flag to indicate how to handle the connection and what message to send,
as follows:
1: the SST remains connected after a Transaction Request (TREQ), will
wait for a Transaction Response (TREP) and subsequently send a Ready
message with CP. All message headers will have RQ, CP or CC. If the
Message after CP Option is set to 1 then the application will wait for the
time defined by the CP Message Timer before terminating the connection
after sending the Ready message with CP.

0: the SST terminates the connection at TREP. All message headers will
have EQ, EP or EC. If the Message after CP Option is set to 1, then the
application will wait for the time defined by the CP Message Timer
before terminating the connection.
This option affects only the Ready message sent in response to a
Transaction Reply command; All other Ready messages will still be sent
even if this option set to 0.

Dial Up Last Msg Request Set to 1 if the last message sent from Central was a transaction reply.

Dial Up Disconnect Received Set to 1 when a disconnect command is received from Central.

Dial Up T Reply Received Set to 1 when a transaction reply is received.

Dial Up Bin A 7‐character field containing information about communications access

routing; used in the dial up header sent to Central.

Dial Up Terminal ID A 6‐character field containing information supplied by the host and used
in the dial up header sent to Central.

Note: Support of dial up in 64‐bit systems (Windows 7 or Windows

10) is not available. For more information, please contact NCR FSE
Product Management.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-18 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
EJ Upload

EJ Upload C

Table C-13
EJ Upload

CDI Store Worker Description

EJLastCharThisBlock Holds the last character position of the current EJ data block sent to
Central.

EJLastCharRecvd Holds the last character position of the EJ data received by Central.

EJLastCharPrevBlock Holds the last character of the previous data block received by Central.
Binary zeroes are replaced with a question mark (?).

PendingEJFlag Holds a flag indicating if there are pending EJ commands to be

processed.

EJAckTimer Holds a timer containing the timeout period allowed for Central to
acknowledge an EJ Upload Message sent from the terminal.

EJRetryLeft Holds the number of retries left before the terminal will automatically
disable EJ Upload, when Central does not acknowledge an EJ data block
within the timeout period.

EJBlockSize Holds the size of (number of characters in) the EJ data block sent to
Central.

EJRetryThreshold Holds the maximum (threshold) number of retry attempts allowed

before the terminal will automatically disable EJ Upload, when Central
does not acknowledge an EJ data block within the timeout period.

EJUploadMsg Holds the actual EJ Upload message sent to Central.

EJCommandCode Holds the command code of the current EJ command being processed
by the terminal.

PendingEJCommand Holds the command code of any pending EJ commands waiting to be

processed by the terminal.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-19

Common Data Interface Stores
EMV

EMV C

Table C-14
EMV

CDI Store Worker Description

Currency Mapping Table This holds the information used to define the currency held in the
currency cassettes, such as currency type, cassette type and
denomination.

Contactless EMV Data This holds the EMV data of the smart card used for contactless
transactions.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-20 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Encryptor Variant

Encryptor Variant C

Table C-15
Encryptor Variant

CDI Store Worker Description

EncryptorVariant This holds the type of encryptor variant configured for the terminal:
‐1 = UNKNOWN
0 = NBS Service Variant
1 = BAPE Service Variant
6 = EPP Service Variant
The default is ‐1.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-21

Common Data Interface Stores
Error Processing

Error Processing C

Table C-16
Error Processing

CDI Store Worker Description

Reject Status Value and Qualifier This holds the Reject Status Value and Qualifier used in a Specific
Command Reject message, for example A01.

CDI Error Number This holds the Error Number to be reported. It is used internally within
Advance NDC and is not intended for customer use.

CDI Error Message This holds the Error Message to be reported. It is used internally within
Advance NDC and is not intended for customer use.

CDI Error Parameter 1 This holds the variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

CDI Error Parameter 2 This holds the Variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

CDI Error Parameter 3 This holds the Variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

CDI Error Parameter 4 This holds the Variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

CDI Error Parameter 5 This holds the Variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

CDI Error Parameter 6 This holds the Variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

CDI Error Parameter 7 This holds the Variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

CDI Error Parameter 8 This holds the Variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

CDI Error Parameter 9 This holds the Variable String to be reported in the Error Message. It is used
internally within Advance NDC and is not intended for customer use.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-22 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Exit Migration

Exit Migration C

The workers in this catalog contain data exposed in NDC+ but either
not supported or is represented differently in Advance NDC. You
should not need to use these workers.

Table C-17
Exit Migration

CDI Store Worker Description

Option Digit 0 This holds the first Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 1 This holds the 2ndNative Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 2 This holds the 3rd Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 3 This holds the 4th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 4 This holds the 5th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 5 This holds the 6th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 6 This holds the 7th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 7 This holds the 8th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 8 This holds the 9th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 9 This holds the 10th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 10 This holds the 11th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 11 This holds the 12th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 12 This holds the 13th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 13 This holds the 14th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-23

Common Data Interface Stores
Exit Migration

CDI Store Worker Description

Option Digit 14 This holds the 15th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Option Digit 15 This holds the 16th Native Mode Option byte entered in the MSG MODE
Configure Supervisor function.

Free JDATA Enable Flag This Flag, which is set via a Terminal Command, controls access to
tampered journal records using the Free Jdata function in the Supervisor
Access menu. The tampered records feature is not supported.

Audio Echo Option Non Supported Feature.

DAS Error Reporting Option Non Supported Feature.

Option Digits String This holds the 16 Native Mode Option Values as a string for use in the
Terminal State response to the ‘Send Local Configuration Option Digits’
Terminal Command.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-24 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
FIT Data

FIT Data C

Most of the CDI workers in this catalog store information from the
currently matched FIT definition.

Table C-18
FIT Data

CDI Store Worker Description

Bank ID Index This is the offset on a card, which is combined with the PINDX to
determine an Algorithm number. It is used for Diebold Local PIN
Verification, which is not supported.

PAN Data Index This is the offset on a card which is combined with the PINDX to
determine the PAN.

PAN Data Length This combines the number of digits from the PAN and a local check for a
short PIN. CDI is provided for NDC+ migration.

Local Check Flag This allows for a local check for a short PIN when Remote PIN
Verification is used.

PIN Check Length This holds the number of digits to be used from the offset PANDX for
PIN Verification.

PAN Pad Option This combines the keys required for PIN verification and PAN Pad
character. CDI is provided for NDC+ migration.

PAN Pad char This holds the PAN Pad character for padding the PAN, to the right, up
to 16 digits.

PAN Pad key This is the PIN verification Key (Master Key or PEKEY in FIT).

PIN Digits Option This combines the PIN verification method and the number of digits to
use from the PIN. CDI is provided for NDC+ migration.

PIN Digits Check Number This is the number of digits from the PIN to check in the local PIN
verification. It must be less than the maximum digits for the entered
PIN.

PIN Verification Method This determines whether the PIN verification is Remote or Local. If it is
Local, the type of verification must be selected, (VISA, DES or Diebold).

Institution ID Table Entry 0 This holds the first element of Financial Institution ID as matched on the
card during the FIT Search.

Institution ID Table Entry 1 This holds the second element of Financial Institution ID as matched on
the card during the FIT Search.

Institution ID Table Entry 2 This holds the third element of Financial Institution ID as matched on
the card during the FIT Search.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-25

Common Data Interface Stores
FIT Data

CDI Store Worker Description

Institution ID Table Entry 3 This holds the fourth element of Financial Institution. ID as matched on
the card during the FIT Search.

Institution ID Table Entry 4 This holds the fifth element of Financial Institution ID as matched on the
card during the FIT Search.

Institution ID Table Entry 5 This is not used. Only elements 0 to 4 are actually used as FIID is
compressed into 5 CDIs.

Institution ID Table Entry 6 This is not used. Only elements 0 to 4 are actually used as FIID is
compressed into 5 CDIs.

Institution ID Table Entry 7 This is not used. Only elements 0 to 4 are actually used as FIID is
compressed into 5 CDIs.

Institution ID Table Entry 8 This is not used. Only elements 0 to 4 are actually used as FIID is
compressed into 5 CDIs.

Institution ID Table Entry 9 This is not used. Only elements 0 to 4 are actually used as FIID is
compressed into 5 CDIs.

Institution ID Index Option This holds the offset on a card, which is combined with the PINDX for
the Financial Institution ID, and used in the FIT Search.

Institution ID Index Location This holds the offset on a card, combined with the PINDX, for Financial
Institution ID. It is used in the FIT Search.

Institution ID Index Location Flag This holds the offset on a card, combined with the PINDX, for Financial
Institution ID. It is used in the FIT Search.

Index Reference Point Entry 0 This holds the location of the following fields (track, delimiter, search
direction), PIDDX, PAGDX, PANDX, PRCNT, POFDX, PLNDX.

Index Reference Point Entry 1 This holds the location of the following fields (track, delimiter, search
direction), PIDDX, PAGDX, PANDX, PRCNT, POFDX, PLNDX.

Index Reference Point Entry 2 This holds the location of the following fields (track, delimiter, search
direction), PIDDX, PAGDX, PANDX, PRCNT, POFDX, PLNDX.

Index Reference Point Entry 3 This is not used. Only entries 0 to 2 are required and used, since data
downloaded in FIT Table is compressed.

Index Reference Point Entry 4 This is not used. Only entries 0 to 2 are required and used, since data
downloaded in FIT Table is compressed.

Index Reference Point Entry 5 This is not used. Only entries 0 to 2 are required and used, since data
downloaded in FIT Table is compressed.

PIN Pad Option This combines Pad Char and Encryption method. CDI is provided for
NDC+ migration.

PIN Pad Encrypt Type This holds the encryption method and keys to use for the creation of the
PIN block.

PIN Pad Character This holds the PIN Pad character for padding the PIN, to the right, up to
16 digits.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-26 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
FIT Data

CDI Store Worker Description

Language Code Index This holds the offset on a card, which combined with the PINDX makes
up the Language Code.

PIN Block Option This combines the data for maximum PIN digits, and PIN Block type.
CDI is provided for NDC+ migration.

PIN Block Type This holds the PIN Block type for inclusion in the Transaction Request.

PIN Block Max Digits This holds the maximum number of digits for the PIN Entry.

PIN Offset Index This is the offset on a card and combines with PINDX, for the PIN Offset
data; or with PVKI and PVV in the VISA Pin Verification.

PIN Retry Count Option This combines the PIN Retry Count location and whether the retry is
incremented or decremented. CDI is provided for NDC+ migration.

PIN Retry Count Location This is the offset on a card and combines with the PINDX for the PIN
Retry Count.

PIN Retry Count Type This is the Specifies Retry count mechanism, which increments or
decrements the count.

GBP Reference Point This is part of the FIT Data and is not used in Advance NDC.

Indirect Next State Index Option This combines the data for Branch & Logo. CDI is provided for NDC+
migration.

Indirect Next State Index Location This is used by the FIT Switch and the Expanded FIT Switch, to allow
branching based the FIT definition the card is matched to.

Indirect Next State Index Logo This displays the logo when the FIT dependent logo control is in a
Number screen definition.

GBP B Index This is part of the FIT Data and not used in Advance NDC.

GBP B Length This is part of the FIT Data and not used in Advance NDC.

Language Code The is the Language Code read from the card, the location of which is
determined by FIT Data.

Financial Institute ID This is not used. It is a duplicate of PFIID, the Financial Institute ID, as
matched on the card during the FIT Search.

Bank ID This is the bank ID read from a card, the location of which is determined
by the FIT Data.

PIN Retry Count This is the PIN Entry retry count read from the card, the location of
which is determined by the FIT Data.

PAN This is the Primary Account Number read from the card, the location of
which is determined by the FIT Data.

PIN Offset Data This holds the PIN Offset data used in local PIN Verification. It is read
from the card based on the specification of the FIT table.

Encrypted PE Key The Encrypted PE Key for use in PIN verification (optional).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-27

Common Data Interface Stores
FIT Data

CDI Store Worker Description

Decimalisation Table The Decimalisation Table for the current FIT, used to convert
hexadecimal data during a DES PIN verification.

Base FIT Present The number of the FIT on which a FIT match has occurred.

FIT Match Index A flag set TRUE when the Base FIT has been loaded, and FALSE when a
Linked FIT has been loaded.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-28 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Key Entry Mode

Key Entry Mode C

Table C-19
Key Entry Mode

CDI Store Worker Description

Key Entry Mode This holds the current key entry mode configured for the terminal:
1 = Single Key Entry without XOR
2 = Single Key Entry with XOR
3 = Double Key Entry with XOR
4 = Double Key Entry—restricted
The default is 1.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-29

Common Data Interface Stores
Misc Counters

Misc Counters C

Table C-20
Misc Counters

CDI Store Worker Description

Camera Film Frames Remaining This is not used in Advance NDC; the value is always “00000”.

Camera TSN This holds the value used to report the Transaction Serial Number when
taking camera snapshots

Card Captured Count This counts the number of cards captured. The data is used in the Send
Counters Terminal Command, Supervisor Replenish functions and
locations where cards are captured

Current Mode This holds an integer value that represents the current mode:
 0 ‐ Initialisation
 2 ‐ Out of Service
 3 ‐ Supervisor
 4 ‐ In Service
 5 ‐ Offline

Envelopes Deposited Count This counts the number of envelopes deposited. It is used in the Send
Counters Terminal Command, Supervisor Replenish functions and the
Dispense Function Execution

Previous Mode This holds an integer value that represents the previous mode:
 0 ‐ Initialisation
 2 ‐ Out of Service
 3 ‐ Supervisor
 4 ‐ In Service
 5 ‐ Offline

Statement Captured Count This counts the number of statements captured. It is used in the Send
Counters Terminal Command, Supervisor Replenish functions and the
Statement Capture

Total Transaction Count Low See TSN and TSNBackup on page C‐39. Low holds up to 10000

Total Transaction Count High See TSN and TSNBackup on page C‐39. High holds up to 1000

All ‘... Last Cleared Date’ workers, These are not used in Advance NDC.
for example Card Count Last
Cleared Date

Last Envelope Serial Number This is not used in Advance NDC.

DPM Pocket/Bin Counts These are not used; the DPM is not supported in Advance NDC.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-30 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Note Counters

Note Counters C

Table C-21
Note Counters

CDI Store Worker Description

CDM Retract Bin Count This stores the retracted note type counts.

CDM 1 Retract Bin Count This store is reserved for future use.

CDM 2 Retract Bin Count This store is reserved for future use.

CDM Type Denoms This read‐only store returns the denominations that are configured for
the cash handler.
On a dual cash handler, this is used when combined counters are used
and returns denominations that are configured across both cash
handlers.

CDM Type Denoms CDM1 This read‐only store returns the denominations that are configured for
cash handler 1 of a dual cash handler when separated counters are used.

CDM Type Denoms CDM2 This read‐only store returns the denominations that are configured for
cash handler 2 of a dual cash handler when separated counters are used.

Notes To Dispense Cassette x This holds Transaction Reply field g, indicating the number of notes to
be dispensed from cassette typex.
If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7

Dispense More Than 99 Notes This allows to dispense more than 99 notes
0 ‐ Do not allow to dispense more than 99 notes
1 ‐ Allow to dispense more than 99 notes
If bit 2 of option 76 is set, this CDI will also be set to 1 to enable
dispensing more than 99 notes

Notes Dispensed Cassette x Backup This is a backup store of notes dispensed from cassette type x.
Count If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7

Notes Remaining Cassette x This is a backup store of notes remaining in cassette type x.
Backup Count If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7

Notes Purged Cassette x Backup This is a backup store of notes purged from cassette type x
Count If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-31

Common Data Interface Stores
Note Counters

CDI Store Worker Description

Notes Last Dispensed This holds the number of notes dispensed in the last transaction from
Cassette x Count cassette type x.
If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7
It allows Central to recover the note counts in the event of a power
failure. The data is used in field g7 of the Counters Message.

Notes Dispensed Cassette x Count This holds the total number of notes dispensed from cassette type x.
If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7

Notes Remaining Cassette x Count This holds the number of notes remaining in cassette type x.
If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7

Notes Purged Cassette x Count This holds the number of notes purged from cassette type x.
If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7

Standard Note Count Cassette x This holds the standard note count for cassette type x, set via the ‘Set
Cash’ Supervisor Configure Menu function.
If option 76 is set to 000, there are instances for cassette types 1 to 4
If option 76 is set to 001, there are instances for cassette types 1 to 7

Initial Total Notes Count CDM 1 This holds the total number of notes entered for the cassette types in
cash handler 1 of a dual cash handler

Initial Total Notes Count CDM 2 This holds the total number of notes entered for the cassette types in
cash handler 2 of a dual cash handler

Cash Count Last Cleared Date This holds the last cleared date for the cash handler, or for cash handler
1 in a dual cash handler

Cash Count Last Cleared Date This holds the last cleared date for cash handler 2 in a dual cash handler
CDM2

Notes To Dispense Count This holds the number of notes to dispense from each cassette type.

CDM1 Reject and Retract Bin This holds the reject and retract bin counts for cash handler 1. This is an
Counts integer array store of length six. (The first three positions are used to
store the count of reject bins and the last three positions are used to store
the count of retract bin.)
On an S2 dispenser, index 0 and index 1 are used for reject bin 1 and 2
respectively, and index 3 is used for the retract bin. The unused
positions are set to ‐1.

CDM2 Reject and Retract Bin This holds the reject and retract bin counts for cash handler 2. This is an
Counts integer array store of length six. (The first three positions are used to
store the count of reject bins and the last three positions are used to store
the count of retract bin.)
On an S2 dispenser, index 0 and index 1 are used for reject bin 1 and 2
respectively, and index 3 is used for the retract bin. The unused
positions are set to ‐1.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-32 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Note Counters

CDI Store Worker Description

CDM1 Reject and Retract Bins Last This holds the last cleared date for reject and retract bins of the cash
Cleared Date handler, or for cash handler 1 in a dual cash handler.

CDM2 Reject and Retract Bins Last This holds the last cleared date for reject and retract bins of the cash
Cleared Date handler 2.

NotesPickedFromCU) This holds the count of notes picked from a recycling cassette or bill
(5069) cassette and moved to a recycling or cash‐in cassette when notes with
incorrect denomination present.

NotesAddedToCU This holds the count of notes added to the recycling cassette which are
(5070) picked from another cassette and moved due to incorrect denomination.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-33

Common Data Interface Stores
Option Digit Stores

Option Digit Stores C

Table C-22
Option Digit Stores

CDI Store Worker Description

Option 41 This holds the value of Enhanced Configuration option 41 (Send Track
(3777) Details on Card Retract)
For details of this option, refer to Chapter 7, “Configuration
Parameters” in the APTRA Advance NDC, Reference Manual

Option Array 45 Option Array 45

(1318) This holds the setting of Enhanced Configuration Parameter option 45
For details of the possible settings, refer to Chapter 7, “Configuration
Parameters” in the APTRA Advance NDC, Reference Manual.

Option 48 This holds the value of option 48

For details of this option, refer to the APTRA Advance NDC, Reference
Manual.

BNA Option This holds the setting of Enhanced Configuration Parameter option 44
(3218) For details of the possible settings, refer to Chapter 7, “Configuration
Parameters” in the APTRA Advance NDC, Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-34 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Printing

Printing C

Table C-23
Printing

CDI Store Worker Description

Envelope First use After Supervisor This is set to TRUE if using the Envelope Dispenser for the first time
mode after a Supervisor exit. It determines whether Unsolicited device fault
messages need to be sent.

Journal Printed Flag This is set to TRUE if printing has occurred and it is used to tidy up in
the Close State.

Journal First use After Supervisor This is set to TRUE if using the Journal Printer for the first time after a
mode Supervisor exit. It determines if Unsolicited device fault messages need
to be sent.

Receipt First use After Supervisor This is set to TRUE if using the Receipt Printer for the first time after a
mode Supervisor exit. It determines if Unsolicited device fault messages need
to be sent.

Statement First use After This is set to TRUE if using the Statement Printer for the first time after a
Supervisor mode Supervisor exit. It determines if Unsolicited device fault messages need
to be sent.

Printer Data Block 1 This holds the Transaction Reply field ‘r’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 2 This holds the Transaction Reply field ‘t’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 3 This holds the Transaction Reply field ‘v’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 4 This holds the Transaction Reply field ‘v2’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 5 This holds the Transaction Reply field ‘v4’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 6 This holds the Transaction Reply field ‘v6’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 7 This holds the Transaction Reply field ‘v8’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-35

Common Data Interface Stores
Printing

CDI Store Worker Description

Printer Data Block 8 This holds the Transaction Reply field ‘v10’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 9 This holds the Transaction Reply field ‘v12’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 10 This holds the Transaction Reply field ‘v14’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 11 This holds the Transaction Reply field ‘v16’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 12 This holds the Transaction Reply field ‘v18’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Printer Data Block 13 This holds the Transaction Reply field ‘v20’ Print Data with embedded
controls. The Transaction Handler processes this data and then sends it
to the relevant device.

Transaction Reply Printer Flags This holds the Transaction Reply fields such as ‘s’, ‘u’, ‘v1’. It holds up to
13 printer flags specifying the devices on which each data field is to be
printed. The Transaction Reply validation and Function Execution must
handle many occurrences of the same Printer in the flags, matching with
Func Id, and so on.

Depository Data This holds data sent by Central in a Transaction Reply. This buffer
contains the data that will be printed on the Depository.

DPM First Use After Supervisor This is not used; the DPM is not supported in Advance NDC.
Mode

Sideways Receipt Cancelled This is set to TRUE if the sideways receipt print is cancelled.

Sideways Receipt Printed This is set to TRUE if the sideways receipt is successfully printed.

Statement Cancelled This is set to TRUE if the statement print is cancelled.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-36 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Screen Display

Screen Display C

Table C-24
Screen Display

CDI Store Worker Description

Track 1 Account Number This is set by Track One Decomposer worker, and used when displaying
the Track1 information.

Track 1 Country Code This is set by Track One Decomposer worker, and used when displaying
the Track1 information.

Track 1 Forename This is set by Track One Decomposer worker, and used when displaying
the Track1 information.

Track 1 Format This is set by Track One Decomposer worker, and used when displaying
the Track1 information.

Track 1 Optional Data This is set by Track One Decomposer worker, and used when displaying
the Track1 information.

Track 1 Surname This is set by Track One Decomposer worker, and used when displaying
the Track1 information.

Track 1 Title This is set by Track One Decomposer worker, and used when displaying
the Track1 information.

Screen Offset This holds the offset to the first screen in the active language group.

Screen Group Size This holds the screen group size for multi‐language screens, which can
be set in an 8 FDK Select or Language Select From Card State.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-37

Common Data Interface Stores
Security

Security C

Table C-25
Security

CDI Store Worker Description

Time Variant Number This holds data in the Transaction Request field ‘e’. The MAC Security
Flags determine whether a Transaction Reply validation checks
Transaction Reply field ‘e’ against data sent in Transaction Request.

Transaction Serial Number This holds data from the Transaction Reply field ‘k’. It is used when
taking pictures, printing on the Envelopes during a Deposit and journal
traces.

Comms Key Loaded Flag Set to TRUE if the Comms Key has been loaded. If FALSE, the locally
entered Comms Key is used.

Message Coordination Number This holds data in the Transaction Request field ‘g’. Incremented on each
Transaction Request (rolls from 31H to 3FH) before inclusion and
storing. In Transaction Reply validation, if the field ‘o’ in Transaction
Reply is ‘0’ do not check. If non‐zero, check the two values.

Last Message Status Holds the last status issued as part of the Transaction Request field ‘r’.
Set to 0 between Transaction Reply validation and Function Execution
(no status sent).
Set to 1 in Ready 9/B Builder (good).
Set to 3 in Reject Message Builder (Transaction Reply rejected).
Set to 2 in solicited device fault messages.

MAC Key Loaded Flag Set to TRUE if the MAC Key has been loaded. If FALSE, the locally
entered Comms Key is used.

NDC Security Trace Number This holds the three‐digit Security Trace Number used when printing
security trace messages on the Journal.

MAC Machine Number This holds the six‐digit Security Terminal Number entered in the Enter
MAC Access Supervisor function.

MAC Security Flags This holds the ten Security Flags entered in the Enter MAC Access
Supervisor function.

Other Message MAC Field Selection This holds the MAC field selection for FIT Load, State Table Load,
Terminal State and Dispenser Currency Cassette Mapping Table
messages.

Solicited Status MAC Field This holds the MAC field selection for Solicited Status Messages.
Selection

Track 1 MAC Field Selection This holds the MAC field selection for Track 1 data in Transaction
Request and Transaction Reply.

Track 2 MAC Field Selection This holds the MAC field selection for Track 2 data in Transaction
Request and Transaction Reply.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-38 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Security

CDI Store Worker Description

Track 3 MAC Field Selection This holds the MAC field selection for Track 3 data in Transaction
Request and Transaction Reply.

Transaction Reply MAC Field This holds the MAC field selection for Transaction Reply fields.
Selection

Transaction Request MAC Field This holds the MAC field selection for Transaction Request fields.
Selection

TSN This holds the last Transaction Serial Number, which is sent as part of
the response to the Send Counters Terminal Command, and is part of
field ‘r’ in Transaction Request.

TSN Backup This is the backup store of TSN, catering for power failures during the
Transaction Reply Function execution.

VISA Key A0 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in the PIN Entry States
when local VISA verification is specified.

VISA Key A1 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in the PIN Entry States
when local VISA verification is specified.

VISA Key A2 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

VISA Key A3 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

VISA Key A4 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

VISA Key A5 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

VISA Key B0 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

VISA Key B1 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

VISA Key B2 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-39

Common Data Interface Stores
Security

CDI Store Worker Description

VISA Key B3 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

VISA Key B4 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

VISA Key B5 This holds the VISA Key Table Data. It is downloaded using the
Encryption Key Change Command, and is used in PIN Entry States
when the local VISA verification is specified.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-40 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
State Information

State Information C

Table C-26
State Information

CDI Store Worker Description

Current State Number Number of the State about to be executed.

Current State Type State Type Id of the State about to be executed.

Primary Extension State Entry 0 Holds first parameter for first extension State.

Primary Extension State Entry 1 Holds second parameter for first extension State.

Primary Extension State Entry 2 Holds third parameter for first extension State.

Primary Extension State Entry 3 Holds fourth parameter for first extension State.

Primary Extension State Entry 4 Holds fifth parameter for first extension State.

Primary Extension State Entry 5 Holds sixth parameter for first extension State.

Primary Extension State Entry 6 Holds seventh parameter for first extension State.

Primary Extension State Entry 7 Holds eight parameter for first extension State.

Secondary Extension State Entry 0 Holds first parameter for second extension State.

Secondary Extension State Entry 1 Holds second parameter for second extension State.

Secondary Extension State Entry 2 Holds third parameter for second extension State.

Secondary Extension State Entry 3 Holds fourth parameter for second extension State.

Secondary Extension State Entry 4 Holds fifth parameter for second extension State.

Secondary Extension State Entry 5 Holds sixth parameter for second extension State.

Secondary Extension State Entry 6 Holds seventh parameter for second extension State.

Secondary Extension State Entry 7 Holds eight parameter for second extension State.

State Table Entry 0 Holds first parameter of main State Table entry (Table entry 2).

State Table Entry 1 Holds second parameter of main State Table entry (Table entry 3).

State Table Entry 2 Holds third parameter of main State Table entry (Table entry 4).

State Table Entry 3 Holds fourth parameter of main State Table entry (table entry 5).

State Table Entry 4 Holds fifth parameter of main State Table entry (Table entry 6).

State Table Entry 5 Holds sixth parameter of main State Table entry (Table entry 7).

State Table Entry 6 Holds seventh parameter of main State Table entry (Table entry 8).

State Table Entry 7 Holds eight parameter of main State Table entry (Table entry 9).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-41

Common Data Interface Stores
State Information

CDI Store Worker Description

Tertiary Extension State Entry 0 Holds first parameter for third extension State.

Tertiary Extension State Entry 1 Holds second parameter for third extension State.

Tertiary Extension State Entry 2 Holds third parameter for third extension State.

Tertiary Extension State Entry 3 Holds fourth parameter for third extension State.

Tertiary Extension State Entry 4 Holds fifth parameter for third extension State.

Tertiary Extension State Entry 5 Holds sixth parameter for third extension State.

Tertiary Extension State Entry 6 Holds seventh parameter for third extension State.

Tertiary Extension State Entry 7 Holds eight parameter for third extension State.

Fourth Extension State Entry 0 Holds first parameter for fourth extension State.

Fourth Extension State Entry 1 Holds second parameter for fourth extension State.

Fourth Extension State Entry 2 Holds third parameter for fourth extension State.

Fourth Extension State Entry 3 Holds fourth parameter for fourth extension State.

Fourth Extension State Entry 4 Holds fifth parameter for fourth extension State.

Fourth Extension State Entry 5 Holds sixth parameter for fourth extension State.

Fourth Extension State Entry 6 Holds seventh parameter for fourth extension State.

Fourth Extension State Entry 7 Holds eight parameter for fourth extension State.

Fifth Extension State Entry 0 Holds first parameter for fifth extension State.

Fifth Extension State Entry 1 Holds second parameter for fifth extension State.

Fifth Extension State Entry 2 Holds third parameter for fifth extension State.

Fifth Extension State Entry 3 Holds fourth parameter for fifth extension State.

Fifth Extension State Entry 4 Holds fifth parameter for fifth extension State.

Fifth Extension State Entry 5 Holds sixth parameter for fifth extension State.

Fifth Extension State Entry 6 Holds seventh parameter for fifth extension State.

Fifth Extension State Entry 7 Holds eight parameter for fifth extension State.

Sixth Extension State Entry 0 Holds first parameter for sixth extension State.

Sixth Extension State Entry 1 Holds second parameter for sixth extension State.

Sixth Extension State Entry 2 Holds third parameter for sixth extension State.

Sixth Extension State Entry 3 Holds fourth parameter for sixth extension State.

Sixth Extension State Entry 4 Holds fifth parameter for sixth extension State.

Sixth Extension State Entry 5 Holds sixth parameter for sixth extension State.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-42 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
State Information

CDI Store Worker Description

Sixth Extension State Entry 6 Holds seventh parameter for sixth extension State.

Sixth Extension State Entry 7 Holds eight parameter for sixth extension State.

Seventh Extension State Entry 0 Holds first parameter for seventh extension State.

Seventh Extension State Entry 1 Holds second parameter for seventh extension State.

Seventh Extension State Entry 2 Holds third parameter for seventh extension State.

Seventh Extension State Entry 3 Holds fourth parameter for seventh extension State.

Seventh Extension State Entry 4 Holds fifth parameter for seventh extension State.

Seventh Extension State Entry 5 Holds sixth parameter for seventh extension State.

Seventh Extension State Entry 6 Holds seventh parameter for seventh extension State.

Seventh Extension State Entry 7 Holds eight parameter for seventh extension State.

Eighth Extension State Entry 0 Holds first parameter for eighth extension State.

Eighth Extension State Entry 1 Holds second parameter for eighth extension State.

Eighth Extension State Entry 2 Holds third parameter for eighth extension State.

Eighth Extension State Entry 3 Holds fourth parameter for eighth extension State.

Eighth Extension State Entry 4 Holds fifth parameter for eighth extension State.

Eighth Extension State Entry 5 Holds sixth parameter for eighth extension State.

Eighth Extension State Entry 6 Holds seventh parameter for eighth extension State.

Eighth Extension State Entry 7 Holds eight parameter for eighth extension State.

Current Mode Determines the Current Mode of the SST.

PIN Entry Status Used to determine the outcome of PIN Entry initiation in a Card Read
State. Values are 0 = PIN Good, 1 = PIN Cancelled, 2 = PIN Timeout.

PIN Entry Initiated Used to determine if the previous state was a PIN Entry Initiation state.
Only used by PIN Entry State.

Current Mode (NVRAM) Used to determine the current Supervisor mode.

INITIALISE = 0, POWERUP = 1, OOS = 2, SUPPLY/SUPERVISOR = 3, IN
SERVICE = 4,
OFFLINE =5, SUSPEND = 6.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-43

Common Data Interface Stores
Supervisor

Supervisor C

Table C-27
Supervisor

CDI Store Worker Description

Envelope Dispenser Status This holds the Status of the Envelope Dispenser, and is used to
determine if an Unsolicited Device Status message needs to be sent to
Central.

Card Capture Bin Status This holds the Status of the Card Capture Bin, and is used to determine if
an Unsolicited Device Status message needs to be sent to Central.

Receipt Paper Status This holds the Status of the Receipt Paper, and is used to determine if an
Unsolicited Device Status message needs to be sent to Central.

Receipt Ribbon Status This holds the Status of the Receipt Ribbon, and is used to determine if
an Unsolicited Device Status message needs to be sent to Central.

Receipt Printhead Status This holds the Status of the Receipt Printhead, and is used to determine
if an Unsolicited Device Status message needs to be sent to Central.

Receipt Knife Status This holds the Status of the Receipt Knife, and is used to determine if an
Unsolicited Device Status message needs to be sent to Central.

Journal Paper Status This holds the Status of the Journal Paper, and is used to determine if an
Unsolicited Device Status message needs to be sent to Central.

Journal Ribbon Status This holds the Status of the Journal Ribbon, and is used to determine if
an Unsolicited Device Status message needs to be sent to Central.

Journal Printhead Status This holds the Status of the Journal Printhead, and is used to determine
if an Unsolicited Device Status message needs to be sent to Central.

Statement Paper Status This holds the Status of the Statement Paper, and is used to determine if
an Unsolicited Device Status message needs to be sent to Central.

Statement Ribbon Status This holds the Status of the Statement Ribbon, and is used to determine
if an Unsolicited Device Status message needs to be sent to Central.

Statement Printhead Status This holds the Status of the Statement Printhead, and is used to
determine if an Unsolicited Device Status message needs to be sent to
Central.

Statement Knife Status This holds the Status of the Statement Knife, and is used to determine if
an Unsolicited Device Status message needs to be sent to Central.

Statement Capture Bin Status This holds the Status of the Statement Capture Bin, and is used to
determine if an Unsolicited Device Status message needs to be sent to
Central.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-44 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Supervisor

CDI Store Worker Description

Return Mode This determines which mode to return to when exiting from Supervisor ‐
previous mode or Out of Service. It is configured using a downloaded
Configuration Parameter or Enhanced Configuration Parameter (Option
1).

Supervisor Password This holds the 4‐digit (numeric) password which, if configured, controls
entry to the Supervisor Configure and Access menus. The password is
configured using a function in the Access Menu.

Initial Supervisor Menu This specifies which of the following menus is to be displayed when
entering the Supervisor mode:
 0 ‐ Select
 1 ‐ Replenish
 2 ‐ Exit Supervisor.
This is configured using a function in the Supervisor Access menu.

Initial Supervisor Display This specifies which of the following interfaces is to be used on entry to
Supervisor mode:
 0 ‐ default
 1 ‐ front.
It is configured using a function in the Supervisor Access menu.

Supervisor Password Flag This Flag indicates whether or not a Supervisor password has been
configured, allowing for a controlled entry to the Configure and Access
menus.

Exit Mode If this is 0, the Supervisor mode switch plus entering 9 on the Select
Supervisor menu is needed to exit Supervisor. If it is 1, only the mode
switch is needed to exit Supervisor. This is defined in the Exit Mode
Supervisor Access Menu function.

Default Printer This holds the Default Printer to use for the PRNT CMPNT VERS, PRNT
SCRW VERS, PRNT SPPLY, PRNT CNTRS, PRNT CONFIG, PRNT
TCP/IP, and PRNT ACC Supervisor functions. This is defined in the Set
Print Supervisor Configure Menu function.

Restart Mode This determines the recovery after power failure/reset. The value is
entered in the Restart Mode Supervisor Configure Menu function.

Return Mode (NVRAM) This is used at power‐up to determine the mode to return to after exiting
from Supervisor mode.

Supervisor Password Retry This Counter keeps track of the number of attempts there has been to
enter the Supervisor password which controls the entry to the Configure
and Access menus. Five attempts are allowed at the front interface, but
only one attempt at the rear interface.

EJ Log Sequence Number This is used in the filename extension of the backup EJ log file.

Depository Bin Status This holds the Status of the Depository Bin, and is used to determine if
an Unsolicited Device Status message needs to be sent to Central.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-45

Common Data Interface Stores
Supervisor

CDI Store Worker Description

Journal Knife Status This holds the Status of the Journal Knife, which is always ‘good’ as
there is no journal knife.

Set Access This is used to write the Supervisor access configuration to disk.

Set Default This is used to write the Supervisor defaults to disk.

DPM Enable Image Dump Flag This is not used; the DPM is not supported in Advance NDC.

Supervisor Entry Message This is used to contain the unsolicited Supervisor Keys message
(pending) indicating entry to Supervisor mode.

Supervisor Exit Message (pending) This is used to contain the unsolicited Supervisor Keys message
indicating exit from Supervisor mode.

Backup Next State Number This is used to store an existing next state number when cardless
transactions are disabled using CARDLESS TRANSACTIONS (Option
93 on the Configure menu in Supervisor). This number is restored when
cardless transactions are re‐enabled.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-46 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Terminal Configuration

Terminal Configuration C

Table C-28
Terminal Configuration

CDI Store Worker Description

PAN DCS Option This specifies whether or not to include PAN in the data sent to the DCS.

Product ID This holds the Product Id which is reported back within the Terminal
State response to a Send Configuration Information Terminal
Command.

Auto Voice Option This is an Enhanced Configuration Parameter (Option 2). If set to TRUE,
voice message 1 is played at the same time as the please wait screen. It is
used to control the playing of fixed message numbers.

Beep at Card Eject This is an Option Digit (part of 4). If set to 0, a beep will sound when the
card is ejected.

Beep at Cash Present This is an Option Digit (part of 2). If set to 1, a beep will sound when
presenting cash during the Cash Dispense Transaction Reply Function
Execution.

Beep at Deposit This is an Option Digit (part of 2). If set to 0, a beep will sound when
depositing an envelope during the Deposit Transaction Reply Function
Execution.

Card Holder Display Unsol This is Enhanced Configuration Parameter (Option 32). If set to 1, an
unsolicited message will be sent when an active/inactive state change
occurs in the cardholder display sensor. If the unsolicited message for
state changes in the cardholder display alarm is disabled. the value is 0.

Camera NAK Reporting Option This is an Option Digit (part of 3). It determines if NAK from the camera
is reported to Central.

Camera Control Option This is a Configuration Parameter or an Enhanced Configuration

Parameter (Option 0). If a valid Transaction Reply is received and this
flag is set to 0 or 1, a picture is taken automatically.

Cancel/Clear Swap Option This is an Option Digit (part of 7). It determines if the cancel/clear keys
are swapped. (Not supported in Advance NDC)

Cancel On Statement and Wait This is an Option Digit (part of 3). If set to 1, the Cancel key is enabled
Option during the Statement Print and Wait Transaction Reply.

Card Captured Trace Option This is an Option Digit (part of 5). If set to 1, data is printed on the
Journal when a card is captured.

Card Read Error Threshold This is a Configuration Parameter or an Enhanced Configuration

Parameter (Option 13). It is not used as it is a Diebold‐only feature.

Night Safe Depository Check Flag This is an Option Digit (part of 3). It determines when to check the Night
Safe for an overfill condition.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-47

Common Data Interface Stores
Terminal Configuration

CDI Store Worker Description

Comms Status Trace Option This is an Option Digit (part of 5). If set to 1, tracing is done on the
Journal when the Communications goes On/Off line.

Date Format Option This is an Enhanced Configuration Parameter (Option 3) which specifies
the format of the date when using it for tasks such as printing.

Dispense Status Delay Option This is an Option Digit (part of 4), which controls when the Dispenser
solicited status messages are sent.

Download Save Option This is an Option Digit (part of 5) and determines when any
downloaded data is saved to disk.

Hard Copy Backup Time Limit This is an Enhanced Configuration Parameter (option 16) holding the
maximum time for the Journal backup when Printer is non‐operational.

Hard Copy Backup Records Limit This is an Enhanced Configuration Parameter (option 17) holding the
maximum number of records to backup for the Journal backup when
Printer is non‐operational.

Envelope Dispenser Status This is an Enhanced Configuration Parameter (Option 23) and
Reporting Option determines whether the Envelope Dispenser status messages should be
sent to Central.

Extended Status Reporting Option This is an Enhanced Configuration Parameter (Option 11). It is not used
as it is a Diebold only feature.

Journal Mode This determines where the Journal output is to be directed.

Left / Right FDK Swap Option This is an Option Digit (part of 7) and determines whether the Left/Right
FDKs are to be used in Keyboard Entry States.

Left Print Column This holds the value for the left margin for the Receipt. It is entered in
either the Roll Width Configure Supervisor function, or set using an
Enhanced Configuration Parameters download, (Option 5).

Max Receipt Lines This is an Option Digit (part of 6) and specifies the maximum number of
receipt lines; 49 if TRUE, or 24. The standard receipt length for Advance
NDC is 24 lines. Applications must add a FF and CUT after 24 lines (or
49 if idMaxReceiptLines is set). The conversion process will not
modify this flag.

MEI Flash Rate Option This is an Enhanced Configuration Parameter (Option 25), or Option
Digit (8), and controls the flash rate of the Media Entry Indicators.

Product Class Not used in Advance NDC.

Ready B Option This is a Configuration Parameter or Enhanced Configuration Parameter

(part of Option 1). If it is set to TRUE, after a successful Transaction
Reply Function Execution a Ready B message is sent instead of a Ready
9.

Remote Relay Option This is an Enhanced Configuration Parameter (Option 27), and
determines when the Remote relay is active.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-48 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Terminal Configuration

CDI Store Worker Description

Retract Untaken Notes Option This is an Option Digit (Part of 2), and determines whether any notes not
taken should be retracted during the Cash Dispense Transaction Reply
Function Execution.

Software ID Option This is an Option Digit (part of 6), and determines if Advance NDC
release number and S/W ID are in the Configuration Terminal State
messages.

Specific Command Reject Option This is an Enhanced Configuration Parameter (Option 12). If execution
of an incoming message fails, this flag determines if Command Reject or
Specific Command Reject is to be used.

Supervisor Key Reporting Option This is an Option Digit (0), and determines which Supervisor Key
presses are reported to Central.

Track 1 Format Option This is an Enhanced Configuration Parameter (Option 7), and holds the
format for Track 1. This can also be set via the Track 1 Configure
Supervisor function.

Transmit TI Status Option This is an Enhanced Configuration Parameter (Option 10), used for
transmitting TI Status. It is not used as it is a Diebold only feature.

TI Sensor Status Reporting Option This is an Enhanced Configuration Parameter (Option 24), for
determining whether enhanced TI/Sensor status unsolicited status
messages are sent.

Security Trace Option This flag is set using the Trace On/Off Configure Supervisor functions. It
determines if Communications tracing on the Journal Printer is active.

Transaction Status Information This is an Enhanced Configuration Parameter (Option 15), used for the
Option inclusion of Transaction Status Information in the Transaction Request
message.

Roll Width This defines the number of columns to print on for the Receipt and
Journal printers. The information is entered in the Roll Width Configure
Supervisor function or set in an Enhanced Configuration Parameter
(Option 4). The conversion process will not modify this flag.

Supervisor Auto Return This is a Configuration Parameter or Enhanced Configuration Parameter

(Part of Option 1), and determines whether or not to return to the
previous mode on exiting from Supervisor mode.

Configuration ID This holds the Configuration ID downloaded in a Configuration ID

Load message.

Current Version This holds the Current Release Number of Advance NDC. It is used in
the Terminal State message in response to the Send Configuration
Information Terminal Command.

Logical Unit Number This holds the LUNO (Logical Unit Number) which is present in many
NDC+ Communications messages.

Machine Number This holds the Machine Number which is entered in one of the machine
number options on the Supervisor Config menu. It is used when taking
camera pictures, in Deposit printing and in the EJ backup log filename.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-49

Common Data Interface Stores
Terminal Configuration

CDI Store Worker Description

Configuration Saved This is a flag, used to indicate that the configuration data has been
saved.

PromoteEnabled This holds an integer to indicate whether Promote is currently enabled

or disabled. The store is set at start of day, before going in‐service and on
exit from Supervisor based on the current status of Promote as follows:
 If enabled, the store is set to 1 (default)
 If disabled, the store is set to 0

RelateEnabled This holds an integer to indicate whether Relate is currently enabled or

disabled. The store is set at start of day, before going in‐service and on
exit from Supervisor based on the current status of Relate as follows:
 If enabled, the store is set to 1
 If disabled, the store is set to 0 (default)

MM Option This is not supported in Advance NDC.

Touch Screen Error Reporting This is not supported in Advance NDC.

Option

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-50 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Timers

Timers C

Table C-29
Timers

CDI Store Worker Description

Timer 0 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 0.

Timer 1 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 1.

Timer 2 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 2.

Timer 3 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 3.

Timer 4 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 4.

Timer 5 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 5.

Timer 6 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 6.

Timer 7 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 7.

Timer 8 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 8.

Timer 9 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 9.

Timer 10 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 10.

Timer 61 Value This is an Enhanced Configuration Parameter and holds the value for
Timer 61 (barcode reader scan Timer)

Timer 63 Value This is an Enhanced Configuration Parameter and holds the value for
(3775) Timer 63 (hardware failure screen time‐out).

Timer 68 Value This is an Enhanced Configuration Parameter and holds the value for
Timer 68 (Statement Media Entry/Exit Indicator Duration Timer).

Timer 69 Value This is an Enhanced Configuration Parameter and holds the value for
Timer 69 (Receipt Media Entry/Exit Indicator Duration Timer).

Timer 72 Value This is an Enhanced Configuration Parameter and holds

the value for Timer 72 (remove card timer for DASH cards).

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-51

Common Data Interface Stores
Timers

CDI Store Worker Description

Timer 77 Value This is an Enhanced Configuration Parameter and holds the value for
Timer 77 (Cash Acceptance Timer for the BNA).

Timer 82 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 82.

Timer 83 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 83.

Timer 86 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 86.

Timer 87 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 87.

Timer 91 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 91.

Timer 92 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 92.

Timer 93 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 93.

Timer 94 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 94.

Timer 95 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 95.

Timer 96 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 96.

Timer 97 Value This is a Configuration Parameter or an Enhanced Configuration

Parameter and holds the value for Timer 97.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-52 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Transaction Processing Flags

Transaction Processing Flags C

Table C-30
Transaction Processing Flags

CDI Store Worker Description

Card Jammed Flag This is set to TRUE if a Card is jammed. It is not used in Advance NDC.

Return / Retain Card Flag This holds the Transaction Reply field ‘p’, and determines either to eject
or capture the card at the end of a transaction. It is used in the Close State
to eject or capture cards.

Envelope Dispensed Flag This indicates if an envelope has been presented in an Envelope
Dispense State. It determines whether there is a need to dispense an
envelope in the Deposit Function.

Envelope Presented Flag This indicates if an envelope has been presented in an Envelope
Dispense State. It determines whether there is a need to dispense an
envelope in the Deposit Function.

FIT Match Found Flag This is set to TRUE in the Card Read State, if a FIT Match has been
found. It is used in State Types such as the FIT Switch.

Track Language Offset This holds the offset on the Card Track where the language code can be
found. It is not used as a duplicate of the PLNDX.

Next State Number This holds the Next State Number to be executed. This is set by each
State Type on completion determining the next State to be executed.

Receipt Printed Flag If set to TRUE then printing has occurred. It is used to tidy up in the
Close State.

Top of Receipt Flag This holds the Transaction Request field ‘f’, and is used in the
Transaction Reply Printer handling. It is set to TRUE on startup. In the
Close State, if it is set to FALSE and the receipt is printed on, then the
receipt is delivered/cut and the flag is set to TRUE.
This flag is true if the receipt printer head is at the top of the page. The
conversion process will set this flag depending on the value of
TRPrintLineCount, Message Mode Option 6, and whether the last
item processed was a Line Feed sequence. If this flag is set to FALSE in
the Close State then the mNDCPrintFooter will cut and eject a receipt.

Statement Printed Flag If it is set to TRUE then printing has occurred. It is used to tidy up in the
Close State.

Track 1 Update Flag This is set to FALSE in the Transaction Reply initialisation. It is set to
TRUE if there is T1 data in the Transaction Reply. It is used in the Card
Write State.

Track 2 Update Flag This is set to FALSE in the Transaction Reply initialisation. It is set to
TRUE if there is T2 data in the Transaction Reply. It is used in the Card
Write State.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-53

Common Data Interface Stores
Transaction Processing Flags

CDI Store Worker Description

Track 3 Update Flag This is set to FALSE in the Transaction Reply initialisation. It is set to
TRUE if there is T3 data in the Transaction Reply. It is used in the Card
Write State.

Transaction Reply Function ID This holds the Transaction Reply field ‘l’ ‐ function to execute. It
influences the validation of data, controls the function to execute and is
used in the Status Handling.

Customisation Layer Status This holds data for the Status of the Customisation Layer. It is used to
determine what processing of messages, particularly Transaction Reply,
is required in the Application Core.

Power Fail Recovery Flag This holds data for the Power Fail Recovery Flag. It is set before the
Transaction Reply Function Execution, and is checked on start up to see
whether a power fail has occurred during a transaction.

Top of Statement Flag This is used in the Transaction Reply Printer handling. It is set to TRUE
on startup. In the Close State, if it is set to FALSE and the Statement is
printed on, then deliver/cut statement and set flag to TRUE.

Dial up Flag Used to indicate that the SST communicates with Central through dial
up communications (VISA2)

State Flow Sequence If state flow tracing is enabled, the number of any state executed during
a transaction is appended
After the trace is journaled (at Start of Day if a power fail occurred and
during the Close state) this CDI is reset to null
This CDI can store a maximum of 1024 characters. If this maximum is
reached, the store is cleared and any further state numbers continue to
be stored

CAV Started Flag This is not used in Advance NDC.

Document Presented Flag This is not used in Advance NDC.

CAM Flag (1378) idCAMBuffer is the Byte 2 of CAM flags, and the bits are populated as
follows:
The value of bit 1 is set to 0 or 1 to indicate whether the transaction was
performed using a contact or a contactless card.
 Contact ‐ 0
 Contactless ‐ 1
If the transaction is performed using a contactless card, the value of bit 2
is set to 0 or 1 to indicate the mode of the transaction was an EMV‐Like
or a Magnetic Stripe‐Like.
 Magnetic Stripe‐Like ‐ 0
 EMV‐Like ‐ 1
If the transaction is performed using a contactless card, the value of bit 3
is set to 1, and the 4 to 8 bits are set to 0.
When a transaction is performed using a contact card, all the 8 bits are
set to 0.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-54 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
UCDI Stores

UCDI Stores C

UCDI stores provide an easy way to create shared stores across

applications that can be used in different programming
environments, such as C, C++, Script, COM, Author and VB.

Table C-31
UCDI Stores

UCDI Store Worker Description

DM ParamValues DM ParamValues helps the passing of data to web URL.

HostMessage Contains a message received from Central.

MessageForHost Stores a new ʹuserʹ message for sending to Central.

StatusInfo Stores the status information used in a terminal state message.

PendingTC Stores a Pending Terminal Command.

PendingTR Stores a Pending Transaction Request.

CPM cheque present The Cheque Processing Module (CPM) Cheque Accept State (‘w’) sets
this store when a cheque has been successfully entered into the CPM.
This store is checked at start of day and at the end of a transaction, to
determine if a cheque is present in the CPM.
The supervisor Replenish menu option 43 (INIT DEPOS) clears this
store.

PreHeader This persistent store contains header information up to 32 characters

long. This forms part of an optional header that can appear at the top of
a printout when using the PRNT CNTR or PRNT SPPLY supervisor
functions. The pre‐header is part of the reserved screen j4010 and forms
the dynamic content within that reserved screen. The remainder of the
optional header content is based on the reserved screen entry for j4010.
For further information, refer to the APTRA Advance NDC, Reference
Manual.

You must ensure all UCDI stores are cleared, initialised and set by
your application as required.

Note: CDI and UCDI stores used for customising printers are used
only for other vendors’ SSTs. For details, refer to the APTRA
Advance NDC, Multi‐Vendor Support Reference Manual.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-55

Common Data Interface Stores
Voice Guidance Stores

Voice Guidance Stores C

Table C-32
Voice Guidance Stores

Voice Guidance Store Worker Description

Lock Current Screen This holds the cardholder selection during a voice‐guided session
determining whether screens are hidden.
 0 ‐ Screens are displayed
 1 ‐ Screens are hidden.

VG Session This holds a value determining whether the current session is a

voice‐guided session.
 0 ‐ Session is not a voice‐guided session
 1 ‐ Session is a voice‐guided session.

TranReply Voice Data This holds the voice guidance data received in the Transaction Reply.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-56 APTRA Advance NDC, Developer’s Guide

 Common Data Interface Stores
Miscellaneous CDIs

Miscellaneous CDIs C

The following CDIs are used by cash acceptors and recycling units,
but are not in any catalog.

Table C-33
CDIs Outside Catalogs

CDI Index Description

1375 This is a flag indicating that the host has timed out during a transaction.
This is set to 1 when a host time‐out occurs during a transaction. It is
reset to 0 at the end of the Close state.

 0 ‐ No host timeout or no interaction with the host occurred during

the transaction
 1 ‐ A host timeout occurred during the transaction. This is set for any
host timeout regardless of the number of transaction requests and
replies within a single transaction.

2167 Custom Faults

This holds the list of reserved screen numbers for the screens
representing messages to be displayed on the Fault Display for
customisations
The customisation must populate this CDI store. For details of the
required format, refer to Chapter 4, “Screens and Keyboards” in APTRA
Advance NDC, Extending the Product.

3765 Cash In Retract Operations

This holds a count of the number of cash‐in retract operations.

5047 This takes a copy of the BNA Retract Bin Counts CDI (5046) before a
retract operation to allow counts to be differenced after the retract
operation

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide C-57

Common Data Interface Stores
Accessing CDI Store Values

Accessing CDI Store Values C

The CDI store values can be accessed in the following ways:

 Using the pre‐defined stores located in the catalogs described in
this chapter
 Calling the COM CDI worker from a script. The COM CDI
worker is an instance of an Automation Object worker class. For
details of this worker class, refer to the worker class on‐line help
provided with the APTRA Author. The workers that can be
accessed are given in the ndcdatae.h file. This file is included in
development installations only, and is located in
<drive>:\ntglobal\final\include.
To call the COM CDI worker from a script, do the following:
1 Create an Active Script Host worker

2 Place the COM CDI worker in the Data Object workgroup

3 Update the variables list with COM CDI

4 Update the script with the code that uses the component.
An example of the code created to provide a count of notes
identified as counterfeit under the ECB 6 regulations is given in
Figure C‐1. The constant, idAccumulatedCAT2 = 5042, is taken
from the ndcdatae.h file.

Figure C-1 Sub activate()

Example Code to Count Counterfeit Notes
Dim total
Const idAccumulatedCAT2 = 5042
For i = 0 To 49
total = total + ComCDI.comInteferArray(idAccumulatedCAT2, i)
Next

End Sub

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

C-58 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Font Definition

Appendix D
Font Definition

Overview D‐1

Defining Fonts D‐2

Creating Fonts D‐2
Font Configuration D‐2
Font Selection D‐3
Font Designators D‐3
Character Sets D‐4
Migrating to the Advance NDC Display XML File D‐5

Installing Fonts D‐9

Checking the Fonts D‐10

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Font Definition

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Font Definition
D

Overview

Overview D

This appendix describes how you can define and use your own
TrueType fonts for use with screens and printers.
The appendix includes examples of the font definition and mapping
files.

Note: To enable an EMV Integrated Circuit Card (ICC), also called

a smart card, to be used, additional fonts and font designators are
provided with Advance NDC. If you wish to use an EMV ICC, refer
to the EMV Integrated Circuit Card (ICC) Reference Manual provided
with the EMV/CAM2 Exits for APTRA Advance NDC product. This
manual lists the additional EMV fonts and font designators.

This appendix also describes how to install a font after it has been
created or edited, and how to check that it is usable.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide D-1

Font Definition
Defining Fonts

Defining Fonts D

The following subsections provide the following information:

 Creating your own fonts for screen display
 Configuring fonts
 Adjusting your downloadable fonts for a different resolution
printer
 Installing fonts
 Checking fonts.
Advance NDC recognises some default font names and designators
for screens, as shown in Table D‐2. These default settings can be
changed, as shown in the “Font Configuration” section, or
additional fonts can be added using the unassigned designators
listed in the table.
For forms‐based printing, you can create a Windows font as
described in the next section, “Creating Fonts”. For example, you
could create a font for a specific language, such as Cyrillic or
Hebrew, for use when printing on a statement printer using forms.

You can extend the default fonts supported by Advance NDC using
Creating Fonts D

the following methods:

 Using an existing TrueType font
 Editing an existing TrueType font
 Creating your own TrueType font using a third‐party utility.

For example, a utility such as ScanFont (available through the

web site www.fontlab.com) is useful as it enables you to move
glyphs within a font table, and hence change the character
displayed for a particular Advance NDC character code.

You can use any fonts or font development utility you prefer.
Further details, utilities and fonts can be found on the Microsoft
Typography web site www.microsoft.com/typography.

The font definition file used comma‐delimited positional fields, as

Font Configuration D

explained in Table D‐4. This file has been replaced by the Advance
NDC display configuration file (DisplayManagerConfig.xml) and the
fields must be translated to similar attributes in the
DisplayManagerConfig.xml file. For details of the
DisplayManagerConfig.xml file, see “Advance NDC Display
Configuration File” on page 5‐162.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

D-2 APTRA Advance NDC, Developer’s Guide

 Font Definition
Defining Fonts

The font definition file was only required if adding additional fonts,
or assigning a different font to one of the designators already
recognised by Advance NDC. For further information, see the “Font
Designators” section.

Font Selection D

Fonts are selected in Advance NDC screens by using the escape

sequences shown in Table D‐1. In these escape sequences, X is the
font designator. The font designator used must be either a default
font supported by Advance NDC or one that you have installed and
included in the DisplayManagerConfig.xml file.

Table D-1 Escape Sequence Description

Font Selection Escape Sequences
ESC ( X Selects the font to use for the primary character set

ESC ) X Selects the font to use for the secondary character

set

Font Designators D

Table D‐2 shows the font designators recognised by Advance NDC

by default. Table D‐2 gives a descriptive form of the font face name.
When specifying the font you must use the typeface name. To view
the default font face and typeface names, complete the following
steps:
1 Open the Font directory. This is usually located in the
C:\WINDOWS path

2 Double‐click the required font filename. A file describing the

font is displayed. The typeface name is given at the top of the
file.
Additional fonts can be assigned to both the unassigned and default
designators. If a new font is assigned to a default designator, the
new font is displayed whenever the designator is used.

Note 1: If no font designator is defined, the default font defined in

the DisplayManagerConfig.xml file is used. The default primary and
secondary font values are as shown in the following:

<fontDefinitions defaultPrimaryFont="1"
defaultSecondaryFont="3">.

Note 2: Any defined fonts must be successfully installed. If they are

not installed, the default font defined in the
DisplayManagerConfig.xml file is used.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide D-3

Font Definition
Defining Fonts

Table D-2 Designator Font Face

Font Designators
1 NDC Alphanumeric 1

2 NDC Alphanumeric 2

3 NDC Standard Graphics Set 1

See Note:

4 NDC Standard Graphics Set 2

5 NDC Standard Graphics Set 3

6 None (NDC Alphanumeric 1)

7 NDC Customer Graphics 2 (Arabic)

8 None (NDC Alphanumeric 1)

9 None (NDC Alphanumeric 1)

: Double Size NDC Chinese 1

; Double Size NDC Chinese 2

< None (NDC Alphanumeric 1)

= None (NDC Alphanumeric 1)

> Double Size NDC Alphanumeric 1

? Double Size NDC Alphanumeric 2

@ None (NDC Alphanumeric 1)

A None (NDC Alphanumeric 1)

B Double Size NDC Customer Graphics 2 (Arabic)

C None (NDC Alphanumeric 1)

D None (NDC Alphanumeric 1)

E None (NDC Alphanumeric 1)

F None (NDC Alphanumeric 1)

G None (NDC Alphanumeric 2)

Note: NDC Standard Graphics Set 1 font is used for graphics only
and not for text display.

Character Sets D

Table D‐3 lists the character sets supported by Microsoft Windows

that can be used in Advance NDC screens. Either the character set
name or value can be used to identify the character set to use.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

D-4 APTRA Advance NDC, Developer’s Guide

 Font Definition
Defining Fonts

Table D-3 Character Set Name Value

Character Set Names and Values
ANSI_CHARSET 0

DEFAULT_CHARSET 1

SYMBOL_CHARSET 2

SHIFTJIS_CHARSET 128

HANGEUL_CHARSET 129

HANGUL_CHARSET 129

GB2312_CHARSET 134

CHINESEBIG5_CHARSET 136

JOHAB_CHARSET 130

GREEK_CHARSET 161

TURKISH_CHARSET 162

VIETNAMESE_CHARSET 163

HEBREW_CHARSET 177

ARABIC_CHARSET 178

RUSSIAN_CHARSET 204

THAI_CHARSET 222

EASTEUROPE_CHARSET 238

Note: If an unsupported character set is requested, Advance NDC

uses the UNKNOWN_CHARSET character set.

For details of the default character sets provided on displays and

printers, refer to the APTRA Advance NDC, Reference Manual.

Migrating to the Advance NDC Display XML File D

The fontdefs.txt file contained a line for additional or redefined fonts,

as follows:
Font Designator, Font Face, Char Set, Width, Height, X Offset,
Y Offset, Double Height, Bold, Italic, Underline, Strikeout

These fields and their mapping to the DisplayManagerConfig.xml file

XML attributes are defined in Table D‐4.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide D-5

Font Definition
Defining Fonts

Table D-4
Field to Attribute Mappings

Advance NDC
Font Definition File
Value Display XML Translated Value Comment
Field
Attribute

Font Designator See Comment id See Comment The symbol identifying the font.
If no font See Table D‐2 for the font
designator is designators and any fonts
specified, 1 assigned by default.
(NDC
Alphanumeric
1) is used

Font Face Name See Comment face See Comment The name of the font face.
See Table D‐2 for the font face
names with their default
designations.

Char Set See Comment charset See Comment The name or value of the
ANSI_CHARSET character set.
by default See Table D‐3 for a list of
accepted character set names
and values.

Width See Comment width See Comment The width of the characters in
By default, 100 By default, 100 logical units according to the
for normal aspect ratio of the selected font.
width fonts, 200
for double
width fonts

Height See Comment height See Comment The height of the characters in
By default, 100 By default, 100 logical units according to the
for normal character cell height minus the
height fonts, internal‐leading value.
200 for double
height fonts

X offset See Comment xOffset See Comment The initial horizontal position of
the text relative to the default
starting position
By default, 0, at the left of the
display or page.
A positive offset positions a
character to the right.
A negative offset positions a
character to the left.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

D-6 APTRA Advance NDC, Developer’s Guide

 Font Definition
Defining Fonts

Advance NDC
Font Definition File
Value Display XML Translated Value Comment
Field
Attribute

Y offset See Comment yOffset See Comment The initial vertical position of the
text relative to the default
starting position
By default, 0, at the top of the
display or page.
A positive offset positions a
character up.
A negative offset positions a
character down.

Double Height 0 ‐ Do not use size Single ‐ Use The height of the font
double height single height font
font (default) (default)
1 ‐ Use double Double ‐ Use
height font double height
font

Weight 0 ‐ Do not use weight FW_NORMAL ‐ Whether to use bold font

bold font Do not use bold
(default) font (default)
1 ‐ Use bold font FW_BOLD ‐ Use
bold font

Italic 0 ‐ Do not use italic false ‐ Do not use Whether to use italic font
italic font italic font
(default) (default)
1 ‐ Use italic true ‐ Use italic
font font

Underline 0 ‐ Do not use underline false ‐ Do not use Whether to use underline font
underline font underline font
(default) (default)
1 ‐ Use true‐ Use
underline font underline font

Strikeout 0 ‐ Do not use strikeout false ‐ Do not use Whether to use strikeout
strikeout strikeout
(default) (default)
1 ‐ Use strikeout true ‐ Use
strikeout

Example Mapping The following line in a font.def file: 4

3,Courier New,RUSSIAN_CHARSET,110,100,0,6,0,0

maps to the following line in the DisplayManagerConfig.xml file:

<font id="3" face="Courier New" charset="RUSSIAN_CHARSET"
width="110" height="100" xOffset="0" yOffset="6"
size="Single" weight="FW_BOLD"

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide D-7

Font Definition
Defining Fonts

Proportional Fonts Additional support for proportional fonts is 4

provided by the DisplayManagerConfig.xml file using the

fixedSpacing attribute. This attribute allows proportional fonts to
be displayed without fitting each character on the default 32 by 16
grid layout.
For further information on the fixedSpacing attribute see
Table 5‐44, “Advance NDC Display XML Elements” on page 5‐163.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

D-8 APTRA Advance NDC, Developer’s Guide

 Font Definition
Installing Fonts

Installing Fonts D

Once you have obtained, created or edited the TrueType fonts to be

used, they must be installed on the SST.
Use the Control Panel to install the required fonts as follows:
1 In Control Panel, select Fonts to display the installed fonts

2 Select File | Install New Font

3 In the Add Fonts dialog box, use the Drives and/or Folders
options to specify the location of your fonts

4 Select the required fonts

5 Ensure the Copy fonts to Fonts folder check box is ticked, and
select OK.
Your selected fonts will now be included in the Windows\Fonts
folder with the other installed Windows fonts.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide D-9

Font Definition
Checking the Fonts

Checking the Fonts D

You can use any Windows program that uses fonts, such as
WordPad, to display the fonts to prove that they are correctly
installed.
If DebugLog is active, the updated font identifiers are logged.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

D-10 APTRA Advance NDC, Developer’s Guide

 Table of Contents
PCI DSS & PA-DSS Compliance in Advance NDC

Appendix E
PCI DSS & PA‐DSS Compliance in
Advance NDC

Overview E‐1

PA‐DSS and Compliance with PCI DSS E‐2

PCI DSS Requirements E‐2
Advance NDC and PA‐DSS Requirements E‐3
Other PA‐DSS Requirements E‐4

Advance NDC Modifications for PA‐DSS Compliance E‐5

Debugging E‐5
Transaction Reply E‐5
OOXFS Logging E‐6
Author Flow E‐6
Transaction Request E‐6
Journaling E‐6
Enhanced Configuration Option 37 E‐6
Reserved Screen t15 E‐7
Option Digit 5B E‐7
Communications Trace E‐7
Cash‐In Component E‐7
Journaling Cardholder Data E‐7
ECB 6 functionality E‐7
DAPI Requirements E‐8
Supervisor Authentication E‐8
Replenish Menu E‐8
Miscellaneous Function Menu E‐8
Configure Menu E‐8
Access Menu E‐8
Local User Group and User Account E‐9
Supervisor Authentication Data Entry E‐9
Password Expiration E‐10
Login Attempts E‐10

Cheque Processing Solutions E‐11

Storing Cheque Images E‐11

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
PCI DSS & PA-DSS Compliance in Advance NDC

Displaying Cheque Images E‐11

Printing Cheque Images E‐11
Deleting Cheque Images Securely E‐11
Cheque Processing with ImageMark Passport E‐12
Secure Deletion of ImageMark Files E‐12

External Audits E‐14

Advance NDC Solutions and Compliance E‐14
Advance NDC Customisations and Compliance E‐14
Customisation Audit Example E‐15

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 PCI DSS & PA-DSS Compliance in Advance NDCE

Overview

Overview E

Compliance of an application with the PA‐DSS (Payment

Application Data Security Standard) “will facilitate and not prevent
customers’ PCI DSS compliance”, according to PCI PA‐DSS,
Requirements and Security Assessment Procedures.
This appendix describes the changes implemented in Advance NDC
to facilitate customers’ compliance with the PCI DSS (Payment Card
Industry Data Security Standard).
For guidelines on deploying Advance NDC in a way that complies
with PCI DSS requirements, refer to the APTRA Advance NDC,
PA‐DSS Implementation Guide.
For more information about PCI DSS and PA‐DSS, refer to the PCI
Security Standards website.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide E-1

PCI DSS & PA-DSS Compliance in Advance NDC
PA-DSS and Compliance with PCI DSS

PA‐DSS and Compliance with PCI

DSS E

The purpose of PA‐DSS is to help software vendors and payment

application providers develop secure payment applications that
handle cardholder data securely. This entails not storing cardholder
data, such as full magnetic stripe, second card verification value
(CVV2) or PIN data.
PA‐DSS is intended to facilitate efforts to develop payment
application solutions that comply with PCI DSS.

PCI DSS has a number of requirements that must be fulfilled. The

PCI DSS Requirements E

following table summarises the requirements:

Table E-1
PCI DSS Requirements

Primary
Control Objective Requirement Primary Requirement Description
Number

Build and Maintain a Secure Network 1 Install and maintain a firewall configuration to protect
cardholder data

2 Do not use vendor‐supplied defaults for system

passwords and other security parameters

Protect Cardholder Data 3 Protect stored cardholder data

4 Encrypt transmission of cardholder data across open,

public networks

Maintain a Vulnerability Management 5 Use and regularly update anti‐virus software

Program

6 Develop and maintain secure systems and applications

Implement Strong Access Control 7 Restrict access to cardholder data by business need to
Measures know

8 Assign a unique ID to each person with computer

access

9 Restrict physical access to cardholder data

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

E-2 APTRA Advance NDC, Developer’s Guide

 PCI DSS & PA-DSS Compliance in Advance NDC
PA-DSS and Compliance with PCI DSS

Primary
Control Objective Requirement Primary Requirement Description
Number

Regularly Monitor and Test Networks 10 Track and monitor all access to network resources and
cardholder data

11 Regularly test security systems and processes

Maintain an Information Security Policy 12 Maintain a policy that addresses information security
for all personnel

For more information about PCI DSS requirements, refer to the PCI
Security Standards website.

The following table summarises the changes that have been

Advance NDC and introduced in Advance NDC to meet specific PA‐DSS requirements:
PA‐DSS Requirements E

Table E-2
Changes to Advance NDC for PA-DSS

PA-DSS Requirement Comment

Do not retain full magnetic stripe, card This includes masking cardholder data in debug logs and journal
validation code or value (CAV2, CID, data.
CVC2, CVV2), or PIN block data See “Debugging” on page E‐5 and “Journaling” on page E‐6

Protect stored cardholder data This includes masking cardholder data in debug logs and journal
data, and securely deleting cheque images.
For logs and journals, see “Debugging” on page E‐5 and “Journaling”
on page E‐6.
For ECB, see “Cash‐In Component” on page E‐7.
For cheque images, see “Deleting Cheque Images Securely” on
page E‐11

Provide secure authentication features This includes controlling access to key Supervisor functions through
secure authentication, as these functions may allow access to
cardholder data, for example, TCP/IP configuration.
See “Supervisor Authentication” on page E‐8

Log payment application activity This includes logging any attempt at secure Supervisor
authentication, and any activity after secure Supervisor
authentication has taken place, to provide an audit trail showing who
has accessed the SST.
See “Supervisor Authentication” on page E‐8

Develop secure payment applications Internal Advance NDC development processes have been tailored to
adhere to this requirement. Customisations also have to adhere to
secure development practices.
Refer to the APTRA Advance NDC, Extending the Product publication

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide E-3

PCI DSS & PA-DSS Compliance in Advance NDC
PA-DSS and Compliance with PCI DSS

PA-DSS Requirement Comment

Test payment applications to address Internal Advance NDC development processes have been tailored to
vulnerabilities adhere to this requirement. Customisations also have to test payment
applications for vulnerabilities.
Refer to the APTRA Advance NDC, Extending the Product publication

Encrypt sensitive traffic over public Advance NDC includes the latest CCM TCPIP component, offering
networks SSL (Secure Sockets Layer) protection for all NDC message
communication with the host application

Maintain instructional documentation A manual, APTRA Advance NDC, Payment Application Data Security
and training programs for customers, Standard, Implementation Guide, is provided with Advance NDC
resellers, and integrators providing more detail about PCI requirements and what must or
must not be done to achieve PCI DSS compliance for an APTRA
Advance NDC solution.
For more information, see “Advance NDC Documentation” on
page A‐2

The following PA‐DSS requirements do not directly affect Advance

Other PA‐DSS NDC, unless it is customised for an end solution to use these
Requirements E
features. No changes have been made to Advance NDC for these
requirements.
 Protect wireless transmissions
 Cardholder data must never be stored on a server connected to
the Internet
 Facilitate secure remote access to payment application
 Encrypt all non‐console administrative access
 Facilitate secure network implementation
For more information about these requirements and best practice,
refer to the APTRA Advance NDC, Payment Application Data Security
Standard, Implementation Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

E-4 APTRA Advance NDC, Developer’s Guide

 PCI DSS & PA-DSS Compliance in Advance NDC
Advance NDC Modifications for PA-DSS Compliance

Advance NDC Modifications for

PA‐DSS Compliance E

Advance NDC has been modified in the following areas to comply

with PA‐DSS requirements:
 Debugging
 Journaling
 Cash‐in component
 DAPI requirements
 Supervisor authentication

DebugLog, Silent Debug and Problem Determination are provided

Debugging E

with Advance NDC to capture debugging information from

development systems, systems under test or live systems.
By default, debugging is disabled but it can be enabled through the
the DebugLog registry entry, or the Troubleshooting menu
available through the Supervisor Configure menu, providing access
to Problem Determination and Silent Debug.
The following subsections describe the sensitive data that may be
logged to one of the debugging tools and include the Advance NDC
changes for PA‐DSS compliance. Registry keys are provided to
enable or disable the masking of sensitive customer data in trace
data when troubleshooting. For details of the registry keys, see
“Example of Adding Flow Points” on page 5‐31.

Transaction Reply E

The following fields in the Transaction Reply message can contain

magnetic stripe data:
 Track 1 data (Field ak2)
 Track 2 data (Field al2)
 Track 3 data (Field x)
This information is present if the host updates the track data on the
magnetic stripe.
These fields are fully masked in debug logs.
Data sent in an Interactive Transaction Reply or a Transaction Reply
to the Message In window, or printer data sent to the OOXFS
window in DebugLog and Silent Debug, can now be masked. The
masking of sensitive data in these messages can be enabled and
disabled through registry configuration settings.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide E-5

PCI DSS & PA-DSS Compliance in Advance NDC
Advance NDC Modifications for PA-DSS Compliance

OOXFS Logging E

When a WFS_EXEE_IDC_INVALIDTRACKDATA event is received from

the XFS platform, some magnetic stripe data is written to the
OOXFS log.
The identified information is fully masked in debug logs.

Author Flow E

In previous versions of Advance NDC, some Debug Message

Sender workers in the Application Core and Customisation Layer
projects wrote sensitive information, (magnetic‐stripe data and
settlement encrypted PIN data) to the various Debug Log windows.
These workers no longer write sensitive data to debug logs.

Transaction Request E

Any Transaction Request message that is traced in debug logs is

PA‐DSS compliant in that all track data and encrypted PIN data is
masked in the debug logs. The following fields are masked:
 Track 2 data (Field h)
 Track 3 data (Field i)
 Encrypted pin (Field l)
 Track 1 data (Field o)
 CSP data (Field av2)
 Confirmation CSP data (Field aw2)
 MICR (Field cb3)
 Bunch cheque deposit (Fields cg1 to cg16)
All other information written to the debug logs is stored in a
plain‐text format. As this information does not contain cardholder
data, it is outside the scope of PA‐DSS.

Cardholder information is written to the journal in a number of

Journaling E

areas in Advance NDC. The following subsections describe the

sensitive data that may be journaled and include the Advance NDC
changes, following PA‐DSS recommendations for PA‐DSS
compliance.

Enhanced Configuration Option 37 E

In previous versions of ANDC, with option 37 set to 001 (print data

on the journal) and a card inserted into the reader, the data stored
on track 2 was journaled. Now, as magnetic stripe data must not be
stored, it is replaced by the PAN (Primary Account Number), with
all digits masked except the last four. This applies to both the Card
Read ‘A’ state, and Card Read ‘T’ state.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

E-6 APTRA Advance NDC, Developer’s Guide

 PCI DSS & PA-DSS Compliance in Advance NDC
Advance NDC Modifications for PA-DSS Compliance

Reserved Screen t15 E

In previous versions of Advance NDC, reserved screen ‘t15’ was

used to control which characters in the data were masked. Now it
masks all data except the last 4 digits.

Option Digit 5B E

In previous versions of Advance NDC, when Option Digit 5B was

enabled and a card was captured, the Primary Account data was
journaled in a plain‐text format. Now, only the last 4 digits are
visible.

Communications Trace E

When the communications trace is enabled (TRACE ON) the first 35

characters of any messages that are sent or received by the SST are
journaled. Although these messages are quite short in length, they
can contain sensitive information, such as track data in a
Transaction Request message. The relevant fields are masked before
being journaled.

Changes have been required in the cash‐in component for

Cash‐In Component E

journaling and ECB 6 functionality to ensure PA‐DSS compliance.

These changes are described in the following subsections.

Journaling Cardholder Data E

The following registry entry controls whether cardholder data is

journaled:
HKEY_LOCAL_MACHINE\SOFTWARE\NCR\Advance NDC\BNA\
CashInJPTR
ReportCustomerData=dword:00000000
The default value is 0: do not journal cardholder data.
If the value is set to 1, the PAN is journaled at the end of a
transaction. In previous releases of Advance NDC, the PAN was
printed in plain text. The PAN is now masked, except for the last 4
digits.

ECB 6 functionality E

ECB 6 is designed to detect counterfeit or suspect notes and record

information, enabling identification of the person who deposited
the notes. To meet this requirement, cardholder data is stored in a
file on the system disk. To meet PCI requirements, the cardholder
data is masked.
To comply with ECB 6 functionality, additional information must be
configured in the class configurator file for inclusion in the device
status information field in the BNA ECB 6 unsolicited status
message. This information includes data to identify the depositor of
the fraudulent notes and is masked in any debugging logs. For

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide E-7

PCI DSS & PA-DSS Compliance in Advance NDC
Advance NDC Modifications for PA-DSS Compliance

details of the unsolicited message, refer to the APTRA Advance NDC

Reference Manual, chapter 9, “Terminal to Central Messages”.
It is the responsibility of the host application to process the
additional unsolicited status message and store the cardholder
information in a manner that does not break PCI DSS requirements.
When the ECB 6 signature file is exported from the SST, the file will
contain the masked customer data, with only the last 4 digits visible.
This information can then be correlated with the logs processed and
stored by the host to identify the depositor of the notes.

To comply with PCI DSS requirements, an approved encrypting

DAPI Requirements E

PINpad (EPP) must be used with the correct firmware version. An

EPP is approved according to the PCI Pin Encrypting Device
standard (PED). For a list of approved PIN entry devices, including
NCR EPPs, refer to the PCI Security Standards website.

In the Supervisor application, there are a number of configuration

Supervisor Authentication E

functions that have the potential to allow consumer data to be

compromised. Therefore, the Visual Basic script,
ANDCSupervisorUserGroup.vbs is provided for a
password‐protected, PA‐DSS compliant solution.
The Supervisor functions that require password authentication are:

Replenish Menu E

 WRITE SIGS

Miscellaneous Function Menu E

 SOFTWARE UPDATE

Configure Menu E

 TCP/IP CONFIG
 DIALUP CONFIG
 CARDLESS TRANSACTIONS

Access Menu E

 ENTER V
 WRITE V
 ENTER A
 WRITE A
 ENTER B
 WRITE B
 ENTER MAC
 KEY ENTRY

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

E-8 APTRA Advance NDC, Developer’s Guide

 PCI DSS & PA-DSS Compliance in Advance NDC
Advance NDC Modifications for PA-DSS Compliance

Note 1: In the Configure menu, EJ Options that copies files to

removable media do not require password‐protection as the
cardholder data is already masked.

Note 2: In the Access menu, SET PASSWRD supports only a

four‐digit numeric password.
To comply with PA‐DSS guidelines, Supervisor authentication for
access to these functions, is handled through group policy and
Microsoft Windows local user accounts. This allows secure storage
of passwords to be handled by the underlying operating system.

Local User Group and User Account E

A VB script, ANDCSupervisorUserGroup.vbs, is provided to create

one user group and one user account for access to the Supervisor
menus that are password protected.
Installation Locations On the development PC, the script is 5

installed in the c:\ntglobal\Final\XFS\dll directory.

On the SST, the script is installed to
C:\Program Files\NCR APTRA\Advance NDC\Security.
Editing the Script The default entries for user name and 5

password must be edited. If more than one user account is required,

the script must be edited, and run for each one. After the user group
and account(s) are set up, the script must be removed from the SST.
It can remain on the development PC.

Note: The VB script is designed for normal setup of an SST,

configuring one user group; but additional groups are supported
for full role‐based access. If these are required, they must be
configured using the User Group attribute of the Secure
Authenticator worker. For more information, refer to the APTRA
Author help.

Supervisor Authentication Data Entry E

Supervisor authentication supports SMS‐style alphanumeric data

entry using the PIN pad. where the password is masked by default.
Each character of the password that is entered can also be displayed
up to three seconds before it is masked. Delayed password masking
assists with the correct entry of alphanumeric passwords while still
complying with PA‐DSS requirements. For more information, refer
to section “PA‐DSS Compliance” in Chapter 1, “Introduction to
Supervisor Mode” of the APTRA Advance NDC, Supervisorʹs Guide.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide E-9

PCI DSS & PA-DSS Compliance in Advance NDC
Advance NDC Modifications for PA-DSS Compliance

Password Expiration E

To comply with PA‐DSS guidelines, the Supervisor password must

be changed at least every 90 days. When the Supervisor password
expires, the operator is prompted to create a new password when
attempting login to any password‐protected Supervisor function.
For more information on password expiration, refer to the
following:
 “Password Expiration” in Chapter 1, “Introduction to
Supervisor Mode” of the APTRA Advance NDC, Supervisorʹs
Guide.
 “Password Policy and Procedures” in Chapter 1, “Compliance
Policy Guidelines” of the APTRA Advance NDC, Payment
Application Data Security Standard Implementation Guide.

Login Attempts E

To meet PA‐DSS requirements, only a limited number of login

attempts can be allowed before the account is disabled. The number
of login attempts is configurable through Microsoft Windows group
policy, dependent on local security policy. If Security for APTRA is
used, the Security for APTRA installer sets up login attempts in
compliance with PCI DSS requirements.
If an account becomes disabled, it will remain that way for a
specified length of time. This is also configurable through Microsoft
Windows group policy.

Note: Any changes to the group policy Account Lockout Policy will
affect all users, including SSTAuto1. The default Account Lockout
Policy, installed by Security for APTRA, limits the number of
incorrect logon attempts for a specific user name to three, before the
account is locked out for 15 minutes.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

E-10 APTRA Advance NDC, Developer’s Guide

 PCI DSS & PA-DSS Compliance in Advance NDC
Cheque Processing Solutions

Cheque Processing Solutions E

Where a cheque processing solution is offered, the following areas

must be addressed to facilitate PCI DSS compliance:
 Storage of cheque images
 Cheque image display
 Cheque image printing
 Cheque processing
 Secure deletion of cheque images

To comply with PA‐DSS requirements, Advance NDC handles the

Storing Cheque Images E

secure deletion of cheque images after a transaction.

To comply with PA‐DSS, the Magnetic Ink Character Recognition

Displaying Cheque Images E

(MICR) characters on the displayed cheque image are masked. The

original cheque image remains unmodified.

When the host application requests a cheque image to be printed, in

Printing Cheque Images E

a PCI DSS compliant solution, a codeline control value of 2 in the

cheque escape sequence must be specified to mask the codeline.
For details refer to the APTRA Advance NDC, Reference Manual,
chapter 5, “Printer Data”, section “Printer Control Sequences and
Registry Settings”.

Note: This functionality may require a change to the host

application to be PCI DSS compliant.

To comply with PA‐DSS requirements, Advance NDC supports

Deleting Cheque Images secure deletion of cheque images (BMP files) and printable graphics
Securely E
files (GPH files).
The default installation ensures the secure deletion of all BMP and
GPH files stored during CPM/SCPM transactions in the directory
specified by the following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\CPM\ImagePath

The following registry entry configures the secure deletion of

cheque images:
HKLM\SOFTWARE\NCR\Advance NDC\CPM\
ChequeImagesSecureDeletion

Valid values are 1 to 5 with security increasing as the value

increases. If the value is missing or outside the valid range, the

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide E-11

PCI DSS & PA-DSS Compliance in Advance NDC
Cheque Processing Solutions

default value of 2 is used. A value of 2 is the minimum required for

compliance with PCI DSS.
The value set equates to the number of overwrites performed. For
example, when the entry ChequeImagesSecureDeletion is set to 2,
Advance NDC overwrites the files twice and then deletes them in
the Close state of every CPM/SCPM transaction and at start of day.
The files cannot be read even if they are recovered after secure
deletion.

Advance NDC supports the use of ImageMark Passport to expedite

Cheque Processing with cheque transaction processing. ImageMark Passport captures the
ImageMark Passport E
cheque image, interprets the data and automatically balances the
transaction before sending the details to the back‐office server.
Some changes have been identified to make Advance NDC support
for ImageMark Passport PA‐DSS compliant.
The following table describes ImageMark Passport requirements
and how they can be fulfilled while remaining PA‐DSS compliant.

Table E-3
ImageMark Passport Requirements and
PA-DSS Compliance

ImageMark Passport Requirements PA-DSS Compliance

Cardholder‐sensitive data, such as magnetic stripe Advance NDC deletes XML files and cheque image
information, must be stored in an XML file alongside files (BMP) at the end of transactions.
the cheque image in a directory that the ImageMark
Passport agent can access. This is different from
where the cheque processor driver stores the images.

ImageMark Passport sends the cheque image and The transmission of the cheque image and cardholder
associated cardholder data to a back‐office server to data must be secured, for example, by using SSL.
complete the processing.

Secure Deletion of ImageMark Files E

Advance NDC securely deletes all BMP and XML files stored
during CPM/SCPM transactions in the directory specified by the
following registry entry:
HKLM\SOFTWARE\NCR\Advance NDC\CPM\Path\
ImageMarkSecureDeletion

The following registry entry configures the secure deletion of

ImageMark files:
HKLM\SOFTWARE\NCR\Advance NDC\CPM\
ImageMarkSecureDeletion

Valid values are 0 to 5 with security increasing as the value

increases. For values 1 to 5, the functionality is enabled. If the value

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

E-12 APTRA Advance NDC, Developer’s Guide

 PCI DSS & PA-DSS Compliance in Advance NDC
Cheque Processing Solutions

is 0, the functionality is disabled. If the entry does not exist or the

value is outside the valid range, a value of 0 is used. A value of 2 is
the minimum required for compliance with PCI DSS.
When the ImageMarkSecureDeletion entry is set to 2, Advance
NDC overwrites the files twice, with each overwrite taking
approximately 0.1 second, and then deletes them in the Close state
of every CPM/SCPM transaction and at start of day. The files cannot
be read even if they are recovered after secure deletion.

Note: For information about the compliance of ImageMark

Passport with PCI DSS, contact your local Payment and Imaging
team representative.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide E-13

PCI DSS & PA-DSS Compliance in Advance NDC
External Audits

External Audits E

An external PA‐DSS audit must take place for an application to be

certified as compliant. To validate that the requirements have been
met for the Advance NDC product, Advance NDC has obtained
PA‐DSS compliance certification from the PCI Security Standards
Council (PCI SSC), following assessment and submission of an audit
report by a PCI DSS Qualified Security Assessor.

Although the APTRA Advance NDC product is certified as PA‐DSS

Advance NDC Solutions compliant, this does not mean any particular Advance NDC end
and Compliance E
solution will be PCI DSS compliant. An end solution must be
audited to be certified as PCI DSS compliant.

If a customisation is intended for one specific customer, and will not

Advance NDC be made available for other customers to use, it is sufficient to audit
Customisations and the customisation as part of the customer’s PCI DSS audit.
Compliance E

If the customisation is intended for a number of customers, it will

require a PA‐DSS audit. NCR PS or the NCR partner will have to
arrange for a PA‐DSS audit to be carried out prior to releasing the
customised software to customers.
For an example, see “Customisation Audit Example” on page E‐15.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

E-14 APTRA Advance NDC, Developer’s Guide

 PCI DSS & PA-DSS Compliance in Advance NDC
External Audits

Customisation Audit Example E

Figure E‐1 shows Customisation A being deployed only to

Customer A, so it will be audited as part of the customer’s PCI DSS
certification.
Customisation B, however, is being deployed to Customer A and
Customer B, so NCR PS or the NCR partner will have to arrange for
a PA‐DSS audit to be carried out on Customisation B prior to
releasing the software.

Figure E-1
Customisation Audit Example

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide E-15

PCI DSS & PA-DSS Compliance in Advance NDC
External Audits

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

E-16 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Example Custom.ini Files

Appendix F
Example Custom.ini Files

Overview F‐1

Runtime SST Example F‐2

Development Example F‐4

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Example Custom.ini Files

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Example Custom.ini Files
F

Overview

Overview F

This appendix contains example custom.ini files for the Runtime SST
and Development environments.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide F-1

Example Custom.ini Files
Runtime SST Example

Runtime SST Example F

The following is an example custom.ini file for the Runtime SST,

with comment lines to explain the content:

Figure F-1
Runtime SST custom.ini example
; custom.ini for APTRA component customisation
;
; Registry entries have the format:
; [Registry.[configuration set name].MSI component name]
; File entries have the format:
; [Files.[configuration set name].MSI component name]
; If the configuration set name is empty, that section of the file is
; always run when the named MSI component name is installed

[Configure]
; Advance NDC has no configuration tool, so this file must be edited
; manually and this option must not be set
; Set=

; ConfigurationSet1
; registry settings set only when the MSI component ‘CustRun’is
; installed and the configuration set name is ConfigurationSet1
[Registry.ConfigurationSet1.CustRun]
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\NumberValue1=#1
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\StringValue1=MyString
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\MultiStringValue1=[~]str1[~]str2
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\BinaryValue1=#x010203

; files copied only when the MSI component ‘CustRun’ is installed and
; the configuration set name is ConfigurationSet1
; The default destination folder is [INSTALLDIR]
[Files.ConfigurationSet1.CustRun]
srcFile1.dll=C:\Program Files\NCR APTRA\Advance NDC\dstFile1.dll

; ConfigurationSet2
; registry settings set only when the MSI component ‘CustRun’is
; installed and the configuration set name is ConfigurationSet2
[Registry.ConfigurationSet2.CustRun]
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\NumberValue2=#1
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\StringValue2=MyString
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\MultiStringValue2=[~]str1[~]str2
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\BinaryValue2=#x010203

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

F-2 APTRA Advance NDC, Developer’s Guide

 Example Custom.ini Files
Runtime SST Example

; files copied only when the MSI component ‘CustRun’ is installed and
; the configuration set name is ConfigurationSet2
; The default destination folder is [INSTALLDIR]
[Files.ConfigurationSet2.CustRun]
srcFile2.dll=C:\Program Files\NCR APTRA\Advance NDC\dstFile2.dll

; registry settings set every time the MSI component ‘CustRun’is

; installed
[Registry.CustRun]
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\InstallDir=[INSTALLDIR]

; files copied every time the MSI component ‘CustRun’ is installed

; The default destination folder is [INSTALLDIR]
[Files.CustRun]
srcCommonFile.dll=[INSTALLDIR]MyCommonFiles\dstCommonFile1.dll

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide F-3

Example Custom.ini Files
Development Example

Development Example F

The following is an example custom.ini file for the development

environment, with comment lines to explain the content:

Figure F-2
Development custom.ini example
; custom.ini for APTRA component customisation
;
; Registry entries have the format:
; [Registry.[configuration set name].MSI component name]
; File entries have the format:
; [Files.[configuration set name].MSI component name]
; If the configuration set name is empty, that section of the file is
; always run when the named MSI component name is installed

[Configure]
; Advance NDC has no configuration tool, so this file must be edited
; manually and this option must not be set
; Set=

; ConfigurationSetA
; registry settings set only when the MSI component ‘CustDev’is
; installed and the configuration set name is ConfigurationSetA
[Registry.ConfigurationSetA.CustDev]
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\NumberValue1=#1
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\StringValue1=MyString
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\MultiStringValue1=[~]str1[~]str2
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\BinaryValue1=#x010203

; files copied only when the MSI component ‘CustDev’ is installed and
; the configuration set name is ConfigurationSetA
; The default destination folder is [INSTALLDIR]
[Files.ConfigurationSetA.CustDev]
srcFile1.dll=C:\Program Files\NCR APTRA\Advance NDC\dstFile1.dll

; ConfigurationSetB
; registry settings set only when the MSI component ‘CustDev’is
; installed and the configuration set name is ConfigurationSetB
[Registry.ConfigurationSetB.CustDev]
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\NumberValue2=#1
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\StringValue2=MyString
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\MultiStringValue2=[~]str1[~]str2
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\BinaryValue2=#x010203

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

F-4 APTRA Advance NDC, Developer’s Guide

 Example Custom.ini Files
Development Example

; files copied only when the MSI component ‘CustDev’ is installed and
; the configuration set name is ConfigurationSetB
; The default destination folder is [INSTALLDIR]
[Files.ConfigurationSetB.CustDev]
srcFile2.dll=C:\Program Files\NCR APTRA\Advance NDC\dstFile2.dll

; registry settings set every time the MSI component ‘CustDev’is

; installed
[Registry.CustDev]
HKEY_LOCAL_MACHINE\Software\MyCompany\MyProduct\InstallDir=[INSTALLDIR]

; files copied every time the MSI component ‘CustDev’ is installed

; The default destination folder is [INSTALLDIR]
[Files.CustDev]
srcCommonFile.dll=[INSTALLDIR]MyCommonFiles\dstCommonFile1.dll

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide F-5

Example Custom.ini Files
Development Example

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

F-6 APTRA Advance NDC, Developer’s Guide

 Table of Contents
User-Configurable States

Appendix G
User‐Configurable States

Overview G‐1

Web Exit State G‐2

State Table Parameters G‐2
Tracking URLS G‐3
Extension to the Web Exit State G‐4

Web Exit Configuration G‐6

WebExitURLTable.XML File G‐6
Adding Websites to the Trusted Sites Zone G‐6
Updating STCONT G‐7
Updating the State Flow G‐7
Example Flow Trace G‐7
State Table Updates G‐8
Configuring Web Page Download Timer G‐8

Cardholder Verification State G‐10

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
User-Configurable States

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 User-Configurable States
G

Overview

Overview G

This appendix provides the following information:

 Enabling a web Exit using the Web Exit State
 Configuring a web Exit
 Enabling cardholder verification by Central for transactions that
will be processed by another host using the Cardholder
Verification State.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide G-1

User-Configurable States
Web Exit State

Web Exit State G

The Web Exit State can be executed anywhere within the state flow
where an Exit state can be executed.
The Web Exit State supports up to eight additional URLs and their
corresponding next states. In addition, the web browsing session
invoked by the web Exit remains active, but hidden, on return to the
Advance NDC state flow. By default the web page is displayed, but
can be hidden to allow script‐only web pages to be used.
If you require further help with web Exit development, contact NCR
Financial Software Engineering.

The state table parameters listed below control the behaviour of the
State Table Parameters G

web Exit.
Table G‐1 “Web Exit State” describes the entries in the Web Exit
State. In Table G‐1, table entry 2 is the URL Index.This entry
specifies the index of the URL path in an XML file, which in turn
specifies the HTML page to be loaded.

Table G-1
Web Exit State

Table Number of
Contents Description
Entry Characters

1 1 State Type The state type letter selected to represent the web Exit
state. This will vary depending on the existing state type
implementation. The default is state type ʹ0ʹ.

2 3 URL Index Specifies the index into the WebExitURLTable.xml file

containing the URL for the web page to be loaded, which
may be the start of a web flow. This XML file and
corresponding schema can be found in the C:\Program
Files\NCR APTRA\Advance NDC\Config folder.

3 3 Browse Time The length of time in seconds that the browser is active
before Advance NDC actively takes back control
A value of “000” means that no timeout is used and the
HTML flow must determine a suitable time to return
control to Advance NDC.

4 3 Browse Complete Next The next state number to execute after the web page
State indicates that browsing is complete.

5 3 Browse Timeout Next State The next state number to execute after the time specified
by the Browse Time state parameter expires.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

G-2 APTRA Advance NDC, Developer’s Guide

 User-Configurable States
Web Exit State

Table Number of
Contents Description
Entry Characters

6 3 Browse Failed Next State The next state number to execute when an error occurs
For example, if the URL index cannot be located, or an
error is found on the initial page
See Table Note 1:

7 3 Display Web Page Specifies whether to display or hide the web page.
Valid values are as follows:
 000 ‐ Display the web page (default)
 001 ‐ Hide the web page
If this entry is invalid, the default Close state is executed

8 3 Reserved Must be 000

9 3 Extension State Specifies the extension state to handle up to eight more

events on the HTML page.

Table Note 1: The standard HTTP 404 error message is not

recognised as an error, and therefore does not use the Browse
Failed Next State parameter.

Advance NDC tracks the state of the web browser using defined
Tracking URLS G

URLs, described in Table G‐2. When a URL in the defined list is

detected, the next page is set based on the state table parameters.
This mechanism is used to pass control back to Advance NDC. The
HTML page designer must specify these URLs, starting with http://,
as the next HTML page when appropriate.

Table G-2
Web Exit Tracking URLs

URL Description

webbrowsecomplete/ The browse session has completed successfully

The next state number is set to the entry defined in table entry 4 of the web
Exit state table parameters

webbrowsetimeout/ The browse session has timed out according to the input rules specified by
the HTML pages
The next state number is set to the entry defined in table entry 5 of the web
Exit state table parameters
See Table Note 2.

webbrowsefailed/ An error condition has been detected during the display of web pages
The next state number is set to the entry defined in table entry 6 of the web
Exit state table parameters

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide G-3

User-Configurable States
Web Exit State

Table Note 2: The web browse timeout is detected by the HTML

page, whereas the Browse Timeout is detected by the state. The next
state is the same in both cases.

Table G‐3 “Extension to the Web Exit State” describes the entries in
Extension to the Web Exit the Web Exit State extension. Extension state entries 2 to 9 specify
State G
the state numbers to execute, depending on the URL navigated to
on the HTML page.

Table G-3
Extension to the Web Exit State

Table Number of
Contents Description
Entry Characters

1 1 State Type The state type entry selected to represent the extension
state. “Z” is implemented as extension state.

2 3 Browse Complete 1 Next The next state number to execute when the HTML page
State raises an event to navigate to the URL
webbrowsecomplete1/.
See Table Note 3:

3 3 Browse Complete 2 Next The next state number to execute when the HTML page
State raises an event to navigate to the URL
webbrowsecomplete2/.
See Table Note 3:

4 3 Browse Complete 3 Next The next state number to execute when the HTML page
State raises an event to navigate to the URL
webbrowsecomplete3/.
See Table Note 3:

5 3 Browse Complete 4 Next The next state number to execute when the HTML page
State raises an event to navigate to the URL
webbrowsecomplete4/.
See Table Note 3:

6 3 Browse Complete 5 Next The next state number to execute when the HTML page
State raises an event to navigate to the URL
webbrowsecomplete5/.
See Table Note 3:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

G-4 APTRA Advance NDC, Developer’s Guide

 User-Configurable States
Web Exit State

Table Number of
Contents Description
Entry Characters

7 3 Browse Complete 6 Next The next state number to execute when the HTML page
State raises an event to navigate to the URL
webbrowsecomplete6/.
See Table Note 3:

8 3 Browse Complete 7 Next The next state number to execute when the HTML page
State raises an event to navigate to the URL
webbrowsecomplete7/.
See Table Note 3:

9 3 Browse Complete 8 Next The next state number to execute when the HTML page
State raises an event to navigate to the URL
webbrowsecomplete8/.
See Table Note 3:

Table Note 3: If the Browse Completen Next State value is defined

as 000, the navigation to the URL for that next state will cause the
Browse Failed Next State to be taken.

If the XML file doesn’t contain the URLPath element with the index
number specified in state table entry 2, the flow goes to the “Browse
Failed Next State”. If there is a URLPath entry, it navigates to that
HTML page.
If the URL navigated to on the HTML page is webbrowsecomplete1/,
the next state is set to “BrowseComplete1 Next State”, that is the
second entry in the extension state. Similarly for the other URLs, for
example webbrowsecomplete2/ sets the next state to
“BrowseComplete2 Next State, and so on for all eight URLs.
If the web page does not navigate to ANY of the specified URLs
during the time specified by the Browse Time state parameter, the
flow goes to the Browse Time Out next state (State Table entry 5).
In order to maintain any session or frame data that may be present
within the navigation, the web browse session invoked by the Web
Exit will still be active (although hidden) on return to the NDC state
flow. This is achieved by maintaining the web browse session in a
separate process called the Web Exit Control.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide G-5

User-Configurable States
Web Exit Configuration

Web Exit Configuration G

To complete the configuration of your web Exits, read and perform

the following instructions.

To complete configuration of your web Exits, set up the

WebExitURLTable.XML WebExitURLTable.XML file. This XML file is used to get the URL
File G
path, based on the URL Index table entry specified in the Web Exit
state flow. This XML file and its corresponding schema can be
found in the C:\Program Files\NCR APTRA\Advance NDC\Config
folder. The format is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<UrlTable Name="WebExit" Version="1.0">
<BaseURL>
<URLPath Index="001">C:\Program Files\NCR APTRA\Advance
NDC\test1.htm</URLPath>
<URLPath Index="099">C:\Program Files\NCR APTRA\Advance
NDC\test99.htm</URLPath>
<URLPath Index="199">C:\Program Files\NCR APTRA\Advance
NDC\test0.htm</URLPath>
<URLPath Index="999">C:\Program Files\NCR APTRA\Advance
NDC\test999.htm</URLPath>

---------
---------
---------
---------
---------
</BaseURL>
</UrlTable>

The web Exit state checks the URL index in the state flow and looks
for the URL path in the XML file, by mapping the URL index to the
index of the URLPath element. If a match is found, that URL gets
displayed. The index values may have a range of 001 to 999.
For example, specifying a URL index of 1 causes the web Exit state
to search for URLPath Index=ʺ001ʺ in the XML file, get the
corresponding URL path, and navigate to that URL.

The system should be configured such that the web pages used
Adding Websites to the within the Web Exit state are added to the trusted websites list. To
Trusted Sites Zone G
do this, in Internet Explorer select Tools | Internet Options |
Security | Trusted sites zone | Sites..., and add the website to the
zone. This is required due to cross‐frame security.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

G-6 APTRA Advance NDC, Developer’s Guide

 User-Configurable States
Web Exit Configuration

To allow the use of the web Exit state, STCONT has been updated so
Updating STCONT G

that Advance NDC recognises the new state. The STCONT file
registers the state type letter and location of the implementation as
follows:
<FS>0NStateWebExitApplicationLink09990099900ZZZ00ZZZ00Z
ZZ000010000000ZZZ1<fs>

The variables are as follows:

StateWebExit is the name of the application specified when the
web Exit state was built from the Author project
ApplicationLink indicates that the implementation of the Exit is
an Author flow.
If you need to change the state type letter to fit your environment,
edit the first character following <FS>, that is, edit 0 in the example
above.

The state flow must be updated so that the Exit can be called at the
Updating the State Flow G

appropriate time.
The Exit is usually called from the appropriate point in the state
flow. When a specific FDK is pressed, the flow exits to the web. This
may require a screen update if a new selection is introduced. The
state update indicates that the next state to execute is a web Exit
state and enables a new FDK.
To work out which state types need to be edited, trace the normal
flow of the application. As highlighted in “Example Flow Trace”,
and defined in “State Table Updates”, the following updates need to
be made:
 The FDK Active Mask in state number 297 needs to be updated
to enable FDK F
 The FDK F Next State number needs to be updated to point to
the definition of the Web Exit State.
The Web Exit state definition also needs to be added.

Example Flow Trace G

Applica.. 13:24:26.203 [297] [X] FDK Info Entry

Applica.. 13:24:26.203 Screen
Number [128]
Applica.. 13:24:26.203 Timeout Next State No [473]
Applica.. 13:24:26.203 Cancel Next State No [445]
Applica.. 13:24:26.218 FDK Next State No [298]
Applica.. 13:24:26.218 Extension State No [301]
Applica.. 13:24:26.218 Buffer
Position [030]
Applica.. 13:24:26.218 FDK Active Mask [044]
->(60) Enable FDK F

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide G-7

User-Configurable States
Web Exit Configuration

Applica.. 13:24:26.250 Multi Language Screens [000]

Applica.. 13:24:26.250 Extension State - Pos [1]
Applica.. 13:24:26.250 1 2 3 4 5 6 7 8 9
Applica.. 13:24:26.250 Z050100250000040030020010
Applica.. 13:24:41.031
Applica.. 13:24:41.046 [298] [W] FDK Switch
Applica.. 13:24:41.046 FDK ‘A’ Next State No [000]
Applica.. 13:24:41.046 FDK ‘B’ Next State No [000]
Applica.. 13:24:41.046 FDK ‘C’ Next State No [205]
Applica.. 13:24:41.046 FDK ‘D’ Next State No [206]
Applica.. 13:24:41.046 FDK ‘F’ Next State No [000]
->(900) Execute Web
Exit
Applica.. 13:24:41.046 FDK ‘G’ Next State No [204]
Applica.. 13:24:41.046 FDK ‘H’ Next State No [000]
Applica.. 13:24:41.046 FDK ‘I’ Next State No [000]

State Table Updates G

The state table needs to be updated as shown in the following:

 Enable FDK F
297X128473445298301030060000

 Goto State 900 for FDK F

298W000000205206900204000000

 State 900 Web Exit State

9000900090297445069000000000

This updated state flow and any associated screens can be stored in
a local customisation file to update the customisation data without
impacting the host. For an example local customisation file, see
“LOCAL File” on page 5‐24.

In a Web Exit state, a timer sets the download time for loading a
Configuring Web Page web page. The timer is configured in seconds and starts when the
Download Timer G
web page is requested and the requested page should be loaded
before the timer expires. If the requested page is not loaded within
the specified time, the Browse Failed Next State (state table entry 6)
is taken. By default, the registry is set to 0.
The timer is configured using the following DWORD registry entry:
HKLM\SOFTWARE\NCR\AdvanceNDC\DisplayManager\
WebPageDownloadTimeout

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

G-8 APTRA Advance NDC, Developer’s Guide

 User-Configurable States
Web Exit Configuration

If the timer is set to 0 (default) then there is no time limit to load a

web page.
If the timer is set to any value other than 0, then the web page
should be loaded within the time limit.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide G-9

User-Configurable States
Cardholder Verification State

Cardholder Verification State G

This Authored state allows cardholder verification by Central for

transactions that will be processed by another host, such as a web
host for web transactions. This reduces the burden of authorisation
and identification on the web host. You configure it according to
your requirements.
The state sends a transaction request with an Operation Code value
specified in a Pre‐Set OpCode buffer state in the application flow.
The Transaction Request is populated using a predefined set of state
parameters from an existing Transaction Request state. The state
number for the existing Transaction Request state must be specified
in the state parameters.
The PIN Block and Track 2 details are verified during the
Transaction Request/Reply sequence. This requires the Cardholder
Verification state to have a valid PIN Entry state preceding it in the
state flow. The host validates the cardholderʹs identity based on the
cardholder data provided and specifies the next state according to
the success or failure of the verification.
Using this state type requires some analysis of the state flow so that
the appropriate actions are taken during the verification process.
The state type can be specified in STCONT and included in the state
flow as required.
To ensure consistent host behaviour, make the Operation Code
value the same as that expected by Central for a balance enquiry;
any other value may cause issues at Central. Set the Operation Code
value by invoking the Pre‐Set Operation Code Buffer state before
the Cardholder Verification state. For details of the Pre‐Set
Operation Code Buffer state, refer to the APTRA Advance NDC,
Reference Manual.
This mechanism is similar to the one used during a settlement
transaction. Like the settlement transaction, this state type does not
execute the Transaction Request state but instead uses Author
workers to achieve the same effect.
Central must also specify the function ID to be one of the following:
 Next State and Print
 Display and Print
 Print Immediate
These function IDs are triggered from Central according to the
transaction request and Operation Code. This is the reason for using
the same value in the Operation Code as a balance enquiry, since

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

G-10 APTRA Advance NDC, Developer’s Guide

 User-Configurable States
Cardholder Verification State

typically these function IDs are returned in response to a balance

transaction request.
The function executed sets the next state based on the state table
entries in Table G‐4 on page G‐11 and does not display or print
anything. If the function ID returned in the transaction reply is not
one of the specified function IDs, the transaction reply is rejected
with specific command reject B06—Illegal Transaction Reply
Function Identifier.
State table entry 4, Authentication Valid Host State, specifies the
Next State ID expected from the host for a valid authentication. If
the Next State ID in the transaction reply matches this value, the
verification has succeeded. In this case, the contents of table entry 5
are examined. This specifies the Authentication Valid Next State to
take on successful authentication and is used to override the Next
State specified by the host. This Table Entry is optional and if
specified as 255, the next state specified by the host is used as the
next state.
If the Next State ID specified by the host does not match the
Authentication Valid Host State in table entry 4, the verification is
regarded as unsuccessful. In this case, table entry 6 can be used to
override the Next State ID for the authentication failed next state. If
table entry 6 is 255, then the next state ID specified in the transaction
reply is used.
Remember that this state only validates the cardholder PIN, which
has the following implications:
 There is no guarantee that sufficient funds are available for a
transaction. For this reason, it is the responsibility of the host
processing the transaction to validate whether there are
sufficient funds for the transaction to complete successfully
 No balance information is displayed. For this reason, the
cardholder may not be aware of incurring banking charges and
reciprocity fees may be disputed by the issuing institution.

Table G-4
Cardholder Verification State

Table Number of
Contents Description
Entry Characters

1 1 State Type ‘O’

2 3 Transaction Request State Specifies the Transaction Request state number for
Number the transaction request parameters to use for
(Base 10 range 000–254, 256–999) verification.
(Base 36 range 000–254, 256–ZZZ)

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide G-11

User-Configurable States
Cardholder Verification State

Table Number of
Contents Description
Entry Characters

3 3 Screen Number Screen displayed while transaction request is sent

(001–999) and host verification is carried out.

4 3 Authentication Valid Host State State number compared against the next state
(Base 10 range 000–254, 256–999) specified in the transaction reply to verify whether
(Base 36 range 000–254, 256–ZZZ) the cardholder is an authenticated user. If
unspecified (set to 255), verification is processed as
unverified (the next state taken is host‐specified)

5 3 Authentication Valid Next State State number to which the application goes if the
(Base 10 range 000–254, 256–999) cardholder is an authenticated user. If unspecified
(Base 36 range 000–254, 256–ZZZ) (255), the good next state in the transaction reply
(state table entry 4) is taken.

6 3 Authentication Failed Next State State number to which the application goes if the
(Base 10 range 000–254, 256–999) cardholder is not an authenticated user. If
(Base 36 range 000–254, 256–ZZZ) unspecified (set to 255), the next state in the
transaction reply is taken.

7 3 000 Reserved

8 3 000 Reserved

9 3 000 Reserved

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

G-12 APTRA Advance NDC, Developer’s Guide

 Table of Contents
Advance NDC and Customer Relationship Management

Appendix H
Advance NDC and Customer
Relationship Management

Overview H‐1

Configuring APTRA Promote and APTRA Relate H‐2

Enable/Disable Promote H‐2
Configuring Consumer ID H‐3
Multiple Backgrounds Support in Relate H‐3
Promote Flowpoint Configuration for Continuous Display H‐4
Relate Coupon Printing H‐7
Reporting Errors in a Relate Transaction H‐9
Cancelling a Marketing Session H‐10
Displaying Promote Campaigns H‐10
Input Validation H‐10

Configuring CxM Content Deployer H‐12

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

Table of Contents
Advance NDC and Customer Relationship Management

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide

 Advance NDC and Customer Relationship Management
H

Overview

Overview H

Advance NDC supports two products: APTRA Promote for

customer‐targeted marketing and advertising campaigns and
APTRA Relate for building relationships with customers.
Advance NDC also supports .NET CxM Content Deployer
component to synchronise and load the marketing and advertising
campaigns available on the CxM server. This marketing
communication are imported to the SST from the CxM server and
presented to the consumer.
Support for APTRA Promote and APTRA Relate in Advance NDC
is provided through configuration files and registry settings.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide H-1

Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

Configuring APTRA Promote and

APTRA Relate H

The following sections provide few configurations and settings in

Advance NDC to support APTRA Promote and APTRA Relate.

Promote can be enabled or disabled either by updating the

Enable/Disable Promote H

ServiceEnabled property of TMSPromote Class in the

AdvanceNDCCustom.accfg file or through the ‘4 ENABLE/DISABLE
PROMOTE’ (15 PROMOTE/COPYFILE) Supervisor option on the
Access menu.
The following extract shows the default entry for the
ServiceEnabled property in the AdvanceNDCCustom.accfg file:

Figure H-1
Example Enable Promote Extract
<Class ID="TMSPromote"
Name="NCR.APTRA.TMSPromote.PromoteTMSrv"Assembly="NCR.APTRA.TMSPromote.dll">
<Interface>
<Property Name="ServiceEnabled" Value="true"/>
</Interface>
</Class>

The enabling and disabling of Promote through Supervisor option

takes precedence over the AdvanceNDCCustom.accfg file settings.
To avoid possible conflicts in configuration, the following steps are
recommended:

1 Delete the PersistedData folder located at: C:\Program Files\NCR

APTRA\Advance NDC\PersistedData.

2 Modify the TMSPromote Class in the AdvanceNDCCustom.accfg

file.

3 Restart the SST to verify if Promote is functioning according to

the .accfg file settings.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

H-2 APTRA Advance NDC, Developer’s Guide

 Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

In the Targeted Marketing Service, a consumer is identified with a

Configuring Consumer ID H

unique Consumer ID. The Consumer ID is either picked from the

PAN field or card track 2 data based on the following DWORD
registry entry:
HKLM\Software\NCR\AdvanceNDC\Promote\
ConsumerIDDefinedByTrack2Data

Valid values are as follows:

 0 = Consumer ID is obtained from PAN field (CDI store 2077)
(default).
 1 = Consumer ID is obtained from T2 Data field (CDI store 2043)
(card track 2 data). The data between the start sentinel ( ; ) and
the first field separator ( = ) from the NDC T2Data field (CDI
store 2043) becomes the Consumer ID.

Note: If an invalid value is used or the key does not exist, the
default value is used.
Based on the registry entry, the consumer ID is obtained as shown
in the following example.
 When the registry is set to 0, and the PAN field has the value of
1234567890123456, the consumer ID will be
1234567890123456.
 When the registry is set to 1, and the T2 data field has the value
of ;4556667890123456=1234?, the consumer ID will be
4556667890123456.

The marketing and advertising campaigns targeted to customers

Multiple Backgrounds can be enhanced with several and different background images
Support in Relate H
grouped as one package. In a single transaction, the images are
dynamically selected and are used for different screens in various
backgrounds.
The targeted marketing message has a graphic element that includes
an array of graphics that hold the information about the background
image and other images, which are dynamically updated on the
marketing screen. In the targeted presentation file, the Name and
Path properties of the graphic element define the identity of the
graphic image and name of the graphic image respectively. The
graphic element names are updated in the .acsdf presentation file
with the targeted marketing message graphics when the Name
property matches.

Note: If the .acsdf file has a background image given by the

background attribute and a ScreenBackground graphic element,
the graphic element image will override the background image.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide H-3

Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

The screenBackground graphic element in the array of graphics in

the .acsdf presentation file must contain attributes that will make the
graphic display in a full screen. The screen properties width and
height of the campaign has to be set to the screen resolution that is
specified.
The .acsdf file is designed to ensure that there is a graphic element
with the screenBackground name and it is the first graphic
element in the .acsdf file.
Example for screen background and other images in a Targeted
Marketing Message.
<Message at="Flowpoint name" for="card number" id="2a">
……..
<Graphics>
<Graphic Name = "ScreenBackground" Path="hdfcclassic_TC.jpg"
/>
<Graphic Name = "McDBurger" Path="ISA.PNG" />
<Graphic Name = "McDCoke" Path="MealDeal.jpg" />
</Graphics>
</Message>

Example for .acsdf file that has screen background and other graphic
elements
<?xml version="1.0" encoding="utf-8"?>
<Screen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
DesignResolutionWidth="1024" DesignResolutionHeight="768">
<Language Code="eng">
<Graphics>
<Graphic Name="Screenbackground" Path="hdfc.jpg" X="0"
Y="0" Width="1024" Height="768" />
<Graphic Name="McDBurger" Path="VisaGold.jpg" X="50"
Y="346" Width="239" Height="106" />
</Graphics>
</Language>
</Screen>

In the above example, the screen background is updated from

hdfc.jpg to hdfcclassic_TC.jpg as the message received for
screen background graphic element is hdfcclassic_TC.jpg and
McDBurger graphic element is changed from VisaGold.jpg to
ISA.png.

Promote campaigns will continue to be displayed at a flowpoint (for

Promote Flowpoint example, Approving Transaction, Dispense During Fulfilment and
Configuration for Dispense Complete flowpoints) even after the maximum duration
Continuous Display H for the campaign is elapsed.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

H-4 APTRA Advance NDC, Developer’s Guide

 Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

Advance NDC will not display the corresponding NDC or Display

Manager screens for the configured flowpoints even after the
campaign’s maximum play duration has elapsed.
This can be configured by setting the
ContinueCRMFlowpointsDisplay property in
AdvanceNDCCustom.accfg file to True.
<!-- NDCCRM Configurations-->
<Class ID="NDCCRMService"
Name="NCR.APTRA.NDC.NDCCRM.NDCCRMService"
Assembly="NCR.APTRA.NDC.NDCCRMService.dll">
<Interface>
<Property Name="ContinueCRMFlowpointsDisplay" Value="True" />
</Interface>
</Class>

By default, the value is False, which means that the Promote screen
will be displayed till the time specified in the maximum duration of
the campaign, thereafter the corresponding NDC or HTML Display
Manager screen will be displayed.
The ContinueCRMFlowpointsDisplay property must be
configured to True to get the Continuous Display behavior.
Furthermore, the SupportedFlowpointsArray must be updated
in the AdvanceNDCCustom.accfg file with the Promote flowpoints
where the above behavior of continuous display is required. Below
is a sample configuration to get the above behaviour.
<!-- NDCCRM Configurations-->
<Class ID="NDCCRMService"
Name="NCR.APTRA.NDC.NDCCRM.NDCCRMService"
Assembly="NCR.APTRA.NDC.NDCCRMService.dll">
<Interface>
<Property Name="ContinueCRMFlowpointsDisplay" Value="True" />
</Interface>
</Class>
<Array ID=” SupportedFlowpointsArray”>
<Element Value=”Approving Transaction”/>
<Element Value=”Dispense.During Fulfillment”/>
<Element Value=”Dispense.Complete”/>
</Array>

If the flowpoints are not configured in the array list, then once the
MaxDuration timer elapses for the campaign, the AdvanceNDC
application displays the corresponding NDC/HTML Display
Manager screens.
The Application behaviour when the
ContinueCRMFlowpointsDisplay property in
AdvanceNDCCustom.accfg is set to “True” with the above
SupportedFlowpointsArray is as described below ‐

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide H-5

Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

1 If SupportedFlowpointsArray has “Approving

Transaction” flowpoint as one of its elements, then
AdvanceNDC will send the transaction request after the
Approving Transaction flowpoint maximum display time is
completed and continue displaying the Approving transaction
flowpoint campaign. The campaign display will be interrupted
only when
 the next CRM flowpoint is being displayed during
transaction reply processing.
 the transaction request state timeout occurs.
 the transaction reply is interactive.
 the application take the next state exit.

Application will not display any AdvanceNDC or HTML

Display Manager Screen after the Approving transaction
flowpoint campaign’s maximum display timer completes.

2 If SupportedFlowpointsArray has “Dispense During

Fulfillment” flowpoint as one of its elements, then
AdvanceNDC will continue to display Dispense During
Fulfillment flowpoint campaign even after the campaign’s
maximum display timer completes. The Dispense During
Fulfillment campaign will interrupt only when
 the next CRM flowpoint is being displayed during
transaction reply processing.
 the transaction request state timeout occurs.
 the application take the next state exit.

Application will not display any NDC/html Display Manager

screen after the Dispense During Fulfillment flowpoint
campaign’s maximum display timer completes.

3 If SupportedFlowpointsArray has “Dispense Complete”

flowpoint as one of its elements, then AdvanceNDC will
continue to display Dispense Complete flowpoint campaign
even after the campaign’s maximum display timer completes.
The Dispense Complete campaign will interrupt only when
 the next CRM flowpoint is being displayed during
transaction reply processing.
 the transaction request state timeout occurs.
 the application take the next state exit.

Application will not display any NDC/html Display Manager

Screen after the Dispense Complete flowpoint campaign’s
maximum display timer completes.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

H-6 APTRA Advance NDC, Developer’s Guide

 Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

Note:

 Any CRM flowpoint can be configured to be displayed even

after its maximum timer completes in a state. However,
when using a combination of Promote and Display
Manager, this behavior is supported for Transaction Request
(and reply processing) state flowpoints only.
 If for any flowpoint, the campaign presentation includes a
Coupon selection, then the above behavior of continuous
display is not applicable, as the product is limited either to
display a Presentation with screen/screens or a Presentation
with coupon, but not both. In such cases, the campaign
presentation continues until the coupon is printed and post
printing the NDC/Html Display Manager screen for the
corresponding flowpoint is displayed.

During a Relate transaction, Advance NDC provides the facility to

Relate Coupon Printing H

print coupons. When APTRA Relate is enabled, if the message

retrieved from the CP server has printable data, then Advance NDC
initiates a print either as an attachment to transaction receipt or
towards the end of the Relate campaign display. The CP server
message uses the form name to print the printable data. The
printable content can have dynamic graphics and text.
Example of CP server message extract:
<PrintContent>
<PrinterId>RECEIPT</PrinterId>
<Document>
<DocumentRecordItem>
<Content Name="ECouponCode" Value="ZOO1234" />
<Content Name="Offer" Value="Great offer from McDonalds for
you and your family. Please collect your coupon receipt
from McDonalds." />
<Content Name="Graphic" Value="Burgerking.gif" />
</DocumentRecordItem>
<CutStyle>Standalone</CutStyle>
<DocumentId>Burgerking</DocumentId>
<FormName>RelateCoupon</FormName>
<DocumentUrl>Burgerking.gif</DocumentUrl>
</Document>
</PrintContent>

In the example listed above, the form name RelateCoupon is used

to dynamically print the content received in the printable content
from the CP Server message. The content names ECouponCode,
Offer and Graphic are matched with the XFSFIELD names
ECouponCode, Offer and Graphic in the RelateCoupon form. The
content names are case‐sensitive.
Example of a Relate Coupon form:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide H-7

Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

XFSFORM "RelateCoupon"
BEGIN
UNITROWCOLUMN, 1, 1
SIZE40,24
ALIGNMENTTOPLEFT, 1, 1
ORIENTATIONPORTRAIT
VERSION1, 0, "3", "NCR PROFESSIONAL SERVICES"
LANGUAGE25
COPYRIGHT"COPYRIGHT (C) NCR CORPORATION"
TITLE "Title"
COMMENT "Comment"
XFSFIELD "ECouponCode"
BEGINPOSITION 1, 1
SIZE 26,1
OVERFLOW TRUNCATE
STYLE NORMAL
HORIZONTAL LEFT
VERTICAL TOP
FONT "INTERNATIONAL4"
CPI 14.00
INITIALVALUE ""
END
XFSFIELD "Offer"
BEGIN
POSITION 1, 3
SIZE 26,5
OVERFLOW TRUNCATE
STYLE NORMAL
HORIZONTAL LEFT
VERTICAL TOP
FONT "INTERNATIONAL4"
CPI 14.00
INITIALVALUE ""
END
XFSFIELD "Graphic"
BEGIN
POSITION 1, 11
SIZE 30,11
TYPE GRAPHIC
CLASS OPTIONAL
OVERFLOW TRUNCATE
STYLE NORMAL
HORIZONTAL CENTER
SCALING MAINTAINASPECT
END
END

Printing Relate Coupons Relate coupons can be printed as 8

standalone or attached to the transaction receipt if the following are

true as described in Table H‐1

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

H-8 APTRA Advance NDC, Developer’s Guide

 Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

Table H-1
Relate Coupon Printing

2ST printer? 2ST paper? Delivery Type Used: Receipt Requested/Required? Host Data on Back? Coupon Printed on:

Yes No Attached Yes ‐ Front

Attached to
receipt

No ‐ Attached Yes ‐ Front

Attached to
receipt

Yes No Standalone Yes ‐ Front

Separate from
receipt

No ‐ Standalone No ‐ Front
Separate from
receipt

Yes Yes Attached Yes Yes Front

Attached to
receipt

The MessageCompleted method in the TargetedMarketing service

Reporting Errors in a component is called either when the display of a message is
Relate Transaction H
complete or when an error occurs while displaying the marketing
screen.
The MessageCompleted method contains the ErrorReason and
FailureDescription parameters, which are used to report an
error in case of an early termination of a marketing campaign.
The ErrorReason parameter will help to identify the cause for the
early termination of an interaction. The FailureDescription
parameter provides the detailed description of the error.
To report errors in a Relate transaction, the
IgnoreMissingMarketingFields property in the
AdvanceNDCCustom.accfg file must be set to False as follows:
<Class ID="NDCCRMService"
Name="NCR.APTRA.NDC.NDCCRM.NDCCRMService"
Assembly="NCR.APTRA.NDC.NDCCRMService.dll">
<Interface>
<Property Name="IgnoreMissingMarketingFields" Value="false"/>
</Interface>
</Class>

By default, the value of IgnoreMissingMarketingFields is True,

which does not allow reporting errors in a Relate transaction.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide H-9

Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

For example, if the message retrieved from the server refers to a

presentation file and the file is missing in the package present on the
SST, the application reports the Error Reason as
InvalidDisplayContent and FailureDescription as
Presentation file is missing in the package to the
TargetedMarketing service by the MessageCompleted method and
then the TargetedMarketing service reports that error information
to the TargetedMarketing server.
Advance NDC does not report any error in the following scenarios:
 When the IgnoreMissingMarketingFields property is set to
True (default)
 when the form name referred in the print content is not present
in SST
 when the form is present in the SST but it does not have XFS
fields for the print content received from the TM server.

In a targeted marketing session when user input is required,

Cancelling a Marketing Advance NDC will activate the Cancel key. The Cancel key is used to
Session H
cancel a marketing session and to continue with the consumer
transaction flow.

In a voice‐guided session with APTRA Promote enabled, the

Displaying Promote DisableCRMDuringVGSession property in the
Campaigns H
AdvanceNDCCustom.accfg file allows to enable or disable the display
of Promote campaigns.
Set the property to true to disable the display of CRM campaigns in
a voice guided session. By default, the value is true as follows:
<Class ID="NDCCRMService"
Name="NCR.APTRA.NDC.NDCCRM,NDCCRMService"
Assembly="NCR.APTRA.NDC.NDCCRMService.dll">
<Interface>
...
<Property Name="DisableCRMDuringVGSession" Value=“true”/>
</Interface>
</Class>

Set the DisableCRMDuringVGSession property to false to

display the Promote campaigns.
For information on restrictions of using Promote with voice
guidance, see “Using Voice Guidance with Promote” on page 6‐14.

In the Targeted Marketing Service, the data entered by the user is

Input Validation H

validated before it is sent to the CP server. The settings to configure

the minimum and maximum value is provided under the following
registry key:

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

H-10 APTRA Advance NDC, Developer’s Guide

 Advance NDC and Customer Relationship Management
Configuring APTRA Promote and APTRA Relate

HKLM\Software\NCR\AdvanceNDC\Promote\
InputValidationByAANDC

The valid values are:

 0 = (default) ‐ The value limit is not defined. On FDK key press,
the data is processed.
 1 = The value limit is defined to check the maximum and
minimum value entered by the user.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide H-11

Advance NDC and Customer Relationship Management
Configuring CxM Content Deployer

Configuring CxM Content Deployer H

The CxM Content Deployer can be configured by updating the

ContentDeployerConfig.xml file. For details about the .NET CxM
Content Deployer component and the configuration file, refer to
APTRA Documentation | .NET Consumer Experience Marketing
(CxM) Content Deployer.
Any changes made to the CxM Content Deployer configurations
takes effect only when the NCR.APTRA.CxMContentDeployerSrv.exe
is re‐started.
The CxM Content Deployer component does not affect the
customers who are using the customer power server until the CxM
server details are configured in the XML file. If it is configured, all
the Promote campaigns which were imported through the
Supervisor Import option are deleted.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

H-12 APTRA Advance NDC, Developer’s Guide

 Glossary

Glossary 0

24-volt Reset Turns power on the USB bus off and then on again.
Numerical
AAC Advanced Audio Coding.
A
ABT Aggregate Builder Tool.
Active Script Host APTRA Advance worker that allows the use of
additional processing to be carried out by execution of Microsoft
Visual Basic Script (VBScript).
ActiveX ActiveX is the product of two Microsoft technologies called
OLE and COM.
ActiveX Control A type of COM component which implements
standard interfaces, and can be included in a web page and used in
languages such as VBScript.
ADE Application Development Environment
ADI2 Application Device Interface 2. A proprietary interface from
NCR.
Advance ADE An application development environment from NCR.
Advance ADE is no longer available as a separate product, but the
APTRA Author is used in Advance NDC development.
API Application Programming Interface
Application In the Author, an application is a collection of Workers
that can be built to create an executable.
See also Self‐Service Application.
Application Core The Application Core performs the SST mode
handling and message processing.
APTRA Author A tool that allows you to visually design and develop
a self‐service application.
APTRA Component Directory Any folder containing the _comp.ini file.
APTRA Simulator A tool from NCR enabling the simulation of
self‐service devices on a development PC for the testing of
applications under development.
See also Simulated Services.
ARGB Alpha Red Green Blue
ASCII American Standard Code for Information Interchange. A
computer code for representing alphanumeric characters.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Glossary-1

Glossary

Assembly All of the files that comprise a .NET application,

including the resource, security management, versioning, sharing,
deployment information, and the code. An assembly may appear as
a single DLL or EXE file, or as multiple files, and is roughly the
equivalent of a COM module.
Authenticated note Identified according to ECB 6 rules as a valid
note. This is also referred to as a good or genuine note.
See ECB 6.
Authoring Component The smallest manageable unit in the Author.
Examples of authoring components are Workers, Applications and
Catalogs.
Automation Object An APTRA Advance worker which encapsulates
an Automation Object, and thus enables access to these Automation
Objects from within your application. Automation Objects are not
displayable, but are typically data manipulation objects; for a
displayable ActiveX Control, use the Active Control worker class.
Automatic INIT The process of running an electronic journal (EJ)
initialisation command (INIT) automatically.
Automatic INIT EJ file The EJ file produced when running an
automatic INIT.
AVI Audio Video Interleave. An audio/video standard designed by
Microsoft for Windows.

BAPE Basic Alpha PINpad and Encryptor. A combined PIN pad

B and encryptor from NCR. Supports single‐length DES encryption
with various local and remote PIN verification schemes.
Base Screen A base screen is displayed without taking into account
any screens included in it (nested screens).
See also Nested Screen
BC Bill Cassette.
BNA Bunch Note Acceptor. An NCR device variant reported using
the BNA set of mStatus values. Allows a consumer to deposit a
number of bank notes in a bunch. This is also used as a generic term
for cash acceptors, for example on many Supervisor menu options.
See Cash acceptor.
BOP Basic Operator Panel (not supported by Advance NDC).
BRM Bunch Recycling Module. An NCR device allows a consumer
to deposit a number of bank notes in a bunch. The device can also
dispense notes and recycle deposited notes as configured. The
device is reported using the BRM set of mStatus values.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Glossary-2 APTRA Advance NDC, Developer’s Guide

 Glossary

CAM Card Authentication Method. The method or process for

C authenticating an ICC. See ICC.

Cardholder The SST customer.

Card Validation Value or Code Data element on a cardʹs magnetic
stripe that uses secure cryptographic process to protect data
integrity on the stripe, and reveals any alteration or counterfeiting.
Referred to as CAV, CVC, CVV, or CSC depending on payment
card brand.
A second level of card validation value or code is the three‐digit
code printed on the back of the payment card (four‐digit code on the
front for American Express). This code is uniquely associated with
each individual card and ties the card account number to the card. It
provides an additional level of authentication for card‐not‐present
transactions.
CAR/LAR Courtesy amount recognition/legal amount recognition.
Cash acceptor A generic term for any SST device that accepts
banknote deposits.
See also BNA, Cash recycler, GBNA, GBRU, Genuine note,
Recycling unit and SNA
Cash recycler A generic term for any SST device that accepts and
dispenses the same bank notes.
See also Cash recycling, Recycling unit.
Cash recycling The process of re‐using deposited cash for dispense
operations on a single SST.
Cash unit A cassette. Can also be described as a deposit bin or a
vault.
Catalog A component in the APTRA Author for organising other
Authoring components into manageable groups.
Category 1 note Either not a note or not recognised as a note,
according to ECB 6 definitions.
Category 2 note See Counterfeit note.
Category 3 note See Suspect note.
Category 4 note See Authenticated note.
CAV, CAV2 Card Authentication Value (JCB payment cards).
See Card Validation Value or Code

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Glossary-3

Glossary

CCM Communications Connection Manager. An APTRA

component providing a layer of software to separate an application
from the underlying communications protocol.
CDI Common Data Interface.
CDI Store A data element that is shared by the Customisation Layer,
Application Core and Supervisor. CDI stores are created and
initialised by the APTRA Advance NDC runtime.
CDM Cash Dispenser Module. CEN‐XFS class name for the Cash
Dispenser service.
CDM In NDC+, Coin Dispenser Module. In Advance NDC this has
been replaced by the term coin dispenser.
CEN Comité Européen de Normalisation (European Committee for
Standardization). Responsible for the XFS interface specification.
Central An application that resides on a host computer or switch
and interacts with Advance NDC on the SST to manage self‐service
transactions and maintain the SST in operation.
Chained Transaction A series of transactions carried out in a single
cardholder session.
CI Cash‐in Cassette.
CID Card Identification Number. The three‐ or four‐digit number
on a payment card (American Express and Discover).
See Card Validation Value or Code.
Codec Software that encodes and decodes (or compresses and
decompresses) various types of data such as sound and video files.
Coin Hopper A physical container holding coins in a coin dispenser.
Coin Hopper Type An Advance NDC coin hopper type is a mapping
to one logical XFS CDM cash unit. A coin hopper type is a logical
representation of one or more coin hoppers containing the same
type of coin.
COM Component Object Model from Microsoft. An open
architecture for cross‐platform development of client/server
applications based on object‐oriented technology. Clients have
access to an object through interfaces implemented on the object
(access to Methods, Properties and Events).
Combined Installer Contains all Advance NDC installation types
Component See Authoring Component and Runtime Components.
Compound device A device that has dual functionality. For example,
a device that is both a cash acceptor and a cash dispenser is a
compound device.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Glossary-4 APTRA Advance NDC, Developer’s Guide

 Glossary

Contact Card Reader A card reader that reads data from a card when
the card is inserted into or passed through a slot in the card reader
such as a Magnetic Card Reader/Writer (MCRW), Integrated
Magnetic Card Reader/Writer (IMCRW) or Dip And Smart
Hardware (DASH).
Contactless Card Reader A card reader that reads data from a card
when the card is held near to the card reader.
Control File A file which tells Advance NDC which Supervisor
functions or States are NDC standard, which are user written and
where the user‐written routines are to be found. A control file also
gives information about the chaining of Virtual Controllers and
Hooks.
Coordinator A Worker that coordinates the work of subworkers
contained in its Work Groups.
Counterfeit note A note with authentication features missing or out
of tolerance, which the cash deposit device classifies as a potential
forgery. This is the same as a category 2 note, as defined in the ECB
6 regulation.
Courtesy Amount The numerical representation on a cheque of the
amount to be paid.
CPM/DPM Cheque Processing Module can also refer to other
document processing modules.
CRM Customer Relationship Management. The methodologies and
technologies used by an enterprise to organise, automate and
synchronise business processes for attracting new and retaining
existing customers.
CTF Communications Template File.
CTS Cheque Truncation System.
Customisation Layer The part of Advance NDC that performs the ‘In
Service’ activities associated with the cardholder. For details of the
Customisation Layer worker classes, refer to the on‐line help in the
APTRA Author.
CVC, CVC2 Card Validation Code and Card Validation Code 2
(MasterCard payment cards).
See Card Validation Value or Code.
CVV, CVV2 Card Verification Value and Card Verification Value 2
(Visa payment cards).
See Card Validation Value or Code.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Glossary-5

Glossary

DAPI1 The Basic Security firmware for an EPP.

D
DAPI7 The International Security firmware for an EPP.
DASH Dip And Smart Hardware. The NCR hardware used to read
and write dipped/smart cards.
DebugLog A troubleshooting utility, supported from Advance NDC
3.02 onwards, that enables viewing of trace stream data in the test
environment.
DEP CEN‐XFS class name for the Depository Units service.
Deposit See Encash.
DES Data Encryption Standard. An industry-wide private key
encryption mechanism. The DES algorithm uses a 56-bit private key
(plus 8 bits for key integrity checking) and operates on 64-bit blocks
of data.
See also RSA, Triple DES
DIG Device Identifier Graphic.
Direct Deposit A deposit transaction where the notes are deposited
to the cassettes without being stored in the escrow.
Director In Advance NDC, a worker class that controls the flow of
the application through subordinate work groups of workers.
DIVX Digital Video eXpress.
DLL Dynamic‐Link Library. A library that can be linked at
execution time.
DMC Device Management Console. Part of the XFS Simulator.
DPM Document Processing Module. An NCR device.
DSM Device Status Monitor. Part of the NCR Self‐Service Platform.
DSS Data Security Standard. See PA‐DSS and PCI DSS.
Dual Interface A debit or credit card with an embedded chip that
allows the card to be used both in contact and contactless
transactions.

ECB 6 The collective name for Article 6 of the Council Regulation

E (EC) No 1338/2001 of 28 June 2001, which lays down measures for
protecting the euro against counterfeiting. The Governing Council is
part of the European Central Bank (ECB).
EJ Electronic Journal. In Advance NDC, the electronic journal
emulates the printed journal device. All the data normally recorded

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Glossary-6 APTRA Advance NDC, Developer’s Guide

 Glossary

on the journal printer is written to the EJ log on the system disk of

the SST.
EKC Encrypting Keyboard Controller. A more complex and secure
version of the BAPE, providing high‐level security. Not supported
in Advance NDC.
EMV Europay, Mastercard and VISA. Specifications for payment
systems to ensure interoperability between smart credit/debit cards
and interoperability between the terminals that support them,
jointly created and published by Europay International, MasterCard
and Visa International in 1996.
Encash The movement of notes from the escrow to the cash‐in
cassette. See also Vault.
EOP Enhanced Operator Panel, supported by Advance NDC.
EPP Encrypting PIN Pad A combined PIN pad and encryptor,
supporting triple DES and RSA encryption.
Escrow The stacking area used to hold notes before they are vaulted
or returned to the cardholder. See also Vault.
EUR The ISO currency ID for the euro.
Excess Notes In cash acceptors, notes that cannot be accepted to the
correct cassette, for example, because the cassette for that
denomination is full. Such notes are redirected to the reject bin after
a deposit transaction.
Exits A general programming term used in Advance NDC to cover
user‐defined states, supervisor features, virtual controllers and
special synchronisation routines called hooks. A C Exit is a DLL
accessed through a specific Exit interface.
Exit State A state defined and programmed by the user to customise
Advance NDC.
Exit Supervisor A supervisor function defined and programmed by
the user.
Express Recovery See 24‐volt Reset.

Fault Display This gives information to allow you to anticipate and

F prevent media shortages and device failures.
FDK Function Display Key. These keys are located on each side of
the facia screen and enable various options to be chosen. Some
screens have touch screen areas which emulate FDK functions.
Final Application In Advance NDC, an application created for
delivery to the runtime system.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Glossary-7

Glossary

FIT Financial Institution Table. In Advance NDC, a FIT contains

details of where and how information is stored on the magnetic
strip of the card and how a transaction should be processed.

GBNA Global Bunch Note Acceptor. An NCR device variant that

G allows a consumer to deposit a number of bank notes in a bunch.
See also Cash acceptor, GBRU. GBXX
GBP The ISO currency ID for pounds sterling.
GBRU Global Bill Recycling Unit. An NCR device that is reported
using the GBNA set of mStatus values. A GBRU allows a
consumer to deposit a number of bank notes in a bunch. The device
can also dispense notes and recycle deposited notes.
See also Cash recycler, Genuine note, Recycling unit.
GBXX An NCR term for a cash acceptor or a recycling unit where
the specific device is not significant. Used when the information
applies to both the GBNA and GBRU and/or equivalent devices.
See also GBNA, GBRU
Genuine note Another term for Authenticated note.
GIF Graphics Interchange format.
Global directory The user‐specified directory in which Advance
NDC has been installed. The default is c:\ntglobal.
Glyph A displayed or printed image. In typography, a glyph may be
a single letter, an accent mark, or two or more typeface characters
designed as a single unit (for example, œ)
Good note Another term for Authenticated note.
GOP Graphical Operator Panel. A panel fitted to terminals which
displays messages to the operator.
GUI Graphical User Interface.

HBV Revision H Bill Validator. An NCR note validator.

H
Heartbeat Regular signals allowing communications connections to
be monitored.
Hive On Microsoft Windows systems, a logical group of keys,
subkeys and values in the registry. A hive has a set of supporting
files containing backups of its data.
Hooks General term for miscellaneous Exits detailed in the
MISCONT file.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Glossary-8 APTRA Advance NDC, Developer’s Guide

 Glossary

HKLM HKEY_LOCAL_MACHINE. Fixed location in the registry for

local configuration values belonging to the computer for any user.
HSM Host Security Module.
HTML HyperText Markup Language.

ICC Integrated Circuit Card. A card containing an integrated

I circuit, also known as a ‘smart card’.
ID Identifier.
IDC Identification Card unit. CEN‐XFS class name for the
Identification Card Units service.
IFD Intelligent Fraud Device

JCB Japan Credit Bureau. A credit card company based in Tokyo.

J
JIT Just‐in‐time.
JPEG Joint Photographic Experts Group.
JPTR CEN‐XFS class name for the Journal Printer service.

KVV Key Verification Value.

K
Legal Amount The text representation on a cheque of the amount to
L be paid.
LPI Lines per inch.

MAC Message Authentication Code.

M
MAST See MCRW.
MCRW Magnetic Card Reader/Writer. It reads data from a standard
magnetic stripe card and, depending on the MCRW variant, writes
data to one or more of the tracks on the card’s magnetic stripe.
M-Data Maintenance Data.
MDM Media Dispenser Module.
MEI/MEEI Media Entry/Exit Indicator.
Message reflection The redirection of a message by a virtual
controller, that is, an incoming message to the SST from the host is
changed to an outgoing message from the SST or an outgoing
message is changed to an incoming message. This provides local
control of message processing.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Glossary-9

Glossary

MIDI Musical Instrument Digital Interface. Hardware specification

and software protocol for communication between electronic
musical instruments and computers.
MISCONT A control file detailing miscellaneous Exits: Hooks.
Module A Module is a collection of components created by a single
User. It supports the control and management of multi‐developer
projects.
MPEG Moving Pictures Experts Group. A set of standards for audio
and video compression, or a video/audio file in the MPEG format
(usually with the file extension .mpg).
MP3 ISO‐MPEG Audio Layer‐3.
MSD Magnetic Stripe Data.
MSSA Mini Self‐Service Assistant. Also known as MAST within
Advance NDC.
M-Status Maintenance Status.
Multi-Vendor application An Advance NDC application capable of
running on SSTs that comply with the CEN‐XFS specifications.

NBS National Bureau for Standards.

N
NDC NCR Direct Connect. An NCR application that works in
conjunction with a host‐ or switch‐based Central application to
perform self‐service transactions.
NDCACSDF NDC Activate screen definition format.
Nested Screen A screen included in another screen.
See also Base Screen
Note category A category of note as defined by the ECB 6 regulation.
See also Counterfeit note and Suspect note
Note definition Specifies the notes accepted by the SST.
Note ID The vendor‐specific identifier of the note currency and
value.
Note revision A version of a particular denomination. This could be,
for example, the same denomination issued by different banks.
Note signature Details of a note that are stored for ECB 6 logging
purposes.
Note type The combination of currency and value that identifies a
particular note.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Glossary-10 APTRA Advance NDC, Developer’s Guide

 Glossary

NVRAM Non‐Volatile Random Access Memory.

OEM Original Equipment Manufacturer.

O
OOS Out of Service.
OOXFS Object oriented eXtended Financial Services. The name of a
DebugLog trace stream.
O/S Operating system, such as Microsoft Windows 7 or Microsoft
Windows 10.

PA-DSS Payment Application Data Security Standard.

P
PAN Primary Account Number. The payment card number (credit
or debit) that identifies the issuer and the particular cardholder
account. Also called Account Number.
PCCM PC Communications Module. An NCR communications card
allowing communications with a host.
PCI Payment Card Industry.
PCI DSS Payment Card Industry Data Security Standard.
PCX Picture Exchange.
PDF Portable Document Format. The Adobe native file format for
documents viewable in Adobe Reader.
Persistence The capability of data to exist after the process or thread
that created it has ceased to exist. For example, persistent data is
preserved across SST shutdowns or power failures.
PIN Personal Identification Number. A secret identification number
that is issued to each cardholder. Also the CEN‐XFS class name for
the Personal Identification Number Keypads service.
PIN pads CEN‐XFS short form for the Personal Identification
Number Keypads service class.
PNG Portable Network Graphics.
PPD Programmable Printing Depository. A type of printer
supported by Advance NDC. Also called Envelope Depository.
Project In the APTRA Author, a project is a collection of
components.
PSL Persistent Services List.
PTR CEN‐XFS class name for the Printers service.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Glossary-11

Glossary

Recycler Another term for Recycling unit

R
RC Recycling Cassette.
Recycling unit A generic term for a device that allows a consumer to
deposit a number of bank notes in a bunch. The device can also
dispense notes and recycle deposited notes.
See also GBRU and Genuine note
Reflection See Message reflection.
RESRVD.DEF ASCII text file containing definitions for reserved
screens and keyboards, provided as part of APTRA Advance NDC.
For details, refer to the APTRA Advance NDC, Reference Manual.
RGB Red Green Blue.
RPTR CEN‐XFS class name for the Receipt Printers service.
RSA An asymmetric encryption scheme using private and public
keys, named after the developers (Rivest, Shamir and Adleman) and
based on the algorithm originally developed by Diffie‐Hellman.
See also DES
Rule File See Control File.
Runtime Components These provide the Authoring components used
to construct a self‐service application and the SST runtime software.
Runtime Only An alternative installer with smaller file size.

S2 Dispenser, S2 MDM S2 Media Dispenser Module. An NCR device

S that allows a cardholder to dispense bunches of notes.
SCPM Scalable Cheque Processing Module. A device that allows a
cardholder to deposit a number of cheques simultaneously without
using an envelope. Also known as a bunch cheque acceptor.
Screen Base The screen number of the first screen in each screen
group for each language.
Screen Group The range of screens that are specific to a single
language.
S-Data Severity Data.
SDA Single Note Divert. A reject bin that collects all the pick failure
notes.
SDE Simulated Device Editor. Part of the XFS Simulator.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Glossary-12 APTRA Advance NDC, Developer’s Guide

 Glossary

SDM Scalable Deposit Module. An NCR device that is reported

using the same set of mStatus vales as a BNA. Allows a consumer
to deposit cash or cheques.
SSC Security Standards Council of the PCI. An open global forum
for the ongoing development, enhancement, storage, dissemination
and implementation of security standards for account data
protection. (Web site https://www.pcisecuritystandards.org)
Self-Service Application The application that runs on an SST and
processes all the necessary transactions.
Self-Service Support A 32‐bit open software platform supplied by
NCR for use on NCR SSTs.
Service Provider A software layer responsible for hardware
abstraction providing applications with transparent access to
services.
Shortcut menu A menu that appears when the user right‐clicks an
item. The menu lists commands pertaining with that item.
Short Dispense A dispense transaction where requested amount of
notes are not presented. During short dispense notes are moved to
the cassette, reject bin or stays in the stacker as per the registry
configuration.
Signal Some types of worker generate a signal to allow a work flow
to be created in the application.
Signature See Note signature.
Silent Debug A utility introduced with Advance NDC 3.02 that
enables trace logging on live SSTs.
Simulated Services Simulations of SST devices. Used instead of real
devices when running a Test Application.
SIU CEN‐XFS class name for the Sensors And Indicators Units
service.
Smart Card Common name for a card that uses an integrated circuit
(microchip) rather than a magnetic stripe. See also: ICC
SMS Short Message Service. A service for transmitting short text
messages of up to 160 alphanumeric characters by mobile phone,
fax machine or IP address.
SNA Single Note Acceptor. An NCR device variant that is reported
using the same set of mStatus values as a BNA. Allows a
consumer to deposit a single banknote.
See BNA, Cash acceptor.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Glossary-13

Glossary

SNMP Simple Network Management Protocol. A widely‐used

network monitoring and control protocol.
SP See Service Provider.
SPL Software Product Line. A set of software‐intensive systems
that share a common, managed set of features satisfying the specific
needs of a particular market segment or mission and that are
developed from a common set of core assets in a prescribed way.

SSL Secure Sockets Layer. A cryptographic protocol for secure

communications on the Internet.
SST Self‐Service Terminal.
Stacker See Escrow.
STCONT A control file defined by Exits when user‐defined States
are added.
Subworker A term given to a worker that is contained within a work
group of another worker, in a worker hierarchy.
SUPCTR A control file used by Exits when user‐defined Supervisor
features are added.
Supervisor The Supervisor application in Advance NDC performs
the SST out‐of‐service functions associated with the
operator/supervisor.
Suspect note A note with recognised authentication features but
quality and/or tolerance deviations. In most cases, this means a
damaged or soiled banknote. This is the same as a category 3 note,
as defined in the ECB 6 regulation.

TCP/IP Transmission Control Protocol/Internet Protocol (TCP/IP) is

T the suite of network protocols used for all Internet traffic.
Test Application An application running on a development PC is
called a test application.
TI Tamper Indicator.
TLS Transport Layer Security. A cryptographic protocol for secure
communications on the Internet.
Top Worker The worker at the top of the worker hierarchy.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Glossary-14 APTRA Advance NDC, Developer’s Guide

 Glossary

TTS Text‐To‐Speech. Third‐party software that transforms text to

voiced audio.
Triple DES DES encryption performed three times successively, for
greater security.
See also DES
TTU CEN‐XFS class name for the Text Terminal Units service.

UCDI User‐defined Common Data Interface. Functionally identical

U to the CDI, it enables you to create new CDI stores (called UCDI
stores).
UPS Uninterruptible Power Supply. A device that provides battery
backup when mains power fails or drops to an unacceptable voltage
level.
USB Universal Serial Bus. A hardware interface for attaching
peripheral devices, such as disk drives.
USD The ISO currency ID for US dollars.
User A developer who has installed the Author using a personal
User ID. A user can create and own components.
User Messages A director worker provided for a user to process a
new message class.
User Terminal Data A director worker provided for a user to include
additional data in a Terminal State message.

Valid note Another term for Authenticated note.

V
Vault The movement of notes from the escrow to the cash‐in
cassette.
VCCONT A control file used by Exits when Virtual Controllers are
added.
VDA Vendor Dependent Application. Also CEN‐XFS class name for
the Vendor Dependent Application service.
VDM Vendor Dependent Mode. Also CEN‐XFS class name for the
Vendor Dependent Mode service.
VEROP VGA Enhanced Rear Operator Panel (not supported in
Advance NDC).
Virtual Controller (or Intercept Routine) A routine defined and
programmed by the user which can intercept and respond to
messages.
Visual Basic Script A Microsoft scripting language which is an
extension of the Microsoft Visual Basic language.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Glossary-15

Glossary

Vulnerability Management A PCI term defined as “the process of

systematically and continuously finding weaknesses in an organization’s
payment card infrastructure system.” For more information, refer to
the PCI Security Standards website.

WAVE WAVE or .wav (Waveform Audio). A standard Windows

W based sound format.
WMV Windows Media Video.
Work Flow In APTRA Author, a work flow allows Workers to
communicate across work groups by associating two work groups.
It specifies the flow of control from one work group to another.
Work Group A collection of workers with similar roles in the worker
hierarchy.
Worker A graphical building block in APTRA Author. Workers are
the Authoring components in a self‐service application.
Worker Class Every worker belongs to a worker class. the worker
class defines the characteristics and functions that any given worker
will have.
Working directory In Advance NDC, the user‐specified directory
containing customised authored projects. Also used to build the
final application.

XFS EXtensions for Financial Services. Application and service

X provider interface specifications from CEN.
XFS Simulator A component of the APTRA Simulator.
XML Envelope An XML document type defined to be a holder for
other XML data.

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Glossary-16 APTRA Advance NDC, Developer’s Guide

 Index

Index 0

.NET Software Update Tasks component 1‐53

Symbols
64‐Bit Windows 7
Numerics Importing Printer Registry Files Manually 5‐205

Abstract Classes B‐1

A Access menu and customer‐sensitive data E‐8
Activating the Customisation Layer and Supervisor 1‐5
Active Script Host 12‐7
ActiveXFS and the BNA 4‐6
Adding data to Terminal State Messages 9‐11
Additional DASH reader handling 5‐209
Advance NDC
and data security E‐3, E‐4
Application Core 1‐4, 7‐10
enhancing 9‐1
authored applications 1‐15
Common Data Interface 1‐11, C‐1
Customisation Layer 1‐8, 7‐3
customisations and data security E‐14
device access 4‐14
environment variables 7‐36
extending the runtime application 8‐27
installing on a PC 2‐4
installing on SSTs 11‐5
introducing 1‐1
localising 1‐76
migrating from NDC+ 3‐2
modification methods 13‐1
modifying the applications 13‐2
re‐installing on a PC 2‐5
starting on an SST 11‐7
testing the application 7‐35
in the Author environment 7‐37
running in the PC environment 7‐36
simulating communications 7‐45
XFS Simulator 7‐38
Card Reader 7‐40
Currency Dispenser 7‐40
preparing for use 7‐38
Simulated PINpad 7‐39
Simulated Terminal Text Unit 7‐38
testing the Customisation Layer 8‐26
translating the on‐line information 1‐76
unsupported features 1‐56, 1‐65
upgrading 4‐12
upgrading from earlier releases 4‐12

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-1

Index

using the Author for enhancements 13‐4

workers B‐1
Advance NDC Aggregate
building 1‐80
modification 11‐16
Advance NDC and APTRA Security
customisations 11‐9
updates 11‐9
Advance NDC and NDC+
differences in MACing 1‐73
proving the NDC+ download works 3‐10
Advance NDC exits
further reading 13‐7
Advance NDC on 64‐bit Windows 7 Systems
Advance NDC on 64‐bit Windows 7 Systems 11‐2
Mapping 32‐bit folder to 64‐bit folder 11‐2
Redirecting registry entry 11‐3
Renaming 64‐bit folder 11‐2
Advance NDC trace information 12‐5
Advance NDC troubleshooting utilities 12‐2
Aliases for device names 5‐17
Alphanumeric dialup 1‐24
Alphanumeric state entries 4‐23
Alphanumeric state number 1‐50
Altering Modes 9‐16
Always On tracing 12‐2, 12‐11
Animation files, recreating 3‐6
Application Core 1‐4, 7‐10
Applications catalog 7‐10, 7‐18
before modifying 9‐4
customisation preparation guidelines 9‐4
enhancing 1‐5, 9‐1
purpose 7‐10
workers B‐9
Application DLLs 4‐3
Authored State Types 4‐3, 4‐4
cash‐in component 4‐4
Transaction Reply functions 4‐4
Application executable 4‐2
Application links 7‐3, 7‐4
examples 5‐16
registry entry 5‐14
Application synchronisation 1‐10
Application timer 5‐101
APTRA Author, introduction 7‐2
APTRA Promote, enabled 1‐35
APTRA Security 11‐9
APTRA Simulator 4‐10
APTRAUCDI properties and methods 10‐6
Archiving
Cache files 5‐70
Deleting Cache files 5‐70
Associated keyboards 1‐75

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-2 APTRA Advance NDC, Developer’s Guide

 Index

Audio 6‐49
Audio Control state, unsupported 1‐65
Audio files, recreating 3‐5
Authenticator, secure B‐17
Author
documentation A‐4
migration from NDC+ 1‐1
supported graphics file formats 3‐3, 3‐4
working directory 2‐5
Author flow 12‐6
author flow
DebugOutput attribute 12‐6
DebugTextLine attribute 12‐6
Author Script Host
DebugMessage.DebugMessage object 12‐7
Authored customisations 4‐12
Authored states, referencing 4‐2
Automatic error recovery,configuring 5‐364
Automatic Language Selection 5‐217
AVI system limit 5‐156

BAPE emulation 1‐68

B BAPE registry settings 11‐11
Barcode filter 5‐210
Barcode Reader Filter and Extraction Rules 5‐210
Basic Operator Panel (BOP) 1‐74
Beep configuration 1‐29
bin overflow 5‐328
BNA
configuring counts to print 5‐350
currency for printing totals 5‐349
printing totals 5‐349, 5‐350
BNA Counts
and counters configuration 5‐348
display 5‐347
Print 5‐347
Supervisor Counters Cassette Names Array 5‐347
BRM 1‐35
Buffers
CDI store catalog C‐12
general purpose 1‐11
Bunch cheque acceptor, configuring the simulator 7‐45
Bunch Note Acceptor
encash, print and set next state configuration 5‐377
journal format configuration 5‐379
Bunch Note Acceptor (BNA)
and ActiveXFS 4‐6
CDI store catalogs
Accepted Denomination Counts C‐4
Active Banknotes C‐5
Denomination Configuration C‐8
Deposited Denomination Counts C‐9

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-3

Index

MISC C‐10
support in Advance NDC 1‐75
Bunch Recycling Module
Cassette Configuration 5‐407
default cassette names 5‐359
deposit only configuration 5‐414
dispense only configuration 5‐414
Features 1‐35
Bunched cheque amount, display 1‐23

C Exit method 13‐4

C C++ code 12‐6
debug method 12‐6
DebugOut class 12‐6
C05 screen 1‐78
Cancel Collector B‐16
Cancel/Clear swap option 4‐9
Card ATR Reader B‐15
Card Eject State 4‐4
Card Holder Display Alarm C‐47
Cardholder graphics 3‐3
Cardholder verification state G‐10
Cardless transactions 5‐142
configuration 5‐142
key mask definitions 5‐147
Cash deposit handling off‐line 1‐40
Cash Deposit Handling state
handling off‐line 5‐329
off‐line states Array 5‐330
off‐line states array, example 5‐331
Cash handler
configuring 5‐267, 5‐275
denomination 5‐268
multiple currencies 5‐275
suppressing status in dialup environment 5‐50
tamper indication 5‐297
Cash Handler Retract Counts 1‐20
Cash Handler Retract Counts/Reject and Retracted Total Counts 1‐20
Cash Recycler Reject and Retracted Total Counts 1‐20
Cash‐in component
and data security E‐7
configuring
automatic error recovery 5‐364
BNA count journal format 5‐379
BNA encash, print and set next state 5‐377
BNA MEI 5‐377
ECB 6 5‐367, Glossary‐6
GBXX cassette configuration 5‐389
GBXX dynamic note sorting 5‐386
installed registry entries 5‐313
Cassette Information Screen
enabling in Add Cash 5‐272

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-4 APTRA Advance NDC, Developer’s Guide

 Index

enabling in Test Cash 5‐273

purpose 5‐271
Cassette, GBXX configuration 5‐389
Catalogs
Application Core 7‐10, 7‐18
Application Core Applications 7‐10
CDI stores C‐1
Customisation Layer 7‐3
NDC Core 7‐9
NDC Encryption Keys 7‐9
NDC Field Workers 7‐9
User Control Examples 7‐18
User Controls 7‐18
User Stores and Signals 7‐18
CDI store catalogs
BNA Accepted Denomination Counts C‐4
BNA Active Banknotes C‐5
BNA Denomination Configuration C‐8
BNA Deposited Denomination Counts C‐9
BNA MISC C‐10
Buffers C‐12
CPM C‐16
Dialup C‐17
EJ Upload C‐19
EMV C‐20
Encryptor Variant C‐21
Error processing C‐22
Exit Migration C‐23
FIT Data C‐25
Key Entry Mode C‐29
Misc Counters C‐30
Note Counters C‐31
Printing C‐34
Screen Display C‐37
Security C‐38
State Information C‐41
Supervisor C‐44
Terminal Configuration C‐47
Timers C‐51
Transaction Processing Flags C‐53
CDI stores for a Transaction Request 8‐15
CDI, see Common Data Interface
CDM and CIM NDC Cassette Types 5‐401
Central to Terminal messages
Enhanced configuration parameters load 4‐8
CEN‐XFS Exits
logical device names 5‐17
Changing RESRVD.DEF 3‐8
Character sets 1‐76, D‐4
Cheque image display 1‐23
Cheque images
deleting securely E‐11
displaying securely E‐11

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-5

Index

printing securely E‐11

secure storage E‐11
Cheque processing
data security in solutions E‐11
with ImageMark Passport E‐12
Cheque Processing Module (CPM) 1‐21
Endorse forms and media 5‐421
ImageMark Passport ATM Image Agent 5‐426
Close state 7‐8
Codeline, configuring 1‐23
Coin dispenser 1‐62
configuring the simulator 7‐40
currency 5‐264
setting coin value 5‐264
setting low threshold 5‐265
Commands in Silent Debug 12‐13
Common Data Interface (CDI) 1‐11
catalogs C‐1
CDI ‐ ‹name› Catalog 7‐9
enhancing the Customisation Layer 1‐13
migrating from NDC+ 1‐12
Communications
clearing the buffer 5‐44
domain name server 5‐46
internet protocols supported 1‐36
Keep Alive 5‐46
protocols 1‐36, 1‐73
recreating template files 3‐9
template files and TCP/IP 3‐9
trace masking E‐7
Comparing Advance NDC with NDC+ 1‐57
Compatibility considerations 8‐5, 9‐4
Compliance with PCI DSS E‐2
Component folder 2‐5
Configuration
cardless transactions 5‐142
XML files 5‐37
Configuration options 5‐19
Registry entry 5‐14, 5‐55
Status handling 5‐19
Configuration parameters, ignored by Advance NDC 1‐66
Configure menu, access to customer‐sensitive data E‐8
Configuring Cash Handlers
Cash Dispenser Cassette Status 5‐269
Automatic XFS Exchange 5‐270
Manual XFS Exchange 5‐270
XFS Exchange and Cassette Information 5‐271
Configuring printers
non‐thermal 5‐203
receipt 5‐191
statement 5‐195
USB receipt and journal 5‐199
Configuring readers

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-6 APTRA Advance NDC, Developer’s Guide

 Index

contact and contactless card readers 5‐213

Configuring Silent Debug 12‐13
Configuring TCP/IP 5‐45
Configuring the journal printer at Start of Day 7‐13
Configuring the Off‐line Timer 5‐45
Configuring Third‐Party TTS Software 6‐10
Confirmation Screens 1‐45
Contact and Contactless Card Readers
MEI 5‐225
Contactless Card Reader
24‐Volt reset 5‐223
configuring through XML 5‐228
ContactlessEnabler.XML 5‐228
GASPER‐compatible SNMP traps 5‐62
reset 5‐222
Counters
CDI ‐ Note Counters catalog C‐31
entering for dual cash handlers 5‐294
Misc CDI store catalog C‐30
CPM, CDI store catalog C‐16
Creating a UCDI store
using an Automation object 10‐5
using the CreateObject function 10‐6
using the UCDI Initialisation File and Stores 10‐5
Creating new State Types 8‐16
CRM
cancel market session H‐10
consumer ID H‐3
Promote H‐2
display campaigns H‐10
Enable/Disable Promote H‐2
Relate
coupon printing H‐3
Multipe backgrounds H‐3
reporting errors H‐9
CRM flowpoint state 5‐436
Currency
coin dispenser 5‐264
dispenser 7‐40
multiple 5‐275
setting 5‐267
Custdat utility
error messages 7‐49
using 7‐48
custom.dat 7‐47
exporting 7‐48
importing 7‐49
custom.ini 11‐16, 11‐18
Customer relationship management (CRM) 1‐35
Customer‐sensitive data, journaling E‐7
Customisation
Application Core 9‐2
guidelines 8‐4

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-7

Index

preparation guidelines 8‐7

settlements screen 5‐103
specifying local data 5‐23
using APTRA Author 9‐19
Customisation data
commands 1‐67
processing 7‐26
Customisation Layer 1‐8, 7‐3
Applications catalog 7‐3
before modifying 8‐4
catalogs 7‐3
checking the status of 7‐19
director 7‐5
enhancing 1‐9
functionality 1‐8
migrating to Advance NDC 1‐8
status query 7‐19
synchronisation with 7‐18, 9‐17
testing 8‐26
workers B‐2
CustomisationLayer.mpj 7‐35
Customisations
re‐applying in the Customisation Layer 4‐12
Customising Modes 9‐16
Customization
and functions 13‐6

DAPI and data security E‐8

D DASH card reader 1‐16
additional fatal/suspend handling 5‐209
Data
PAN 5‐143
specifying local customisation 5‐23
data 5‐144
Data Copy and Compare state 1‐34
Data fields, adding to Transaction Request Message 8‐18
Data security
and Advance NDC customisation E‐14
and CPM solutions E‐11
and DAPI requirements E‐8
and debugging E‐5
and ECB 6 E‐7
and journaling E‐6
and the CIC E‐7
cheque images E‐11
cheque printing E‐11
Data security standards E‐2
Debugging and data security E‐5
DebugLog 1‐36, 2‐5
Auto Save function 12‐17, 12‐18
configuring the Auto Save function 12‐17
Reflected Messages 12‐26

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-8 APTRA Advance NDC, Developer’s Guide

 Index

trace stream messages 12‐26

trace stream windows 12‐26
troubleshooting with 12‐25
using 12‐25
Default User Messages director 9‐5
Default User Terminal Data director 9‐11
De‐installing .NET Assemblies 11‐22
De‐installing Advance NDC
On the PC 2‐6
On the SST 11‐21
Deleting cheque images securely E‐11
Denomination and the cash handler 5‐268
Desktop installation of the Advance NDC package 11‐4
before you start 11‐4
installing Advance NDC on an SST
SST directory structure 11‐5
starting the Advance NDC application 11‐7
Device access 4‐14
Device name aliases 5‐17
Device Suspend work group 7‐8
Dialup comms
cash handler status suppression 5‐50
CDI store catalog C‐17
configuration 5‐49
timers and modem baud rate 5‐52
Diebold emulation mode status messages 1‐70
Differences between Advance NDC and NDC+ 1‐57
Digital Audio Service 1‐64
Direct Deposits 1‐40
Display Image Files Control 3‐4
Display, configuration file 5‐162
Displaying Direct Deposit Error Messages 5‐326
Displays 1‐33
DM ParamValues C‐55
DNS, see domain name server
Document Processing Module, not supported 1‐59
Domain name server, configuring 5‐46
Downloadable keyboard definitions 4‐9
Dual cash handler
counter entry mode 5‐294
interlock handling 5‐297
multiple currencies 5‐296
setting priority 5‐294
status reporting 5‐295
Dual cash handlers
counters 5‐294
Dual cash handlers, configuring 5‐294
Dynamic note sorting (GBXX) 1‐40, 5‐386

ECB 6
E and data security E‐7
BNA mode 1 registry entries 5‐375

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-9

Index

counterfeit notes 5‐368

database support utility 5‐376
GBXX mode 0 registry entries 5‐375
GBXX mode 2 registry entries 5‐375
note categories 5‐367
suspect notes 5‐368
ECB 6 Regulations 1‐41
Editing State Types authored in Advance NDC 8‐16
EJ level 5‐188
ejdata.log 1‐68
ejrcpy.log 1‐68
Electronic Journal
automatic INIT options 5‐181
agent 5‐183
copy drive 5‐184
cutover 5‐181
example agent batch file 5‐67, 5‐68, 5‐69, 5‐77, 5‐78, 5‐79, 5‐86,
5‐184, 5‐425, 5‐426
scheduled 5‐181
checksum 5‐180
compression 5‐180
configuration at Start of Day 7‐13
enhanced EJ backup 5‐187
file format 1‐69
file location 4‐7, 11‐9
journal printer packup 1‐68
log file checksum 1‐68
log file inspection (In Service Supervisor) 1‐68
maximum file size 5‐180
maximum number of backups 5‐187
multiple destinations 5‐186
upload, CDI store catalog for C‐19
EMV C Exits 4‐9
EMV, CDI store catalog C‐20
EMV/CAM2 Exits 4‐13
Enable/Disable Promote H‐2
Enabling
state flow tracing 12‐9
web exits 5‐21
Encrypting PIN Pad (EPP) support 1‐50
Encryptor configuration on NCR SSTs 11‐10
Encryptor Variant, CDI store catalog C‐21
Enhanced configuration
Parameters load 4‐8
Enhanced configuration option 37 and customer data E‐6
Enhanced Configuration Parameters, processing new 9‐15
Enhancing Advance NDC 13‐2
Enhancing the Application Core 1‐5, 9‐1
Enhancing the Customisation Layer 1‐9
overview 1‐13
EPP registry settings 11‐10
Error messages
custdat utility 7‐49

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-10 APTRA Advance NDC, Developer’s Guide

 Index

Error processing, CDI store catalog C‐22

Example XML Configuration File 6‐45
Examples
custom.ini file F‐2, F‐4
EJ batch file 5‐67, 5‐68, 5‐69, 5‐77, 5‐78, 5‐79, 5‐86, 5‐184, 5‐425, 5‐426
GBXX configuration file 5‐397, 6‐45
GBXX schema 5‐391
LOCAL file 5‐25
SCXLOC file 5‐23
UCDI Initialisation File 10‐3, 10‐9
user examples catalog 7‐18
User Messages director, implementation 9‐8
User Terminal Data director, implementation 9‐13
Executing a worker hierarchy 8‐15
Executing an entire NDC+ download 3‐2
Exit migration, CDI store catalog C‐23
Exiting a State Flow 8‐14
Exits 13‐4
web 5‐21
Exporting custom.dat 7‐48
Extending Advance NDC 13‐2
Extending the Advance NDC runtime 8‐27
External C function method 13‐5

Features, unsupported in Advance NDC 1‐68

F Files
.prn 5‐200
AudioGuidanceData.xml 6‐7
AudioGuidanceDataLocal.xml 6‐13
custom.dat 7‐47
custom.ini 11‐18
DisplayManagerConfig.xml 5‐162
ejdata.log 1‐68
ejrcpy.log 1‐68
krep.dat 11‐15
LOCAL 5‐24
NDCConfigurationControl.xsd 5‐38
NoAudio.xml 6‐7, 6‐13
PersonasPrinters.reg 5‐198
pmdata 7‐13, 11‐6
resrvd.def 3‐8, 4‐8
SCXLOC 5‐23
FIT data, CDI store catalog C‐25
Font
creating D‐2
definition 1‐76, D‐1
definition file 1‐48, D‐2
designators D‐3
installing D‐9
Front operator keyboard 5‐433
Function IDs for foreign currency exchange 1‐20
Function IDs, processing new 8‐19

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-11

Index

GBRU
G maximum notes 5‐405
registry entries 5‐399
reporting the MANIP status 5‐401
GBXX
cassette configuration 5‐389
configuration file 5‐397, 6‐45
GBXX2 7‐44
note reporting 5‐389
note sorting 5‐386
schema 5‐391
elements 5‐392
GBXX cassettes, configuring 5‐389
General purpose buffers 1‐11
Graphics
recreating 3‐3
Graphics, cardholder 3‐3

Hardcopy Backup, file location 4‐7, 11‐9

H Help for Advance NDC workers B‐1, B‐15

ImageMark Passport
I requirements and PA‐DSS 5‐109, E‐12
Implementing APTRA Security XP with Advance NDC 11‐9
Importingcustom.dat 7‐49
In Service Mode
synchronisation with the Customisation Layer 9‐17
work group 7‐17
Indicator volume control 6‐8
Initialisation file, UCDI 10‐3
Initialise
task 1‐4, 9‐16
work group 7‐13
Installers
combined 11‐5
Installing Advance NDC
on a development PC 2‐3
on an SST 11‐4
on SSTs 11‐5
Intelligent Fraud Device, replaced 1‐32
Internet protocols 5‐48

Journal
J BNA count format 5‐379
Journal configuration at Start of Day 7‐13
Journal printer level 5‐190
Journal records, tampered 1‐68
Journaling 1‐43
Journaling and data security E‐6
Journaling state low trace 12‐9

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-12 APTRA Advance NDC, Developer’s Guide

 Index

Keep Alive registry entry 5‐46

K Key Entry Mode, CDI store catalog C‐29
Key Manager
functionality 11‐11
registry settings 11‐11
troubleshooting 11‐15
Key names, NCR encryptor 11‐11
Keyboard data, unsupported features 4‐9
Keyboard, front operator 5‐433
Keyboards
associated 1‐75
nested (not supported) 1‐29
touch‐screen for alphanumeric data entry 5‐152
Keys, retaining 11‐13
krep.dat 11‐15

Link name for TCP/IP communications 5‐47

L Local Cash Dispense State 4‐4
Local customisation data 5‐22
specifying 5‐23
LOCAL file
example 5‐25
location 5‐25
Local User Group and User Account E‐9
Localising Advance NDC 1‐76
Logical device names and CEN‐XFS 5‐17
Logo control 3‐3
Long receipt retract 5‐191

Machine Number Entry 1‐30

M MACing 1‐73
Mapping the Enter key to an FDK 5‐150
Masking
PAN 5‐34
Track 2 data 5‐34
Master expansion state 1‐51
Maximum state number 1‐50
MCRW
security jitter 4‐8
Message Class
extracting 9‐7
processing new classes 9‐5
Message Handler
and User Messages/User Terminal Data 9‐2
functionality 7‐24
Message handling 1‐4
in the Application Core 7‐21
Message processing
Director 7‐22
Terminal Commands 7‐24
transaction processing flags 7‐19

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-13

Index

transaction reply 7‐27

Message Processor Script Host 7‐23
Message reflection 1‐36
Message Selector
default User Messages 9‐7
User Messages example 9‐8
Messages
Enhanced configuration parameters load 4‐8
external system event handling 5‐19
Methods of implementing Exits 13‐2
Migrating from Advance NDC 4‐12
Migrating from NDC+ 1‐12
Migrating to Advance NDC 1‐8, 3‐2
changes required 3‐2
Misc Counters, CDI store catalog C‐30
Mode Handler
adding functionality to Modes 9‐16
Director 7‐15
work groups 7‐11
Mode Handling
implementation 7‐20
Mode handling
functionality 1‐4
Modes, modifying 9‐16
Modifying Advance NDC 13‐2
Modularisation in Advance NDC 4‐2
Modularisation of state types 1‐8
MPEG files
support 3‐6
unsupported Screen Data feature 1‐70

NCR documentation, other A‐7

N NCR encryptor configuration 11‐10
NCR SP device names 5‐17
NDC Core catalog 7‐9
NDC Core workers B‐4
NDC CRM Interface Worker Class 1‐35
NDC CRM Service 1‐35
NDC DES Loader B‐9
NDC Dialup worker B‐9
NDC Encryption Keys catalog 7‐9
NDC Field Workers catalog 7‐9
NDC Monitor 5‐89
NDC Sensors Status Builder B‐10
NDC Supplies Data Builder B‐10
NDC Tally Builder B‐10
NDC Transaction Handler 8‐20
worker 8‐18
NDC Transactions Catalog 7‐9
NDC+, migrating from 1‐12
NDCBarcodeReader.xml 5‐210
NDCSecurityCamera.xml file

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-14 APTRA Advance NDC, Developer’s Guide

 Index

camera configuration 5‐26

Nested keyboards, not supported 1‐29
New Message Class 9‐9
processing 9‐5
Note Counters, CDI store catalog C‐31
Note deposit
category counts 5‐351
total counts 5‐353
Notes
Dynamic sorting (GBXX) 5‐386
GBRU maximum 5‐405
reporting (GBXX) 5‐389
signatures 5‐368

Offline Mode
O altering 9‐17
work group 7‐17
Off‐line Timer
configuring 5‐45
registry setting 5‐45
Off‐line transactions
deposit handling 5‐329
Operator keyboard
configuration 5‐103, 5‐151
front 5‐433
Option digit 5B and customer data E‐7
Orientation Message 6‐8
Out of Service Mode
altering 9‐17
and Mode handling 7‐20
work group 7‐17

PA‐DSS
P changes in Advance NDC for compliance E‐5
external audits E‐14
requirements and Advance NDC E‐3, E‐4
PAN
masking 5‐34
Passbook printer
support 1‐28, 1‐78
worker classes 1‐28, B‐12
Password changer, secure B‐17
Payment Application Data Security Standard (PA‐DSS) E‐2
Payment Card Industry Data Security Standard (PCI DSS) E‐2
PC environment
testing touch events 7‐36
PCI DSS
external audits E‐14
overview E‐1
requirements E‐2
Persistence levels 10‐4
UCDI 10‐4

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-15

Index

Persistent storage 7‐13

Picture Control 3‐3
PIN Block ‐ No Encryption 1‐67
PIN entry and verification 1‐67
PIN Entry Initiation state 1‐16
PIN Entry States 1‐67
pmdata 7‐13, 11‐6
Power Fail 7‐14
Power‐up 1‐4
Prepare Dispense 5‐300
Preparing the XFS Simulator for use 7‐38
print 5‐347
Printer
receipt 4‐21
Printers
LEAP receipt printer configuration 5‐202
non‐thermal configuration 5‐203
receipt configuration 5‐191
statement configuration 5‐195
USB and .prn files 5‐200
USB receipt and journal configuration 5‐199
Printing Exception Reports 5‐379
Printing promote coupon 5‐192
Printing, CDI store catalog C‐34
Priority
dual cash handler 5‐294
Processing a new Message Class 9‐5
Processing new Enhanced Configuration Parameter 9‐15
Processing new Function IDs in Transaction Reply Message 8‐19
Product class support 1‐46
Program Text
Audio 6‐49
Programming techniques for modifying Advance NDC 13‐4
Promote, coupon format 5‐192
Protocols, communications 1‐73

Ready 9 Message 7‐25, 7‐27, 7‐28

R Receipt handling 5‐191
long receipt retract 5‐191
receipt retract 5‐191
USB printers 5‐200
Receipt printer 4‐21
top margin 1‐33
Recreating Animation Files 3‐6
Recreating Audio Files 3‐5
Recreating Communications Template Files 3‐9
Recreating Graphics 3‐3
Registry entries
ECB 6 mode 0 or 2 5‐375
ECB 6 mode 1 on BNA devices 5‐375
for Advance NDC 5‐14
for Service Providers 5‐55

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-16 APTRA Advance NDC, Developer’s Guide

 Index

GBRU 5‐399
Keep Alive 5‐46
Off‐line Timer 5‐45
Service Class 5‐44
Registry entries for application DLLs 5‐14
Registry entry for Silent Debug 12‐13
Registry settings
BAPE 11‐11
EPP 11‐10
Key Manager 11‐11
Re‐installing Advance NDC on a PC 2‐5
Related documentation
overview A‐1
Release bulletin 2‐2
Remote key management 1‐50
Replacing State Types with workers 8‐13
Reporting Direct Deposit Capability 5‐326
Reserved Screen Retriever B‐10
Reserved screen t15 and customer data E‐7
Reserved Screens 9‐19
resrvd.def, changing 3‐8, 4‐8
Retracting long receipts 5‐191
Retracting receipts 5‐191
Returning to a State Flow 8‐15
RSA
authentication process 4‐8
encryption support 1‐50
Running in the Author Environment 7‐37
Running in the PC Environment 7‐36
Runtime Only Installer 11‐5
Runtime, extending in Advance NDC 8‐27

S2 Dispenser
S 1 Retract 5‐303
1.5 Retract 5‐303
2 Retract 5‐303
2.5 Retract 5‐303
Carriage Sweep 5‐299
Parallel Carriage Sweep 5‐300
Serial Carriage Sweep 5‐300
Fifth cassette configuration 5‐280, 5‐281
fitness reporting 5‐286
registry entries 5‐299
reject and retract counts 5‐307
S2 dispenser 5‐297
supplies reporting 5‐284
tamper indication 5‐308
Screen Data 1‐70
Screen Display, CDI store catalog C‐37
Screens
more than 999 supported 1‐47
support 1‐78

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-17

Index

C05 1‐78
X screens 1‐78
Script host method 13‐5
SCXLOC
example 5‐23
location 5‐23
Secure deletion of cheque images E‐11
Secure Encryption Key Collector B‐16
Secure Initial Unattended Installation (IUI) 11‐9
Advance NDC customisations under APTRA Security 11‐9
Windows XP 11‐9
Advance NDC updates for APTRA Security 11‐9
Implementing APTRA Security XP with Advance NDC 11‐9
Secure Key Entry 1‐17
Secure workers B‐17
Security camera 1‐74
Security CDI store catalog C‐38
Security jitter 4‐8
Security standards for data E‐2
Selecting a debugging utility 12‐2
Selector (Device 1) User Terminal Data 9‐13
Serial Number Information
journal configuration 5‐331
printing configuration on receipt 5‐337
reading and journaling for cash handlers 5‐288
Service Class setting 5‐44
Session Releaser worker 7‐19
Set display mode 1‐78
Setting coin value for coin dispenser 5‐264
Setting low threshold for coin dispenser 5‐265
Setting the CDI Stores used in a Transaction Request 8‐15
Settlements screen customisation 5‐103
Signals in user controls 7‐18
Signatures, note 5‐368
Silent Debug 1‐36, 2‐5, 12‐3
commands 12‐13, 12‐22
configuration settings 12‐13
counter 12‐14
log files 12‐14
LOGBYDAY 12‐15
MAXFILESIZE 12‐14
MERGEDTRACE 12‐14
overwriting file 12‐14
registry entry 12‐13
starting remotely 12‐22
TRACE 12‐14
trace log files 12‐22
trace logging 12‐22
troubleshooting with 12‐22
using silent debug 12‐16
Simple Network Management Protocol (SNMP) 5‐58–5‐62, ??–5‐63
Simulated PINpad 7‐39
Simulated Supervisor Entry/Exit Messages in Automatic Error

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-18 APTRA Advance NDC, Developer’s Guide

 Index

Recovery 5‐120
Simulated Terminal Text Unit (TTU) 7‐38
Simulating Communications 7‐45
Simulator
APTRA 4‐10
configuring for bunch cheque acceptor 7‐45
configuring for coin dispenser 7‐40
configuring for TCP/IP 7‐45
Single application executable 4‐2
Skimming Protection System
Unusual Object Monitoring time‐out 5‐101
Smart Delay Timer 5‐262
Smart Delay Timer for Smart Dip Card Reader 5‐262
SMS Data Collector worker B‐16
SNMP, see Simple Network Management Protocol 5‐58
Software Management 1‐75
Software update 1‐53
SP and application timers, configuration 5‐101
Specifying local customisation data 5‐23
SSDS DLL Interface worker 4‐3
SST directory structure 11‐5
SSTs, installing Advance NDC 11‐5
Start of Day 1‐4
director 7‐12
initialisation 7‐12
task 9‐16
work group 7‐6
Starting Advance NDC on an SST 11‐7
State flow tracing 12‐9
State Flow, returning to 8‐15
State Flow, updating for web exits G‐7
State Information, CDI store catalog C‐41
State number
alphanumeric 1‐50
maximum 1‐50
State numbers
alphanumeric state entries 4‐23
State table
web exit parameters G‐2
State Type modularisation 1‐8
State Types
editing authored 8‐16
support in Advance NDC 1‐65
Status 5‐209
reporting for dual cash handlers 5‐295
Status handling in CEN XFS 5‐19
Status messages
Diebold emulation 1‐70
STCONT
updating web exit state type letter G‐7
STCONT file updates 4‐23
Storage, persistent 7‐13
Stores

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-19

Index

Common Data Interface (CDI) catalogs C‐1

UCDI C‐55
User‐defined Common Data Interface (UCDI) catalog C‐1
Voice guidance C‐56
String store, secure B‐17
Supervisor
login attempts E‐10
Supervisor Counters Cassette Names Array 5‐347
Supervisor Data Collector 9‐20
Supervisor Entry/Exit Message 1‐30
Supervisor menus 4‐9
Supervisor Mode 7‐17
customising 9‐18
functionality 7‐17
implementation 1‐4
Supervisor mode 1‐72
Supervisor Option to Auto‐configure Devices 5‐2
Supervisor, CDI store catalog C‐44
Supplies Data Formatter B‐11
Support Applications for Troubleshooting
troubleshooting with DebugLog 12‐25
trace stream information 12‐26
troubleshooting with Silent Debug 12‐22
Support for foreign currency exchange transactions 1‐20
Support for screens 1‐78
C05 1‐78
X screens 1‐78
Supported Codecs 3‐6
Suspend 1‐4
Suspend mode
additional DASH reader handling 5‐209
Synchronisation
and Mode handling 7‐21
considerations when modifying Modes 9‐16
In Service Mode 9‐17
In Service Mode work group 7‐17
of Customisation Layer and Application Core 1‐9
workers 7‐18
Synchronisation between applications 1‐10
System requirements 2‐2

Tamper indication
T cash handler 5‐297
Tampered journal records 1‐68
Tasks
initialise 1‐4, 9‐16
Start of Day 9‐16
TCP/IP
configuring the simulator 7‐45
TCP/IP communications
configuration 1‐72
simulating 7‐45

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-20 APTRA Advance NDC, Developer’s Guide

 Index

Terminal Commands, processing 7‐24

Terminal Configuration, CDI store catalog C‐47
Terminal ID Source 5‐87
Terminal State Message 7‐25
adding data to 9‐11
Testing the Advance NDC application 7‐35
Testing the Customisation Layer 8‐26
The Advance NDC Application 1‐15
Timer application 5‐101
Timers
CDI store catalog C‐51
ignored by Advance NDC 1‐66
Timestamp 12‐5
TM‐Alert (not supported) 1‐59
Touch events, generating in a test environment 7‐36
Touch‐screen keyboards 5‐152
Trace information 12‐5
trace output 12‐5
trace point 12‐5
Trace Messages, localising text 9‐19
Tracing
contactless transactions 5‐226
Tracing from C++ code 12‐6
Tracing from the Active Script Hosts 12‐7
Tracing from the Author Flows 12‐6
Tracing state flow 12‐9
Track 2 5‐144
Track 2 data 5‐144
Tracking URLs for web exits G‐6
Transaction Handler workers
NDC Transaction Handler 8‐18
Transaction Request State 8‐18
Transaction limit 5‐328
Transaction Processing Flags, CDI store catalog C‐53
Transaction Reply
command processing 7‐27
processing new Function IDs 8‐19
Transaction Request
adding data fields 8‐18
before modifying 8‐18
setting the CDI Stores 8‐15
State worker 8‐18
Transaction Request Extension State 1‐76
Transaction Request/Reply 8‐18
Transactions, off‐line deposits 5‐329
Translating Advance NDC on‐line information 1‐76
Traps, SNMP 5‐58
Treatment of Notes After a Power Failure 1‐17
Troubleshooting
Advance NDC trace information 12‐5
Advance NDC troubleshooting utilities 12‐2
Always On tracing 12‐2
assistance 1‐36

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-21

Index

Key Manager 11‐15

overview 12‐1
selecting a debugging utility 12‐2
Problem Determination 12‐2
Silent Debug 12‐3
tracing from C++ code 12‐6
tracing from the Active Script Hosts 12‐7
tracing from the Author Flows 12‐6
using Problem Determination 12‐2

UCDI, see User‐defined Common Data Interface

U Uninterruptible Power Supply (UPS) 1‐17, 5‐99
Unknown Command Code director 9‐9
Unsolicited Status Messages 1‐77
Unsolicited status messages
external events 5‐19
Unsupported features 1‐56
Audio Control state 1‐65
Upgrading from Advance NDC 4‐12
UPS 5‐99
UPS worker B‐11
URLs
tracking for web exits G‐6
USB and RS232 DASH Card Readers 5‐263
User Control Examples Catalog 7‐18
User controls
Catalog 7‐18
signals 7‐18
User Messages
default implementation 9‐5
default Message Selector 9‐7
overview 9‐2
User Messages and User Terminal Data 9‐2
User Messages example
Message Selector 9‐8
Process Message work group 9‐9
User Stores and Signals Catalog 7‐18
User Terminal Data
default implementation 9‐11
director 9‐11
example implementation 9‐13
message Selector (Device 1) 9‐13
overview 9‐2
User‐defined Common Data Interface
APTRA UCDI properties and methods 10‐6
creating a store 10‐5
using an Automation object 10‐5
using the CreateObject function 10‐6
using the UCDI Initialisation File and Stores 10‐5
initialisation file 10‐3
persistence levels 10‐4
service 10‐2

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-22 APTRA Advance NDC, Developer’s Guide

 Index

stores catalog C‐55

using stores 10‐1

VGA Enhanced Rear Operator Panel (VEROP) 1‐74

V Voice Guidance
and Display Manager 6‐15
and Promote 6‐14
configuring 6‐7
introduction 6‐2
schema elements 6‐24
Setting volume control 6‐8
stores catalog C‐56
Voices Array 6‐11
XML file
other XML files used 6‐12
required Audio elements 6‐12
Voicing the Clear Key Press 6‐37
Voicing the Clear key press 6‐37

Web exits 5‐21, 13‐6

W state table parameters G‐2
tracking URLs G‐6
updating the state flow G‐7
updating the state type letter G‐7
Web Page Download Timer Configuration G‐8
Worker classes
developing 13‐6
passbook printer B‐12
Worker hierarchy, executing 8‐15
Workers supplied with Advance NDC B‐1
on‐line help for B‐1, B‐15
Working directory, Author 2‐5

X screen support 1‐78

X XML
configuration file envelope 5‐37
GBXX configuration file 5‐397, 6‐45
GBXX schema 5‐391

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

APTRA Advance NDC, Developer’s Guide Index-23

Index

Confidential and proprietary information of NCR.

Unauthorised use, reproduction and/or distribution is strictly prohibited.

Index-24 APTRA Advance NDC, Developer’s Guide

 User Feedback Form

Title: APTRA™ Advance NDC, Developer’s Guide

Number: B006‐6046‐T000 Release: Issue 1 Date: May 2019

NCR welcomes your feedback on this publication. Your comments can be of great value in helping us improve
our information products.
Cut

You may send your comments to us electronically. See over for details.

Circle the numbers below that best represent your opinion of this publication.

Ease of use 5 4 3 2 1 0 5 = Excellent

4 = Good
Accuracy 5 4 3 2 1 0
3 = Adequate
Clarity 5 4 3 2 1 0 2 = Fair
1 = Poor
Completeness 5 4 3 2 1 0
Organisation 5 4 3 2 1 0 0 = Not applicable
Appearance 5 4 3 2 1 0
Examples 5 4 3 2 1 0
Illustrations 5 4 3 2 1 0
Job performance 5 4 3 2 1 0
Question resolution 5 4 3 2 1 0
Overall satisfaction 5 4 3 2 1 0

Indicate the ways you feel we could improve this publication.

 Improve the table of contents  Add more/better quick reference aids

 Improve the overview/introduction  Add more examples
 Improve the organisation  Add more illustrations
 Improve the index  Add more step‐by‐step procedures
 Make it less technical  Add more troubleshooting information
 Make it more concise/brief  Add more detail
Write any additional comments you may have below and on additional sheets, if necessary. Include page
numbers where applicable.

Use the following address to send your comments to us electronically:

E‐mail ‐ Advance NDC, Information Products

Cut
Fold

If we may contact you concerning your comments, please fill in the information below:

Name:
Organisation:
Company:
Address:

Phone: Fax:

Thank you for your evaluation of this publication. Fold the form where indicated, tape (please do not staple),
and drop in the mail.

F 8763‐0695

Fold

Affix
Postage
Stamp
Here

NCR Financial Solutions Group Ltd

Product Management Feedback
Kingsway West
Dundee
Scotland
DD2 3XX