Copyright 2000 by

TCR Twin Safe TSAPI Interface Description De La Rue International Ltd., Basingstoke, Berne Branch Morgenstrasse 131 CH-3018 Bern-Bmpliz Telephone +41 31 997 56 00 Telefax +41 31 997 56 60

All rights reserved. The contents of this document may not be copied or reproduced in any way or form, nor made available to third parties without prior written permission of the publishers. Information or modification changes can be carried out at any time without previous notice.

Administration Document Document No. Date of issue Location Created with Version Issue 1.00 1.01 1.10 2.00 2.01 2.02 2.03 2.04 2.07 2.08 3.00a 3.00b 3.00c 3.00 4.00 4.01 4.03 5.00 5.02 Synopsis:

TSAPI Interface Description 539.1261/03 27 June 2012 Microsoft Word Note Draft version Revised version Revised version Revised version Revised version Revised version Revised version Revised version Revised version Revised version Draft version Draft version Draft version Draft version Draft version Draft version Draft version Draft version Draft version

Language Version

English 5.02

Date 09.1999 10.1999 02.2000 01.2002 02.2002 04.2002 12.2002 01.2003 01.2003 05.2005 07.2006 08 2006 03.2007 04.2007 04.2007 05.2007 10.2007 04.2008 03.2009

The DeLaRue TCR Twin Safe Interface Architecture defines the mechanism by which a retail banking application can control a DeLaRue TCR Twin Safe. This document describes the Function Level Application Programming Interface (FLAPI), which are provided by the TSDLLWIN.DLL or TSDLLOS2.DLL and defines the software interface between the DeLaRue TCR Twin Safe API and an DeLaRue Twin Safe device. It is intended for use by application development personnel requiring definitions of functions that provide Twin Safe level services via the FLAPI. The FLAPI is supplied as a DLL plus C language header files and an import library. This document is intended to be used in conjunction (where appropriate) with the relevant documentation including:

27 June 2012

539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description

DeLaRue TCR Twin Safe documentation "Interface Description RS232 539.1625/02" and Functional description 539.1624/01.

The content of this document corresponds to the TSAPI Version 5.02.

539.1261/3 Version 5.02

27 June 2012


Table of Contents

TCR Twin Safe TSAPI Interface Description

1 INTRODUCTION..................................................................................................... 8 2 ABOUT THE FLAPI DEFINITION...........................................................................9 3 USING THE FLAPI...............................................................................................10

4 OVERVIEW .......................................................................................................................................10 5 SYNCHRONOUS AND ASYNCHRONOUS OPERATION.........................................................................................12 6 DELIVERY OF THE SOFTWARE PACKAGE....................................................................................................14 7 Contents of the delivery for Windows 32bits and OS/2 Warp4.............................................................14 8 RS232 or TCP/IP...................................................................................................................................14 9 CONFIGURATION OF THE TSAPI............................................................................................................17 Contents of the file handler.ini................................................................................................................17 10 Configuration of the TSServer: file TSServer.ini ................................................................................22

11 USING AND INTEGRATING THE TSAPI...........................................................23

12 SYSTEM REQUIREMENTS FOR THE TELLER WORKSTATIONS............................................................................23 13 Workstations communicating through RS232 ....................................................................................23 14 Workstations communicating through TCP/IP.....................................................................................23 15 TSAPI DLL AND HEADER FILES.........................................................................................................24 16 HOW TO INTEGRATE TSAPI INTO AN APPLICATION....................................................................................24 17 Integration on the Windows 32bits platform .......................................................................................24 18 Integration on the OS/2 Warp4 platform .............................................................................................25

19 FLAPI FUNCTIONS............................................................................................ 26
20 MINIMUM INSTRUCTION SET FUNCTIONS...................................................................................................29 21 Ping command - TSC_FPing...............................................................................................................29 22 Start deposit - TSC_FStartDeposit......................................................................................................32 23 Extended start deposit - TSC_FExtStartDeposit.................................................................................34 24 Deposit - TSC_FDeposit......................................................................................................................36 25 End deposit - TSC_FEndDeposit........................................................................................................38 26 Withdrawal - TSC_FWithdrawal..........................................................................................................39 27 Consultation - TSC_FConsult..............................................................................................................41 28 Cash balancing - TSC_FCashBalancing.............................................................................................42 29 Empty roll storage module - TSC_FEmptyRSM..................................................................................44 30 Empty roll storage module extended - TSC_FEmptyRSMExt.............................................................46 31 Get event text - TSC_ FGetEventText.................................................................................................48 32 System status - TSC_FSystemStatus.................................................................................................49 33 Self-test/ purge - TSC_FTest...............................................................................................................51 34 Get date and time - TSC_FGetDateAndTime......................................................................................52 35 Set date and time - TSC_FSetDateAndTime.......................................................................................53 36 Get machine type and capabilities- TSC_FGetTypeAndCapabilities.................................................54 37 Poll the output cassette status - TSC_FPollOutputCassette...............................................................55 38 TCR TWIN SAFE SPECIFIC FUNCTIONS...................................................................................................56 39 Initialize MCU - TSC_FInitMcu............................................................................................................56 40 Deposit arbitrary objects - TSC_FDepositObjects..............................................................................57 41 TCRTS deposit - TSC_ FExtDeposit...................................................................................................58 42 TCRTS deposit with note stack - TSC_ FExtDepositNoteStack.........................................................60 43 Deposit with reject flag - TSC_FDeposit2............................................................................................62 44 TCRTS deposit with reject flag - TSC_ FExtDeposit2.........................................................................64 45 TCRTS deposit with note stack and reject flag - TSC_ FExtDepositNoteStack2...............................66 46 TCRTS Rollback deposit - TSC_FRollbackDeposit............................................................................68 47 TCRTS withdrawal - TSC_FWithdrawal2............................................................................................70 48 TCRTS note bundle counting - TSC_FCounter...................................................................................72 49 Start summarized counting - TSC_FStartCounter...............................................................................74 50 TCRTS summarized counting - TSC_FCounterSummarized.............................................................76 51 TCRTS consultation - TSC_FConsultEx.............................................................................................79 52 TCRTS consultation - TSC_FConsultEx2...........................................................................................80 53 TCRTS SafeMaster consultation total TSC_FSMConsTotalEx.......................................................81
27 June 2012 539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description

54 TCRTS self-test/ purge - TSC_FTestExt.............................................................................................82 55 TCRTS self-test/ purge - TSC_FTestExt2...........................................................................................83 56 TCRTS poll the output cassette status - TSC_FPollOutputCassette2................................................84 57 Poll the input cassette status - TSC_FNoteInputQuery......................................................................85 58 TCRTS calculate a note mix TSC_FCalculateNotemix....................................................................86 59 TCRTS get input switch state TSC_FGetInputSwitchState..............................................................88 60 TCRTS get reservation state TSC_FGReservationState.................................................................89 61 Get all RSM assignments - FGetAllRSMAssignments........................................................................90 62 Set all RSM assignments - FSetAllRSMAssignments.........................................................................91 63 Get currency template serial number - TSC_FGetCurrencyTemplateSN..........................................92 64 Delete currency template - TSC_FDeleteCurrencyTemplate.............................................................93 65 Download currency template - TSC_FDownloadCurrencyTemplate..................................................94 66 Download parameter file - TSC_FDownloadParameterfile.................................................................95 67 Download software - TSC_FDownloadSoftware.................................................................................96 68 Download visibility file - TSC_FDownloadVisibility..............................................................................98 69 Download language file - TSC_FDownloadLanguage........................................................................99 70 Upload parameter file - TSC_FUploadParameterfile........................................................................100 71 Upload DLL trace file - TSC_FUploadDLLTrace...............................................................................102 72 Upload ODA file (all sections of the parameter file) - TSC_FUploadODAFile..................................103 73 Upload ODA file & Twin Safe log (last n lines) - TSC_FUploadODAFileAndLogXLines..................104 74 Upload ODA file & Twin Safe log (range) - TSC_FUploadODAFileAndLogRange..........................106 75 Upload ODA file & Twin Safe log (entire log) - TSC_FUploadODAFileAndLogAllLines...................108 76 TCRTS get daylight saving time - TSC_FGetDLSTimes..................................................................109 77 TCRTS set daylight saving time - TSC_FSetDLSTimes..................................................................110 78 TCRTS download generic data - TSC_FWriteData.........................................................................111 79 TCRTS upload generic data - TSC_FReadData..............................................................................113 80 TCRTS claim sync semaphore - TSC_FClaimSyncSemaphore......................................................115 81 TCRTS release sync semaphore - TSC_FReleaseSyncSemaphore..............................................116 82 TCR ES SPECIFIC FUNCTIONS...........................................................................................................117 83 Deposit arbitrary objects with given noteid - TSC_FDepositObjects2..............................................117 84 TCR ECO SPECIFIC FUNCTIONS........................................................................................................118 85 Get all RSM assignments TSC_FGetAllRSMAssignmentsEco.....................................................118 86 Set all RSM assignments TSC_FSetAllRSMAssignmentsEco......................................................119 87 TCR ES AND ECO SPECIFIC FUNCTIONS............................................................................................120 88 Get RSM note stack details TSC_FGetRSMNoteStackDetails......................................................120 89 TCR ERF COMPATIBLE..................................................................................................................121 90 Get ERF mode TSC_FGetErfMode................................................................................................121 91 Set ERF mode TSC_FSetErfMode.................................................................................................122 92 Deposit TSC_FDepositErf (general purpose with/without amount, note stack, reject flag and ERF flag)........................123 93 Deposit arbitrary objects TSC_FDepositObjectsErf (general purpose with/without assigned note Id and ERF flag).............................................125 94 Read one note (single note separation) - TSC_FReadOneNote......................................................126 95 STANDARD INSTRUCTION SET FUNCTIONS..............................................................................................129 96 Open safe door - TSC_FOpenDoor..................................................................................................129 97 Copy data files TSC_FCopyDataFiles............................................................................................130 98 SafeMaster consultation total TSC_FSMConsTotal.......................................................................131 99 SafeMaster consultation currency code - TSC_FSMConsCurr........................................................132 100 SafeMaster cancel movements - TSC_FSMCancelMovements.....................................................134 101 SafeMaster unlock - TSC_FSMUnlock............................................................................................135 102 SafeMaster open drawer - TSC_FSMOpenDrawer........................................................................136 103 SafeMaster deposit - TSC_FSMDeposit.........................................................................................137 104 SafeMaster withdrawal - TSC_FSMWithdrawal..............................................................................138 105 STATISTICS FUNCTIONS..................................................................................................................139 106 Clear statistics - TSC_FClearStatistics...........................................................................................140 107 Get statistics - TSC_FGetStatistics.................................................................................................141 108 TSAPI ADMINISTRATIVE FUNCTIONS..................................................................................................142 109 Change logging level - TSC_FChangeLoggingLevel......................................................................143 110 Set new log file name - TSC_FNewLogFileName...........................................................................144 111 Add text to log - TSC_FAddToLog...................................................................................................145 112 Get DLL version - TSC_FGetVersion..............................................................................................146 113 Get TSServer version - TSC_FGetServerVersion..........................................................................147 114 Get alarm flag - TSC_FGetAlarmFlag.............................................................................................148 4
539.1261/3 Version 5.02 27 June 2012

TCR Twin Safe TSAPI Interface Description

115 Shutdown server - TSC_FShutdownServer....................................................................................149 116 Reinitialize the TSAPI - TSC_FReInitDLL.......................................................................................150 117 Set DLL configuration - TSC_FSetDLLConfig.................................................................................151 118 Get DLL configuration - TSC_FGetDLLConfig................................................................................152 119 TWIN SAFE LOGGING FUNCTIONS ......................................................................................................153 120 Get information about the TCR Twin Safe log - TSC_FGetLogInfo................................................153 121 Add a TCR Twin Safe log entry - TSC_FLog..................................................................................155 122 Get a TCR Twin Safe log entry (TwinSafe format) - TSC_FGetLogLine........................................156 123 Get a TCR Twin Safe log entry (TCR Twin Safe format) - TSC_FGetLogLineEx..........................157 124 Upload TCR Twin Safe log (last n lines) - TSC_FUploadLogXLines..............................................158 125 Upload TCR Twin Safe log (range) - TSC_FUploadLogRange......................................................159 126 Upload TCR Twin Safe log (entire log) - TSC_FUploadLogAllLines..............................................161 127 ASYNCHRONOUS FUNCTIONS............................................................................................................162 128 Asynchronous get response - TSC_FAGetResponse....................................................................163 129 Asynchronous deposit - TSC_FADeposit........................................................................................165 130 Asynchronous withdrawal - TSC_FAWithdrawal............................................................................166 131 Asynchronous cash balancing - TSC_FACashBalancing...............................................................167 132 Asynchronous empty RSM - TSC_FAEmptyRSM..........................................................................169 133 Asynchronous system status - TSC_FASystemStatus...................................................................170 134 Asynchronous self-test/ purge - TSC_FATest.................................................................................172 135 Asynchronous TCRTS self-test/ purge - TSC_FATestExt..............................................................173 136 Asynchronous copy data files - FACopyDataFiles..........................................................................174 137 Asynchronous SM unlock - TSC_FASMUnlock..............................................................................175 138 Asynchronous SM open drawer - TSC_FASMOpenDrawer...........................................................176 139 ASYNCHRONOUS FUNCTIONS (TCR ECO SPECIFIC)................................................................................177 140 AUTHORISATION FUNCTIONS............................................................................................................178 141 Add user - TSC_FAddUser..............................................................................................................178 142 Delete user - TSC_FDeleteUser.....................................................................................................179 143 Get user - TSC_FGet User..............................................................................................................180 144 Validate user - TSC_FValidateUser................................................................................................181 145 CURRENCY DATA..........................................................................................................................182 146 Get currency data - TSC_FGetCurrencyData.................................................................................182 147 Get next currency data - TSC_FGetNextCurrencyData.................................................................183 148 Add currency data - TSC_FAddCurrencyData................................................................................184 149 Update currency data - TSC_FUpdateCurrencyData.....................................................................185 150 Delete currency data - TSC_FDeleteCurrencyData.......................................................................186 151 DELAY TIMES..............................................................................................................................187 152 Get withdrawal delay - TSC_FGetWithdrawalDelay.......................................................................187 153 Get num delay classes - TSC_FGetNumDelayClasses.................................................................189 154 Set num delay classes - TSC_FSetNumDelayClasses..................................................................190 155 Get delay class params - TSC_FGetDelayClassParams...............................................................191 156 Set delay class params - TSC_FSetDelayClassParams................................................................192 157 SYSTEM LANGUAGE .......................................................................................................................193 158 Get system language - TSC_FGetSystemLanguage......................................................................193 159 Set system language - TSC_FSetSystemLanguage.......................................................................194 160 TCRTS get system language - TSC_FGetLanguage.....................................................................195 161 SECURITY...................................................................................................................................196 162 Get alarm factor - TSC_FGetAlarmFactor.......................................................................................196 163 Set alarm factor - TSC_FSetAlarmFactor........................................................................................197 164 Get printer control - TSC_FGetPrinterControl.................................................................................198 165 Set printer control - TSC_FSetPrinterControl..................................................................................199 166 Get door unlock delay - TSC_FGetDoorUnlockDelay....................................................................200 167 Set door unlock delay - TSC_FSetDoorUnlockDelay.....................................................................201 168 Get door unlock interval - TSC_FGetDoorUnlockInterval...............................................................202 169 Set door unlock interval - TSC_FSetDoorUnlockInterval................................................................203 170 Get SafeMaster unlock delay - TSC_FGetSMUnlockDelay............................................................204 171 Set SafeMaster unlock delay - TSC_FSetSMUnlockDelay.............................................................205 172 Get SafeMaster unlock interval - TSC_FGetSMUnlockInterval......................................................206 173 Set SafeMaster unlock interval - TSC_FSetSMUnlockInterval.......................................................207 174 Get SafeMaster reaction time - TSC_FGetSMReactionTime.........................................................208 175 Set SafeMaster reaction time - TSC_FSetSMReactionTime..........................................................209 176 Get SafeMaster open interval - TSC_FGetSMOpenInterval...........................................................210 177 Set SafeMaster open interval - TSC_FSetSMOpenInterval............................................................211
27 June 2012 539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description

178 OPERATING HOURS.......................................................................................................................212 179 Get operating hours TSC_FGetOpHours.....................................................................................212 180 Set operating hours TSC_FSetOpHours......................................................................................214 181 Get periodic hours - TSC_FGetPeriodicHours................................................................................215 182 Set periodic hours - TSC_FSetPeriodicHours.................................................................................216 183 Get aperiodic hours - TSC_FGetAperiodicHours............................................................................217 184 Get next aperiodic hours - TSC_FGetNextAperiodicHours............................................................219 185 Add aperiodic hours - TSC_FAddAperiodicHours..........................................................................221 186 Set aperiodic hours - TSC_FSetAperiodicHours............................................................................222 187 Delete aperiodic hours - TSC_FDelAperiodicHours.......................................................................223 188 ROLL STORAGE DATA....................................................................................................................224 189 Get roll storage data - TSC_FGetRollStorageData.........................................................................224 190 Set roll storage data - TSC_FSetRollStorageData..........................................................................226 191 Get roll storage low limit - TSC_FGetRollStorageLowLimit............................................................227 192 Set roll storage low limit - TSC_FSetRollStorageLowLimit.............................................................228 193 Get roll storage upper limit - TSC_FGetRollStorageUpperLimit.....................................................229 194 Set roll storage upper limit - TSC_FSetRollStorageUpperLimit......................................................230 195 SAFEMASTER DATA......................................................................................................................231 196 Get number of SafeMaster drawers - TSC_FGetNumberOfSMDrawers........................................231 197 Init SafeMaster data - TSC_FInitSMData........................................................................................232 198 Delete SafeMaster data - TSC_FDelSMData..................................................................................233 199 Get SafeMaster drawer delay - TSC_FGetSMDrawerDelay..........................................................234 200 Set SafeMaster drawer delay - TSC_FSetSMDrawerDelay...........................................................236 201 Get SafeMaster drawer currency data - TSC_FGetSMDrawerCurrData.......................................238 202 Add SafeMaster drawer currency data - TSC_FAddSMDrawerCurrData......................................240 203 Update SafeMaster drawer currency data - TSC_FUpdateSMDrawerCurrData............................242 204 Delete SafeMaster drawer currency data - TSC_FDeleteSMDrawerCurrData..............................243

205 DATA TYPES AND STRUCTURES................................................................244

206 CONSTANTS AND ENUMERATED DATA TYPES.........................................................................................244 207 TSC_DENOMINATIONS_LIST................................................................................................253 208 TSC_AMOUNT_LIST..............................................................................................................253 209 TSC_ DISPENSEDATA..................................................................................................................253 210 TSC_ VERSION..........................................................................................................................254 211 TSC_TELLERINFO.......................................................................................................................254 212 TSC_BASICEVENT DATA...............................................................................................................256 213 TSC_CASHBALANCERESPONSE.....................................................................................................257 214 TSC_EMPTYRSMP ARAMS...........................................................................................................257 215 TSC_EMPTYRSMRESPONSE........................................................................................................258 216 TSC_EMPTYRSMEXT RESPONSE...................................................................................................258 217 ASCOM_DATE , ASCOM_TIME AND ASCOM_DATE TIME ..............................................................259 218 TSC_SYSTEM STATUS RESPONSE....................................................................................................261 219 TSC_CONSULT RESPONSE.............................................................................................................263 220 TSC_OPERATINGTIMES................................................................................................................264 221 TSC_STATISTIC TYPES.................................................................................................................265 222 TSC_STATISTIC VALUES...............................................................................................................265 223 TSC_SMCONSULTDRAWERDATA...................................................................................................267 224 TSC_SMCONSULTRESPONSE........................................................................................................267 225 TSC_SM_CURRDATA.................................................................................................................268 226 TSC_ASYNCRESPONSEDATA.........................................................................................................268 227 ASCOMUSERLIST.....................................................................................................................269 228 TSC_NEWTELLERINFO.................................................................................................................269 229 TSC_CURRENCYDATA.................................................................................................................270 230 TSCDELAYCLASS PARAMS............................................................................................................270 231 TSCROLLSTORAGE DATA..............................................................................................................271 232 TSC_SMDRAWERCURRDATA.......................................................................................................271 233 TSC_DEPOSIT.......................................................................................................................272 234 TSC_DEPOSIT_INPUT...........................................................................................................273 235 TSC_DEPOSIT_OUTPUT.......................................................................................................274 236 TSC_DEPOSIT_OBJECT_INPUT...........................................................................................276 237 TSC_DEPOSIT_OBJECT_OUTPUT.......................................................................................278 238 TSC_ERF_NOTE_INFO..........................................................................................................279 239 TSC_ERFMODE........................................................................................................................282 6
539.1261/3 Version 5.02 27 June 2012

TCR Twin Safe TSAPI Interface Description

240 TSC_TYPEANDCAPABILITIES .........................................................................................................283 241 TSC_RSM_ASSIGN................................................................................................................285 242 TSC_RSM_ASSIGN_2............................................................................................................286 243 TSC_RSM_ASSIGNMENT......................................................................................................287 244 TSC_RSM_ASSIGNMENT_LIST.............................................................................................287 245 TSC_RSM_ECO_ASSIGNMENT.............................................................................................289 246 TSC_RSM_ECO_ASSIGNMENT_LIST...................................................................................289 247 TSC_RSM_NOTESTACK_DETAILS.......................................................................................291 248 TSC_RSM_NOTESTACK_DETAILS_LIST..............................................................................291 249 TSC_DOWNLOAD_SW_INFO................................................................................................293 250 TSC_DOWNLOAD_LANGUAGE_INFO..................................................................................293 251 TSC_UPLOAD_PARAMETERFILE_INFO...............................................................................294 252 TSC_UPLOAD_PARAMETER................................................................................................294 253 TSC_TSCOUNTERRESPONSE........................................................................................................296 254 TSC_TSCOUNTERNOTEDATA..............................................................................................296 255 TSC_RESERVATIONDATA.............................................................................................................298 256 TSC_NOTE STACK......................................................................................................................298 257 TSC_NOTE STACKDATA...............................................................................................................299 258 TSC_LOGINFO...........................................................................................................................299 259 TSCTSLANGUAGE................................................................................................................300 260 TSC_TSDLSTDATA................................................................................................................300 261 TSC_TSDLSTRESPONSE...........................................................................................................301 262 TSC_COMMCONFIG.....................................................................................................................301 263 TSC_DLLCONFIG......................................................................................................................302

264 STATUS CODES............................................................................................304

27 June 2012

539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description

INTRODUCTION
The DeLaRue TCR Twin Safe API is a software component that facilitates the integration of the DeLaRue TCR Twin Safe device into retail banking branch environments without requiring the user to address issues concerning low-level serial communications or TCP/IP communication as managing the TCR Twin Safe message protocol. This is achieved by providing a Function Level Application Programming Interface (FLAPI) which delivers the full functionality of the TCR Twin Safe Standard Integration Set in a manner that is easy and efficient for application development personnel to use. This FLAPI allows users to create powerful TCR Twin Safe applications that exploit all the features of the TCR Twin Safe device in an easy and efficient manner.

539.1261/3 Version 5.02

27 June 2012


2 ABOUT THE FLAPI DEFINITION

TCR Twin Safe TSAPI Interface Description

The FLAPI definition provides a comprehensive description of all the services available as application function calls via the FLAPI. It therefore is the definitive reference for specific information relating to the development of applications written in accordance with the FLAPI. Each function call is described in terms of the following: function name input parameters output parameters return values additional information cross-references

Also included are a list of important FLAPI data types and structures that are often utilized as calling parameters to the FLAPI functions.

27 June 2012

539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description

3
4

USING THE FLAPI

Overview The FLAPI is implemented as a Dynamic Link Library-type software layer (DLL) currently available for Windows 32bits or OS/2 Warp4 platforms. This DLL allows client applications to utilize FLAPI services by calling appropriate functions contained within the TSDLLWin or the TSDLLOS2.. The TSAPI manages the communication with the TCR TwinSafe directly on the RS232 native protocol or through TCP/IP socket if the TSServer is available. This process is described in the following diagram for the RS232 communication:

Client Application FLAPI TSAPI RS-232 TCR Twin Safe

Figure 3.1a - How the FLAPI services are used by a calling application

10

539.1261/3 Version 5.02

27 June 2012

Teller workstation
Windows 32bits or OS/2 Warp4

TCR Twin Safe TSAPI Interface Description

The integration of the TCR Twin Safe can be considerably enhanced by connecting each client workstations on the LAN and connect them to the TCR Twin Safe through the TSServer. TSAPI In this case, the communication process is performed on the TCP/IP protocol: C Client Application
Function processingMarshalling

LAN IP Socket

LAN PC
Windows 2000

TSServer

MarshallingFunction dispatchingRS232 Communication

C COM1

RS232COM2

TCR Twin Safe

By using the provided services, the calling application need not be concerned with managing the low level TCR TwinSafe message protocol or be aware of low level TCR TwinSafe commands. This is all performed by the TSAPI. The calling application need only be aware of the functions provided by the FLAPI. The caller supplies appropriate parameters and receives (and makes use of) any returned values.

27 June 2012

539.1261/03 DRAFT Version 5.02

11

TCR Twin Safe TSAPI Interface Description 5 Synchronous and asynchronous operation

The FLAPI allows calling applications to communicate in either a synchronous or asynchronous fashion with the TSDLLWIN or TSDLLOS2. Synchronous operation is when the function return occurs only after the TCR Twin Safe device itself has returned a response message to the TSAPI. During that time, the calling application will be blocked. This is described as follows:

client application

TCR TwinSafe

F function call L A P I function return

TSAPI

command ACK

response ACK

Figure 3.2a - Synchronous operation

12

539.1261/3 Version 5.02

27 June 2012

TCR Twin Safe TSAPI Interface Description Asynchronous operation is more complicated in that it is a two step process. The first step involves the initial function call to the TSAPI. This function call return occurs immediately. In the function call the TSAPI starts a new thread, which then communicates with the TCR Twin Safe device. A second query type function call allows the calling application to determine the actual result of the first function call. This second function call is issued asynchronously by the calling application. If the call is made before the TCR Twin Safe has responded to the TSAPI, then the return will indicate that this is the case. Otherwise, the call will return with the result. This is described as follows:

client application

TCR Twin Safe

function call

F function call L function return TSAPI A P function call I function return

command ACK

response ACK

query call

Figure 3.2b - Asynchronous operation

27 June 2012

539.1261/03 DRAFT Version 5.02

13

TCR Twin Safe TSAPI Interface Description 6 Delivery of the software package

The TSAPI is supplied as a DLL and an import file. Some include files for the language C are also provided to facilitate its integration in most of the C development tools. The files are supplied in the form of a zip file, indicating the version of the package. 7 Contents of the delivery for Windows 32bits and OS/2 Warp4 The package name is: TSDLLxxx_01_00.zip for both the Windows 32 bits version as well as the OS/2 Warp4 version. It includes the files: - TSDLLWin.dll - TSDLLWin.lib 8 TSDLLWin_VB.dll TSDLLWin_VB.lib TSAPIWin.dll TSAPIWin.lib TSDLLOS2.dll TSDLLOS2.lib TSExt.h TSType.h TSCons.h Handler.ini Readme.txt the dynamic link library for Windows 95/98/NT/2K (32 bits) to allow a static importation of the library in a Windows environement (32 bits) the dynamic link library for Windows 95/98/NT/2K for Visual Basic usage (exported functions dddeclared as _stdcall) to allow a static importation of the library in a Windows environement for Visual Basic usage (exported functions dddeclared as _stdcall) the dynamic link library for Windows 95/98/NT/2K (16bits) to allow a static importation of the library in a Windows environement (16 bits) the dynamic link library for OS/2 Warp4 to allow a static importation of the library in an OS/2 environement the declaration of all functions including the types and structures declaration common constants and definitions example of the TSAPI configuration file indicating the last changes and the state of the version

RS232 or TCP/IP The TSAPI provides the same DLL for both communication principle: RS232 or TCP/IP. The selection of one of the protocol is done through a parameter in the configuration file of the TSAPI: handler.ini. (See also chapter 3.4 ) The selection of the RS232 protocol is performed by the following entry in Handler.ini : [TwinSafe] Protocol = RS The selection of the TCP/IP protocol is performed by the following entry in Handler.ini : [TwinSafe] Protocol = IP Without specific entry, the RS protocol will be selected by default.

14

539.1261/3 Version 5.02

27 June 2012


RS232 configuration
Teller A workstation

TCR Twin Safe TSAPI Interface Description

Teller B workstation

Left side

Right side

RS 232 Link

RS 232 Link

TCR Twin Safe

The teller application, integrating the TSDLL, runs on two different teller workstations. Each station is connected to one of the RS232 links available on the TCR Twin Safe. To work simultaneously on both sides of the TCR Twin Safe, each workstation has to specify some information about the side and the user name. This information must be supplied with each function call in the structure TellerInfo and must be mandatory different from one station to the other.

27 June 2012

539.1261/03 DRAFT Version 5.02

15

TCR Twin Safe TSAPI Interface Description TCP/IP configuration

Teller B workstation Teller C workstation Administrator

remote or local

Teller A workstation

Left side

Right side

Right side

Left side

Branch LAN
TCP/IP

TCR Twin Safe with TSServer on the embedded PC

2X RS232

Branch server

The teller application, integrating the TSDLL communicating over TCP/IP, runs on several teller workstations. Each station is connected to the LAN of the branch. An administrator PC can be added to fulfill configuration or teller administration tasks on the TCR Twin Safe. Each workstation has to specify some information about the side and the user name. This information must be supplied with each function call in the structure TellerInfo. In the LAN configuration, the stations having different sides will be able to work simultaneously. If a transaction is running on one side, the attempt to initiate a transaction on the same side from another station will be rejected with a ERR_BUSY information in the return code of the function. (see section 264 Status Codes)

16

539.1261/3 Version 5.02

27 June 2012


9 Configuration of the TSAPI

TCR Twin Safe TSAPI Interface Description

The TSAPI uses environment variables or entries in a .ini file to set certain parameter values. Dependent on the operating system the environment variables are set up in the file CONFIG.SYS (OS/2) or in Autoexec.bat (Windows 95/98) or up using the Windows NT-2000 Control Panel within System option Tab: Environment, Section: User Variables. The .ini file setup can either be a default one or can be created specifically for different users. Except for a few cases described below, the environment variables will always over-ride those setting made in a .ini file. The DLL will pick up the settings automatically and modify its behavior appropriately. In the following all environment variables known by the TSDLL are presented Environment Variable TSC_CONFIG_FILE Definition and Example Defines the location of the .ini file to be used for the TSDLLWin setup. TSC_CONFIG_FILE=c:\DeLaRue\TCRTS\tsdllwin.ini Defines the trace level for the TSDLL. Level 0 means no trace, the log file will not be created. Level 1 writes only statistical information and text send by the function TSC_Flog(). Level 4 means very detailed diagnostics for DeLaRue technical support personnel. TSC_TRACE = 0 Defines the location of the trace file (in case trace is enabled). TSC_TRACE_FILE = c:\temp\logfile.txt If no configuration file is specified in the environment variables, the TSAPI uses the default file handler.ini located in the directory of the DLL or in the directory of the application. Contents of the file handler.ini In the following all sections and settings for the .ini file are presented: Section / Variable [TwinSafe] Protocol Definition and Example Defines the communication protocol used by the TSAPI: RS232 or TCP/IP Protocol=RS or Protocol=IP Defines the trace level for the TSAPI. Level 0 means no trace, the log file will not be created. Level 1 writes only statistical information and text send by the function TSC_Flog(). Level 4 means very detailed diagnostics for DeLaRue technical support personnel. This entry exceptionally overwrite the environment variable setting. TwinSafeTrace=0 Defines the location of the trace file (in case trace is enabled).
539.1261/03 DRAFT Version 5.02

TSC_TRACE

TSC_TRACE_FILE

TwinSafeTrace ! This entry overwrites setting of environment variable: TSC_TRACE

TwinSafeTraceFile

27 June 2012

17

TCR Twin Safe TSAPI Interface Description ! This entry overwrites setting of environment variable: TSC_TRACE_FILE TraceFileSizeKB This entry exceptionally overwrite the environment variable setting. TwinSafeTraceFile=c:\temp\logfile.txt Defines the maximum size of the trace file in kBytes. Old entries are deleted from the file to keep its size limited. If this variable is 0 the size of the trace file is not limited. Default setting is 1024. TraceFileSizeKB=1024 Enables (=Y) or disables (=N) the TSAPI debug switch. If debug is enabled the FLAPI just returns faked TCRTS answers, hence, an offline testing is possible. Default setting is N. TwinSafeDebug=N If this flag is enabled (=Y) the TSAPI uses only one shared output buffer for all users for asynchronous function calls. If it is disabled (=N) each user gets assigned its own output buffer. Default setting is N. AllowOverwriteReply=N Enables (=Y) or disables (=N) the summarization of RSM with the same denomination assigned. This feature is used in deposit, withdrawal, empty RSM and consultation functions. Default setting is N. SummarizeDenominations=N Enables (=Y) or disables (=N) that TSAPI closes leaks that may occur in case of RSM summarization. The RSMs at the end of the list are marked as not existing/ used in this case. This variable is ignored if SummarizeDenominations is N. Default setting is N. PackDenominations=N If this parameter is set to N TSAPI closes the COM port after each command. This makes the application slower because the COM port must be reopened for each command, but it enables other applications to access the COM port and communicate with the Twin Safe. This may be useful for monitoring. Default setting is Y. KeepCommOpen=Y [TSConnection1] CommPort Defines the RS232 CommPort to be used for physical connection 1. CommPort=1 Defines the bit rate to be used for physical connection 1 BitRate=0 Defines the maximum time in ms to wait for an answer of the TCRTS for physical connection 1. TranTimeout =900000 Defines the maximum time in ms to wait for an ACK from the TCRTSfor physical connection 1. AckTimeout =2500 Defines the maximum time in ms to wait if a second

TwinSafeDebug

AllowOverwriteReply

SummarizeDenominations

PackDenominations

KeepCommOpen

BitRate

TranTimeout

AckTimeout

ProcWaitTimeout 18

539.1261/3 Version 5.02

27 June 2012


SharePort variable.

TCR Twin Safe TSAPI Interface Description instance of the TSAPI (or a related application) blocks the CommPort for physical connection 1. Compare also ProcWaitTimeout =900000 Defines the number of retries before a communication request for physical connection 1 is aborted. NumRetries =3 If this flag is enabled (=1) the TSAPI does not dispatch windows messages while waiting for an answer from the TCRTS at physical connection 1. If it is disabled (=0) message dispatching is supported. This is not relevant for asynchronous communication, since there the communication process runs in its own thread. DoBlock =1 If this flag is enabled (=1) the TSAPI allows other instances of the TSAPI (or a related applications) to share the same CommPort used for physical connection 1. If the flag is disabled (=0) all attempts done by other instances of TSAPI (or related applications) to open the same port will be rejected. Shared access of two or more instances of TSAPI for the same CommPort is protected at FLAPI level. Shared access of TSAPI and related applications is protected at TCRTS protocol level.
Compare also ProcWaitTimeout variable.

NumRetries

DoBlock

SharePort

Use4CashierSide

SharePort =1 Defines, for which cashier side this physical connection shall be invoked. This feature is nondominant. This means, if there is a FLAPI request for the left cashier side, but the setup just defines a connection for cashier side right (Use4CashierSide=R), the request will nevertheless be handled via the left connection. Use4CashierSide =L Defines, for which station address this physical connection shall be invoked. This feature is nondominant. This means, if there is a FLAPI request for station address 1234, but the setup just defines a connection for station address abcd (Use4StationAdr =abcd), the request will nevertheless be handled via this connection. Use4CashierSide has higher priority than Use4StationAdr. Use4StationAdr =wxyz Defines a delay time in ms after each command. This may be useful to avoid flooding the Twin Safe with commands in a very fast sequence. The default is 0. WaitAfterCommand=0 This parameter defines the factor for the timeout delay for receiving one byte from the COM port. You may want to increase this value if the teller application is running in a terminal server environment like Citrix MetaFrame. In this case the communication may be slow and causes timeout while receiving the answer telegram. The default is 3.
539.1261/03 DRAFT Version 5.02

Use4StationAdr

WaitAfterCommand

GuardTolerance

27 June 2012

19

TCR Twin Safe TSAPI Interface Description

GuardTolerance=3 [TSConnection2] Same variables as defines for [TSConnection1], but for physical connection number 2. Note: Physical connection number 2 is not necessarily equal to CommPort 2!

If the TCP/IP Protocol is selected, through the variable Protocol=IP, Handler.ini must mandatory include the following information: Section / Variable [Client] IPAddr Definition and Example Indicate the IP address of the TSServer with which the application is communicating. This entry must absolutely match the IP address of the TSServer. You may also specifiy a host name instead of an IP address. IPAddr =10.20.0.200 IP port number. Do not use reserved port such as 8080: http. This entry must absolutely match the port number that is defined in TSServer.INI. Port =2000 Application Id if there are more than one instance of the TSAPI dll on the same workstation (define a unique Id for each application). AppID=1

Port

AppID

20

539.1261/3 Version 5.02

27 June 2012


Example of .ini file entries:

TCR Twin Safe TSAPI Interface Description

[TwinSafe] Protocol=IP TwinSafeTrace=4 TwinSafeTraceFile=C:\DeLaRue\TCRTwinSafe\Trace.log [TSConnection1] CommPort=1 BitRate=57600 Use4CashierSide=L [TSConnection2] CommPort=2 BitRate=57600 Use4CashierSide=R [Client] IPAddr = 10.20.0.200 Port = 3000 AppID = 1 ClientTrace=1

27 June 2012

539.1261/03 DRAFT Version 5.02

21

TCR Twin Safe TSAPI Interface Description

If there hasnt been defined any connection, neither using environment variables nor using the .ini file, TSAPI will start-up with the following default settings: 10 Protocol=RS CommPort=1 BitRate=9600 TranTimeout=900000 AckTimeout=10000 ProcWaitTimeout=900000 NumRetries=3 DoBlock=1 (True) SharePort=1 (True) Use4CashierSide = L Use4StationAdr = <ignored> AppID = 0 ClientTrace=0 Configuration of the TSServer: file TSServer.ini The file TSServer.ini is placed on the LANPC harddisk, in the working directory of the TSServer : C:\Program files\De La Rue\TSServer. This file allows the indication of the IP Port which should match the configuration of the clients. The file TSServer.ini must mandatory include the following information: Section / Variable [Client] Port Definition and Example IP port Do not use reserved port such as 8080: http Port =2000 [Beep] Time Duration time (in ms) of a beep for every incoming message. Allowed range is 0 (beep is off) to 100 ms. Beep=20

Example of TSServer.ini file entries: [Client] Port =2000 [Beep] Time=20

22

539.1261/3 Version 5.02

27 June 2012


11
12 13

TCR Twin Safe TSAPI Interface Description

USING AND INTEGRATING THE TSAPI

System requirements for the teller workstations Workstations communicating through RS232 Either for Windows 32 bits as for OS/2, the PC must have a RS232 Com port available to communicate with the TCR Twin Safe. If two different instances of the bank application are working with the same TSDLL, then a second Com port is required.

14

Workstations communicating through TCP/IP This solution is based on IP socket, so a network adapter and the TCP/IP protocol must be installed on the workstation. The IP addresses of the client and of the TCR Twin Safe server must be in the same sub net mask or you must use a router. Example: Sub net mask: 255.255.255.0 TSServer : 192.25.32.110 Client workstation 1: 192.25.32.112 router not required Client workstation 2: 34.165.28.12 request a router Windows 32bits platform Windows NT 4 minimum SP5 or Windows 2000 SP1 or Windows 98 SE or Windows 95 Network adapter with TCP/IP protocol installed OS/2 Warp4 TCP/IP sockets must be installed Minimum OS/2 FixPack 6 (Syslevel XRxM006) IP stack: IBM MPTS LAN Adapter and Protocol Support FixPak WR08610 (or better) (IBM ftp server) DLLs for VAC++ 4.0: CPPRMI40.DLL CPPRBI40.DLL CPPOBI40.DLL CPPOUI40.DLL CPPZM40I.DLL CPPOGI40.DLL

27 June 2012

539.1261/03 DRAFT Version 5.02

23

TCR Twin Safe TSAPI Interface Description 15 TSAPI DLL and header files

The DeLaRue TSAPI product consists of a Dynamic Link Library (DLL), a Microsoft Visual C++ or IBM Visual Age compatible Import Library (LIB) and several C-language header files. The TSAPI provides definitions for various structures, types and constants that are used within individual function call definitions. The definitions are supplied in C header files as part of the DeLaRue TCR Twin Safe TSAPI product. The following header files are available: - TSExt.h the declaration of all functions - TSType.h including the types and structures declaration - TSCons.h common constants and definitions TSExt.h contains all interface function definitions. It already includes the file TSType.h TSType.h contains type and constant definitions needed for the TSDLLxxx FLAPI. It already includes the file TSCons.h TSCons.h defines some basic constants used by the TSDLLxxx An application should explicitly include the header file TSExt.h only.

16 17

How to integrate TSAPI into an application Integration on the Windows 32bits platform The TSAPI can easily be integrated into a software project using the Microsoft Visual C++ compatible import library (TSDLLWin.lib). This may be linked with the calling application or the DLL may be loaded explicitly from within the calling application in the normal manner. In either case, the DLL file TSDLLWin.dll must either be located in the same directory as the application program or in the system directory or in a directory specified in the PATH environment variable. By including the header file TSExt.h, all FLAPI definitions are directly available for a C/C++ application. If you intent to use the Microsoft Visual C++ compiler you should define the following compiler symbol before including the file TSExt.h: #define _MSVISUALCPP_

The DLLs interface has been compiled using the C-style calling convention cdecl and the natural structure member alignment of Windows 32bits: 8 bytes pointer.

24

539.1261/3 Version 5.02

27 June 2012


18 Integration on the OS/2 Warp4 platform

TCR Twin Safe TSAPI Interface Description

The TSAPI can easily be integrated into a software project using the import library (TSDLLOS2.lib). This may be linked with the calling application or the DLL may be loaded explicitly from within the calling application in the normal manner. In either case, the DLL file TSDLLOS2.dll must either be located in the same directory as the application program or in the system directory or in a directory specified by the PATH variable of the config.sys file. By including the header file TSExt.h, all FLAPI definitions are directly available for a C/C++ application. Because the Include files are common for the different operating systems, the constant OS2 has to be defined before their inclusion. #define OS2

27 June 2012

539.1261/03 DRAFT Version 5.02

25

TCR Twin Safe TSAPI Interface Description

19

FLAPI FUNCTIONS
This section provides a complete listing of all the FLAPI function calls. All parameters to the functions are passed by address unless they are integers. The functions always return a status value, which is duplicated in a field of one of these data structures. Most function calls are synchronous, i.e. they wait for the TCR Twin Safe to complete the requested operation before control is returned to the calling application. Certain TCR Twin Safe operations can take a variable length of time before they complete. These slower functions include all those where notes are processed and the TCR Twin Safe configuration and download routines. With the current Version of TSAPI Synchronous and Asynchronous variants are provided for all these functions, which are included in the minimum and standard instruction set (compare section below). Hence, the calling application can choose whether to wait for the response or to retain control and to obtain the response details using a further function call once the TCR Twin Safe operation has completed. The function return code will be TSC_SUCCESS unless there has been an error in the parameters or any other communication or protocol error. TCR Twin Safe errors and warnings are not reflected in this value. In the following listing of the FLAPI function calls, there are defined possible return values for the given functions (e.g. TSC_SUCCESS). In addition to the specified values any other communication or protocol error can be return. A full list of these error types is defined in section 264 Status Codes. Most of the FLAPI functions calls are compatible to those provided by the older NCI Twin Safe DLL Handler. For some few functions, modifications in the function call definition had to be made, in order to adapt to new TCR Twin Safe features. If a call is not compatible to the NCI Twin-Safe DLL Handler you will find a note in the function call descriptions (Section: Additional information). In addition, for any specifier (#defines, function names and struct type names) the abbreviation NCI_ has been changed to TSC_ (TwinSafeCommunication). The descriptions of the FLAPI function calls are grouped into several categories: Statistics The DLL maintains volatile statistics in addition to the non-volatile information held by the TCR Twin Safe. These volatile statistics can be retrieved and reset using the FLAPI and are not retained after the application program terminates. Logging The TSAPI supports communication logging, which can be used for application debugging or for diagnostics within DeLaRue. The name of the text file in which all logging information is recorded can be defined. The FLAPI defaults to no logging. Minimum Instruction Set These instructions include the commands to deposit, to count and to dispense notes; to empty RSMs; to run TCR Twin Safe internal tests; to determine the total contents of the TCR Twin Safe and to set the date and time. Added to this set are a Ping function to verify if the communication with the TCR Twin Safe is consistent and a user validation function to implement a login procedure.

26

539.1261/3 Version 5.02

27 June 2012


Standard Instruction Set

TCR Twin Safe TSAPI Interface Description

These instructions include the commands to control the SafeMaster drawers (if fitted and configured), to determine or over-ride the operating hours for a particular date and to control the TCR Twin Safe's electrically operated door lock. Furthermore this command-set contains functions to access the TCR Twin Safe feature Object- and Currency-RSM. Asynchronous Variants Some of the Minimum and Standard instructions have asynchronous equivalents. After calling any of the asynchronous functions within the API, the calling application can either wait for a notification that the response is available or else it must repeatedly poll the FLAPI until the response is available. Extended Command Set Authorization These API calls allow an application to check whether a user ID, PIN and user level are known to the TCR Twin Safe. Calls are provided to validate, add, update and remove user definitions. Currency data These API calls allow an application to maintain the TCR Twin Safe database of currencies. Delay times These API calls allow an application to maintain the TCR Twin Safe database of variable delays, associated with dispensing notes from the Roll Storage Modules. System language These API calls allow an application to determine and alter the language in which the TCR Twin Safe logs events. Security These API calls allow an application to maintain the TCR Twin Safe settings for: the alarm factor (the amount by which all other delays are multiplied if the TCR Twin Safe's internal alarm relay is enabled); the TCR Twin Safe printer control flag; the TCR Twin Safe door unlocking delay; the TCR Twin Safe door unlocking time (the period during which the solenoid lock stays released); the SafeMaster unlocking delay (in a sequence, the delay before which the first SafeMaster drawer will be unlocked); the SafeMaster opening interval (in a sequence, the interval after one drawer is closed before the next one opens); the SafeMaster reaction time (the time within which the drawer must be opened or else it relocks automatically); the SafeMaster opening time (the time allowed for any drawer to remain open, exceeding this time raises an audible alarm).

27 June 2012

539.1261/03 DRAFT Version 5.02

27

TCR Twin Safe TSAPI Interface Description Periodic operating hours

These API calls allow an application to determine and alter the standard operating hours for the days of the week. There can be set up to four ON-OFF windows for each day. Aperiodic operating hours These API calls allow an application to determine and alter the operating hours for a particular date. There can be set up to four ON-OFF windows for each entry. Roll storage data These API calls allow an application to determine and alter the notes to be stored in a particular RSM and to set the low level warning values for each RSM. SafeMaster data These API calls allow an application to determine and alter the SafeMaster settings for one side of the SafeMaster at a time. These calls only operate on the specified side, so that the drawers on the left can be defined differently to the corresponding drawers on the right. Furthermore, these API calls allow the SafeMaster to be initialized (if the TCR Twin Safe has not been instructed that a SafeMaster is attached to the selected side), and allows the individual drawer delays and currency information to be maintained.

28

539.1261/3 Version 5.02

27 June 2012


20 21 Minimum instruction set functions Ping command - TSC_FPing Function prototype TSCStatusType DLL_FUNC TSC_FPing ( PTSC_TellerInfo const PTSC_BasicEventData

TCR Twin Safe TSAPI Interface Description

lpTellerInfo, lpBasicEventData);

The Ping function allows a calling application to verify if the TCR Twin Safe communication is consistent. The user name in the TellerInfo structure does not need to express an authorised user. TCR Twin Safe will only fill the lpBasicEventData with the no event value. Note: if the TCR Twin Safe is not connected or if the communication parameters are not consistent, a specific return value of the function will mention it. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe will not do any check on this structure for the ping command. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. In the case of the Ping command, eEventStatus and EventNumber members will return NO_ERROR as default. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS communication consistent

27 June 2012

539.1261/03 DRAFT Version 5.02

29

TCR Twin Safe TSAPI Interface Description With RS232 protocol:

0xF0000002 ERR_NAK TCR Twin Safe has not acknowledged the request. (maybe the communication setup is wrong, or the connection to the TwinSafe is disturbed) Received invalid response from the TCR Twin Safe (maybe the communication setup is wrong, or the connection to the TwinSafe is disturbed) Received an invalid checksum (maybe the communication setup is wrong, or the connection to the TwinSafe is disturbed) Received an invalid telegram header (maybe the communication setup is wrong, or the connection to the TwinSafe is disturbed) CommPort seems to be blocked by another process. (Try again later) No Acknolewdge to a command from TCRTS . Cannot open communication port TCR TWIN SAFE LAN-PC RS232

0xF0000003

ERR_INVALID_RESPONSE

TCR TWIN SAFE LAN-PC RS232

0xF0000004

ERR_CHECKSUMM

TCR TWIN SAFE LAN-PC RS232 TCR TWIN SAFE LAN-PC RS232

0xF0000005

ERR_HEADER

0xF0000006 0xF0000007 0xF0000011

ERR_COMM_PORT_BLOCK_ TIMEOUT ERR_ACK_TIME_OUT ERR_NO_PORT_OPEN

LAN error / other terminal on RS232 same port busy Cable not connected or TCRTS not switched on RS232 communication down

With TCP/IP protocol:

0xF0000007 0xF0000010 0xF0000011 0xF0000012 0xF0000013 0xF0000014 0xF0000015 0xF0000100 0xF00000101 0xF00000103 ERR_ACK_TIME_OUT ERR_OPEN_LOG ERR_NO_PORT_OPEN ERR_BUSY ERR_COMM_EXTERNAL_AB ORT ERR_MAX_SUPPORTED_CO MM_PORTS_REACHED ERR_LOG_FILE_NOT_OPEN ERR_CAL_NOT_IDLE ERR_CAL_BLOCKED_BY_O THER_PROC ERR_NO_VALID_MUTEX No Acknolewdge to a command from TCRTS . Cannot open log file Cannot open communication port Another transaction process on this CommPort is still active Communication aborted by an external event Maximum number of supported CommPorts has been reached (Max 2 Com port) Function Add text to log called but no log file open ? This communication socket is actually in use by another process TSDLL hasnt been able to get a valid Mutex handle for this communication socket (maybe low on resources) TSDLL has detected an illegal reference onto a communication socket (maybe low on memory) Error in handler.ini. IP address is missing Error in handler.ini. Port Number is missing TSServer is not found or not running at this IP address Cable not connected or TCRTS not switched on DLL error RS232 communication down Communication 2 users try to access the same side of TCR TS DLL internal error Configuration handler.ini is wrong Configuration wrong Application SW Error or LAN error Application SW Error Reboot Windows in

0x0F000104 0xF00000200 0xF00000201 0xF00000202

ERR_NO_VALID_SOCKET ERR_LAN_NO_ADDRESS_D EFINED ERR_LAN_NO_PORT_DEFIN ED ERR_LAN_NO_SERVER_FO UND

Network Interface Unit out of order Check handler.ini Check handler.ini Embedded PC off or defect. Check handler.ini

See definition of section 264 Status Codes 30

539.1261/3 Version 5.02 27 June 2012


Additional information None. Cross-references None.

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

31

TCR Twin Safe TSAPI Interface Description

22

Start deposit - TSC_FStartDeposit Function prototype TSCStatusType DLL_FUNC TSC_FStartDeposit ( PTSC_TellerInfo const lpTellerInfo, char * const lpszCurrencyCode, PTSC_BasicEventData lpBasicEventData); The Start deposit function allows a calling application to reserve the TCR Twin Safe for a deposit or a counting transaction. It must be called every prior to every Deposit or Count function call. Upon completion of the Start deposit call, the teller must place bank notes into the input tray and the application must then call the Deposit or Count function. Note: The TCR Twin Safe will remain reserved until another transaction from the same Station Address (see the description of data type TSC_TellerInfo below) is received for the same side. If this is a Deposit or Count then the TCR Twin Safe transaction will proceed. If it is anything else, the reservation will be cancelled but an error in the command sequence may be returned. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszCurrencyCode A pointer to null-terminated string containing the currency code. TCR Twin Safe currency codes are fixed length and may contain both letters and characters. Currency codes will be padded with trailing spaces but may not contain embedded spaces. The generic currency code: -MUL- can be specified to allow the deposit of a bundle of mixed currencies. With this currency code, any note from any currency, assigned to a RSM, will be accepted and stored. The application has, in this case, to manage correctly the accounting of several currencies in the same transaction. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code.

32

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information Multiple calls to the Start deposit function only result in a single reservation of the TCR Twin Safe side. The calling application will be blocked until the TCR Twin Safe completes the operation and returns the response data. Cross-references Extended start deposit Deposit Count Asynchronous deposit Deposit object

27 June 2012

539.1261/03 DRAFT Version 5.02

33

TCR Twin Safe TSAPI Interface Description

23

Extended start deposit - TSC_FExtStartDeposit Function prototype TSCStatusType DLL_FUNC TSC_FExtStartDeposit ( PTSC_TellerInfo const lpTellerInfo, char* const lpszCurrencyCode, BOOL KeepReserved, PTSC_BasicEventData lpBasicEventData); The Extended start deposit function allows a calling application to reserve the TCR Twin Safe for a series of deposit transactions. If it is invoked with the KeepReserved flag set to TRUE it must only be called once rather than prior to every Deposit or Count function call. Upon completion of the Extended start deposit call, the teller must place bank notes into the input tray and the application must call the Deposit or Count function zero or more times until the transaction sequence is completed by calling the End deposit function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszCurrencyCode A pointer to null-terminated string containing the currency code. TCR Twin Safe currency codes are fixed length and may contain both letters and characters. Currency codes will be padded with trailing spaces but may not contain embedded spaces. The generic currency code: -MUL- can be specified to allow the deposit of a bundle of mixed currencies. With this currency code, any note from any currency, assigned to a RSM, will be accepted and stored. The application has, in this case, to manage correctly the accounting of several currencies in the same transaction. KeepReserved Flag to indicate whether this is a single deposit or the start of a sequence throughout which the TCR Twin Safe will remain reserved. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

34

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information Multiple calls to the Extended start deposit function only result in a single reservation of the TCR Twin Safe side. The calling application will be blocked until the TCR Twin Safe completes the operation and returns the response data. Cross-references Start deposit Deposit Count End deposit Asynchronous deposit Deposit object

27 June 2012

539.1261/03 DRAFT Version 5.02

35

TCR Twin Safe TSAPI Interface Description

24

Deposit - TSC_FDeposit Function prototype TSCStatusType DLL_FUNC TSC_FDeposit ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpDepositList) ; This function will fail unless a successful Start deposit function call has been made with the same teller information. The application will receive information about the notes deposited and whether any TCR Twin Safe error occurred while processing the notes. If any notes are rejected and placed in the TCR Twin Safe's dispense hopper, the TCR Twin Safe response will not be available until those notes have been retrieved by the teller. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start deposit call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDepositList A pointer to a list of notes processed into each RSM during the deposit processing. This

36

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. Cross-references Asynchronous deposit Deposit object Ext deposit

27 June 2012

539.1261/03 DRAFT Version 5.02

37

TCR Twin Safe TSAPI Interface Description

25

End deposit - TSC_FEndDeposit Function prototype TSCStatusType DLL_FUNC TSC_FEndDeposit ( PTSC_TellerInfo const pTellerInfo, PTSC_BasicEventData pBasicEventData); The End deposit function completes a sequence that was started by an Extended start deposit with the KeepReserved flag set to TRUE. This completes the transaction sequence. Input parameters pTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters pBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Start deposit Deposit End deposit Asynchronous deposit Cancel deposit Deposit object This

38

539.1261/3 Version 5.02

27 June 2012


26 Withdrawal - TSC_FWithdrawal Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FWithdrawal ( PTSC_TellerInfo const lpTellerInfo, PTSC_DispenseData const lpWithdrawalData, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpWithdrawalList) ; The TCR Twin Safe will count down any configured security delay before dispensing the notes. The notes will be dispensed in batches of 100. The TCR Twin Safe cannot dispense more notes until the previous batch have been removed from the dispense hopper. The TCR Twin Safe will only generate a response after all the notes have been collected by the teller. Due to the configurable nature of the security delays it is not possible to predict how long this transaction might take, but the calling application will be blocked throughout this interval. (Other applications will still be active). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpWithdrawalData A pointer to a data structure defining the numbers of notes to be dispensed from each RSM. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpWithdrawalList A pointer to a list of notes processed into each RSM during the dispense processing. This

27 June 2012

539.1261/03 DRAFT Version 5.02

39

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Asynchronous withdrawal

40

539.1261/3 Version 5.02

27 June 2012


27 Consultation - TSC_FConsult Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FConsult ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_ConsultResponse lpConsultResponse) ; This function carries out a consultation with the Twin Safe to obtain the current denominations and note counts for all RSMs. This function does not return any total amount stored in a RSM, then is not able to return consistent data for the accounting on currency and object RSMs. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpConsultResponse A pointer to a data structure containing the information about each RSM in the TCR Twin Safe. The information includes the denomination and currency together with the note count recorded by the TCR Twin Safe counter for that RSM. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information Do not use this function for new developments on TCR Twin Safe, this function does not support currency and object RSMs. Cross-references TCRTS consultation This

27 June 2012

539.1261/03 DRAFT Version 5.02

41

TCR Twin Safe TSAPI Interface Description

28

Cash balancing - TSC_FCashBalancing Function prototype: TSCStatusType DLL_FUNC TSC_FCashBalancing ( PTSC_TellerInfo const lpTellerInfo, BOOL const ResetCounters, PTSC_BasicEventData lpBasicEventData, PTSC_CashBalanceResponse lpBalanceInfo) ; The TCR Twin Safe maintains an overall cash balance for each user. This balance shows the number of notes deposited and withdrawn for each RSM since the last time that the totals were reset for the specified user. The cash balance is returned as numbers of notes; the TCR Twin Safe does not compute the total value. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. ResetCounters When set to TRUE, the TCR Twin Safe counters are reset after retrieving the cash balance. If FALSE, the counters are not reset and a subsequent request will include the balance already reported in the previous call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpBalanceInfo A pointer to a data structure containing the number of notes deposited into each RSM by the specified user. The response also contains separate values for the number of notes withdrawn from each RSM. This

42

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Asynchronous cash balancing

27 June 2012

539.1261/03 DRAFT Version 5.02

43

TCR Twin Safe TSAPI Interface Description

29

Empty roll storage module - TSC_FEmptyRSM Function prototype TSCStatusType DLL_FUNC TSC_FEmptyRSM PTSC_TellerInfo const PTSC_EmptyRSMParams PTSC_BasicEventData PTSC_EmptyRSMResponse ( lpTellerInfo, lpEmptyRSMParams, lpBasicEventData, lpEmptyRSMResponse) ;

For RSMs holding high denomination notes, the configured security delay can be very long. An optional flag allows the application to bypass the security delay and deliver the notes immediately. Any security implications are the responsibility of the calling application. It must be noted that large amounts of cash can be dispensed very quickly using this option, either immediately or after the security delay. Due to the configurable nature of the security delays it is not possible to predict how long this transaction might take, but the calling application will be blocked throughout this interval. (Other applications will still be active). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpEmptyRSMParams The RSM number and the Boolean flag for optional disabling of the TCR Twin Safe security delay. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpEmptyRSMResponse A pointer to a data structure containing the number of notes dispensed and the number of notes recorded by the TCR Twin Safe software counter. This

44

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information If these numbers are different then the note count returned in some previous transaction (not necessarily for this user) may have been erroneous. N.B. The TCR Twin Safe returns a warning status and event number 634 (RSM is empty) if this transaction completes correctly. Cross-references Empty roll storage module extended Asynchronous empty roll storage module

27 June 2012

539.1261/03 DRAFT Version 5.02

45

TCR Twin Safe TSAPI Interface Description

30

Empty roll storage module extended - TSC_FEmptyRSMExt Function prototype TSCStatusType DLL_FUNC TSC_FEmptyRSMExt ( PTSC_TellerInfo const lpTellerInfo, PTSC_EmptyRSMParams lpEmptyRSMParams, PTSC_BasicEventData lpBasicEventData, PTSC_EmptyRSMExtResponse lpEmptyRSMResponse) ; For RSMs holding high denomination notes, the configured security delay can be very long. An optional flag allows the application to bypass the security delay and deliver the notes immediately. Any security implications are the responsibility of the calling application. It must be noted that large amounts of cash can be dispensed very quickly using this option, either immediately or after the security delay. Due to the configurable nature of the security delays it is not possible to predict how long this transaction might take, but the calling application will be blocked throughout this interval. (Other applications will still be active). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpEmptyRSMParams The RSM number and the Boolean flag for optional disabling of the TCR Twin Safe security delay. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpEmptyRSMResponse A pointer to a data structure containing the number of notes dispensed and the number of notes recorded by the TCR Twin Safe software counter. This structures also holds the difference between dispensed notes and recorded notes. This

46

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information If these numbers are different then the note count returned in some previous transaction (not necessarily for this user) may have been erroneous. N.B. The TCR Twin Safe returns a warning status and event number 634 (RSM is empty) if this transaction completes correctly. Cross-references Empty roll storage module Asynchronous empty roll storage module

27 June 2012

539.1261/03 DRAFT Version 5.02

47

TCR Twin Safe TSAPI Interface Description

31

Get event text - TSC_ FGetEventText Function prototype TSCStatusType DLL_API TSC_FGetEventText( PTSC_TellerInfo const lpTellerInfo, ASCOM_EventNumber eventNumber, PTSC_BasicEventData lpBasicEventData, char *eventText); The GetEventText returns the assigned text of an event number. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. eventNumber A variable, containing the event number. Output parameters eventText A pointer to a buffer of a null-terminated string, containing the event text. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

48

539.1261/3 Version 5.02

27 June 2012


32 System status - TSC_FSystemStatus Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSystemStatus ( PTSC_TellerInfo const lpTellerInfo, TSCSensorTest TestSensors, PTSC_BasicEventData lpBasicEventData, PTSC_SystemStatusResponse lpStatusResponse) ; This function retrieves the TCR Twin Safe configuration information and the version numbers of the software attached to each component. It also returns a condensed history of the recent transaction types and event numbers. The optional sensor test routine can return the identities of up to 50 faulty sensors/probes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. TestSensors A flag indicating whether the TCR Twin Safe should perform an internal test of its probes and return the ID's of up to ten or even 50 faulty components. If this flag is set to TSC_NoSensors, the probe ID field in the response will be filled with spaces. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpStatusResponse A pointer to a data structure which contains all the information returned by the TCR Twin Safe. This

27 June 2012

539.1261/03 DRAFT Version 5.02

49

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information This function call definition is not compatible to the NCI Twin Safe Handler DLL. Cross-references Asynchronous system status

50

539.1261/3 Version 5.02

27 June 2012


33 Self-test/ purge - TSC_FTest Function prototype TSCStatusType DLL_FUNC TSC_FTest ( PTSC_TellerInfo const PTSC_BasicEventData

TCR Twin Safe TSAPI Interface Description

lpTellerInfo, lpBasicEventData) ;

This function carries out a TCR Twin Safe self test. If the returned status is non-zero, the function must be called again. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references TCSTS self-test/ purge This

27 June 2012

539.1261/03 DRAFT Version 5.02

51

TCR Twin Safe TSAPI Interface Description

34

Get date and time - TSC_FGetDateAndTime Function prototype TSCStatusType DLL_FUNC TSC_FGetDateAndTime ( PTSC_TellerInfo const lpTellerInfo, PASCOM_DateTime const lpDateAndTime, PTSC_BasicEventData lpBasicEventData) ; This function receives the TCR Twin Safe date and time. This information is used within the TCR Twin Safe for time stamping its own log entries (the TCR Twin Safe log is separate from the TCR Twin Safe Handler optional log file) and for monitoring the operating hours. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDateAndTime A pointer to the data structure receiving the current data and time values. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references Set date and time. This

52

539.1261/3 Version 5.02

27 June 2012


35 Set date and time - TSC_FSetDateAndTime Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetDateAndTime ( PTSC_TellerInfo const lpTellerInfo, PASCOM_DateTime const lpDateAndTime, PTSC_BasicEventData lpBasicEventData) ; This function allows the application to update the TCR Twin Safe date and time. This information is used within the TCR Twin Safe for time stamping its own log entries (the TCR Twin Safe log is separate from the TCR Twin Safe Handler optional log file) and for monitoring the operating hours. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateAndTime A pointer to the data structure containing the new data and time values. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references Get date and time. This

27 June 2012

539.1261/03 DRAFT Version 5.02

53

TCR Twin Safe TSAPI Interface Description

36

Get machine type and capabilities- TSC_FGetTypeAndCapabilities Function prototype TSCStatusType DLL_API TSC_FGetTypeAndCapabilities ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_TypeAndCapabilities lpTypeAndCapabilities) This function retreives the type and capabilities of the TCR. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpTypeAndCapabilities A pointer to the data structure receiving the machine type, note handling type, roll storage type, ERF capabilities and the current erf mode. This

Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references None

54

539.1261/3 Version 5.02

27 June 2012


37 Poll the output cassette status - TSC_FPollOutputCassette Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FPollOutputCassette ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_POLLINGFLAG pollingflag) ; The status of the output cassette will be returnd. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Pollingflag A pointer to a variable, containing the output cassette status; Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None. Cross-references None. This

27 June 2012

539.1261/03 DRAFT Version 5.02

55

TCR Twin Safe TSAPI Interface Description 38 39 TCR Twin Safe specific functions Initialize MCU - TSC_FInitMcu Function prototype TSCStatusType DLL_API TSC_FInitMcu ( PTSC_TellerInfo const TSC_MCU_RESET_MODE PTSC_BasicEventData lpTellerInfo, type, lpBasicEventData);

The InitMCU function resets the TCR Twin Safes MasterControlUnit. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. type A variable, containing in the reset mode. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

56

539.1261/3 Version 5.02

27 June 2012


40 Deposit arbitrary objects - TSC_FDepositObjects Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FDepositObjects ( PTSC_TellerInfo const lpTellerInfo, PTSC_DEPOSIT lpDepositInputData, PTSC_BasicEventData lpBasicEventData, PTSCNumberOfObjects lpObjects); The Deposit objects function allows a calling application to deposit an arbitrary object into the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDepositInputData A pointer to a data structure, containing the amount and number of the objects and the destination RSM. Output parameters lpObjects A pointer to a variable, containing the number of deposited objects. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

57

TCR Twin Safe TSAPI Interface Description

41

TCRTS deposit - TSC_ FExtDeposit Function prototype TSCStatusType DLL_FUNC TSC_ FExtDeposit ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpDepositList, PTSC_AMOUNT_LIST lpAmountList); This function has to be specificaly called when currency RSMs are configured in the TCR Twin Safe. The total amount deposited in each RSM will then be returned to the application. This function will fail unless a successful Start Deposit function call has been made with the same teller information. If any notes are rejected and placed in the TCR Twin Safe's dispense hopper, the TCR Twin Safe response will not be available until those notes have been retrieved by the teller. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDepositList A pointer to a list of notes processed into each RSM during the deposit processing. lpAmountList A Pointer to a list of amounts processed into each RSM during the deposit processing. This

58

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. Cross-references Asynchronous deposit Deposit object

27 June 2012

539.1261/03 DRAFT Version 5.02

59

TCR Twin Safe TSAPI Interface Description

42

TCRTS deposit with note stack - TSC_ FExtDepositNoteStack Function prototype TSCStatusType DLL_FUNC TSC_ FExtDeposit ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpDepositList, PTSC_AMOUNT_LIST lpAmountList, PTSC_NoteStack lpNoteStack); This function has to be specificaly called when currency RSMs are configured in the TCR Twin Safe. The total amount deposited in each RSM will then be returned to the application. For currency RSMs the details for each denomination is also returned by this function. This function will fail unless a successful Start Deposit function call has been made with the same teller information. If any notes are rejected and placed in the TCR Twin Safe's dispense hopper, the TCR Twin Safe response will not be available until those notes have been retrieved by the teller. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDepositList A pointer to a list of notes processed into each RSM during the deposit processing. lpAmountList A Pointer to a list of amounts processed into each RSM during the deposit processing. lpNoteStack A pointer to a structure receiving the details for each denomination deposited in a currency RSM. The NumberOfStackEntries attribute stores how much entries in the noteStack array are filled. This array holds details for each denomination including the RSM number where these notes where deposited. This

60

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. Cross-references Asynchronous deposit Deposit object

27 June 2012

539.1261/03 DRAFT Version 5.02

61

TCR Twin Safe TSAPI Interface Description

43

Deposit with reject flag - TSC_FDeposit2 Function prototype TSCStatusType DLL_FUNC TSC_FDeposit2 PTSC_TellerInfo const PTSC_BasicEventData PTSC_DENOMINATIONS_LIST PTSC_POLLINGFLAG ( lpTellerInfo, lpBasicEventData, lpDepositList, pNotesRejected) ;

This function will fail unless a successful Start Deposit function call has been made with the same teller information. The application will receive information about the notes deposited and whether any TCR Twin Safe error occurred while processing the notes. If any notes are rejected and placed in the TCR Twin Safe's dispense hopper, the TCR Twin Safe response will not be available until those notes have been retrieved by the teller. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDepositList A pointer to a list of notes processed into each RSM during the deposit processing. pNotesRejected A pointer to a TSC_POLLINGFLAG variable. The parameter becomes TRUE if there were notes rejected during separation. This

62

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. Cross-references Asynchronous deposit Deposit object Extended deposit

27 June 2012

539.1261/03 DRAFT Version 5.02

63

TCR Twin Safe TSAPI Interface Description

44

TCRTS deposit with reject flag - TSC_ FExtDeposit2 Function prototype TSCStatusType DLL_FUNC TSC_ FExtDeposit2 ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpDepositList, PTSC_AMOUNT_LIST lpAmountList, PTSC_POLLINGFLAG pNotesRejected); This function has to be specificaly called when currency RSMs are configured in the TCR Twin Safe. The total amount deposited in each RSM will then be returned to the application. This function will fail unless a successful Start Deposit function call has been made with the same teller information. If any notes are rejected and placed in the TCR Twin Safe's dispense hopper, the TCR Twin Safe response will not be available until those notes have been retrieved by the teller. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDepositList A pointer to a list of notes processed into each RSM during the deposit processing. lpAmountList A Pointer to a list of amounts processed into each RSM during the deposit processing. pNotesRejected A pointer to a TSC_POLLINGFLAG variable. The parameter becomes TRUE if there were notes rejected during separation. This

64

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. Cross-references Asynchronous deposit Deposit object

27 June 2012

539.1261/03 DRAFT Version 5.02

65

TCR Twin Safe TSAPI Interface Description

45

TCRTS deposit with note stack and reject flag - TSC_ FExtDepositNoteStack2 Function prototype TSCStatusType DLL_FUNC TSC_ FExtDeposit2 ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpDepositList, PTSC_AMOUNT_LIST lpAmountList, PTSC_NoteStack lpNoteStack, PTSC_POLLINGFLAG pNotesRejected); This function has to be specificaly called when currency RSMs are configured in the TCR Twin Safe. The total amount deposited in each RSM will then be returned to the application. For currency RSMs the details for each denomination is also returned by this function. This function will fail unless a successful Start Deposit function call has been made with the same teller information. If any notes are rejected and placed in the TCR Twin Safe's dispense hopper, the TCR Twin Safe response will not be available until those notes have been retrieved by the teller. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDepositList A pointer to a list of notes processed into each RSM during the deposit processing. lpAmountList A Pointer to a list of amounts processed into each RSM during the deposit processing. lpNoteStack A pointer to a structure receiving the details for each denomination deposited in a currency RSM. The NumberOfStackEntries attribute stores how much entries in the noteStack array are filled. This array holds details for each denomination including the RSM number where these notes where deposited. pNotesRejected A pointer to a TSC_POLLINGFLAG variable. The parameter becomes TRUE if there were notes rejected during separation. This

66

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. Cross-references Asynchronous deposit Deposit object

27 June 2012

539.1261/03 DRAFT Version 5.02

67

TCR Twin Safe TSAPI Interface Description

46

TCRTS Rollback deposit - TSC_FRollbackDeposit Function prototype TSCStatusType DLL_FUNC TSC_FRollbackDeposit ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpDepositList) ; This function will pay out all notes, which were deposited since the last Start Deposit function call. The reservation of the machine will also be cleared by this function. A call to End Deposit is not required after this function. This function will fail unless a successful Start Deposit function call has been made with the same teller information. The application will receive information about the notes payed out and whether any TCR Twin Safe error occurred while processing the notes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDepositList A pointer to a list of notes processed from each RSM during the rollback processing. This

68

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. Cross-references Asynchronous deposit Deposit Deposit object Extended deposit

27 June 2012

539.1261/03 DRAFT Version 5.02

69

TCR Twin Safe TSAPI Interface Description

47

TCRTS withdrawal - TSC_FWithdrawal2 Function prototype TSCStatusType DLL_FUNC TSC_FWithdrawal2 ( PTSC_TellerInfo const lpTellerInfo, PTSC_DispenseData const lpWithdrawalData, TSC_TestReservation reservation, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpWithdrawalList) ; The TCR Twin Safe will count down any configured security delay before dispensing the notes. The notes will be dispensed in batches of 100. The TCR Twin Safe cannot dispense more notes until the previous batch have been removed from the dispense hopper. The TCR Twin Safe will only generate a response after all the notes have been collected by the teller. Due to the configurable nature of the security delays it is not possible to predict how long this transaction might take, but the calling application will be blocked throughout this interval. (Other applications will still be active). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpWithdrawalData A pointer to a data structure defining the numbers of notes to be dispensed from each RSM. reservation This parameter specifies if the reservation of the TCR Twin Safe should be released or not. Possible values are. ReleaseOwnReservation Releases the reservation fort his user KeepReservation Any existing reservation will be kept. ReleaseAllReservation Releases all reservation (for all users) Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpWithdrawalList A pointer to a list of notes processed into each RSM during the dispense processing. This

70

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Asynchronous withdrawal

27 June 2012

539.1261/03 DRAFT Version 5.02

71

TCR Twin Safe TSAPI Interface Description

48

TCRTS note bundle counting - TSC_FCounter Function prototype TSCStatusType DLL_FUNC TSC_FCounter ( PTSC_TellerInfo const lpTellerInfo, TSCDenominationType numberOfNotes, TSCCounterModeType counterMode, PTSC_BasicEventData lpBasicEventData, PTSC_TSCounterResponse lpCounterResponse); This function will fail unless a successful Start Deposit function call has been made with the same teller information. When the counting function is not successful, a purge must be initiated to remove all notes from the transport path after counted notes have been removed from the output pocket by the teller. The application will receive information about the notes counted and whether any TCR Twin Safe error occurred while processing the notes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. NumberOfNotes Maximum size of the note bundle. The machine will stop counting when NumberOfNotes notes are processed. A value of 0 means no bundle size is set. The maximum value is 100. CounterMode If this flag is zero, the machine will count the whole bundle and does not stop on false or unrecongnized notes. A value of 1 will cause the machine to stop counting when a false note was detected. In this case a purge has to be executed. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpCouterResponse A pointer to a data structure receiving the counting information for each denomination counted, unassigned notes and double notes. This

72

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. Cross-references Asynchronous deposit Deposit object

27 June 2012

539.1261/03 DRAFT Version 5.02

73

TCR Twin Safe TSAPI Interface Description

49

Start summarized counting - TSC_FStartCounter Function prototype TSCStatusType DLL_FUNC TSC_FExtStartDeposit ( PTSC_TellerInfo const lpTellerInfo, char * const lpszCurrencyCode, PTSC_BasicEventData lpBasicEventData); The Start summarized counting function allows a calling application to reserve the TCR Twin Safe for a series of counting transactions. This function calls TSC_FExtStartDeposit (in extended mode) to get the reservation. The counters are also initialized by this function. The application must call the Summarized counting function zero or more times until the transaction sequence is completed by calling the End deposit function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszCurrencyCode A pointer to null-terminated string containing the currency code. TCR Twin Safe currency codes are fixed length and may contain both letters and characters. Currency codes will be padded with trailing spaces but may not contain embedded spaces. The generic currency code: -MUL- can be specified to allow the counting of a bundle of mixed currencies. With this currency code, any note from any currency, known by the note reader, will be accepted and counted. The application has, in this case, to manage correctly the accounting of several currencies in the same transaction. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

74

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information Multiple calls to the Start counting function only result in a single reservation of the TCR Twin Safe side. But the counters are reset. The calling application will be blocked until the TCR Twin Safe completes the operation and returns the response data. Cross-references Summarized counting End deposit

27 June 2012

539.1261/03 DRAFT Version 5.02

75

TCR Twin Safe TSAPI Interface Description

50

TCRTS summarized counting - TSC_FCounterSummarized Function prototype TSCStatusType DLL_FUNC TSC_TSC_FCounterSummarized ( PTSC_TellerInfo const lpTellerInfo, TSCDenominationType numberOfNotes, TSCCounterModeType counterMode, PTSC_BasicEventData lpBasicEventData, PTSC_TSCounterResponse lpCounterResponse, PTSC_POLLINGFLAG pPurgeNext); This function will fail unless a successful Start summarized counting function call has been made with the same teller information. This function uses the TSC_FCounter function to count a bundle of notes. The counters will be added to the previous counters. The returned lpCounterResponse will contain a summary of all counting since the last Start summarized counting. When the counting function is not successful, a purge must be initiated to remove all notes from the transport path after counted notes have been removed from the output pocket by the teller. The pPurgeNext will indicate that the purge will be done by Summarized counting function next time the application calls it. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. NumberOfNotes Maximum size of the note bundle. The machine will stop counting when NumberOfNotes notes are processed. A value of 0 means no bundle size is set. The maximum value is 100. CounterMode If this flag is zero, the machine will count the whole bundle and does not stop on false or unrecongnized notes. A value of 1 will cause the machine to stop counting when a false note was detected. In this case a purge has to be executed.

76

539.1261/3 Version 5.02

27 June 2012


Output parameters lpBasicEventData

TCR Twin Safe TSAPI Interface Description

A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpCouterResponse

This

A pointer to a data structure receiving the counting information for each denomination counted, unassigned notes and double notes. This structure contains a summary of all countings since the last call to Start summarized counting. pPurgeNext Indicates that a purge will be executed next time the Summarized counting function is called. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information When the CounterMode parameter ios set to 1 the TCR Twin Safe will stop when a unrecognized or false note is detected. The value of pPurgeNext will become 1. When the function is called once again no counting will be done. The Summarized Counting function will call TSC_FTest to purge the notes from the transport. Cross-references Start summarized counting End deposit

27 June 2012

539.1261/03 DRAFT Version 5.02

77

TCR Twin Safe TSAPI Interface Description Flowchart

Start

Start summarized counting TSC_FStartCounter (Cmd 100105)

Start extended deposit TSC_FExtStartDeposit (Cmd 100105)

Put notes into input tray

The user should have the possibility to abort this loop

Query input tray sensor TSC_FNoteInputQuery (Cmd 100510) No Notes in input tray ? Yes Summarized counting function TSC_FCounterSummarized (Cmd 100108) Yes

No Yes Take the counted (accepted) notes

Error occured ?

Yes

Error handler

Query output tray sensor TSC_FPollOutputCassette (Cmd 100116)

No Take the jammed notes when purge has finished

Yes Notes in output tray ? Event status >= 3

No

Yes

Start self test TSC_FTest (Cmd 100140)

PurgeNext ?

Take the counted (accepted) notes

No

Continue counting?

Yes Take the notes First note was not accepted No Summarized counting function TSC_FCounterSummarized (Cmd 100108) Yes Notes in output tray ? Query output tray sensor TSC_FPollOutputCassette (Cmd 100116)

Continue counting?

No

End deposit TSC_FEndDeposit (Cmd 100107)

No

End

78

539.1261/3 Version 5.02

27 June 2012


51 TCRTS consultation - TSC_FConsultEx Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FConsultEx( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_RSM_ASSIGN pResultData); The ConsultEx returns information about each RSM. This function is specially intended to manage amounts in currency and object RSMs. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters pResultData A pointer to a data structure, containing the information about each RSM in the TCR Twin Safe. The structure includes the denomination, RSM-type, module availability, total amount stored and the number of notes or objects. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information This function supports currency and object RSMs. This

Cross-references Consultation

27 June 2012

539.1261/03 DRAFT Version 5.02

79

TCR Twin Safe TSAPI Interface Description

52

TCRTS consultation - TSC_FConsultEx2 Function prototype TSCStatusType DLL_API TSC_FConsultEx2( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_RSM_ASSIGN_2 pResultData); This function is similar to the TSC_FConsultEx. it contains an additional information about the state of each RSM. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters pResultData A pointer to a data structure, containing the information about each RSM in the TCR Twin Safe. The structure includes the denomination, RSM-type, module availability, total amount stored, the number of notes or objects and the RSM-state. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information This function supports currency and object RSMs. This

Cross-references Consultation

80

539.1261/3 Version 5.02

27 June 2012


53 TCRTS SafeMaster consultation total TSC_FSMConsTotalEx Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSMConsTotalEx ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_SMConsultResponse lpSMConsultResponse) ; This function retrieves information about all SafeMaster drawers configured for the specified side. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMConsultResponse A pointer to a data structure containing the SafeMaster Consultation information. The currency text field will not be filled in the response, it will be set to an empty string. In this command also the DrawerNum fields will be filled! Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None. This

27 June 2012

539.1261/03 DRAFT Version 5.02

81

TCR Twin Safe TSAPI Interface Description

54

TCRTS self-test/ purge - TSC_FTestExt Function prototype TSCStatusType DLL_FUNC TSC_FTestExt ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpPurgeList) ; This function carries out a TCR Twin Safe self test. If the returned status is non-zero, the function must be called again. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpPurgeList A pointer to a list of notes processed into each RSM during the self test. When the value is negative, the notes were payed out. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references Self-test/ purge This

82

539.1261/3 Version 5.02

27 June 2012


55 TCRTS self-test/ purge - TSC_FTestExt2 Function prototype TSCStatusType DLL_FUNC TSC_FTestExt2 PTSC_TellerInfo const TSC_TestReservation PTSC_BasicEventData PTSC_DENOMINATIONS_LIST

TCR Twin Safe TSAPI Interface Description

( lpTellerInfo, reservation, lpBasicEventData, lpPurgeList) ;

This function carries out a TCR Twin Safe self test. If the returned status is non-zero, the function must be called again. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. reservation This parameter specifies if the reservation of the TCR Twin Safe should be released or not. Possible values are. ReleaseOwnReservation Releases the reservation fort his user KeepReservation Any existing reservation will be kept. ReleaseAllReservation Releases all reservation (for all users) Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpPurgeList A pointer to a list of notes processed into each RSM during the self test. When the value is negative, the notes were payed out. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references Self-test/ purge This

27 June 2012

539.1261/03 DRAFT Version 5.02

83

TCR Twin Safe TSAPI Interface Description

56

TCRTS poll the output cassette status - TSC_FPollOutputCassette2 Function prototype TSCStatusType DLL_FUNC TSC_FPollOutputCassette2 ( PTSC_TellerInfo const lpTellerInfo, TSC_TestReservation reservation, PTSC_BasicEventData lpBasicEventData, PTSC_POLLINGFLAG pollingflag) ; The status of the output cassette will be returnd. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. reservation This parameter specifies if the reservation of the TCR Twin Safe should be released or not. Possible values are. ReleaseOwnReservation Releases the reservation fort his user KeepReservation Any existing reservation will be kept. ReleaseAllReservation Releases all reservation (for all users) Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Pollingflag A pointer to a variable, containing the output cassette status; Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None. Cross-references None. This

84

539.1261/3 Version 5.02

27 June 2012


57 Poll the input cassette status - TSC_FNoteInputQuery Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FNoteInputQuery ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_POLLINGFLAG pollingflag) ; The status of the input cassette will be returnd. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Pollingflag A pointer to a variable, containing the input cassette status; Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None. Cross-references None. This

27 June 2012

539.1261/03 DRAFT Version 5.02

85

TCR Twin Safe TSAPI Interface Description

58

TCRTS calculate a note mix TSC_FCalculateNotemix Function prototype TSCStatusType DLL_FUNC TSC_FCalculateNotemix ( PTSC_TellerInfo const lpTellerInfo, char *currencycode, TSCAmount amount, TSC_NotemixAlgorithm algorithm, PTSC_BasicEventData lpBasicEventData, PTSC_DENOMINATIONS_LIST lpNotemix); This function calculated a notemix for a given amount and currency. The function internally calls TSC_FConsultEx to determine the availability of notes. It is possible that not all of the requested amount can be denominated. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. currencycode A pointer to a string containing the currency code. amount Contains the amount of money. algorithm Specifies, which algorithm should be used to calculate the note mix. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpNotemix A pointer to a list of notes for each RSM. You may use this values in a subsequent call to TSC_FWithdrawal. This

86

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information When using ALG_Programmed for algorithm parameter, the information will read from an AUTOMIX.INI file. This file is structured as follows. There is one section for each currency, named like the currency. In each section the Notevalues key contains a list of available denominations separated by semi colon. The Mixn keys contain the mix information. The first value is the amount followed by the number of notes for each denomination. These numbers correspond to the denominations specified in the Notevalues key. For better understanding see the exsample: [CHF] Notevalues=10.00;20.00;50.00;100.00;200.00;1000.00 Mix0=20.00;2;0;0;0;0;0 Mix1=50.00;1;2;0;0;0;0 Mix2=100.00;1;2;1;0;0;0 Mix3=200.00;0;0;2;1;0;0 Mix4=500.00;0;0;0;1;2;0 [L] Notevalues=1000.00;2000.00;5000.00;10000.00;50000.00;50000.00;1 00000.00;100000.00;500000.00 Mix0=1000000.00;0;0;0;0;0;10;0;5;0 Mix1=5000000.00;0;0;0;0;0;10;0;5;8 Cross-references TCRTS consultation

27 June 2012

539.1261/03 DRAFT Version 5.02

87

TCR Twin Safe TSAPI Interface Description

59

TCRTS get input switch state TSC_FGetInputSwitchState Function prototype TSCStatusType DLL_FUNC TSC_FGetInputSwitchState ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_POLLINGFLAG pollingFlag); This function can be used to determine if the input switch was pressed or not. If the left or right button should be queried is specified in the lpTellerInfo structure. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. The cTellerSide attribute will be used to specify which button will be queried. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. pollingFlag A pointer to a variable containing the status of the input switch. If the button was pressed this variable is set to 1. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information none Cross-references none This

88

539.1261/3 Version 5.02

27 June 2012


60 TCRTS get reservation state TSC_FGReservationState Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetReservationState ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_ReservationData lpReservation); This function is used to check the reservation state of the TCRTS. The information is returned in the lpReservation structure. From this structure you can learn if the safe is reserved, which side and user has the reservation, the reason for the reservation etc. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. The cTellerSide attribute will be used to specify which button will be queried. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpReservation This data structure receives the current reservation state of the TCR TwinSafe. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information none Cross-references none This

27 June 2012

539.1261/03 DRAFT Version 5.02

89

TCR Twin Safe TSAPI Interface Description

61

Get all RSM assignments - FGetAllRSMAssignments Function prototype TSCStatusType DLL_API TSC_FGetAllRSMAssignments( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_RSM_ASSIGNMENT_LIST pRSMAssignList); The GetAllRSMAssignment function returns the assignment information for all RSMs. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. pRSMAssignList A pointer to a data structure, containing the assignment information for each assigned RSM. The attribute numRSMs has to be set to a number between 1 and 8 before the function is called. This parameter specifies the number of RSMs to be queried. Output parameters pRSMAssignList A pointer to a data structure, containing the assignment information for each assigned RSM. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

90

539.1261/3 Version 5.02

27 June 2012


62 Set all RSM assignments - FSetAllRSMAssignments Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FGetAllRSMAssignments( PTSC_TellerInfo const lpTellerInfo, PTSC_RSM_ASSIGNMENT_LIST pRSMAssignList PTSC_BasicEventData lpBasicEventData); The SetAllRSMAssignment function sets the assignment information for all RSMs. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. pRSMAssignList A pointer to a data structure, containing the assignment information for each assigned RSM. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

91

TCR Twin Safe TSAPI Interface Description

63

Get currency template serial number - TSC_FGetCurrencyTemplateSN Function prototype TSCStatusType DLL_API TSC_FGetCurrencyTemplateSN ( PTSC_TellerInfo const lpTellerInfo, TSCIndexNumber index, PTSC_BasicEventData lpBasicEventData, char *szSerialNumber); This function returns the serial number of a currency template used by the note reader. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. index Specifies the index of the template from which the serial number should be returned. The index of the templates starts with 1 for the first template. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. szSerialNumber A pointer to a array of char which receives the serial number as a string. The array should be dimensioned to hold at least 17 characters inclusive the terminating zero. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references Download currency template Delete currency template This

92

539.1261/3 Version 5.02

27 June 2012


64 Delete currency template - TSC_FDeleteCurrencyTemplate Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FDeleteCurrencyTemplate ( PTSC_TellerInfo const lpTellerInfo, char *szSerialNumber, PTSC_BasicEventData lpBasicEventData); This function deletes a currency template from note reader. To determine the korrect serial number use the TSC_FGetCurrencyTemplateSN function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. szSerialNumber Contains the serial number of the currency template which should be deleted. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references Get currency template serial number Download currency template This

27 June 2012

539.1261/03 DRAFT Version 5.02

93

TCR Twin Safe TSAPI Interface Description

65

Download currency template - TSC_FDownloadCurrencyTemplate Function prototype TSCStatusType DLL_API TSC_FDownloadCurrencyTemplate ( PTSC_TellerInfo const lpTellerInfo, char *filename, PTSC_BasicEventData lpBasicEventData); The DownloadParameterfile function downloads parameter settings from a file to the TCR Twin Safes MasterControlUnit. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. filename A pointer to a null-terminated string, holding the full filename (incl. pathname). Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references Get currency template serial number Delete currency template This

94

539.1261/3 Version 5.02

27 June 2012


66 Download parameter file - TSC_FDownloadParameterfile Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FDownloadParameterfile( PTSC_TellerInfo const lpTellerInfo, char *filename, PTSC_BasicEventData lpBasicEventData); The DownloadParameterfile function downloads parameter settings from a file to the TCR Twin Safes MasterControlUnit. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. filename A pointer to a null-terminated string, holding the full filename (incl. pathname). Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

95

TCR Twin Safe TSAPI Interface Description

67

Download software - TSC_FDownloadSoftware Function prototype TSCStatusType DLL_API TSC_FDownloadSoftware( PTSC_TellerInfo const lpTellerInfo, TSC_DOWNLOAD_SW_INFO *lpInputData, PTSC_BasicEventData lpBasicEventData); The DownloadSoftware function downloads the firmware to the specified modul. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpInputData A pointer to a data structure, containing the full filename (incl. pathname) of the software package and the destination module. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS This

96

539.1261/3 Version 5.02

27 June 2012


Additional information Possible destination modules are: The first 5 characters: RSM TRM NHM MCU OVM AVM ISM

TCR Twin Safe TSAPI Interface Description

The next 27 characters specifies the modul number. E.g.: RSM 1,2,3 The following code will be downloaded to RSM 1, RSM 2 and RSM3. Cross-references None

27 June 2012

539.1261/03 DRAFT Version 5.02

97

TCR Twin Safe TSAPI Interface Description

68

Download visibility file - TSC_FDownloadVisibility Function prototype TSCStatusType DLL_API TSC_FDownloadVisibility( PTSC_TellerInfo const lpTellerInfo, Char *filename, PTSC_BasicEventData lpBasicEventData); The DownloadVisibility function downloads a visibility file to the TCR Twin Safes MCU. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. filename A pointer to a null-terminated string, including the full filename (incl. pathname). Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

98

539.1261/3 Version 5.02

27 June 2012


69 Download language file - TSC_FDownloadLanguage Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FDownloadLanguage ( PTSC_TellerInfo const lpTellerInfo, TSC_DOWNLOAD_LANGUAGE_INFO *lpInputData, PTSC_BasicEventData lpBasicEventData); The DownloadLanguage function downloads a language file to the TCR Twin Safes MCU. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpInputData A pointer to a data structure, containing the full filename (incl. pathname), the language name and the slot number. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

99

TCR Twin Safe TSAPI Interface Description

70

Upload parameter file - TSC_FUploadParameterfile Function prototype TSCStatusType DLL_API TSC_FUploadParameterfile ( PTSC_TellerInfo const lpTellerInfo, TSC_UPLOAD_PARAMETERFILE_INFO *lpInputData, PTSC_BasicEventData lpBasicEventData, TSC_UPLOAD_PARAMETER *outputData); The UploadParameterfile function saves the parameter settings from the TCR Twin Safes MCU to the specified file. The current parameter settings are also return via outputData. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpInputData A pointer to a data structure, containing the section, the full filename (incl. pathname), the append flag and the data type flag. If data type flag is zero the function uploads the configuration data only. The complete operation data will be uploaded when data type flag is nonzero. Output parameters OutputData A pointer to a data structure, containing a pointer to the buffer of a nullterminated result-string and the size in characters of the result-string. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

100

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS Additional information The meaning of the append-flag:

TCR Twin Safe TSAPI Interface Description

False, means the file will be overwritten if it already exist. True, means the result-string will be append to the existing file content. Possible characters and the meaning of the data-type-flag: B K Cross-references None (Operating data) (Configuration data)

27 June 2012

539.1261/03 DRAFT Version 5.02

101

TCR Twin Safe TSAPI Interface Description

71

Upload DLL trace file - TSC_FUploadDLLTrace Function prototype TSCStatusType DLL_FUNC TSC_FUploadDLLTrace ( PTSC_TellerInfo const lpTellerInfo, TSC_UPLOAD_FILENAME lpszTraceFilepath, PTSC_BasicEventData lpBasicEventData) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszTraceFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Windows system error codes (file handling) Additional information This function works for Twinsafe and TCR Twinsafe. Cross-references none. This

102

539.1261/3 Version 5.02

27 June 2012


72 Function prototype

TCR Twin Safe TSAPI Interface Description

Upload ODA file (all sections of the parameter file) - TSC_FUploadODAFile

TSCStatusType DLL_FUNC TSC_FUploadODAFile ( PTSC_TellerInfo const lpTellerInfo, TSC_UPLOAD_FILENAME lpszODAFilepath, PTSC_BasicEventData lpBasicEventData) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszODAFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Windows system error codes (file handling) Additional information This function works for Twinsafe and TCR Twinsafe. Cross-references none. This

27 June 2012

539.1261/03 DRAFT Version 5.02

103

TCR Twin Safe TSAPI Interface Description

73

Upload ODA file & Twin Safe log (last n lines) - TSC_FUploadODAFileAndLogXLines Function prototype TSCStatusType DLL_FUNC TSC_FUploadODAFileAndLogXLines ( PTSC_TellerInfo const lpTellerInfo, TSC_UPLOAD_FILENAME lpszODAFilepath, TSC_LogLineNumber numLines, TSC_UPLOAD_FILENAME lpszLogFilepath, PTSC_BasicEventData lpBasicEventData) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszODAFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. numLines Number of log lines to be uploaded to a file. This function uploads the newest numLines entries of the log. lpszLogFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

104

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Windows system error codes (file handling) Additional information This function works for Twinsafe and TCR Twinsafe. Cross-references Upload TCR Twin Safe log (last n lines)

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

105

TCR Twin Safe TSAPI Interface Description

74

Upload ODA file & Twin Safe log (range) - TSC_FUploadODAFileAndLogRange Function prototype TSCStatusType DLL_FUNC TSC_FUploadODAFileAndLogRange ( PTSC_TellerInfo const lpTellerInfo, TSC_UPLOAD_FILENAME lpszODAFilepath, PASCOM_DateTime start, PASCOM_DateTime end, TSC_UPLOAD_FILENAME lpszLogFilepath, PTSC_BasicEventData lpBasicEventData) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszODAFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. lpStartDateTime Address of a Date / Time variable. If general log information is required then this variable is ignored. If information for a specific day is required then this variable should contain the relevant date, the time element of the variable is ignored. If log information for a specific period is required then this variable should contain the start date and time of that period. lpEndDateTime Address of a Date / Time variable. If general log information or information for a specific day is required then this variable is ignored. If log information for a specific period is required then this variable should contain the end date and time of that period. lpszLogFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten.

106

539.1261/3 Version 5.02

27 June 2012


Output parameters lpBasicEventData

TCR Twin Safe TSAPI Interface Description

A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID TSC_DATE_INVALID TSC_TIME_INVALID Windows system error codes (file handling) Additional information This function works for Twinsafe and TCR Twinsafe. Cross-references Upload TCR Twin Safe log (range)

This

27 June 2012

539.1261/03 DRAFT Version 5.02

107

TCR Twin Safe TSAPI Interface Description

75

Upload ODA file & Twin Safe log (entire log) - TSC_FUploadODAFileAndLogAllLines Function prototype TSCStatusType DLL_FUNC TSC_FUploadODAFileAndLogAllLines ( PTSC_TellerInfo const lpTellerInfo, TSC_UPLOAD_FILENAME lpszODAFilepath, TSC_UPLOAD_FILENAME lpszLogFilepath, PTSC_BasicEventData lpBasicEventData) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszODAFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. lpszLogFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Windows system error codes (file handling) Additional information This function works for Twinsafe and TCR Twinsafe. Cross-references Upload TCR Twin SafelLog (entire log) This

108

539.1261/3 Version 5.02

27 June 2012


76 TCRTS get daylight saving time - TSC_FGetDLSTimes Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_TSC_FGetDLSTimes ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_TSDLSTResponse lpDLSTimes) ; This function receives the information when the daylight saving will start and end. The adjustment (1 hour in most cases) is also returned. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDLSTimes A pointer to the data structure receiving information when daylight saving time will start and end. The structure stores this information in an array. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references Set date and time This

27 June 2012

539.1261/03 DRAFT Version 5.02

109

TCR Twin Safe TSAPI Interface Description

77

TCRTS set daylight saving time - TSC_FSetDLSTimes Function prototype TSCStatusType DLL_FUNC TSC_FSetDLSTimes ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_TSDLSTResponse lpDLSTimes) ; This function allows the application to program the TCR Twin Safe to switch the system time when daylight saving time starts or ends. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDLSTimes A pointer to the data structure containing the dates and times and adjustments when daylight saving time starts or ends. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references Get date and time This

110

539.1261/3 Version 5.02

27 June 2012


78 TCRTS download generic data - TSC_FWriteData Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FWriteData( PTSC_TellerInfo const lpTellerInfo, TSCIndexNumber const Item, TSCDataLength const NbrOfBytes, TSCData const Data, PTSC_BasicEventData lpBasicEventData); This function allows the application to store generic user data to the TCR Twin Safe. There are 16 slots available to write strings with a maximum length of 128 bytes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Item The parameter Item specifies the slot number, where the string should be stored. Any number between 1 and 16 is valid for this parameter. NbrOfBytes This parameter specifies the length of the data string that should be stored. Possible values are 0 to 128. Data A pointer to the data string, which will be stored in the TCR Twin Safe. The maximum string length is 128 bytes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

27 June 2012

539.1261/03 DRAFT Version 5.02

111

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references TCRTS upload generic data.

112

539.1261/3 Version 5.02

27 June 2012


79 TCRTS upload generic data - TSC_FReadData Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FReadData( PTSC_TellerInfo const lpTellerInfo, TSCIndexNumber const Item, TSCDataLength *NbrOfBytes, TSCData Data, PTSC_BasicEventData lpBasicEventData); This function allows the application to store generic user data to the TCR Twin Safe. There are 16 slots available to write strings with a maximum length of 128 bytes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Item The parameter Item specifies the slot number, where the string should be stored. Any number between 1 and 16 is valid for this parameter. NbrOfBytes The maximum length of the data string that can be uploaded to the Data buffer. Possible values are 0 to 128. Output parameters NbrOfBytes The length of the data string that was uploaded will be returned in this parameter. Possible values are 0 to 128. Data A pointer to a string buffer, where the uploaded string should be stored. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

27 June 2012

539.1261/03 DRAFT Version 5.02

113

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references TCRTS download generic data.

114

539.1261/3 Version 5.02

27 June 2012


80 TCRTS claim sync semaphore - TSC_FClaimSyncSemaphore Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FClaimSyncSemaphore ( PTSC_TellerInfo const lpTellerInfo, TSCDelayType timeout, PTSC_BasicEventData lpBasicEventData, TSCHandle *handle); This function allows the application to get a synchronization semaphore that is provided by the TCR Twin Safes MCU. This semaphore can be used to avoid concurrent access to the generic data with TSC_FReadData and TSC_FWriteData. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. timeout The maximum delay time in milliseconds to get the synchronization semaphore. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. handle The handle of the semaphore will be returned in this parameter. If the function failed to claim the semaphore the returned handle is 0. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references TCRTS release sync semaphore. This

27 June 2012

539.1261/03 DRAFT Version 5.02

115

TCR Twin Safe TSAPI Interface Description

81

TCRTS release sync semaphore - TSC_FReleaseSyncSemaphore Function prototype TSCStatusType DLL_FUNC TSC_FReleaseSyncSemaphore ( PTSC_TellerInfo const lpTellerInfo, TSCHandle handle PTSC_BasicEventData lpBasicEventData ); This function allows the application to release the previously claimed synchronization semaphore that is provided by the TCR Twin Safes MCU. This semaphore can be used to avoid concurrent access to the generic data with TSC_FReadData and TSC_FWriteData. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. handle The handle of the semaphore that should be released. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references TCRTS claim sync semaphore. This

116

539.1261/3 Version 5.02

27 June 2012


82 83 TCR ES specific functions Function prototype

TCR Twin Safe TSAPI Interface Description

Deposit arbitrary objects with given noteid - TSC_FDepositObjects2

TSCStatusType DLL_API TSC_FDepositObjects2 ( PTSC_TellerInfo const lpTellerInfo, TSC_DEPOSIT_EXT *lpDepositInputData, PTSC_BasicEventData lpBasicEventData, PTSCNumberOfObjects lpObjects); The deposit objects function allows a calling application to deposit an arbitrary object into the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDepositInputData A pointer to a data structure, containing the amount, number of the objects, the note identification number and the destination RSM. The note identification number can be used instead of specifying an amount. Output parameters lpObjects A pointer to a variable, containing the number of deposited objects. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references TSC_FDepositObjects This

27 June 2012

539.1261/03 DRAFT Version 5.02

117

TCR Twin Safe TSAPI Interface Description 84 85 TCR ECO specific functions Get all RSM assignments TSC_FGetAllRSMAssignmentsEco Function prototype TSCStatusType DLL_API TSC_FGetAllRSMAssignmentsEco( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_RSM_ECO_ASSIGNMENT_LIST pRSMECOAssignmentList);

The TSC_FGetAllRSMAssignmentEco function returns the assignment information for all RSMs. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. pRSMECOAssignmentList A pointer to a data structure TSC_RSM_ECO_ASSIGNMENT_LIST, containing the assignment information for each assigned RSM. The attribute numRSMs has to be set to a number between 1 and 8 before the function is called. This parameter specifies the number of RSMs to be queried. Output parameters pRSMECOAssignmentList A pointer to a data structure TSC_RSM_ECO_ASSIGNMENT_LIST, containing the assignment information for each assigned RSM. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information The use of this function is restricted to the new TCR TS generation (Eco and more). Cross-references None This

118

539.1261/3 Version 5.02

27 June 2012


86 Set all RSM assignments TSC_FSetAllRSMAssignmentsEco Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FSetAllRSMAssignmentsEco( PTSC_TellerInfo const lpTellerInfo, PTSC_RSM_ECO_ASSIGNMENT_LIST pRSMECOAssignmentList PTSC_BasicEventData lpBasicEventData); The TSC_FSetAllRSMAssignmentEco function sets the assignment information for all RSMs. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. pRSMECOAssignList A pointer to a data structure TSC_RSM_ECO_ASSIGNMENT_LIST, containing the assignment information for each assigned RSM. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information The use of this function is restricted to the new TCR TS generation (Eco and more). Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

119

TCR Twin Safe TSAPI Interface Description 87 88 TCR ES and ECO specific functions Get RSM note stack details TSC_FGetRSMNoteStackDetails Function prototype

TSCStatusType DLL_API TSC_FGetRSMNoteStackDetails ( PTSC_TellerInfo const lpTellerInfo, TSCRSMType rsmNumber, PTSC_RSM_NOTESTACK_DETAILS_LIST lpRSMNoteStackDetailsList, PTSC_BasicEventData lpBasicEventData);

The TSC_FGetRSMNoteStackDetails function returns the note stack details for one RSM Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. rsmNumber The selected RSM. Output parameters lpRSMNoteStackDetailsList A pointer to a data structure TSC_RSM_NOTESTACK_DETAILS_LIST, containing the note stack details for the selected RSM. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information The use of this function is restricted to the new TCR TS generation (ES, Eco and more). Cross-references None This

120

539.1261/3 Version 5.02

27 June 2012


89 90 TCR ERF compatible Get ERF mode TSC_FGetErfMode Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FGetErfMode( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_ERFMode pERFMode); The application will receive information about the ERF mode. 0 ERF Mode disabled 1 ERF Mode enabled (Standard) 2 ERF Mode enabled (Integrated) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

pDepositOutData A pointer to a data structure containing all requested information. (cf. TSC_ERFMode. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. The use of this function is restricted to TCR which are ERF compatible. Cross-references

27 June 2012

539.1261/03 DRAFT Version 5.02

121

TCR Twin Safe TSAPI Interface Description

91

Set ERF mode TSC_FSetErfMode Function prototype TSCStatusType DLL_API TSC_FSetErfMode( PTSC_TellerInfo const lpTellerInfo, PTSC_ERFMode pERFMode, PTSC_BasicEventData lpBasicEventData); To set the ERF mode. 0 ERF Mode disabled 1 ERF Mode enabled (Standard) 2 ERF Mode enabled (Integrated) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. pERFMode A pointer to the new erf mode. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. The use of this function is restricted to TCR which are ERF compatible. Cross-references This

122

539.1261/3 Version 5.02

27 June 2012


92

TCR Twin Safe TSAPI Interface Description

Deposit - TSC_FDepositErf (general purpose with/without amount, note stack, reject flag and ERF flag)

Function prototype TSCStatusType DLL_API TSC_FDepositErf( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DEPOSIT_INPUT lpDepositInData, PTSC_DEPOSIT_OUTPUT pDepositOutData); The application will receive information about the notes deposited and whether any TCR Twin Safe error occurred while processing the notes. This function will fail unless a successful Start Deposit function call has been made with the same teller information. If any notes are rejected and placed in the TCR Twin Safe's dispense hopper, the TCR Twin Safe response will not be available until those notes have been retrieved by the teller. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. lpDepositInData A pointer to a data structure containing flags to specify if the deposit function should return information about amounts, note stack, rejected notes. And finally if the function deposit should run in ERF mode or not. If this flag is FALSE all notes are deposited to the target RSM. If erfMode is TRUE the counterfeit and suspect notes are returned to the output tray. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

pDepositOutData A pointer to a data structure containing all requested information. (cf. TSC_DEPOSIT_OUTPUT Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information The TCR Twin Safe will no longer be reserved once this transaction has completed. 123

27 June 2012

539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description

The use of this function is restricted to TCR which are ERF compatible. Cross-references

124

539.1261/3 Version 5.02

27 June 2012


93 Deposit arbitrary objects - TSC_FDepositObjectsErf (general purpose with/without assigned note Id and ERF flag) Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FDepositObjectsErf ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_DEPOSIT_OBJECT_INPUT lpDepositObjectsInData, PTSC_DEPOSIT_OBJECT_OUTPUT pDepositObjectsOutData); The deposit objects function allows a calling application to deposit an arbitrary object into the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDepositObjectsInData A pointer to a data structure, containing the amount, the destination RSM, number of the objects, the note identification number and the erf flag. The note identification number can be used instead of specifying an amount.

Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. pDepositObjectsOutData A pointer to a structure, containing the number of deposited objects and the erf flag Return value Possible return values are: TSC_SUCCESS Additional information The use of this function is restricted to the TCR which are ERF compatible Cross-references

27 June 2012

539.1261/03 DRAFT Version 5.02

125

TCR Twin Safe TSAPI Interface Description

94

Read one note (single note separation) - TSC_FReadOneNote Function prototype TSCStatusType DLL_FUNC TSC_FReadOneNote( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, BOOL bDeposit, PTSC_ERF_CLASSIFICATION lpErfInfo); This function will fail unless a successful Start deposit function call has been made with the same teller information. This function separates one note from the input tray and returns it to the TCRs output tray. The application will receive information about the note separated and whether any TCR Twin Safe error occurred while processing the note. The TCR Twin Safe response will not be available until the note has been retrieved by the teller. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. bDeposit 0 Is an ERF Check the note is sent to the output compartment 1 Is like a deposit; the note is stored in the safe if the decision is ok Remark: the member RSM_Number of the TSC_ERF_CLASSIFICATION structure informs on which RSM the note is stored. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. lpErfInfot A pointer to a structure containing the details of the processed note. (NoteId, Staff_ECBCategory, Customer_ECBCategory, Presentation, NoteValue, Currency, NoteModel, SDA_Category, SDA_Fitness, RSM_Number)

Return value Possible return values are: TSC_SUCCESS

126

539.1261/3 Version 5.02

27 June 2012


Additional information

TCR Twin Safe TSAPI Interface Description If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure.

The TCR Twin Safe will no longer be reserved once this transaction has completed. The use of this function is restricted to the new TCR TS generation (Eco and more).

Cross-references Deposit object Extended deposit

27 June 2012

539.1261/03 DRAFT Version 5.02

127

TCR Twin Safe TSAPI Interface Description

Start

Start extended deposit TSC_FExtStartDeposit (Cmd 100105)

Put notes into input tray

Query input tray sensor TSC_FNoteInputQuery (Cmd 100510) The user should have the possibility to abort this loop No Notes in input tray ? Yes Deposit3 TSC_FDeposit3 (Cmd 100106) Yes

No

Error occured ?

Yes

Take the rejected notes

Error handler

Query output tray sensor TSC_FPollOutputCassette (Cmd 100116) Yes Yes Notes in output tray ? No

No

Event status >= 3 Yes Take the counted (accepted) notes Take the jammed notes when purge has finished

erfFlag ?

Yes Put the rejected notes into input tray Yes Single note separation TSC_FSingleNoteSeparation (Cmd 100110) Notes in output tray ? Continue counting? Query output tray sensor TSC_FPollOutputCassette (Cmd 100116) Start self test TSC_FTest (Cmd 100140)

No

Take the separated note

Query output tray sensor TSC_FPollOutputCassette (Cmd 100116) Yes Notes in output tray ? No Query input tray sensor TSC_FNoteInputQuery (Cmd 100510)

No

Yes

Notes in input tray ? No Continue deposit? No End deposit TSC_FEndDeposit (Cmd 100107) No

End

128

539.1261/3 Version 5.02

27 June 2012


95 96 Standard instruction set functions Open safe door - TSC_FOpenDoor Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FOpenDoor ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData) ; This unlocks the TCR Twin Safe door lock after the configured delay. After the configured door unlocking time, the lock is relatched even if the door is still open. To close the TCR Twin Safe, a second call must be made to the Open Door function in order to release the lock for a second time. Due to the configurable nature of the security delays it is not possible to predict how long this transaction might take, but the calling application will be blocked throughout this interval. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None. This

27 June 2012

539.1261/03 DRAFT Version 5.02

129

TCR Twin Safe TSAPI Interface Description

97

Copy data files TSC_FCopyDataFiles Function prototype TSCStatusType DLL_FUNC TSC_FCopyDataFiles ( PTSC_TellerInfo const lpTellerInfo, AscomCopyFileType eFileType, PTSC_BasicEventData lpBasicEventData) ; This function copies the specified category of TCR Twin Safe files to or from the TCR Twin Safe's flash card socket. Refer to the TCR Twin Safe documentation for a discussion of these file types and the permitted values. The safe door must be open before this instruction so that a flash card can be inserted into the TCR Twin Safe flash card socket. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. eFileType The file category to be copied. Please use only those values defined within the enumeration type AscomCopyFileType. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Asynchronous copy data files This

130

539.1261/3 Version 5.02

27 June 2012


98 SafeMaster consultation total TSC_FSMConsTotal Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSMConsTotal ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_SMConsultResponse lpSMConsultResponse) ; This function retrieves information about all SafeMaster drawers configured for the specified side. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMConsultResponse A pointer to a data structure containing the SafeMaster Consultation information. The currency text field will not be filled in the response, it will be set to an empty string. The DrawerNum fields will not be filled in by this call, they will be set to zero. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None. This

27 June 2012

539.1261/03 DRAFT Version 5.02

131

TCR Twin Safe TSAPI Interface Description

99

SafeMaster consultation currency code - TSC_FSMConsCurr Function prototype TSCStatusType DLL_FUNC TSC_FSMConsCurr ( PTSC_TellerInfo const lpTellerInfo, char *lpszCurrencyCode, PTSC_BasicEventData lpBasicEventData, PTSC_SMConsultResponse lpSMConsultResponse) ; This function retrieves information about all SafeMaster drawers configured for the specified side with the specified currency. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszCurrencyCode A pointer to null-terminated string containing the currency code. TCR Twin Safe currency codes are fixed length and may contain both letters and characters. Currency codes will be padded with trailing spaces but may not contain embedded spaces. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMConsultResponse A pointer to a data structure containing the SafeMaster consultation information. The currency code fields for each drawer will not be filled in the response, they will be set to empty strings. This

132

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None.

27 June 2012

539.1261/03 DRAFT Version 5.02

133

TCR Twin Safe TSAPI Interface Description

100

SafeMaster cancel movements - TSC_FSMCancelMovements Function prototype TSCStatusType DLL_FUNC TSC_FSMCancelMovements ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData) ; This function resets the moved flags for all drawers assigned to the specified side. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None. This

134

539.1261/3 Version 5.02

27 June 2012


101 SafeMaster unlock - TSC_FSMUnlock Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSMUnlock ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData) ; After the SafeMaster unlocking delay, all the drawers are unlocked one at a time starting with the first. Once the first drawer has been closed the second is released and so on. It is not possible to abort this sequence once it has started other than by waiting for the drawer open timer to expire. If no action is taken within the time-out period, the drawers are relocked. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Asynchronous SM unlock. This

27 June 2012

539.1261/03 DRAFT Version 5.02

135

TCR Twin Safe TSAPI Interface Description

102

SafeMaster open drawer - TSC_FSMOpenDrawer Function prototype TSCStatusType DLL_FUNC TSC_FSMOpenDrawer ( PTSC_TellerInfo const lpTellerInfo, TSCDrawerNumber DrawerNumber, PTSC_BasicEventData lpBasicEventData) ; After the SafeMaster drawer delay, the specified drawer is unlocked for the configured time. After the time-out period, if no activity has taken place the drawer is re-locked. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. DrawerNumber The number of the drawer to be opened. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Asynchronous SM open drawer. This

136

539.1261/3 Version 5.02

27 June 2012


103 SafeMaster deposit - TSC_FSMDeposit Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSMDeposit ( PTSC_TellerInfo const lpTellerInfo, PTSC_SM_CurrData const lpCurrData, PTSC_BasicEventData lpBasicEventData) ; The specified amount is added to the SafeMaster deposit totals for the specified drawer. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpCurrData A pointer to a data structure defining the currency, index within that currency and amount to be added to the SafeMaster deposit totals. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None. This

27 June 2012

539.1261/03 DRAFT Version 5.02

137

TCR Twin Safe TSAPI Interface Description

104

SafeMaster withdrawal - TSC_FSMWithdrawal Function prototype TSCStatusType DLL_FUNC TSC_FSMWithdrawal ( PTSC_TellerInfo const lpTellerInfo, PTSC_SM_CurrData lpCurrData, PTSC_BasicEventData lpBasicEventData) ; The specified amount is added to the SafeMaster deposit totals for the specified drawer. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpCurrData A pointer to a data structure defining the currency, index within that currency and amount to be added to the SafeMaster deposit totals. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None. This

138

539.1261/3 Version 5.02

27 June 2012


105 Statistics functions

TCR Twin Safe TSAPI Interface Description

Statistical information will be collated during a single program run. Other than log files (which are optional) the TCR Twin Safe Handler never writes to disk files so any statistical data will be lost when an application program terminates. The following statistical information is collated: Number of deposit transactions Number of withdrawal transactions Total number of notes deposited per RSM Total number of notes withdrawn per RSM Max/min number of notes deposited per RSM Max/min number of notes withdrawn per RSM Number of events by category (i.e. successful, warning, etc.)

27 June 2012

539.1261/03 DRAFT Version 5.02

139

TCR Twin Safe TSAPI Interface Description

106

Clear statistics - TSC_FClearStatistics Function prototype TSCStatusType DLL_FUNC TSC_FClearStatistics ( PTSC_StatisticTypes const lpStatTypes, PTSCStatusType lprc) ; The specified statistics will be reset to zero. If the current logging level is greater than zero, the current values of the statistics will be written to the log file. Input parameters lpStatTypes A pointer to a data structure containing a Boolean flag for each category of statistics. Output parameters lprc A pointer to a return variable. This will hold the same value as the function return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None. Cross-references None.

140

539.1261/3 Version 5.02

27 June 2012


107 Get statistics - TSC_FGetStatistics Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetStatistics ( PTSC_StatisticValues lpStatValues, PTSCStatusType lprc) ; The current values for all the Handler statistics will be returned. Input parameters None. Output parameters lpStatValues A pointer to a data structure containing the numeric data for each category of statistics. lprc A pointer to a return variable. This will hold the same value as the function return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None. Cross-references None.

27 June 2012

539.1261/03 DRAFT Version 5.02

141

TCR Twin Safe TSAPI Interface Description 108 TSAPI administrative functions

TSAPI log information is written to a file. The file will be created if it does not exist. The information in the log file is always appended to any existing data, the file will continue to grow indefinitely if logging is enabled. A invalid filename causes an error. The logging levels are 0 1 4 Logging is disabled. The log file will not be created. Only log statistical information and text send by the function TSC_Flog(). Very detailed diagnostics for DeLaRue technical support personnel.

142

539.1261/3 Version 5.02

27 June 2012


109 Change logging level - TSC_FChangeLoggingLevel Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FChangeLoggingLevel ( TSCLoggingLevel NewLogLevel, PTSCStatusType lprc) ; The specified statistics will be reset to zero. If the current logging level is greater than zero, the current values of the statistics will be written to the log file. Input parameters NewLogLevel If this is not in the permitted range, the return code will be set to TSC_PARAM_INVALID and the current trace level will remain unaltered. Output parameters lprc A pointer to a return variable. This will hold the same value as the function return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None. Cross-references None.

27 June 2012

539.1261/03 DRAFT Version 5.02

143

TCR Twin Safe TSAPI Interface Description

110

Set new log file name - TSC_FNewLogFileName Function prototype TSCStatusType DLL_FUNC TSC_FNewLogFileName ( char *lpszNewFileName, PTSCStatusType lprc) ; Any previous log file will be closed but will not be deleted from the hard disc. If the new log file name is the same as the previous file name then no action will be taken and the returned status will be TSC_SUCCESS. Input parameters lpszNewFileName If this file cannot be created, the return code will be set to TSC_PARAM_INVALID and the current trace file name will remain unaltered. Output parameters lprc A pointer to a return variable. This will hold the same value as the function return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID ERR_OPEN_LOG Additional information None. Cross-references None.

144

539.1261/3 Version 5.02

27 June 2012


111 Add text to log - TSC_FAddToLog Function prototype TSCStatusType DLL_FUNC TSC_FAddToLog ( char *lpszText, PTSCStatusType lprc) ; Input parameters lpszText

TCR Twin Safe TSAPI Interface Description

The text will be added to the log file, with a time stamp taken from the system date and time. Output parameters lprc A pointer to a return variable. This will hold the same value as the function return code. Return value Possible return values are: TSC_SUCCESS Additional information None. Cross-references None.

27 June 2012

539.1261/03 DRAFT Version 5.02

145

TCR Twin Safe TSAPI Interface Description

112

Get DLL version - TSC_FGetVersion Function prototype TSCStatusType DLL_FUNC TSC_FGetVersion( TSC_VERSION *version); The version of the CommDLL will be returned. Input parameters None. Output parameters version A pointer to a data structure containing a pointer to the string buffer and a variable which should be initialized with the size of the string buffer. Return value Possible return values are: TSC_SUCCESS Additional information None. Cross-references None.

146

539.1261/3 Version 5.02

27 June 2012


113 Get TSServer version - TSC_FGetServerVersion Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetServerVersion( PTSC_TellerInfo const lpTellerInfo, TSC_VERSION *version) ; The version of the connected TSServer will be returned. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters version A pointer to a data structure containing a pointer to the string buffer and a variable which should be initialized with the size of the string buffer. Return value Possible return values are: TSC_SUCCESS Additional information This function only returns a valid result when connected thru LAN (TCP/ IP). Cross-references None.

27 June 2012

539.1261/03 DRAFT Version 5.02

147

TCR Twin Safe TSAPI Interface Description

114

Get alarm flag - TSC_FGetAlarmFlag Function prototype TSCStatusType DLL_FUNC TSC_FGetAlarmFlag( PTSC_TellerInfo const lpTellerInfo, TSC_AlarmType *eAlarmFlag) ; This function returns the current alarm flag status. At least one command must be called before this function can be used. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters eAlarmFlag The alarm flag received with the last answer telegram is returned in this parameter. Please refer to the TSC_AlarmType documentation for a list of possible values. Return value Possible return values are: TSC_SUCCESS Additional information None. Cross-references None.

148

539.1261/3 Version 5.02

27 June 2012


115 Shutdown server - TSC_FShutdownServer Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FShutdownServer ( PTSC_TellerInfo const lpTellerInfo, TSCShutdownType shutdownType) ; Call this function to shutdown the embedded PC inside the TCR Twin Safe. Depending on the shutdownType the PC will be rebooted or turned off. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. ShutdownType Specifies if the embedded PC should be rebooted, shutdown or powered off. Output parameters None. Return value Possible return values are: TSC_SUCCESS Additional information This functions works only when connected to a TSServer thru LAN (TCP/ IP). Cross-references None.

27 June 2012

539.1261/03 DRAFT Version 5.02

149

TCR Twin Safe TSAPI Interface Description

116

Reinitialize the TSAPI - TSC_FReInitDLL Function prototype TSCStatusType DLL_FUNC TSC_FReInitDLL () ;

Call this function to force the DLL to close all com ports and to reload the configuration settings. Input parameters None. Output parameters None. Return value Possible return values are: TSC_SUCCESS Additional information None. Cross-references None.

150

539.1261/3 Version 5.02

27 June 2012


117 Set DLL configuration - TSC_FSetDLLConfig Function prototype TSCStatusType DLL_FUNC

TCR Twin Safe TSAPI Interface Description

TSC_FSetDLLConfig (PTSC_DLLConfig pConfig) ;

Call this function to set a new DLL configuration. Internally the ReInitDLL function is used to close all communications and reload the configuration values. Instead of taking the configuration from the HANDLER.INI file (refer to chapter 3.4) the configuration parameters in pConfig are used. The new configuration is activated immediately. It is recommended to call TSC_FGetDLLConfig first to receive a valid configuration. You may then modify the parameters you want to change and set the new configuration. Input parameters pConfig A pointer to a data structure containing the configuration parameters. Please refer to the TSC_DLLConfig documentation for more details. Output parameters None. Return value Possible return values are: TSC_SUCCESS Additional information None. Cross-references TSC_FGetDLLConfig.

27 June 2012

539.1261/03 DRAFT Version 5.02

151

TCR Twin Safe TSAPI Interface Description

118

Get DLL configuration - TSC_FGetDLLConfig Function prototype TSCStatusType DLL_FUNC TSC_FGetDLLConfig (PTSC_DLLConfig pConfig) ;

Call this function to receive the current configuration of the TSAPI. Input parameters None. Output parameters pConfig The configuration parameters of the TSAPI are returned in this data structure. Please refer to the TSC_DLLConfig documentation for more details. Return value Possible return values are: TSC_SUCCESS Additional information None. Cross-references TSC_FSetDLLConfig.

152

539.1261/3 Version 5.02

27 June 2012


119 120 Twin Safe logging functions Function prototype

TCR Twin Safe TSAPI Interface Description

Get information about the TCR Twin Safe log - TSC_FGetLogInfo

TSCStatusType DLL_FUNC TSC_FGetLogInfo ( TSC_LogRequestType eLogRequestType, PASCOM_DateTime const lpStartDateTime, PASCOM_DateTime const lpEndDateTime, PTSC_LogInfo lpLogInfo, PTSC_BasicEventData lpBasicEventData) ; Input parameters eLogRequestType Enumerated value which tells the FLAPI whether general log information is required, information required for a specific day or information required for a specific period. The enumerated values allowed are TSC_GeneralLogDetails, TSC_DayLogDetails, and TSC_RangeLogDetails. lpStartDateTime Address of a Date / Time variable. If general log information is required then this variable is ignored. If information for a specific day is required then this variable should contain the relevant date, the time element of the variable is ignored. If log information for a specific period is required then this variable should contain the start date and time of that period. lpEndDateTime Address of a Date / Time variable. If general log information or information for a specific day is required then this variable is ignored. If log information for a specific period is required then this variable should contain the end date and time of that period. Output parameters lpLogInfo Address of an TSC_LogInfo variable in which is returned the number of lines available in the TCR Twin Safe Log or the number of log entries for a specific day or the number of log entries for a specific period. The variable also contains the first line number and the last line number of the log entries either in total or for a given day or for a given period. Finally this variable also contains the line length of the log entries.

lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

27 June 2012

539.1261/03 DRAFT Version 5.02

153

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS TSC_DATE_INVALID TSC_TIME_INVALID TSC_PARAM_INVALID Additional information

If Log information for a given period is required and the start date/time variable is empty (i.e. set to binary 0s) then the date of the first entry in the log file is used. If Log information for a given period is required and the end date/time variable is empty (i.e. set to binary 0s) then the date/time of the last entry in the log file is used. Cross-references None.

154

539.1261/3 Version 5.02

27 June 2012


121 Add a TCR Twin Safe log entry - TSC_FLog Function prototype TSCStatusType DLL_FUNC TSC_FLog ( PTSC_TellerInfo const char PTSC_BasicEventData

TCR Twin Safe TSAPI Interface Description

lpTellerInfo, *lpszLogText, lpBasicEventData) ;

This function adds the specified text to the TCR Twin Safe log. If the supplied string is too long it will be truncated and the return status will be TSC_PARAM_INVALID unless a TCR Twin Safe error is returned. The truncated text will be written to the TCR Twin Safe log. The C header files include a macro definition for this maximum length, the name of this macro is ASCOM_LOG_LEN. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszLogText A pointer to the null terminated text string to be logged by the TCR Twin Safe. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None. This

27 June 2012

539.1261/03 DRAFT Version 5.02

155

TCR Twin Safe TSAPI Interface Description

122

Get a TCR Twin Safe log entry (TwinSafe format) - TSC_FGetLogLine Function prototype TSCStatusType DLL_FUNC TSC_FGetLogLine ( TSC_LogLineNumber const LogLineNumber, TSC_LogLineText LogLineText, PTSC_BasicEventData lpBasicEventData); This command returns the specified journal line in the old TS-format. Input parameters LogLineNumber The number of the TCR Twin Safe Log line to be returned by this function Output parameters LogLineText Returns specified line of TCR Twin Safe Log. The text returned is null terminated. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information The returned text is in the old TS-format. Cross-references None. This

156

539.1261/3 Version 5.02

27 June 2012


123 Function prototype

TCR Twin Safe TSAPI Interface Description

Get a TCR Twin Safe log entry (TCR Twin Safe format) - TSC_FGetLogLineEx

TSCStatusType DLL_FUNC TSC_FGetLogLineEx ( TSC_LogLineNumber const LogLineNumber, TSC_LogLineText LogLineText, PTSC_BasicEventData lpBasicEventData); This command returns the specified journal line in the new TS2-format. Input parameters LogLineNumber The number of the TCR Twin Safe Log line to be returned by this function Output parameters LogLineText Returns specified line of TCR Twin Safe Log. The text returned is null terminated. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information The returned text is in the new TS2-format. Cross-references None. This

27 June 2012

539.1261/03 DRAFT Version 5.02

157

TCR Twin Safe TSAPI Interface Description

124

Upload TCR Twin Safe log (last n lines) - TSC_FUploadLogXLines Function prototype TSCStatusType DLL_FUNC TSC_FUploadLogXLines ( PTSC_TellerInfo const lpTellerInfo, TSC_LogLineNumber numLines, TSC_UPLOAD_FILENAME lpszLogFilepath, PTSC_BasicEventData lpBasicEventData) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. numLines Number of log lines to be uploaded to a file. This function uploads the newest numLines entries of the log. lpszLogFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Windows system error codes (file handling) Additional information This function works for Twinsafe and TCR Twinsafe. Cross-references Upload ODA file TCR Twin Safe log (last n lines) function call. This

158

539.1261/3 Version 5.02

27 June 2012


125 Upload TCR Twin Safe log (range) - TSC_FUploadLogRange Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FUploadLogRange ( PTSC_TellerInfo const lpTellerInfo, PASCOM_DateTime start, PASCOM_DateTime end, TSC_UPLOAD_FILENAME lpszLogFilepath, PTSC_BasicEventData lpBasicEventData) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpStartDateTime Address of a Date / Time variable. If general log information is required then this variable is ignored. If information for a specific day is required then this variable should contain the relevant date, the time element of the variable is ignored. If log information for a specific period is required then this variable should contain the start date and time of that period. lpEndDateTime Address of a Date / Time variable. If general log information or information for a specific day is required then this variable is ignored. If log information for a specific period is required then this variable should contain the end date and time of that period. lpszLogFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

27 June 2012

539.1261/03 DRAFT Version 5.02

159

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID TSC_DATE_INVALID TSC_TIME_INVALID Windows system error codes (file handling) Additional information This function works for Twinsafe and TCR Twinsafe. Cross-references Upload ODA file & TCR Twin Safe log (range) function call.

160

539.1261/3 Version 5.02

27 June 2012


126 Function prototype

TCR Twin Safe TSAPI Interface Description

Upload TCR Twin Safe log (entire log) - TSC_FUploadLogAllLines

TSCStatusType DLL_FUNC TSC_FUploadLogAllLines ( PTSC_TellerInfo const lpTellerInfo, TSC_UPLOAD_FILENAME lpszLogFilepath, PTSC_BasicEventData lpBasicEventData) Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszLogFilepath A pointer to the null terminated text string that contains the destination file name including the path. If this file does not exist the function will create it, otherwise the file will be overwritten. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Windows system error codes (file handling) Additional information This function works for Twinsafe and TCR Twinsafe. Cross-references Upload ODA file & TCR Twin Safe log (entire log) function call. This

27 June 2012

539.1261/03 DRAFT Version 5.02

161

TCR Twin Safe TSAPI Interface Description 127 Asynchronous functions

For an application there are two possibilities how to detect whether an asynchronous function has already finished or not. The first is to poll the TSAPI with help of the function TSC_FAGetResponse(). The second possibility is to use some means of event handling. For this the TSAPI defines a special placeholder, which is defined as follows: #define TSC_ASYNCREPLYPARAM HANDLE CompletionEventHandle,

This defines a single parameter, the handle of an event. An appropriate event handle is returned by a call to the system function Windows OS/2 WindowsCreateEvent (NULL, FALSE, FALSE, (LPSTR) NULL) ; DosCreateEventSem ( NULL, &event, 0L, FALSE );

The calling application can pass this handle to the system call WaitForSingleObject() (OS/2: DosWaitEventSem(event, WAIT_TIME_ASYNCHRON);) which will return when the asynchronous transaction has completed. The calling object can then call TSC_FAGetResponse() (see below) to get the results of the transaction. Alternatively the calling application may repeatedly call TSC_FAGetResponse() until the reply from this function indicates that the transaction has completed. If the event handle is created as shown above then the event is automatically reset after it has been signaled and therefore the calling application has no need to reset it before re-using the event handle for a subsequent asynchronous FLAPI call.

162

539.1261/3 Version 5.02

27 June 2012


128 Asynchronous get response - TSC_FAGetResponse Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FAGetResponse ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSC_AsyncResponseData lpResponse) ; This function call is made whenever an application needs to recover the data following an asynchronous API call. Since this function call returns data from any of the asynchronous function calls of the FLAPI, the returned data is returned to an untyped data buffer which is interpreted as being of the appropriate type. This function call checks that the buffer size is sufficient for the information to be written, else an error response is generated. It is the responsibility of the calling routine to ensure that there is sufficient memory allocated to the buffer so that the expected response may be written without generating an access violation. Input parameters lpTellerInfo A pointer to a data structure containing the same information as was used in the preceding asynchronous call for which the response is requested. This ensures that one application does not erroneously recover data belonging to another application. Output parameters lpBasicEventData A pointer to a data structure containing the various status codes from the TCR Twin Safe. This structure also contains a copy of the function's return code. The data structure pointed to by lpResponse. This structure contains a field defining the operation for which the response has been returned, and a pointer buffer to a buffer whose contents are structured according to the formal parameters to the equivalent synchronous calls. For example, the buffer will be structured as a TSC_DispenseData if the operation type is TSWithdrawal. Note that for some asynchronous calls, the buffer is not used. All the returned data is returned via the lpBasicEventData parameter.

27 June 2012

539.1261/03 DRAFT Version 5.02

163

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS TSC_NO_SUCH_TRANSACTION ERR_DATA_BUFFER_TO_SMALL

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information This function may be used to poll for a response from the TCR Twin Safe. If a previous response has not been collected, it will be overwritten by a new response for the same teller. Cross-references All asynchronous FLAPI function calls and their corresponding synchronous calls.

164

539.1261/3 Version 5.02

27 June 2012


129 Asynchronous deposit - TSC_FADeposit Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FADeposit ( PTSC_TellerInfo const lpTellerInfo, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the Synchronous Deposit function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. It must match the information in the preceding Start Deposit call. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a return variable containing the same value as the function return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information Refer to the description of the synchronous function. Cross-references Start deposit Deposit Cancel deposit Asynchronous get response

27 June 2012

539.1261/03 DRAFT Version 5.02

165

TCR Twin Safe TSAPI Interface Description

130

Asynchronous withdrawal - TSC_FAWithdrawal Function prototype TSCStatusType DLL_FUNC TSC_FAWithdrawal ( PTSC_TellerInfo const lpTellerInfo, PTSC_DispenseData const lpWithdrawalData, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpWithdrawalData A pointer to a data structure defining the numbers of notes to be dispensed from each RSM. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a variable containing the same value as the function return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Withdrawal Asynchronous get response

166

539.1261/3 Version 5.02

27 June 2012


131 Asynchronous cash balancing - TSC_FACashBalancing Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FACashBalancing ( PTSC_TellerInfo const lpTellerInfo, BOOL const ResetCounters, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. ResetCounters When set to TRUE, the TCR Twin Safe counters are reset after retrieving the cash balance. If FALSE, the counters are not reset and a subsquent request will include the balance already reported in the previous call. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a variable containing the same value as the function return code.

27 June 2012

539.1261/03 DRAFT Version 5.02

167

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Cash balancing Asynchronous get response

168

539.1261/3 Version 5.02

27 June 2012


132 Asynchronous empty RSM - TSC_FAEmptyRSM Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FAEmptyRSM ( PTSC_TellerInfo const lpTellerInfo, PTSC_EmptyRSMParams lpEmptyRSMParams, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpEmptyRSMParams The RSM number and the Boolean flag for optional disabling of the TCR Twin Safe security delay. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a variable containing the same value as the function return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references Empty roll storage module Asynchronous get response

27 June 2012

539.1261/03 DRAFT Version 5.02

169

TCR Twin Safe TSAPI Interface Description

133

Asynchronous system status - TSC_FASystemStatus Function prototype TSCStatusType DLL_FUNC TSC_FASystemStatus ( PTSC_TellerInfo const lpTellerInfo, TSCSensorTest TestSensors, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. TestSensors A flag indicating whether the TCR Twin Safe should perform an internal test of its probes and return the ID's of up to ten or even 50 faulty components. If this flag is set to TSC_NoSensors, the probe ID field in the response will be filled with spaces. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a return variable containing the same value as the function return code.

170

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information This function call definition is not compatible to the NCI Twin Safe Handler DLL. Cross-references System status Asynchronous get response

27 June 2012

539.1261/03 DRAFT Version 5.02

171

TCR Twin Safe TSAPI Interface Description

134

Asynchronous self-test/ purge - TSC_FATest Function prototype TSCStatusType DLL_FUNC TSC_FATest ( PTSC_TellerInfo const TSC_ASYNCREPLYPARAM, TSCStatusType lpTellerInfo, *lprc) ;

For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a return variable containing the same value as the function return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references Self-test/ purge Asynchronous self-test/ purge (extended) Asynchronous get response

172

539.1261/3 Version 5.02

27 June 2012


135 Asynchronous TCRTS self-test/ purge - TSC_FATestExt Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FATestExt ( PTSC_TellerInfo const lpTellerInfo, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a return variable containing the same value as the function return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references TCRTS self-test/ purge Asynchronous self-test/ purge Asynchronous get response

27 June 2012

539.1261/03 DRAFT Version 5.02

173

TCR Twin Safe TSAPI Interface Description

136

Asynchronous copy data files - FACopyDataFiles Function prototype TSCStatusType DLL_FUNC TSC_FACopyDataFiles ( PTSC_TellerInfo const lpTellerInfo, AscomCopyFileType eFileType, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. eFileType The file category to be copied. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a variable containing the same value as the function return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None Cross-references Copy data files Asynchronous get response

174

539.1261/3 Version 5.02

27 June 2012


137 Asynchronous SM unlock - TSC_FASMUnlock Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FASMUnlock ( PTSC_TellerInfo const lpTellerInfo, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a return variable containing the same value as the function return code. Return value Possible return values are: TSC_SUCCESS If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references SM unlock Asynchronous get response

27 June 2012

539.1261/03 DRAFT Version 5.02

175

TCR Twin Safe TSAPI Interface Description

138

Asynchronous SM open drawer - TSC_FASMOpenDrawer Function prototype TSCStatusType DLL_FUNC TSC_FASMOpenDrawer ( PTSC_TellerInfo const lpTellerInfo, TSCDrawerNumber DrawerNumber, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc) ; For a discussion on this function and the response data that is retrieved by calling the Asynchronous Get Response function, please refer to the section on the equivalent synchronous function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. DrawerNumber The number of the drawer to be opened. TSC_ASYNCREPLYPARAM See the description for the appropriate operating system in section 4.5.1 above. Output parameters lprc A pointer to a variable containing the same value as the function return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references SM open drawer. Asynchronous get response

176

539.1261/3 Version 5.02

27 June 2012


139 Asynchronous functions (TCR Eco specific) TSCStatusType DLL_API TSC_FADepositErf( PTSC_TellerInfo const lpTellerInfo, PTSC_DEPOSIT_INPUT lpDepositInData, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc);

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API TSC_FADepositObjectsErf ( PTSC_TellerInfo const lpTellerInfo, PTSC_DEPOSIT_OBJECT_INPUT depositInputData, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc); TSCStatusType DLL_API TSC_FAReadOneNote ( PTSC_TellerInfo const lpTellerInfo, TSC_ASYNCREPLYPARAM, TSCStatusType *lprc); TSCStatusType DLL_API TSC_FAGetAllRSMAssignmentsEco ( PTSC_TellerInfo const lpTellerInfo, TSC_ASYNCREPLYPARAM, TSCStatusType * lprc); TSCStatusType DLL_API TSC_FASetAllRSMAssignmentsEco ( PTSC_TellerInfo const lpTellerInfo, PTSC_RSM_ECO_ASSIGNMENT_LIST pRSMECOAssignmentList, TSC_ASYNCREPLYPARAM, TSCStatusType * lprc);

27 June 2012

539.1261/03 DRAFT Version 5.02

177

TCR Twin Safe TSAPI Interface Description 140 141 Authorisation functions Add user - TSC_FAddUser Function prototype TSCStatusType DLL_FUNC TSC_FAddUser ( PTSC_TellerInfo const lpTellerInfo, PTSC_NewTellerInfo const lpNewTellerInfo, PTSC_BasicEventData lpBasicEventData) ;

The Add User function allows a calling application to add a new user ID to the TCR Twin Safe authorisation database. Input parameters lpTellerInfo A pointer to a data structure defining a user with sufficient privilege (i.e. user level) for the operation. The TCR Twin Safe uses this for validation purposes. lpNewTellerInfo A pointer to a data structure defining the new user. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

178

539.1261/3 Version 5.02

27 June 2012


142 Delete user - TSC_FDeleteUser Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FDeleteUser ( PTSC_TellerInfo const lpTellerInfo, PTSC_NewTellerInfo const lpDeleteTellerInfo, PTSC_BasicEventData lpBasicEventData) ; The Delete User function allows a calling application to delete an existing user ID from the TCR Twin Safe authorisation database. Input parameters lpTellerInfo A pointer to a data structure defining a user with sufficient privilege (i.e. user level) for the operation. The TCR Twin Safe uses this for validation purposes. lpDeleteTellerInfo A pointer to a data structure defining the user to be deleted. Only the user ID and level are required, the password field is ignored by this API call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

27 June 2012

539.1261/03 DRAFT Version 5.02

179

TCR Twin Safe TSAPI Interface Description

143

Get user - TSC_FGet User Function prototype TSCStatusType DLL_FUNC TSC_FGet User ( PTSC_TellerInfo const lpTellerInfo, PASCOMUserList lpUserList, PTSC_BasicEventData lpBasicEventData) ; The GetUser function allows a calling application to retrieve the IDs of all the user IDs of the given level from the TCR Twin Safe authorisation database. Input parameters lpTellerInfo A pointer to a data structure defining a user with sufficient privilege (i.e. user level) for the operation. The TCR Twin Safe uses this for validation purposes. lpUserList A pointer to a data structure containing the user level for which the list is required. Output parameters lpUserList A pointer to a data structure filled with the list of known user IDs. There is also a field containing the number of IDs returned. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

180

539.1261/3 Version 5.02

27 June 2012


144 Validate user - TSC_FValidateUser Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FValidateUser ( PTSC_TellerInfo const lpTellerInfo, char * const lpszPassword, PTSC_BasicEventData lpBasicEventData) ; The Validate User function allows a calling application to ensure that the entered teller ID and password match those declared in the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszPassword A pointer to null-terminated string containing the PIN. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

27 June 2012

539.1261/03 DRAFT Version 5.02

181

TCR Twin Safe TSAPI Interface Description 145 146 Currency data Get currency data - TSC_FGetCurrencyData Function prototype TSCStatusType DLL_FUNC TSC_FGetCurrencyData ( PTSC_TellerInfo const lpTellerInfo, PTSC_CurrencyData const lpCurrencyData, PTSC_BasicEventData lpBasicEventData) ;

The Get Currency Data function allows a calling application to modify an existing currency definition. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpCurrencyData A pointer to a data structure that defines the currency to be retrieved. Only the szCurrencyCode field is required. Note that the length of the szCurrencyCode field is as specified in this document, certain versions of the DeLaRue documentation are incorrect. Output parameters lpCurrencyData A pointer to a data structure that holds the returned currency data. All fields are updated except szCurrencyCode. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references Get next currency data

182

539.1261/3 Version 5.02

27 June 2012


147 Get next currency data - TSC_FGetNextCurrencyData Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetNextCurrencyData ( PTSC_TellerInfo const lpTellerInfo, PTSC_CurrencyData const lpCurrencyData, PTSC_BasicEventData lpBasicEventData) ; The Get Next Currency Data function allows a calling application to modify an existing currency definition. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpCurrencyData A pointer to a data structure that defines the preceding currency. Only the szCurrencyCode field is required. Note that the length of the szCurrencyCode field is as specified in this document, certain versions of the DeLaRue documentation are incorrect. Output parameters lpCurrencyData A pointer to a data structure that holds the returned currency data. All fields are updated, including szCurrencyCode. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references Get currency data

27 June 2012

539.1261/03 DRAFT Version 5.02

183

TCR Twin Safe TSAPI Interface Description

148

Add currency data - TSC_FAddCurrencyData Function prototype TSCStatusType DLL_FUNC TSC_FAddCurrencyData ( PTSC_TellerInfo const lpTellerInfo, PTSC_CurrencyData const lpCurrencyData, PTSC_BasicEventData lpBasicEventData) ; The Add Currency Data function allows a calling application to define a new currency to the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpCurrencyData A pointer to a data structure that defines the new currency. Note that the length of the szCurrencyCode field is as specified in this document, certain versions of the DeLaRue documentation are incorrect. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

184

539.1261/3 Version 5.02

27 June 2012


149 Update currency data - TSC_FUpdateCurrencyData Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FUpdateCurrencyData ( PTSC_TellerInfo const lpTellerInfo, PTSC_CurrencyData const lpCurrencyData, PTSC_BasicEventData lpBasicEventData) ; The Update Currency Data function allows a calling application to modify an existing currency definition. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpCurrencyData A pointer to a data structure that defines the currency to be modified. Note that the length of the szCurrencyCode field is as specified in this document, certain versions of the DeLaRue documentation are incorrect. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

27 June 2012

539.1261/03 DRAFT Version 5.02

185

TCR Twin Safe TSAPI Interface Description

150

Delete currency data - TSC_FDeleteCurrencyData Function prototype TSCStatusType DLL_FUNC TSC_FDeleteCurrencyData ( PTSC_TellerInfo const lpTellerInfo, PTSC_CurrencyData const lpCurrencyData, PTSC_BasicEventData lpBasicEventData) ; The Delete Currency Data function allows a calling application to remove an existing currency definition. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpCurrencyData A pointer to a data structure that defines the currency. Only the szCurrencyCode field is required. Note that the length of the szCurrencyCode field is as specified in this document, certain versions of the DeLaRue documentation are incorrect. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

186

539.1261/3 Version 5.02

27 June 2012


151 152 Delay times Get withdrawal delay - TSC_FGetWithdrawalDelay Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetWithdrawalDelay ( PTSC_TellerInfo const pTellerInfo, PTSC_DispenseData const pWithdrawalData, PTSC_BasicEventData pBasicEventData, PTSCDelayType pDispenseDelay) ; This function allows an application to determine how long it will have to wait before the specified withdrawal would commence. This information could then be displayed to the user if it exceeded a programmed threshold. Input parameters pTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. pWithdrawalData A pointer to a data structure defining the numbers of notes to be dispensed from each RSM. Output parameters pBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. pDispenseDelay A pointer to the delay that will occur should the suggested transaction be undertaken. This

27 June 2012

539.1261/03 DRAFT Version 5.02

187

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information None. Cross-references None

188

539.1261/3 Version 5.02

27 June 2012


153 Get num delay classes - TSC_FGetNumDelayClasses Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetNumDelayClasses ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCCountType lpNumDelayClasses) ; The Get Num Delay Classes function allows a calling application to determine the programmed variable delays and the range of dispense amounts over which they apply. There may be zero or more defined classes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpNumDelayClasses A pointer to a variable which will be updated with the number of defined delay classes. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

27 June 2012

539.1261/03 DRAFT Version 5.02

189

TCR Twin Safe TSAPI Interface Description

154

Set num delay classes - TSC_FSetNumDelayClasses Function prototype TSCStatusType DLL_FUNC TSC_FSetNumDelayClasses ( PTSC_TellerInfo const lpTellerInfo, TSCCountType NumDelayClasses, PTSC_BasicEventData lpBasicEventData) ; The Set Num Delay Classes function allows a calling application to change the number of programmed variable delays and the range of dispense amounts over which they apply. There may be zero or more defined classes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. NumDelayClasses The new number of defined delay classes. This value must lie between 1 and 10 Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None

190

539.1261/3 Version 5.02

27 June 2012


155 Get delay class params - TSC_FGetDelayClassParams Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetDelayClassParams ( PTSC_TellerInfo const lpTellerInfo, PTSCDelayClassParams lpDelayClassParams, PTSC_BasicEventData lpBasicEventData) ; The Get Delay Class Params function allows a calling application to retrieve the settings for a particular programmed variable delays and the range of dispense amounts over which they apply. There may be zero or more defined classes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDelayClassParams A pointer to a data structure containing the index of the requested delay class. Output parameters lpDelayClassParams A pointer to a data structure containing the returned data. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

191

TCR Twin Safe TSAPI Interface Description

156

Set delay class params - TSC_FSetDelayClassParams Function prototype TSCStatusType DLL_FUNC TSC_FSetDelayClassParams ( PTSC_TellerInfo const lpTellerInfo, PTSCDelayClassParams lpDelayClassParams, PTSC_BasicEventData lpBasicEventData) ; The Set Delay Class Params function allows a calling application to update the settings for a particular programmed variable delays and the range of dispense amounts over which they apply. There may be zero or more defined classes. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDelayClassParams A pointer to a data structure containing the new information for the requested delay class. Only the upper limits can be set, the TCR Twin Safe sets the lower limit and delay by reference to the preceding delay class. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

192

539.1261/3 Version 5.02

27 June 2012


157 158 System language Get system language - TSC_FGetSystemLanguage Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetSystemLanguage ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, char *lpszSystemLanguage) ; The Get System Language function allows a calling application to determine the current language in which the TCR Twin Safe logs events. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. lpszSystemLanguage A pointer to a buffer for a null-terminated string of at least TSC_NATIONALITY_LEN+1 characters which will be updated with the current TCR Twin Safe language. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

27 June 2012

539.1261/03 DRAFT Version 5.02

193

TCR Twin Safe TSAPI Interface Description

159

Set system language - TSC_FSetSystemLanguage Function prototype TSCStatusType DLL_FUNC TSC_FSetSystemLanguage ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, char *lpszSystemLanguage) ; The Set System Language function allows a calling application to alter the current language in which the TCR Twin Safe logs events. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpszSystemLanguage A pointer to a buffer for a null-terminated string of at least TSC_NATIONALITY_LEN+1 characters with which the current TCR Twin Safe language will be updated. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

194

539.1261/3 Version 5.02

27 June 2012


160 TCRTS get system language - TSC_FGetLanguage Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_API_C TSC_FGetLanguage( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCTSLANGUAGE lpSystemLanguage); The TCRTS Get System Language function allows a calling application to determine the current language in which the TCR Twin Safe logs events. This function also returns the languages available in the 3 slots. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. lpSystemLanguage A pointer to a structure receiving the current system language and the available langauges. Return value Possible return values are: TSC_SUCCESS Additional information This function works not on Twin Safe Classic. Cross-references None

27 June 2012

539.1261/03 DRAFT Version 5.02

195

TCR Twin Safe TSAPI Interface Description 161 162 Security Get alarm factor - TSC_FGetAlarmFactor Function prototype TSCStatusType DLL_FUNC TSC_FGetAlarmFactor ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCAlarmFactor lpAlarmFactor) ;

The Get Alarm Factor function allows a calling application to determine the multiplier which affects all configured delays once the TCR Twin Safe's alarm relay is triggered. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. This structure also contains a copy of the function's return code. lpAlarmFactor A pointer to a variable which will be updated with the current value of the alarm factor. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None

196

539.1261/3 Version 5.02

27 June 2012


163 Set alarm factor - TSC_FSetAlarmFactor Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetAlarmFactor ( PTSC_TellerInfo const lpTellerInfo, TSCAlarmFactor AlarmFactor, PTSC_BasicEventData lpBasicEventData); The Set Alarm Factor function allows a calling application to modify the multiplier which affects all configured delays once the TCR Twin Safe's alarm relay is triggered. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. AlarmFactor The new value value for the alarm factor. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

197

TCR Twin Safe TSAPI Interface Description

164

Get printer control - TSC_FGetPrinterControl Function prototype TSCStatusType DLL_FUNC TSC_FGetPrinterControl ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, BOOL *lpPrinterControl) ; The Get Printer Control function allows a calling application to determine the state of the printer control flag. (If the flag is TRUE, the TCR Twin Safe will not operate unless a working printer is attached). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpPrinterControl A pointer to a variable which will be updated with the current value of the printer control flag. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

198

539.1261/3 Version 5.02

27 June 2012


165 Set printer control - TSC_FSetPrinterControl Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetPrinterControl ( PTSC_TellerInfo const lpTellerInfo, BOOL PrinterControl, PTSC_BasicEventData lpBasicEventData) ; The Set Printer Control function allows a calling application to set the state of the printer control flag. (If the flag is TRUE, the TCR Twin Safe will not operate unless a working printer is attached). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. PrinterControl A pointer to a variable which will be updated with the current value of the printer control flag. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

199

TCR Twin Safe TSAPI Interface Description

166

Get door unlock delay - TSC_FGetDoorUnlockDelay Function prototype TSCStatusType DLL_FUNC TSC_FGetDoorUnlockDelay ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCDelayType lpDoorUnlockDelay); The Get Door Unlock Delay function allows a calling application to determine the current delay time before the TCR Twin Safe solenoid lock will open after an unlock request. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDoorUnlockDelay A pointer to a variable which will be updated with the current value of the door unlock delay. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

200

539.1261/3 Version 5.02

27 June 2012


167 Set door unlock delay - TSC_FSetDoorUnlockDelay Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetDoorUnlockDelay ( PTSC_TellerInfo const lpTellerInfo, TSCDelayType DoorUnlockDelay, PTSC_BasicEventData lpBasicEventData) ; The Set Door Unlock Delay function allows a calling application to set the delay time before the TCR Twin Safe solenoid lock will open after an unlock request. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. DoorUnlockDelay The new value of the door unlock delay. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

201

TCR Twin Safe TSAPI Interface Description

168

Get door unlock interval - TSC_FGetDoorUnlockInterval Function prototype TSCStatusType DLL_FUNC TSC_FGetDoorUnlockInterval ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCDelayType lpDoorUnlockInterval); The Get Door Unlock Interval function allows a calling application to determine the current interval for which the TCR Twin Safe solenoid lock will remain open after an unlock request. (The TCR Twin Safe door may remain open when this interval expires). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDoorUnlockInterval A pointer to a variable which will be updated with the current value of the door unlock interval. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

202

539.1261/3 Version 5.02

27 June 2012


169 Set door unlock interval - TSC_FSetDoorUnlockInterval Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetDoorUnlockInterval ( PTSC_TellerInfo const lpTellerInfo, TSCDelayType DoorUnlockInterval, PTSC_BasicEventData lpBasicEventData); The Set Door Unlock Interval function allows a calling application to set the interval for which the TCR Twin Safe solenoid lock will remain open after an unlock request. (The TCR Twin Safe door may remain open when this interval expires). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. DoorUnlockInterval The new value for the door unlock interval. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

203

TCR Twin Safe TSAPI Interface Description

170

Get SafeMaster unlock delay - TSC_FGetSMUnlockDelay Function prototype TSCStatusType DLL_FUNC TSC_FGetSMUnlockDelay ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCDelayType lpSMUnlockingDelay); The Get SafeMaster Unlock Delay function allows a calling application to determine the current delay time before the first SafeMaster drawer will open after an unlock request (unlock opens all the drawers in sequence). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMUnlockingDelay A pointer to a variable which will be updated with the current value of the SafeMaster unlock delay. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

204

539.1261/3 Version 5.02

27 June 2012


171 Set SafeMaster unlock delay - TSC_FSetSMUnlockDelay Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetSMUnlockDelay ( PTSC_TellerInfo const lpTellerInfo, TSCDelayType SMUnlockingDelay, PTSC_BasicEventData lpBasicEventData); The Set SafeMaster Unlock Delay function allows a calling application to set the delay time before the first SafeMaster drawer will open after an unlock request (unlock opens all the drawers in sequence). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. SMUnlockingDelay The new value for the SafeMaster unlock delay. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

205

TCR Twin Safe TSAPI Interface Description

172

Get SafeMaster unlock interval - TSC_FGetSMUnlockInterval Function prototype TSCStatusType DLL_FUNC TSC_FGetSMUnlockInterval ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCDelayType lpSMUnlockInterval); The Get SafeMaster Unlock Interval function allows a calling application to determine the current delay time between SafeMaster drawers during an unlock request (unlock opens all the drawers in sequence). This is command number 050430 in the DeLaRue documentation. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMUnlockInterval A pointer to a variable which will be updated with the current value of the SafeMaster unlock interval. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

206

539.1261/3 Version 5.02

27 June 2012


173 Set SafeMaster unlock interval - TSC_FSetSMUnlockInterval Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetSMUnlockInterval ( PTSC_TellerInfo const lpTellerInfo, TSCDelayType SMUnlockInterval, PTSC_BasicEventData lpBasicEventData) ; The Set SafeMaster Unlock Interval function allows a calling application to set the delay time between SafeMaster drawers during an unlock request (unlock opens all the drawers in sequence). This is command number 050430 in the DeLaRue documentation. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. SMUnlockInterval The new value for the SafeMaster unlock interval. between 1 and ASCOM_MAX_SM_UNLOCK_INT. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This This value must lie

27 June 2012

539.1261/03 DRAFT Version 5.02

207

TCR Twin Safe TSAPI Interface Description

174

Get SafeMaster reaction time - TSC_FGetSMReactionTime Function prototype TSCStatusType DLL_FUNC TSC_FGetSMReactionTime ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCDelayType lpSMReactionTime); The Get SafeMaster Reaction Time function allows a calling application to determine the current delay time before which each SafeMaster drawer relocks automatically if unopened. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMReactionTime A pointer to a variable which will be updated with the current value of the SafeMaster Reaction Time. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

208

539.1261/3 Version 5.02

27 June 2012


175 Set SafeMaster reaction time - TSC_FSetSMReactionTime Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetSMReactionTime ( PTSC_TellerInfo const lpTellerInfo, TSCDelayType SMReactionTime, PTSC_BasicEventData lpBasicEventData) ; The Set SafeMaster Reaction Time function allows a calling application to Set the delay time before which each SafeMaster drawer relocks automatically if unopened. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. SMReactionTime The new value for the SafeMaster Reaction Time. between 1 and ASCOM_MAX_SM_REACTION_TIME. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This This value must lie

27 June 2012

539.1261/03 DRAFT Version 5.02

209

TCR Twin Safe TSAPI Interface Description

176

Get SafeMaster open interval - TSC_FGetSMOpenInterval Function prototype TSCStatusType DLL_FUNC TSC_FGetSMOpenInterval ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCDelayType lpSMOpenInterval); The Get SafeMaster Open Interval function allows a calling application to determine the current delay time before which each SafeMaster drawer must be closed else the audible alarm will sound. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMOpenInterval A pointer to a variable which will be updated with the current value of the SafeMaster Open Interval. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

210

539.1261/3 Version 5.02

27 June 2012


177 Set SafeMaster open interval - TSC_FSetSMOpenInterval Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FSetSMOpenInterval ( PTSC_TellerInfo const lpTellerInfo, TSCDelayType SMOpenInterval, PTSC_BasicEventData lpBasicEventData); The Set SafeMaster Open Interval function allows a calling application to set the delay time before which each SafeMaster drawer must be closed else the audible alarm will sound. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. SMOpenInterval The new value for the SafeMaster Open Interval. This value must lie between ASCOM_MIN_SM_OPEN_INT and ASCOM_MAX_SM_OPEN_INT. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

211

TCR Twin Safe TSAPI Interface Description 178 179 Operating hours Get operating hours TSC_FGetOpHours Function prototype TSCStatusType DLL_FUNC TSC_FGetOpHours ( PTSC_TellerInfo const lpTellerInfo, PTSC_OperatingTimes lpDateTime, PTSC_BasicEventData lpBasicEventData) ;

This function retrieves the operating hours for a particular day. These will be the default hours for that day of the week unless they have been modified by a call to the Set Operating Hours function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure in which the Date field is a required input to this routine. Furthermore you have to specify how many ON-OFF windows shall be reported by the safe. This is done with help of the NumOfOpWindows field in the data structure. In the current version of TSAPI the NumOfOpWindows field must be set to TwoTimeWindows or FourTimeWindows. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDateTime A pointer to a data structure in which the OnTimes array and the OffTimes array are output from this routine. The elements of those arrays define the ON and OFF components for the different windows. This

212

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID

TCR Twin Safe TSAPI Interface Description

If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information This function call definition is not compatible to the NCI Twin Safe Handler DLL. Cross-references None.

27 June 2012

539.1261/03 DRAFT Version 5.02

213

TCR Twin Safe TSAPI Interface Description

180

Set operating hours TSC_FSetOpHours Function prototype TSCStatusType DLL_FUNC TSC_FSetOpHours ( PTSC_TellerInfo const lpTellerInfo, PTSC_OperatingTimes const lpDateTime, PTSC_BasicEventData lpBasicEventData) ; This function retrieves the operating hours for a particular day. These will be the default hours for that day of the week unless they have been modified by a call to the Set Operating Hours function. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure containing the specified date and the new ON/OFF time windows. It is mandatory to define all four time windows. An unused window should be set to ON=24:00:00 / OFF= 24:00:00. In the current version of TSAPI the NumOfOpWindows field must be set to FourTimeWindows. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID If any TCR Twin Safe condition is reported, the TCR Twin Safe error status and error code will be returned in fields within the output data structure. Additional information This function call definition is not compatible to the NCI Twin Safe Handler DLL. Cross-references None. This

214

539.1261/3 Version 5.02

27 June 2012


181 Get periodic hours - TSC_FGetPeriodicHours Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetPeriodicHours ( PTSC_TellerInfo const lpTellerInfo, PTSC_OperatingTimes lpDateTime, PTSC_BasicEventData lpBasicEventData); The Get Periodic Hours function allows a calling application to determine the standard operating hours for a particular day of each week. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure where the field eDay determines the requested day of the week. Furthermore you have to specify how many ON-OFF windows shall be reported by the safe. This is done with help of the NumOfOpWindows field in the data structure. In the current version of TSAPI the NumOfOpWindows field must be set to TwoTimeWindows or FourTimeWindows. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpDateTime A pointer to a data structure in which the OnTimes array and the OffTimes array are output from this routine. The elements of those arrays define the ON and OFF components for the different windows. Return value Possible return values are: TSC_SUCCESS Additional information The parameters of this function call are not compatible to the "NCI Twin Safe Handler DLL". Cross-references Aperiodic operating hours API calls This

27 June 2012

539.1261/03 DRAFT Version 5.02

215

TCR Twin Safe TSAPI Interface Description

182

Set periodic hours - TSC_FSetPeriodicHours Function prototype TSCStatusType DLL_FUNC TSC_FSetPeriodicHours ( PTSC_TellerInfo const lpTellerInfo, PTSC_OperatingTimes lpDateTime, PTSC_BasicEventData lpBasicEventData) ; The Set Periodic Hours function allows a calling application to set the standard operating hours for a particular day of each week. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure containing the new ON/OFF time windows. It is mandatory to define all four time windows. An unused window should be set to ON=24:00:00 / OFF= 24:00:00. In the current version of TSAPI the NumOfOpWindows field must be set to FourTimeWindows. The field eDay determines the requested day of the week. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information Idem p. 108 Cross-references Aperiodic operating hours API calls This

216

539.1261/3 Version 5.02

27 June 2012


183 Get aperiodic hours - TSC_FGetAperiodicHours Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetAperiodicHours ( PTSC_TellerInfo const lpTellerInfo, PTSC_OperatingTimes lpDateTime, PTSC_BasicEventData lpBasicEventData); The Get Aperiodic Hours function allows a calling application to detemine the over-ridden on and off time windows for a particular day. The TCR Twin Safe will return an error if no aperiodic hours have been defined for the supplied date. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure where the field Date determines the requested date. Furthermore you have to specify how many ON-OFF windows shall be reported by the safe. This is done with help of the NumOfOpWindows field in the data structure. In the current version of TSAPI the NumOfOpWindows field must be set to TwoTimeWindows or FourTimeWindows. Output parameters lpDateTime A pointer to a data structure in which the OnTimes array and the OffTimes array are output from this routine. The elements of those arrays define the ON and OFF components for the different windows. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

27 June 2012

539.1261/03 DRAFT Version 5.02

217

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information Idem p. 108 Cross-references Periodic operating hours API calls

218

539.1261/3 Version 5.02

27 June 2012


184 Get next aperiodic hours - TSC_FGetNextAperiodicHours Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetNextAperiodicHours ( PTSC_TellerInfo const lpTellerInfo, PTSC_OperatingTimes lpDateTime, PTSC_BasicEventData lpBasicEventData); The Get Next Aperiodic Hours function allows a calling application to detemine the overridden on and off times after the supplied date. The TCR Twin Safe will return an error if no more aperiodic hours have been defined. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure where the field Date determines the requested date. Furthermore you have to specify how many ON-OFF windows shall be reported by the safe. This is done with help of the NumOfOpWindows field in the data structure. In the current version of TSAPI the NumOfOpWindows field must be set to TwoTimeWindows or FourTimeWindows. Output parameters lpDateTime A pointer to a data structure in which the OnTimes array and the OffTimes array are output from this routine. The elements of those arrays define the ON and OFF components for the different windows. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

27 June 2012

539.1261/03 DRAFT Version 5.02

219

TCR Twin Safe TSAPI Interface Description Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information Idem p. 108 Cross-references Periodic operating hours API calls

220

539.1261/3 Version 5.02

27 June 2012


185 Add aperiodic hours - TSC_FAddAperiodicHours Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FAddAperiodicHours ( PTSC_TellerInfo const lpTellerInfo, PTSC_OperatingTimes lpDateTime, PTSC_BasicEventData lpBasicEventData); The Add Aperiodic Hours function allows a calling application to set over-ridden on and off times for the supplied date. The TCR Twin Safe will return an error if aperiodic hours have already been defined for the supplied date. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure containing the new ON/OFF time windows. It is mandatory to define all four time windows. An unused window should be set to ON=24:00:00 / OFF= 24:00:00. In the current version of TSAPI the NumOfOpWindows field must be set to FourTimeWindows. The field Date determines the requested date. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information Idem p. 108 Cross-references Periodic operating hours API calls This

27 June 2012

539.1261/03 DRAFT Version 5.02

221

TCR Twin Safe TSAPI Interface Description

186

Set aperiodic hours - TSC_FSetAperiodicHours Function prototype TSCStatusType DLL_FUNC TSC_FSetAperiodicHours ( PTSC_TellerInfo const lpTellerInfo, PTSC_OperatingTimes lpDateTime, PTSC_BasicEventData lpBasicEventData); The Set Aperiodic Hours function allows a calling application to update existing over-ridden on and off times for the supplied date. The TCR Twin Safe will return an error if aperiodic hours have not been defined for the supplied date. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure containing the new ON/OFF time windows. It is mandatory to define all four time windows. An unused window should be set to ON=24:00:00 / OFF= 24:00:00. In the current version of TSAPI the NumOfOpWindows field must be set to FourTimeWindows. The field Date determines the requested date. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information Idem p. 108 Cross-references Periodic operating hours API calls This

222

539.1261/3 Version 5.02

27 June 2012


187 Delete aperiodic hours - TSC_FDelAperiodicHours Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FDelAperiodicHours ( PTSC_TellerInfo const lpTellerInfo, PASCOM_DateTime const lpDateTime, PTSC_BasicEventData lpBasicEventData) ; The Delete Aperiodic Hours function allows a calling application to remove over-ridden on and off times for the supplied date. The TCR Twin Safe will return an error if aperiodic hours have not been defined for the supplied date. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpDateTime A pointer to a data structure containing the requested date. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references Periodic operating hours API calls. This

27 June 2012

539.1261/03 DRAFT Version 5.02

223

TCR Twin Safe TSAPI Interface Description 188 189 Roll storage data Get roll storage data - TSC_FGetRollStorageData Function prototype TSCStatusType DLL_FUNC TSC_FGetRollStorageData ( PTSC_TellerInfo const lpTellerInfo, PTSCRollStorageData lpRollStorageData, PTSC_BasicEventData lpBasicEventData) ;

The Get Roll Storage Data function allows a calling application to retrieve the bank note assignments for a particular RSM. Note that the TCR Twin Safe will return a syntax error (event number 340) if a valid RSM number is supplied but which is not fitted to the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpRollStorageData A pointer to a datastructure. The only field required is RSMNumber, which must lie between 1 and TSC_MAX_RSMS_AND_DENOMINATIONS. Output parameters lpRollStorageData A pointer to a datastructure. All the fields except RSMNumber are updated by this call. lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

224

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

225

TCR Twin Safe TSAPI Interface Description

190

Set roll storage data - TSC_FSetRollStorageData Function prototype TSCStatusType DLL_FUNC TSC_FSetRollStorageData ( PTSC_TellerInfo const lpTellerInfo, PTSCRollStorageData const lpRollStorageData, PTSC_BasicEventData lpBasicEventData) ; The Set Roll Storage Data function allows a calling application to modify the bank note assignments for a particular RSM. Note that the TCR Twin Safe will return a syntax error (event number 340) if a valid RSM number is supplied but which is not fitted to the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpRollStorageData A pointer to a datastructure. All fields are required. The RSMNumber field must contain a value between 1 and TSC_MAX_RSMS_AND_DENOMINATIONS. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

226

539.1261/3 Version 5.02

27 June 2012


191 Get roll storage low limit - TSC_FGetRollStorageLowLimit Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetRollStorageLowLimit ( PTSC_TellerInfo const lpTellerInfo, TSCRSMType RSMNumber, PTSC_BasicEventData lpBasicEventData, PTSCCountType lpLowWarningLimit); The Get Roll Storage Low Limit function allows a calling application to retrieve the low limit warning threshold for a particular RSM. Note that the TCR Twin Safe will return a syntax error (event number 340) if a valid RSM number is supplied but which is not fitted to the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. RSMNumber The number of the Roll Storage Module for which the low limit is required. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpLowWarningLimit A pointer to a variable which will be updated by this API call. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

227

TCR Twin Safe TSAPI Interface Description

192

Set roll storage low limit - TSC_FSetRollStorageLowLimit Function prototype TSCStatusType DLL_FUNC TSC_FSetRollStorageLowLimit ( PTSC_TellerInfo const lpTellerInfo, TSCRSMType RSMNumber, TSCCountType LowWarningLimit, PTSC_BasicEventData lpBasicEventData) ; The Set Roll Storage Low Limit function allows a calling application to modify the low limit warning threshold for a particular RSM. Note that the TCR Twin Safe will return a syntax error (event number 340) if a valid RSM number is supplied but which is not fitted to the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. RSMNumber The number of the Roll Storage Module for which the low limit is required. LowWarningLimit The new value for the low limit warning. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

228

539.1261/3 Version 5.02

27 June 2012


193 Get roll storage upper limit - TSC_FGetRollStorageUpperLimit Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FGetRollStorageLowLimit ( PTSC_TellerInfo const lpTellerInfo, TSCRSMType RSMNumber, PTSC_BasicEventData lpBasicEventData, PTSCCountType lpUpperWarningLimit); The Get Roll Storage Upper Limit function allows a calling application to retrieve the upper limit warning threshold for a particular RSM. Note that the TCR Twin Safe will return a syntax error (event number 340) if a valid RSM number is supplied but which is not fitted to the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. RSMNumber The number of the Roll Storage Module for which the low limit is required. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpUpperWarningLimit A pointer to a variable which will be updated by this API call. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

229

TCR Twin Safe TSAPI Interface Description

194

Set roll storage upper limit - TSC_FSetRollStorageUpperLimit Function prototype TSCStatusType DLL_FUNC TSC_FSetRollStorageLowLimit ( PTSC_TellerInfo const lpTellerInfo, TSCRSMType RSMNumber, TSCCountType UpperWarningLimit, PTSC_BasicEventData lpBasicEventData) ; The Set Roll Storage Upper Limit function allows a calling application to modify the upper limit warning threshold for a particular RSM. Note that the TCR Twin Safe will return a syntax error (event number 340) if a valid RSM number is supplied but which is not fitted to the TCR Twin Safe. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. RSMNumber The number of the Roll Storage Module for which the low limit is required. UpperWarningLimit The new value for the upper limit warning. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

230

539.1261/3 Version 5.02

27 June 2012


195 196 SafeMaster data Function prototype

TCR Twin Safe TSAPI Interface Description

Get number of SafeMaster drawers - TSC_FGetNumberOfSMDrawers

TSCStatusType DLL_FUNC TSC_FGetNumberOfSMDrawers ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCCountType lpNumberOfSMDrawers); The Get Number of SafeMaster Drawers function allows a calling application to retrieve the number of SafeMaster Drawers for the side specified in the lpTellerInfo parameter. The TCR Twin Safe will return an error if no SafeMaster is fitted (or has not been initialised) for the specified side. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpNumberOfSMDrawers A pointer to a variable which will be updated with the number of drawers. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

231

TCR Twin Safe TSAPI Interface Description

197

Init SafeMaster data - TSC_FInitSMData Function prototype TSCStatusType DLL_FUNC TSC_FInitSMData ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData, PTSCCountType lpNumberOfSMDrawers); The Init SafeMaster Data function allows a calling application to initialise the SafeMaster for the side specified in the lpTellerInfo parameter. The TCR Twin Safe returns the number of drawers available for the specified side. The TCR Twin Safe will return an error if no SafeMaster is fitted. Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpNumberOfSMDrawers A pointer to a variable which will be updated with the number of drawers. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

232

539.1261/3 Version 5.02

27 June 2012


198 Delete SafeMaster data - TSC_FDelSMData Function prototype

TCR Twin Safe TSAPI Interface Description

TSCStatusType DLL_FUNC TSC_FDelSMData ( PTSC_TellerInfo const lpTellerInfo, PTSC_BasicEventData lpBasicEventData); The Delete SafeMaster Data function allows a calling application to disable the SafeMaster for the side specified in the lpTellerInfo parameter. The TCR Twin Safe will return an error if no SafeMaster is fitted (or has not been initialised for the specified side). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

233

TCR Twin Safe TSAPI Interface Description

199

Get SafeMaster drawer delay - TSC_FGetSMDrawerDelay Function prototype TSCStatusType DLL_FUNC TSC_FGetSMDrawerDelay ( PTSC_TellerInfo const lpTellerInfo, TSCDrawerNumber DrawerNumber, PTSC_BasicEventData lpBasicEventData, PTSCDelayType lpSMDrawerDelay); The Get SafeMaster Drawer Delay function allows a calling application to retrieve the delay before which the specified SafeMaster drawer will open following a call to the Open Drawer Standard API call. The TCR Twin Safe will return an error if no SafeMaster is fitted (or has not been initialised for the specified side). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. SMDrawerNumber The SafeMaster drawer for which the drawer delay is requested. This value must lie between 1 and ASCOM_MAX_SM_DRAWERS. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMDrawerDelay A pointer to a variable which will be updated with the current value of the drawer delay for the specified drawer. This

234

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

235

TCR Twin Safe TSAPI Interface Description

200

Set SafeMaster drawer delay - TSC_FSetSMDrawerDelay Function prototype TSCStatusType DLL_FUNC TSC_FSetSMDrawerDelay ( PTSC_TellerInfo const lpTellerInfo, TSCDrawerNumber DrawerNumber, TSCDelayType SMDrawerDelay, PTSC_BasicEventData lpBasicEventData); The Set SafeMaster Drawer Delay function allows a calling application to modify the delay before which the specified SafeMaster drawer will open following a call to the Open Drawer Standard API call. The TCR Twin Safe will return an error if no SafeMaster is fitted (or has not been initialised for the specified side). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. SMDrawerNumber The SafeMaster drawer for which the drawer delay is being modified. This value must lie between 1 and ASCOM_MAX_SM_DRAWERS. SMDrawerDelay The new value for the drawer delay for the specified drawer. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. This

236

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

237

TCR Twin Safe TSAPI Interface Description

201

Get SafeMaster drawer currency data - TSC_FGetSMDrawerCurrData Function prototype TSCStatusType DLL_FUNC TSC_FGetSMDrawerCurrData ( PTSC_TellerInfo const lpTellerInfo, PTSC_SMDrawerCurrData lpSMDrawerCurrData, PTSC_BasicEventData lpBasicEventData); The Get SafeMaster Drawer Currency Data function allows a calling application to retrieve currency data for the SafeMaster drawers. Currency Data is uniquely identified by the currency code plus the index. The TCR Twin Safe will return an error if no SafeMaster is fitted (or has not been initialised for the specified side). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpSMDrawerCurrData A pointer to a data structure. The fields szCurrencyCode and Index are required as inputs to this API call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMDrawerCurrData A pointer to a data structure. All fields except szCurrencyCode and Index are updated by this API call. This

238

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

239

TCR Twin Safe TSAPI Interface Description

202

Add SafeMaster drawer currency data - TSC_FAddSMDrawerCurrData Function prototype TSCStatusType DLL_FUNC TSC_FAddSMDrawerCurrData ( PTSC_TellerInfo const lpTellerInfo, PTSC_SMDrawerCurrData lpSMDrawerCurrData, PTSC_BasicEventData lpBasicEventData); The Add SafeMaster Drawer Currency Data function allows a calling application to add new currency data for the SafeMaster drawers. Currency Data is uniquely identified by the currency code plus the index (the latter is generated automatically by the TCR Twin Safe). The TCR Twin Safe will return an error if no SafeMaster is fitted (or has not been initialised for the specified side). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpSMDrawerCurrData A pointer to a data structure. All fields except Index and szCurrencyText are required as inputs to this API call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. lpSMDrawerCurrData A pointer to a data structure. updated by this API call. The fields Index and szCurrencyText are This

240

539.1261/3 Version 5.02

27 June 2012


Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

241

TCR Twin Safe TSAPI Interface Description

203

Update SafeMaster drawer currency data - TSC_FUpdateSMDrawerCurrData Function prototype TSCStatusType DLL_FUNC TSC_FUpdateSMDrawerCurrData ( PTSC_TellerInfo const lpTellerInfo, PTSC_SMDrawerCurrData const lpSMDrawerCurrData, PTSC_BasicEventData lpBasicEventData); The Update SafeMaster Drawer Currency Data function allows a calling application to modify existing currency data for the SafeMaster drawers. Currency Data is uniquely identified by the currency code plus the index. The TCR Twin Safe will return an error if no SafeMaster is fitted (or has not been initialised for the specified side). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpSMDrawerCurrData A pointer to a data structure. The szCurrencyCode, Index and szIndexText are required as inputs to this API call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

242

539.1261/3 Version 5.02

27 June 2012


204 Function prototype

TCR Twin Safe TSAPI Interface Description

Delete SafeMaster drawer currency data - TSC_FDeleteSMDrawerCurrData

TSCStatusType DLL_FUNC TSC_FDeleteSMDrawerCurrData ( PTSC_TellerInfo const lpTellerInfo, PTSC_SMDrawerCurrData const lpSMDrawerCurrData, PTSC_BasicEventData lpBasicEventData); The Delete SafeMaster Drawer Currency Data function allows a calling application to remove existing currency data for the SafeMaster drawers. Currency Data is uniquely identified by the currency code plus the index. The TCR Twin Safe will return an error if no SafeMaster is fitted (or has not been initialised for the specified side). Input parameters lpTellerInfo A pointer to a data structure defining the user. The TCR Twin Safe uses this for validation purposes. lpSMDrawerCurrData A pointer to a data structure. The szCurrencyCode and Index are required as inputs to this API call. Output parameters lpBasicEventData A pointer to a data structure containing the TCR Twin Safe reply. structure also contains a copy of the function's return code. Return value Possible return values are: TSC_SUCCESS TSC_PARAM_INVALID Additional information None Cross-references None This

27 June 2012

539.1261/03 DRAFT Version 5.02

243

TCR Twin Safe TSAPI Interface Description

205
206

DATA TYPES AND STRUCTURES

Constants and enumerated data types In the following the constant definitions of the FLAPI are presented. Some of the constants define the length of a character string. For a C-language implementation a possible variable defintion be look like this: char StringName[TSC_CURRENCY_LEN+1]

where the extra character is required for the terminating null character. Size of Win32 enumerated data types short int long double long double char BOOL Win16 4 2 4 4 8 8 1 4 2 2 2 4 8 10 1 2 OS/2 1 2 4 4 8 16 1 4

For compatibility reasons to the older NCI TwinSafe Handler DLL there sometimes exist more than one definition for the same purpose. #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define 244 CURRENCYCODELENGTH CURRENCYTEXTLENGTH LANGUAGELENGTH PINLENGTH USERIDENTLENGTH SECTION_LENGTH_UPLOAD SECTION_LENGTH_DOWNLOAD MAX_NUMBER_OF_NOTES MAX_NUMBER_OF_ISO_CURRENCYS MAX_NUMBER_OF_LANGUAGES MAX_NUMBER_OF_ONOFFTIMES MAX_NUMBERS_OF_NOTESTRUCTELEMENTS MAX_NUMBER_OF_DELAYCLASSES MAX_NUMBER_OF_SLOTS MAX_NUMBER_OF_RSM MAX_CALIB_VECT_SIZE MAX_RSM_ASSIGNMENTS MAX_EXCEPTIONS MAX_NUMBER_OF_SM_DRAWERS MAX_NUMBER_OF_SM_DRAWER_CURRENCIES MAX_NUMBER_OF_EVENTLEVEL MAX_NUMBER_OF_COUNTERNOTEDATA MAX_RSM_ASSIGNMENTS ASCOM_DRAWER_NUM_LEN ASCOM_ALARMFACTOR_LEN ASCOM_AMOUNT_LEN ASCOM_CB_NUM_NOTES_LEN ASCOM_CMD_HISTORY_LEN ASCOM_CURRENCY_LEN ASCOM_CURR_FACTOR_LEN ASCOM_CURR_TEXT_LEN ASCOM_DENOM_LEN ASCOM_DELAY_TIME_LEN
539.1261/3 Version 5.02

5 5 3 6 9 64 32 60 60 3 4 12 10 3 8 576 128 64 8 32 4 16 128 ASCOM_INDEX_LEN 12 12 6 400 CURRENCYCODELENGTH 12 CURRENCYTEXTLENGTH 12 4

27 June 2012

TCR Twin Safe TSAPI Interface Description #define ASCOM_INDEX_LEN 2 #define ASCOM_INDEX_TEXT_LEN 10 #define ASCOM_MAX_FAULTY_PROBES 50 #define ASCOM_MAX_SM_CURRS_ON_DRAWERS (MAX_NUMBER_OF_SM_DRAWERS * MAX_NUMBER_OF_SM_DRAWER_CURRENCIES) #define ASCOM_MAX_SM_DRAWERS MAX_NUMBER_OF_SM_DRAWERS #define ASCOM_MAX_RSM_NOTES 4 #define ASCOM_NUM_NOTES_LEN 3 #define ASCOM_NUM_GROUPS_LEN 2 #define ASCOM_PWD_LEN PINLENGTH #define ASCOM_RSM_LOW_LIMIT_LEN 3 #define ASCOM_STN_ADDR_LEN 4 #define ASCOM_SW_VERSION_LEN 5 #define ASCOM_TS_SW_VER_LEN 20 #define ASCOM_USER_LEVEL_LEN 1 #define ASCOM_MAX_USERS_PER_LEVEL 99 #define ASCOM_USER_ID_LEN USERIDENTLENGTH #define ASCOM_EVENT_STATUS_RANGE MAX_NUMBER_OF_EVENTLEVEL #define #define #define #define #define ASCOM_MAX_SM_OPEN_INT ASCOM_MIN_SM_OPEN_INT ASCOM_MAX_SM_REACTION_TIME ASCOM_MAX_SM_UNLOCK_INT ASCOM_MIN_APERIODIC_YEAR 600 30 120 30 0

#define TSC_MAX_NUMBER_OF_ONOFFTIMES MAX_NUMBER_OF_ONOFFTIMES #define TSC_CURRENCY_LEN #define TSC_MAX_RSMS_AND_DENOMINATIONS #define TSC_NATIONALITY_LEN #define TSC_MAX_NUMBER_OF_LANGUAGES MAX_NUMBER_OF_LANGUAGES #define TSC_ASYNCREPLYPARAM HANDLE CompletionEventHandle #define TSC_DEFAULT_LOG_FILENAME #define TSC_ERROR_LOG_LINE_LEN

ASCOM_CURRENCY_LEN MAX_NUMBER_OF_RSM LANGUAGELENGTH

"c:\\temp\\TSC_Logfile.log" 159

27 June 2012

539.1261/03 DRAFT Version 5.02

245

TCR Twin Safe TSAPI Interface Description This enumerated type contains the values for setting the silent alarm relay within the TCR Twin Safe : typedef enum { AscomAlarmUnchanged, AscomAlarmOn, AscomAlarmOff } TSC_AlarmType ;

This enumerated type contains values for the different types of note reader that can be fitted to the TCR Twin Safe : typedef enum { AscomNVMLB = 1, AscomBPI200, AscomDVM, AscomOVM__ = 'A', AscomOVM_OVM_, AscomOVM_UVM_AVM } ASCOM_NoteReaderType ; This enumerated type contains values for the different log retrieval options for the TCR Twin Safe : typedef enum { TSC_GeneralLogDetails, TSC_DayLogDetails, TSC_RangeLogDetails, TSC_JournalEnd } TSC_LogRequestType; This enumerated type contains values for the different copy data file options for the TCR Twin Safe : typedef enum { LogToDiskette, ConfigToDiskette, AuthToDiskette, Unused3, Unused4, Unused5, Unused6, LangVisibFile, AuthToMCU, ConfigToMCU, SystemSW, CurrencyDataSet } AscomCopyFileType ; This enumerated type contains values for the different possibilities to shutdown or reset the TCR Twin Safes MasterControlUnit: typedef enum { TSC_MCU_SHUTDOWN, TSC_MCU_SW_RESET, TSC_MCU_COM_RESET, TSC_MCU_SW_NVRAM_RESET 246
539.1261/3 Version 5.02 27 June 2012


} TSC_MCU_RESET_MODE;

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

247

TCR Twin Safe TSAPI Interface Description

This enumerated type contains to configure the TCR Twin Safes advanced possibilities to configure Roll Storage Modules (RSM): typedef enum { TSC_RSM_NORMAL, TSC_RSM_CURRENCY, TSC_RSM_OBJECT } TSC_LAST_RSM_MODES; This enumerated type is used internally within the TS2CommDLL. Certain values are returned by the function Asynchronous Get Response : typedef enum { TSNone, TSStartDeposit, TSDeposit, TSWithdrawal, TSCashBalancing, TSEmptyRSM, TSSetDateAndTime, TSSystemStatus, TSTest, TSConsult, TSOpenSafeDoor, TSCopyDataFiles, TSGetOperatingHours, TSSetOperatingHours, TSLogComment, TSSMConsultTotal, TSSMConsultCurrCode, TSSMCancelMovement, TSSMUnlock, TSSMOpen, TSSMDeposit, TSSMWithdrawal, TSGetLogInfo, TSGetLogLine, TSEndDeposit, TSSpare1, TSSpare2, TSSpare3, TSSpare4, TSSpare5, TSSpare6, TSSpare7, TSSpare8, TSSpare9, TSValidateUser , TSChangePassword , TSAddUser , TSGetUser , TSDeleteUser , TSAddBanknoteData , TSGetBanknoteData , TSGetNextBanknoteData , TSUpdateBanknoteData , TSDeleteBanknoteData , TSAddCurrencyData , TSUpdateCurrencyData , 248
539.1261/3 Version 5.02 27 June 2012


TSGetCurrencyData , TSGetNextCurrencyData , TSDeleteCurrencyData , TSGetNumDelayClasses , TSSetNumDelayClasses , TSGetDelayClassParams , TSSetDelayClassParams , TSGetSystemLanguage , TSSetSystemLanguage , TSGetAlarmFactor , TSSetAlarmFactor , TSGetPrinterControl , TSSetPrinterControl , TSGetDoorUnlockDelay , TSSetDoorUnlockDelay , TSGetDoorUnlockInterval , TSSetDoorUnlockInterval , TSGetSMUnlockDelay , TSSetSMUnlockDelay , TSGetSMUnlockInterval , TSSetSMUnlockInterval , TSGetSMReactionTime , TSSetSMReactionTime , TSGetSMOpenInterval , TSSetSMOpenInterval , TSGetPeriodicHours , TSSetPeriodicHours , TSGetAperiodicHours , TSGetNextAperiodicHours , TSAddAperiodicHours , TSSetAperiodicHours , TSDelAperiodicHours , TSGetRollStorageData , TSSetRollStorageData , TSGetRollStorageLowLimit , TSSetRollStorageLowLimit , TSGetNumberOfSMDrawers , TSInitSMData , TSDelSMData , TSGetSMDrawerDelay , TSSetSMDrawerDelay , TSGetSMDrawerCurrData , TSAddSMDrawerCurrData , TSUpdateSMDrawerCurrData , TSDeleteSMDrawerCurrData , TSExtSpare1, TSExtSpare2, TSExtSpare3, TSExtSpare4, TSExtSpare5, TSExtSpare6, TSExtSpare7, TSExtSpare8, TSExtSpare9, TSLastCommand } ASCOM_CommandType ;

TCR Twin Safe TSAPI Interface Description

This enumerated type contains values for the different possibilities to calculate a note mix for a specified amount. These values are used in the TSC_FcalculateNotemix function. typedef enum
27 June 2012 539.1261/03 DRAFT Version 5.02

249

TCR Twin Safe TSAPI Interface Description { ALG_LeastNotes, ALG_TwinSafe, ALG_Programmed } TSC_NotemixAlgorithm;

250

539.1261/3 Version 5.02

27 June 2012


typedef enum { TSC_NoSensors, TSC_Sensors, TSC_SensorsExt } TSCSensorTest;

TCR Twin Safe TSAPI Interface Description This enumerated type contains values for the different possibilities to check the sensors of the Twin Safe in a TSC_FSystemStatus function.

This enumerated type contains values for the different days in a calendar week. typedef enum { TSCSun, TSCMon, TSCTue, TSCWed, TSCThu, TSCFri, TSCSat, TSCNone } TTSCDayOfWeek ; This enumerated type contains values for the different possibilities to define operating time windows for a Twin Safe. typedef enum { OneTimeWindow TwoTimeWindows, FourTimeWindows } TSC_NumOfOpWindows;

= 0,

This enumerated type contains values for the different possibilities to keep or release the reservation of the Twin Safe when a self- test is executed. typedef enum { ReleaseOwnReservation, KeepReservation, ReleaseAllReservation } TSC_TestReservation;

27 June 2012

539.1261/03 DRAFT Version 5.02

251

TCR Twin Safe TSAPI Interface Description Various numeric data types: typedef long int typedef short int typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedaf typedef TSCStatusType ; ASCOM_EventNumber ;

long int TSCDenominationType ; unsigned short int TSCDelayType ; short int TSCCountType ; short int TSCIndexNumber ; short int TSCDataLength ; char *TSCData; short int TSCRSMType ; short int TSCDrawerNumber ; long int TSCAmountType ; double TSCSMAmountType; double TSCCrncyFactorType; double TSCThresholdAmountType ; double TSCAlarmFactorType ; long int TSC_LogLineNumber; short int TSC_LogLineLength; char TSC_LogLineText[TSC_ERROR_LOG_LINE_LEN+1]; long double TSCAmount; int TSCNumberOfObjects; int TSCLoggingLevel; long int TSCStatsType ; int TSC_POLLINGFLAG; TSCDelayType TSCCountType TSCRSMType TSCAlarmFactorType TSCNumberOfObjects TSCStatusType TSCNumberOfObjects TSC_POLLINGFLAG char *PTSCDelayType; *PTSCCountType; *PTSCCRSMType; *PTSCAlarmFactorType; *PTSCNumberOfObjects; *PTSCStatusType; *PTSCNumberOfObjects; * PTSC_POLLINGFLAG; *TSC_UPLOAD_FILENAME;

252

539.1261/3 Version 5.02

27 June 2012


207 TSC_DENOMINATIONS_LIST

TCR Twin Safe TSAPI Interface Description

TSC_DENOMINATIONS_LIST is a structure that allows the storage of denomination data for each RSM defined for the TCR Twin Safe. Definition: typedef struct { TSCDenominationType lDenom[TSC_MAX_RSMS_AND_DENOMINATIONS] ; } TSC_DENOMINATIONS_LIST ; typedef TSC_DENOMINATIONS_LIST * PTSC_DENOMINATIONS_LIST; Memory alignment: Type TSCDenominationType Name lDenom[8 ] lDenom[0 ] lDenom[1 ] lDenom[7 ] Win32 Size Offset 8*4 0 4 4 4 32 0 4 28 Win16 Size Offset 8*4 0 4 4 4 32 0 4 28 OS/2 Size Offset 8*4 0 4 4 4 32 0 4 28

Structure size

208

TSC_AMOUNT_LIST Definition: typedef struct { TSCAmount amount[MAX_NUMBER_OF_RSM]; } TSC_AMOUNT_LIST; typedef TSC_AMOUNT_LIST * PTSC_AMOUNT_LIST ; Memory alignment:

Type TSCAmount Structure size

Name amount[8]

Win32 Size Offset 0 64

Win16 Size Offset 0 64

OS/2 Size Offset 0 64

209

TSC_ DispenseData This contains the currency code and the numbers of notes to be dispensed from each RSM. Definition: typedef struct { TSCDenominationType char char } TSC_DispenseData; typedef TSC_DispenseData *

lDenom[TSC_MAX_RSMS_AND_DENOMINATIONS] ; szCurrencyCode[ASCOM_CURRENCY_LEN+1] ; pad[10]; PTSC_DispenseData; 253

27 June 2012

539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description Memory alignment: Type TSCDenominationType Name lDenom[8] lDenom[0] lDenom[1] ... lDenom[7] szCurrencyCode[6] pad[10] Win32 Size Offset 8*4 0 4 4 4 6*1 10 48 0 4 28 32 38 Win16 Size Offset 8*4 0 4 4 4 6*1 10 48 0 4 28 32 38

OS/2 Size Offset 8*4 0 4 4 4 6*1 10 48 0 4 28 32 38

char char Structure size

210

TSC_ Version This contains a pointer to the sting buffer and a variable, containing the size of the string buffer. Definition: typedef struct { char int char }TSC_VERSION; Memory alignment:

*versionString; size; pad[-];

Type char * int char Structure size

Name versionString size pad[-]

Win32 Size Offset 4 0 4 4 8 8 16

Win16 Size Offset 4 0 2 4 10 6 16

OS/2 Size Offset 4 0 4 4 8 8 16

211

TSC_TellerInfo This data type is a formal parameter to all FLAPI function calls which communicate with the TCR Twin Safe. It defines the information that the TCR Twin Safe needs in order to identify the user. The field UserLevel is normally 'D' for commands from the minimum or standard instruction sets. Other values are required for certain commands within the extended instruction set. Note: The value in the szStationAddress field must always be set to "0000". DeLaRue have specified this field in readiness for a future version of the TCR Twin Safe software. Definition: typedef struct { HINSTANCE hApplicationInstance ; TSC_AlarmType eAlarmFlag ; char szStationAddress[ASCOM_STN_ADDR_LEN+1] , szUserID[ASCOM_USER_ID_LEN+1] , cTellerSide , cUserLevel ;

254

539.1261/3 Version 5.02

27 June 2012


char pad[-]; } TSC_TellerInfo; typedef TSC_TellerInfo * PTSC_TellerInfo;

TCR Twin Safe TSAPI Interface Description

27 June 2012

539.1261/03 DRAFT Version 5.02

255

TCR Twin Safe TSAPI Interface Description Memory alignment: Type HINSTANCE TSCAlarmType char char char char char Structure size Name hApplicationInstance eAlarmFlag szStationAddress[5] szUserID[10] cTellerSide cUserLevel pad[-] Win32 Size Offset 4 0 4 4 5*1 8 10 * 1 13 1 23 1 24 7 25 32 Win16 Size Offset 2 0 2 2 5*1 4 10 * 1 9 1 19 1 20 11 21 32

OS/2 Size Offset 1 0 5*1 1 10 * 1 6 1 16 1 17 14 18 32

212

TSC_BasicEventData This data type is a formal parameter to all FLAPI function calls. The TCR Twin Safe always sends back this information, though additional information may also be returned. The field rc contains the same return code as the function return type. This allows applications to embed the function calls within conditional expressions without needing to capture the return code. It also means that the FLAPI can be utilised from development environments that are unable to use the return code directly. Definition: typedef struct { TSCStatusType FunctionReturnCode; TSC_ENUM_REPRESENTATION eEventStatus; ASCOM_EventNumber EventNumber; TSC_BOOL_REPRESENTATION EventRSM[TSC_MAX_RSMS_AND_DENOMINATIONS]; char pad[8]; } TSC_BasicEventData; typedef TSC_BasicEventData * PTSC_BasicEventData ; Memory alignment:

Type TSCStatusType TSC_ENUM_REPRESENTATION ASCOM_EventNumber TSC_BOOL_REPRESENTATION char Structure size

Name FunctionReturnCode eEventStatus EventNumber EventRSM[8] Pad[8]

Win32 Size Offset 4 0 2 4 2 6 8*2 8 8 24 32

Win16 Size Offset 4 0 2 4 2 6 8*2 8 8 24 32

OS/2 Size Offset 4 0 2 4 2 6 8*2 8 8 24 32

256

539.1261/3 Version 5.02

27 June 2012


213 TSC_CashBalanceResponse

TCR Twin Safe TSAPI Interface Description

This structure holds the additional information returned by a call to the Cash Balancing FLAPI function call. The NotesIn structure contains the number of notes deposited in each RSM since the last time that the function was invoked for this user with the formal parameter ResetCounters set to TRUE. The NotesOut structure contains the total count of dispensed notes per RSM over the same period. Definition: typedef struct { TSC_DENOMINATIONS_LIST NotesIn , NotesOut ; } TSC_CashBalanceResponse; typedef TSC_CashBalanceResponse * PTSC_CashBalanceResponse ; Memory alignment: Type TSC_DENOMINATIONS_LIST TSC_DENOMINATIONS_LIST Structure size Name NotesIn NotesOut Win32 Siz Offset e 32 0 32 32 64 Win16 Siz Offset e 32 0 32 32 64 OS/2 Siz Offset e 32 0 32 32 64

214

TSC_EmptyRSMParams This structure holds the additional information returned after emptying an RSM. The TCR Twin Safe reports the number of notes actually dispensed and also the number reported by the TCR Twin Safe's own counter. Definition: typedef struct { BOOL UseDelays ; TSCRSMType RSMNumber ; char pad[-]; } TSC_EmptyRSMParams ; typedef TSC_EmptyRSMParams * PTSC_EmptyRSMParams ; Memory alignment:

Type BOOL TSCRSMType char Structure size

Name UseDelays RSMNumber pad[-]

Win32 Size Offset 4 0 2 4 10 6 16

Win16 Size Offset 2 0 2 2 12 4 16

Size 4 2 10 16

OS/2 Offset 0 4 6

27 June 2012

539.1261/03 DRAFT Version 5.02

257

TCR Twin Safe TSAPI Interface Description 215 TSC_EmptyRSMResponse

This structure holds the additional information returned after emptying an RSM. The TCR Twin Safe reports the number of notes actually dispensed and also the number reported by the TCR Twin Safe's own counter. Definition: typedef struct { TSCCountType

char } TSC_EmptyRSMResponse; typedef TSC_EmptyRSMResponse Memory alignment: Type TSCCountType TSCCountType char Structure size Name NotesPhysical NotesLogical pad[12]

NotesPhysical , NotesLogical ; pad[12]; * PTSC_EmptyRSMResponse ;

Win32 Size Offset 2 0 2 2 12 4 16

Win16 Size Offset 2 0 2 2 12 4 16

Size 2 2 12 16

OS/2 Offset 0 2 4

216

TSC_EmptyRSMExtResponse This structure holds the additional information returned after emptying an RSM. The TCR Twin Safe reports the number of notes actually dispensed and also the number reported by the TCR Twin Safe's own counter. The TSAPI calculates the difference between these two values. Definition: typedef struct { TSCCountType

char } TSC_EmptyRSMExtResponse; typedef TSC_EmptyRSMExtResponse Memory alignment: Type TSCCountType TSCCountType TSCCountType TSCCountType char Structure size Name NotesPhysical NotesLogical DiffPlus DiffMinus pad[8]

NotesPhysical , NotesLogical , DiffPlus , DiffMinus ; pad[8]; * PTSC_EmptyRSMExtResponse ; Win32 Size Offset 2 0 2 2 2 4 2 6 8 8 16 Win16 Size Offset 2 0 2 2 2 4 2 6 8 8 16 OS/2 Offset 0 2 4 6 8

Size 2 2 2 2 8 16

258

539.1261/3 Version 5.02

27 June 2012


217 ASCOM_Date, ASCOM_Time and ASCOM_DateTime

TCR Twin Safe TSAPI Interface Description

These data types are used for those functions, which allow to set the TCR Twin Safe time and date. Definition: typedef struct { short int short int } ASCOM_Date ; typedef ASCOM_Date Memory alignment: Type short int short int short int short int Name Day Month Year Pad[5] Pad[0] Pad[1] ... Pad[4] Structure size Definition: typedef struct { short int short int } ASCOM_Time ; typedef ASCOM_Time Memory alignment: Type short int short int short int short int Name Hour Minute Second Pad[5] Pad[0] Pad[1] ... Pad[4] Definition: typedef struct
27 June 2012 539.1261/03 DRAFT Version 5.02

Day, Month, Year; Pad[5]; * PASCOM_Date ;

Win32 Size Offset 2 0 2 2 2 4 5*2 6 2 2 2 16 6 8 14

Win16 Size Offset 2 0 2 2 2 4 5*2 6 2 2 2 16 6 8 14

OS/2 Size Offset 2 0 2 2 2 4 5*2 6 2 2 2 16 6 8 14

Hour, Minute, Second; Pad[5]; * PASCOM_Time ;

Win32 Size Offset 2 0 2 2 2 4 5*2 6 2 6 2 8 2 16 14

Win16 Size Offset 2 0 2 2 2 4 5*2 6 2 6 2 8 2 16 14

OS/2 Size Offset 2 0 2 2 2 4 5*2 6 2 6 2 8 2 16 14

Structure size

259

TCR Twin Safe TSAPI Interface Description { ASCOM_Date Date ; ASCOM_Time Time ; } ASCOM_DateTime ; typedef ASCOM_DateTime Memory alignment: Type ASCOM_Date ASCOM_Time Structure size Name Date Time Win32 Size Offset 16 0 16 16 32 Win16 Size Offset 16 0 16 16 32 OS/2 Size Offset 16 0 16 16 32

* PASCOM_DateTime ;

260

539.1261/3 Version 5.02

27 June 2012


218 TSC_SystemStatusResponse

TCR Twin Safe TSAPI Interface Description

The System Status function call provides information on the software versions of all the components of the TCR Twin Safe plus a condensed history of recent transactions and their event numbers. The function call can also test the sensors within the TCR Twin Safe and up to fifty faulty sensors/probes can be reported at any time.In the field BlockedRSM, a blocked RSM is indicated by an element which is set to TRUE. Likewise, if OperatingState is set to FALSE then the complete TCR Twin Safe is blocked. The format of the history string is explained in the DeLaRue TCR Twin Safe Software Description. Definition: typedef struct { BOOL BOOL TSCRSMType ASCOM_EventNumber ASCOM_NoteReaderType char

char

char char } TSC_SystemStatusResponse ; typedef TSC_SystemStatusResponse Memory alignment: Type BOOL

BlockedRSM[TSC_MAX_RSMS_AND_DENOMINATIONS]; PrinterConnected , SafemasterConfigured ; NumRSMs ; EventNum ; eReader ; szTSSoftwareVersion[ASCOM_TS_SW_VER_LEN+1] , szMM_SW_Version[ASCOM_SW_VERSION_LEN+1] , szNR_SW_Version[ASCOM_SW_VERSION_LEN+1] , szRSM_SW_Version [TSC_MAX_RSMS_AND_DENOMINATIONS] [ASCOM_SW_VERSION_LEN+1] , szLanguage[TSC_NATIONALITY_LEN+1]; szFailedProbeIDs[ASCOM_MAX_FAULTY_PROBES+1], szCmdHistory[ASCOM_CMD_HISTORY_LEN+1] ; OperatingState ; pad[-]; * PTSC_SystemStatusResponse ; Win32 Size Offset 8*4 0 4 0 4 4 4 4 4 2 2 4 21 * 1 6*1 6*1 48 * 1 6*1 6*1 6*1 4*1 51 * 1 401 * 1 1 28 32 36 40 42 44 48 69 75 81 81 87 123 129 133 184 585 Win16 Size Offset 8*2 0 2 0 2 2 2 2 2 2 2 2 21 * 1 6*1 6*1 48 * 1 6*1 6*1 6*1 4*1 51 * 1 401 * 1 1 14 16 18 20 22 24 26 47 53 59 59 65 101 107 111 162 563 OS/2 Size Offset 8*4 0 4 0 4 4 4 4 4 2 2 1 21 * 1 6*1 6*1 48 * 1 6*1 6*1 6*1 4*1 51 * 1 401 * 1 1 261 28 32 36 40 42 44 45 66 72 78 78 84 120 126 130 181 582

BOOL BOOL TSCRSMType ASCOM_EventNumber ASCOM_NoteReaderType char char char char

char char char char

27 June 2012

Name BlockedRSM[8] BlockedRSM[0] BlockedRSM[1] BlockedRSM[7] PrinterConnected SafeMasterConfigured NumRSMs EventNum eReader szTSSoftwareVersion[21] szMM_SW_Version[6] szNR_SW_Version[6] szRSM_SW_Version[8][6] szRSM_SW_Version[0] szRSM_SW_Version[1] szRSM_SW_Version[7] szLanguage[4] szFailedProbeIDs[51] szCmdHistory[401] OperatingState

539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description char Structure size pad[-] 6 592 586 12 576 564

9 592 583

262

539.1261/3 Version 5.02

27 June 2012


219 TSC_ConsultResponse

TCR Twin Safe TSAPI Interface Description

The TCR Twin Safe returns a data value in each of the four fields for each RSM. The note currency code and the face value are reported for each available RSM, as is the number of notes currently held within the RSM. The RSMAvailable array can be used as an indication of whether the other related fields contain valid data. Definition: typedef struct { TSC_DENOMINATIONS_LIST BOOL char

Denominations , NumberOfNotes ; RSMAvailable[TSC_MAX_RSMS_AND_DENOMINATIONS]; szCurrencyCode[TSC_MAX_RSMS_AND_DENOMINATIONS] [ASCOM_CURRENCY_LEN +1] ;

} TSC_ConsultResponse ; typedef TSC_ConsultResponse * PTSC_ConsultResponse ; Memory alignment: Type TSC_DENOMINATIONS_LIST TSC_DENOMINATIONS_LIST BOOL Name Denominations NumberOfNotes RSMAvailable[8] RSMAvailable[0] RSMAvailable[1] RSMAvailable[7] szCurrencyCode[8][6] szCurrencyCode[0] szCurrencyCode[1] szCurrencyCode[7] Win32 Size Offset 32 0 32 32 8*4 64 4 64 4 68 4 48 * 1 6*1 6*1 6*1 144 92 96 96 102 138 Win16 Size Offset 32 0 32 32 8*2 64 2 64 2 66 2 48 * 1 6*1 6*1 6*1 128 78 80 80 86 122 OS/2 Size Offset 32 0 32 32 8*4 64 4 64 4 68 4 48 * 1 6*1 6*1 6*1 144 92 96 96 102 138

Char

Structure size

27 June 2012

539.1261/03 DRAFT Version 5.02

263

TCR Twin Safe TSAPI Interface Description 220 TSC_OperatingTimes

This data structure is used when setting or retrieving the operating hours of the TCR Twin Safe. This can either be periodic operating windows or aperiodic operating windows. The field eDay is used for the setting of periodic windows and the fields Date and Time are used to define the requested date/time for an aperiodic set of operating window. The field NumOfOpWindows is used to set the number of operating windows which are specified by a user. At the moment TS2CommDLL supports two and four operating windows (hence, two or four on and off times), but it is strongly recommended always to work with four windows and set all not required windows to 24:00:00. Definition: typedef struct { ASCOM_Date Date; ASCOM_Time Time ; ASCOM_Time OnTimes[TSC_MAX_NUMBER_OF_ONOFFTIMES]; ASCOM_Time OffTimes[TSC_MAX_NUMBER_OF_ONOFFTIMES]; TTSCDayOfWeek eDay; TSC_NumOfOpWindows NumOfOpWindows; char pad[-]; } TSC_OperatingTimes; typedef TSC_OperatingTimes * PTSC_OperatingTimes; Memory alignment: Type ASCOM_Date ASCOM_Time ASCOM_Time Name Date Time OnTimes[4] OnTimes[0] OnTimes[1] OnTimes[3] OffTimes[4] OffTimes[0] OffTimes[1] OffTimes[3] eDay NumOfOpWindows pad[-] Win32 Size Offset 16 0 16 16 4 * 16 32 16 32 16 48 16 4 * 16 16 16 16 4 4 8 176 80 96 96 112 144 160 164 168 Win16 Size Offset 16 0 16 16 4 * 16 32 16 32 16 48 16 4 * 16 16 16 16 2 2 12 176 80 96 96 112 144 160 162 164 OS/2 Size Offset 16 0 16 16 4 * 16 32 16 32 16 48 16 4 * 16 16 16 16 1 1 14 176 80 96 96 112 144 160 161 162

ASCOM_Time

TTSCDayOfWeek TSC_NumOfOpWindows char Structure size

264

539.1261/3 Version 5.02

27 June 2012


221 TSC_StatisticTypes Definition: typedef struct { BOOL

TCR Twin Safe TSAPI Interface Description

This data structure is used when clearing the Handler statistics gathering totals.

ResetDepositTrans , ResetWithdrawalTrans, ResetEventCounts ; char pad[-]; } TSC_StatisticTypes; typedef TSC_StatisticTypes * PTSC_StatisticTypes ; Memory alignment: Type BOOL BOOL BOOL char Structure size Name ResetDepositTrans ResetWithdrawalTrans ResetEventCounts pad[-] Win32 Size Offset 4 0 4 4 4 8 4 12 16 Win16 Size Offset 2 0 2 2 2 4 10 6 16 OS/2 Size Offset 4 0 4 4 4 8 4 12 16

222

TSC_StatisticValues This data structure is used when retrieving the Handler statistics gathering totals. Definition:

typedef struct { TSCStatsType

char } TSC_StatisticValues; typedef TSC_StatisticValues * PTSC_StatisticValues;

NumNotesDeposited[TSC_MAX_RSMS_AND_DENOMINATIONS], NumNotesWithdrawn[TSC_MAX_RSMS_AND_DENOMINATIONS], MaxNotesDeposited[TSC_MAX_RSMS_AND_DENOMINATIONS], MinNotesDeposited[TSC_MAX_RSMS_AND_DENOMINATIONS], MaxNotesWithdrawn[TSC_MAX_RSMS_AND_DENOMINATIONS], MinNotesWithdrawn[TSC_MAX_RSMS_AND_DENOMINATIONS], TotalEvents[ASCOM_EVENT_STATUS_RANGE+1], NumDepositTrans, NumWithdrawalTrans; pad[4];

27 June 2012

539.1261/03 DRAFT Version 5.02

265

TCR Twin Safe TSAPI Interface Description Memory alignment: Type TSCStatsType Name NumNotesDeposited[8] NumNotesDeposited[0] NumNotesDeposited[1] NumNotesDeposited[7] NumNotesWithdrawn[8] NumNotesWithdrawn[0] NumNotesWithdrawn[1] NumNotesWithdrawn[7] MaxNotesDeposited[8] MaxNotesDeposited[0] MaxNotesDeposited[1] MaxNotesDeposited[7] MinNotesDeposited[8] MinNotesDeposited[0] MinNotesDeposited[1] MinNotesDeposited[7] MaxNotesWithdrawn[8] MaxNotesWithdrawn[0] MaxNotesWithdrawn[1] MaxNotesWithdrawn[7] MinNotesWithdrawn[8] MinNotesWithdrawn[0] MinNotesWithdrawn[1] MinNotesWithdrawn[7] TotalEvents[5] NumDepositTrans NumWithdrawalTrans pad[4] Win32 Size Offset 8*4 0 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 5*4 4 4 4 224 0 4 28 32 32 36 60 64 64 68 92 96 96 100 124 128 128 132 156 160 160 164 188 192 212 216 220 Win16 Size Offset 8*4 0 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 5*4 4 4 4 224 0 4 28 32 32 36 60 64 64 68 92 96 96 100 124 128 128 132 156 160 160 164 188 192 212 216 220

OS/2 Size Offset 8*4 0 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 8*4 4 4 4 5*4 4 4 4 224 0 4 28 32 32 36 60 64 64 68 92 96 96 100 124 128 128 132 156 160 160 164 188 192 212 216 220

TSCStatsType

TSCStatsType

TSCStatsType

TSCStatsType

TSCStatsType

TSCStatsType TSCStatsType TSCStatsType char Structure size

266

539.1261/3 Version 5.02

27 June 2012


223 TSC_SMConsultDrawerData Definition: typedef struct { TSCSMAmountType BOOL TSCIndexNumber TSCDrawerNumber char char char } TSC_SMConsultDrawerData; Memory alignment: Type TSCSMAmountType BOOL TSCIndexNumber TSCDrawerNumber char char char Structure size Name Amount Moved IndexNum DrawerNum szCurrencyCode[6] szIndexText[11] pad[-] Win32 Size Offset 8 0 4 8 2 12 2 14 6*1 16 11 * 1 22 15 * 1 33 48

TCR Twin Safe TSAPI Interface Description

This data structure is used when retrieving the SafeMaster consultation data.

Amount ; Moved ; IndexNum ; DrawerNum ; szCurrencyCode[ASCOM_CURRENCY_LEN+1] ; szIndexText[ASCOM_INDEX_TEXT_LEN+1] ; pad[-];

Win16 Size Offset 8 0 2 8 2 10 2 12 6*1 14 11 * 1 20 1 15 * 1 31 32

OS/2 Size Offset 8 0 4 8 2 12 2 14 6*1 16 11 * 1 22 33 48

224

TSC_SMConsultResponse This data structure is used when retrieving the SafeMaster consultation data. Definition:

typedef struct { TSC_SMConsultDrawerData DrawerData[ASCOM_MAX_SM_CURRS_ON_DRAWERS]; TSCCountType NumGroups ; char szCurrencyText[ASCOM_CURR_TEXT_LEN+1] ; char pad[8]; } TSC_SMConsultResponse; typedef TSC_ SMConsultResponse * PTSC_ SMConsultResponse ; Memory alignment: Type TSC_SMConsultDrawerData Name DrawerData[256] DrawerData[0] DrawerData[1] DrawerData[255] NumGroups szCurrencyText[6] pad[8] Win32 Size Offset 256 * 48 0 48 48 48 2 6*1 8 12304 0 48 12240 12288 12290 12296 Win16 Size Offset 256 * 32 0 32 32 32 2 6*1 8 8208 0 32 8160 8192 8194 8200 OS/2 Size Offset 256 * 48 0 48 0 48 48 48 2 6*1 8 12304 12240 12288 12290 12296

TSCCountType char char Structure size

27 June 2012

539.1261/03 DRAFT Version 5.02

267

TCR Twin Safe TSAPI Interface Description 225 TSC_SM_CurrData

This data structure is used when notifying the SafeMaster subsystem about a Deposit or Withdrawal. Definition: typedef struct { TSCSMAmountType Amount ; TSCIndexNumber IndexNum ; char szCurrencyCode[ASCOM_CURRENCY_LEN+1] ; } TSC_SM_CurrData ; typedef TSC_SM_CurrData * PTSC_SM_CurrData ; Memory alignment: Type TSCSMAmountType TSCIndexNumber char Structure size Name Amount IndexNum szCurrencyCode[6] Win32 Size Offset 8 0 2 8 6*1 10 16 Win16 Size Offset 8 0 2 8 6*1 10 16 OS/2 Size Offset 8 0 2 8 6*1 10 16

226

TSC_AsyncResponseData The FLAPI function call to retrieve data resulting from an asynchronous function call could theoretically generate data from any of the possible asynchronous commands. The calling application must set up this data structure so that the function can avoid causing a data overwrite if the response is not for the expected command. The application must specify the size of the data buffer as well as the location. Data will be written to this buffer as though it were of the appropriate data type. See the description of the FLAPI function call Asynchronous Get Response for the list of which data types correspond to which command types. Definition: typedef struct { void size_t ASCOM_CommandType char } TSC_AsyncResponseData; typedef TSC_AsyncResponseData Memory alignment: Win32 Size Offset 4 0 4 4 4 8 4 12 16 Win16 Size Offset 4 0 2 4 2 6 8 8 16 OS/2 Size Offset 4 0 4 4 1 8 7 9 16

*lpbuf; bufsize; eTwinSafeCommand; pad[-]; * PTSC_AsyncResponseData ;

Type void* size_t ASCOM_CommandType char Structure size

Name lpbuf bufsize eTwinSafeCommand pad[-]

268

539.1261/3 Version 5.02

27 June 2012


227 ASCOMUserList Definition: typedef struct { TSCCountType char char char } ASCOMUserList; typedef ASCOMUserList Memory alignment: Type TSCCountType char Name NumUsers szUsers[99][10] szUsers[0] szUsers[1] szUsers[98] cLevel pad[15] Win32 Size Offset 2 0 990 * 1 2 10 * 1 10 * 1 10 * 1 1 15 1008 2 12 982 992 993

TCR Twin Safe TSAPI Interface Description

NumUsers ; szUsers[ASCOM_MAX_USERS_PER_LEVEL] [ASCOM_USER_ID_LEN+1]; cLevel ; pad[15]; * PASCOMUserList ;

Win16 Size Offset 2 0 990 * 1 2 10 * 1 10 * 1 10 * 1 1 15 1008 2 12 982 992 993

OS/2 Size Offset 2 0 990 * 1 2 10 * 1 2 10 * 1 12 10 * 1 1 15 1008 982 992 993

char char Structure size

228

TSC_NewTellerInfo Definition: typedef struct { char

szUserID[ASCOM_USER_ID_LEN+1] , szPassword[ASCOM_PWD_LEN+1] , cUserLevel ; char pad[14]; } TSC_NewTellerInfo; typedef TSC_NewTellerInfo * PTSC_NewTellerInfo ; Memory alignment: Type char char char char Structure size Name szUserID[10] szPassword[7] cUserLevel pad[14] Win32 Size Offset 10 0 7 10 1 17 14 18 32 Win16 Size Offset 10 0 7 10 1 17 14 18 32 Size 10 7 1 14 32 OS/2 Offset 0 10 17 18

27 June 2012

539.1261/03 DRAFT Version 5.02

269

TCR Twin Safe TSAPI Interface Description 229 TSC_CurrencyData Definition: typedef struct { TSCCrncyFactorType char char char } TSC_CurrencyData ; typedef TSC_CurrencyData Memory alignment: Type TSCCrncyFactorType char char char Structure size Name CurrencyFactor szCurrencyCode[6] szCurrencyText[6] pad[12] Win32 Size Offset 8 0 6*1 8 6*1 14 12 20 32 Win16 Size Offset 8 0 6*1 8 6*1 14 12 20 32

CurrencyFactor; szCurrencyCode[TSC_CURRENCY_LEN+1] ; szCurrencyText[ASCOM_CURR_TEXT_LEN+1]; pad[12]; * PTSC_CurrencyData ;

OS/2 Size Offset 8 0 6*1 8 6*1 14 12 20 32

230

TSCDelayClassParams Definition: typedef struct { TSCThresholdAmountType TSCDelayType TSCIndexNumber char } TSCDelayClassParams ; typedef TSCDelayClassParams Memory alignment:

FromAmount, ToAmount ; FromDelay, ToDelay ; ClassIndex ; pad[10]; * PTSCDelayClassParams ; Win32 Size Offset 8 0 8 8 2 16 2 18 2 20 10 22 32 Win16 Size Offset 8 0 8 8 2 16 2 18 2 20 10 22 32 OS/2 Offset 0 8 16 18 20 22

Type TSCThresholdAmountType TSCThresholdAmountType TSCDelayType TSCDelayType TSCIndexNumber char Structure size

Name FromAmount ToAmount FromDelay ToDelay ClassIndex pad[10]

Size 8 8 2 2 2 10 32

270

539.1261/3 Version 5.02

27 June 2012


231 TSCRollStorageData Definition:

TCR Twin Safe TSAPI Interface Description

typedef struct { TSCIndexNumber BankNotes[ASCOM_MAX_RSM_NOTES]; TSCRSMType RSMNumber ; char pad[6]; } TSCRollStorageData ; typedef TSCRollStorageData * PTSCRollStorageData ; Memory alignment: Type TSCIndexNumber Name BankNotes[4] BankNotes[0] BankNotes[1] BankNotes[3] RSMNumber pad[6] Win32 Size Offset 4*2 0 2 2 2 2 6 16 0 2 6 8 10 Win16 Size Offset 4*2 0 2 2 2 2 6 16 0 2 6 8 10 OS/2 Size Offset 4*2 0 2 2 2 2 6 16 0 2 6 8 10

TSCRSMType char Structure size

232

TSC_SMDrawerCurrData Definition: typedef struct { TSCSMAmountType TSCIndexNumber TSCDrawerNumber TSCDelayType char char char char } TSC_SMDrawerCurrData; typedef TSC_SMDrawerCurrData Memory alignment:

Amount ; Index ; DrawerNumber ; Delay ; szCurrencyCode[ASCOM_CURRENCY_LEN+1] ; szCurrencyText[ASCOM_CURRENCY_LEN+1] ; szIndexText[ASCOM_INDEX_TEXT_LEN+1] ; pad[11]; * PTSC_SMDrawerCurrData ;

Type TSCSMAmountType TSCIndexNumber TSCDrawerNumber TSCDelayType char char char char Structure size

Name Amount Index DrawerNumber Delay szCurrencyCode[6] szCurrencyText[6] szIndexText[11] pad[11]

Win32 Size Offset 8 0 2 8 2 10 2 12 6*1 14 6*1 20 11 * 1 26 11 37 48

Win16 Size Offset 8 0 2 8 2 10 2 12 6*1 14 6*1 20 11 * 1 26 11 37 48

OS/2 Size Offset 8 0 2 8 2 10 2 12 6*1 14 6*1 20 11 * 1 26 11 37 48

27 June 2012

539.1261/03 DRAFT Version 5.02

271

TCR Twin Safe TSAPI Interface Description 233 TSC_DEPOSIT This data structure is used to set the value and specify the destination RSM for objects Definition: typedef struct TTSC_DEPOSIT { TSCAmount TSCNumberOfObjects TSCRSMType char } TSC_DEPOSIT; Memory alignment: Type TSCAmount TSCNumberOfObjects TSCRSMType char Structure size Name amount numberOfObjects RSMNumber pad[-] Win32 Size Offset 8 0 4 8 2 12 2 14 16 Win16 Size Offset 8 0 2 8 2 10 4 12 16 Size 8 4 2 2 16

amount; numberOfObjects; RSMNumber; pad[-];

OS/2 Offset 0 8 12 14

272

539.1261/3 Version 5.02

27 June 2012


234 TSC_DEPOSIT_INPUT

TCR Twin Safe TSAPI Interface Description

This data structure is used with de TSC_FDepositErf and TSC_FADepositErf. It stores all data for the request sent to the TCR TS. It specifies wich information will be available in the TSC_DEPOSIT_OUTPUT structure (response data). Definition: typedef struct { BOOL amountListFlag; BOOL noteStackListFlag; BOOL noteRejectedFlag; BOOL erfFlag; int pad[-]; } TSC_DEPOSIT_INPUT; typedef TSC_DEPOSIT_INPUT *PTSC_DEPOSIT_INPUT; amountListFlag : This flag specifies if the amounts information will be returned or not. noteStackListFlag : This flag specifies if the note stack information will be returned or not. noteRejectedFlag : This flag specifies if the rejected flag information will be returned or not. erfFlag : This flag specifies if the deposit function should run in ERF mode or not. If this flag is FALSE all notes are deposited to the target RSM. If erfMode is TRUE the counterfeit and suspect notes are returned to the output tray. Memory alignment: Type BOOL BOOL BOOL BOOL int Structure size Name amountListFlag noteStackListFlag noteRejectedFlag erfFlag pad[-] Win32 Size Offset 4 0 4 4 4 8 4 12 16 Win16 Size Offset 2 0 2 2 2 4 2 6 4*2 8 16 OS/2 Size Offset 4 0 4 4 4 8 4 12 16

27 June 2012

539.1261/03 DRAFT Version 5.02

273

TCR Twin Safe TSAPI Interface Description 235 TSC_DEPOSIT_OUTPUT

This data structure is used with de TSC_FDepositErf and TSC_FADepositErf. It stores all data received from the TCR TS. According to the values of the flag members in the TSC_DEPOSIT_INPUT structure, some members of this structure will be valid or not. Definition: typedef struct { TSC_NoteStack TSC_AMOUNT_LIST TSC_DENOMINATIONS_LIST BOOL BOOL BOOL TSC_POLLINGFLAG BOOL BOOL int } TSC_DEPOSIT_OUTPUT; typedef TSC_DEPOSIT_OUTPUT

noteStackList; amountList; denominationList; amountListValid; noteStackListValid; noteRejectedValid; noteRejected; erfFlagValid; erfFlag; pad[2]; *PTSC_DEPOSIT_OUTPUT;

denominationList : A list of notes processed into each RSM during the deposit processing amountList : A list of amounts processed into each RSM during the deposit processing noteStackList : A structure receiving the details for each denomination deposited in a currency RSM. The NumberOfStackEntries attribute stores how much entries in the noteStack array are filled. This array holds details for each denomination including the RSM number where these notes where deposited noteRejected : a TSC_POLLINGFLAG variable. The parameter becomes TRUE if there were notes rejected during separation. erfFlag : This flag is set to TRUE if counterfeit or suspect notes were detected during the deposit transaction. In this case the bundle of rejected notes has to be processed a second time to separate the suspects and counterfeits from the rest of the rejected notes amountListValid, noteStackListValid, noteRejectedValid, erfFlagValid : These booleans mention if the corresponding data members in the structure are valid or not. Memory alignment: Type TSC_NoteStack TSC_AMOUNT_LIST TSC_DENOMINATIONS_LIST 274 Name noteStackList amountList denominationList Win32 Size Offset 1616 0 64 1616 32 1680 Win16 Size Offset 1616 0 64 1616 32 1680 OS/2 Size Offset 1616 0 64 1616 32 1680

539.1261/3 Version 5.02

27 June 2012


BOOL BOOL BOOL TSC_POLLINGFLAG BOOL BOOL int Structure size amountListValid noteStackListValid noteRejectedValid noteRejected erfFlagValid erfFlag pad[2] 4 4 4 4 4 4 2*4 1744 1712 1716 1720 1724 1728 1732 1736

TCR Twin Safe TSAPI Interface Description 2 2 2 2 2 2 2*2 1728 1712 1714 1716 1718 1720 1722 1724 4 4 4 4 4 4 2*4 1744 1712 1716 1720 1724 1728 1732 1736

27 June 2012

539.1261/03 DRAFT Version 5.02

275

TCR Twin Safe TSAPI Interface Description 236 TSC_DEPOSIT_OBJECT_INPUT

This data structure is used with de TSC_FDepositObjectEco and TSC_FADepositObjectEco. It stores all data for the request sent to the TCR TS. Definition: typedef struct { TSCAmount amount; TSCNumberOfObjects numberOfObjects; BOOL assignedNoteIdValid; int assignedNoteId; BOOL erfModeFlagValid; BOOL erfModeFlag; TSCRSMType rsmNumber; char pad[-]; } TSC_DEPOSIT_OBJECT_INPUT; typedef TSC_DEPOSIT_OBJECT_INPUT *PTSC_DEPOSIT_OBJECT_INPUT; amount: The amount. rsmNumber: The destination RSM. numberOfObjects: The number of the objects. assignedNoteId : The note identification number. The note identification number can be used instead of specifying an amount. erfFlag : This flag specifies if the deposit function should run in ERF mode or not. If this flag is FALSE all notes are deposited to the target RSM. If erfMode is TRUE the counterfeit and suspect notes are returned to the output tray. assignedNoteIdValid, erfModeFlagValid : These booleans mention if the corresponding data members in the structure are valid or not (must be considered or not by the function). Memory alignment:

276

539.1261/3 Version 5.02

27 June 2012


Type TSCAmount TSCNumberOfObjects BOOL int BOOL BOOL TSCRSMType char Structure size Name amount numberOfObjects assignedNoteIdValid assignedNoteId erfModeFlagValid erfModeFlag rsmNumber pad[-] Win32 Size Offset 8 0 4 8 4 12 4 16 4 20 4 24 2 28 2 30 32

TCR Twin Safe TSAPI Interface Description

Win16 Size Offset 8 0 2 8 2 10 2 12 2 14 2 16 2 18 12 20 32

OS/2 Size Offset 8 0 4 8 4 12 4 16 4 20 4 24 2 28 2 30 32

27 June 2012

539.1261/03 DRAFT Version 5.02

277

TCR Twin Safe TSAPI Interface Description 237 TSC_DEPOSIT_OBJECT_OUTPUT

This data structure is used with de TSC_FDepositObjectEco and TSC_FADepositObjectEco. It stores all data received from the TCR TS. Definition: typedef struct { TSCNumberOfObjects numberOfObjects; BOOL erfFlagValid; BOOL erfFlag; char pad[-]; } TSC_DEPOSIT_OBJECT_OUTPUT; typedef TSC_DEPOSIT_OBJECT_OUTPUT *PTSC_DEPOSIT_OBJECT_OUTPUT; numberOfObjects : The number of deposited objects. erfFlag : This flag is set to TRUE if counterfeit or suspect notes were detected during the deposit transaction. In this case the bundle of rejected notes has to be processed a second time to separate the suspects and counterfeits from the rest of the rejected notes. erfFlagValid: These booleans mention if the corresponding data members in the structure are valid or not. Memory alignment: Type TSCNumberOfObjects BOOL BOOL char Structure size Name numberOfObjects erfFlagValid erfFlag pad[-] Win32 Size Offset 4 0 4 4 4 8 4 12 16 Win16 Size Offset 2 0 2 2 2 4 10 6 16 Size 4 4 4 4 16 OS/2 Offset 0 4 8 12

278

539.1261/3 Version 5.02

27 June 2012


238 TSC_ERF_NOTE_INFO

TCR Twin Safe TSAPI Interface Description

This data structure is used with de TSC_FReadOneNote and TSC_FAReadOneNote. It stores all data received from the TCR TS. typedef struct { int NoteId; int Presentation; int NoteValue; int SDA_Category; int SDA_Fitness; int RSM_Number; char Staff_ECBCategory[3+1]; char Customer_ECBCategory[3+1]; char Currency[6+1]; char NoteModel[5+1]; char pad[-]; } TSC_ERF_NOTE_INFO; typedef TSC_ERF_NOTE_INFO *PTSC_ERF_NOTE_INFO;

NoteId: Note Id. Staff_ECBCategory: Staff-operated-machine. ECB Category A: object not recognised as banknote or suspect counterfeit banknote B1: banknote identified as genuine and fit B2: banknote identified as genuine and unfit Customer_ECBCategory: Customer-operated-machine. ECB Category 1: not a banknote, not recognised as banknote 2: object identified as suspect counterfeit banknote 3: bank note not clearly authenticated 4a: banknote identified as genuine and fit 4b: banknote identified as genuine and unfit Presentation: Presentation. 0: presentation ok 1: eccentric 2: skewed 3: double 4: no rsm for this banknote or RSM blocked NoteValue: Note value. Currency: Currency. NoteModel: Note model. SDA_Category: SDA Category. 0: not recognized 1: counterfeit 2: suspect
27 June 2012 539.1261/03 DRAFT Version 5.02

279

TCR Twin Safe TSAPI Interface Description 3: genuine SDA_Fitness: SDA Fitness. 0: ATM fit 1: Recycling fit 2: Storage fit 3: Storage unfit RSM_Number: Rsm number where the note is stored. 0 to 8 0 output compartment Memory alignment:

280

539.1261/3 Version 5.02

27 June 2012


Type int int int int int int char char char char char Structure size Name NoteId Presentation NoteValue SDA_Category SDA_Fitness RSM_Number Staff_ECBCategory[4] Customer_ECBCategory[4] Currency[7] NoteModel[6] Pad[-]

TCR Twin Safe TSAPI Interface Description

Win32 Size Offset 4 0 4 4 4 8 4 12 4 16 4 20 4*1 24 4*1 28 7*1 32 6*1 39 3 45 48

Win16 Size Offset 2 0 2 2 2 4 2 6 2 8 2 10 4*1 12 4*1 16 7*1 20 6*1 27 15 33 48

OS/2 Size Offset 4 0 4 4 4 8 4 12 4 16 4 20 4*1 24 4*1 28 7*1 32 6*1 39 3 45 48

27 June 2012

539.1261/03 DRAFT Version 5.02

281

TCR Twin Safe TSAPI Interface Description 239 TSC_ERFMode This data structure is used with de TSC_FGetErfMode, TSC_FSetErfMode and TSC_FGetTypeAndCapabilities. typedef enum { TSC_ERF_MODE_DISABLED = 0, // Erf mode is disable TSC_ERF_MODE_STANDARD = 1, // Erf mode is standard TSC_ERF_MODE_INTEGRATED = 2 // Erf mode is integrated } TSC_ERFMode; typedef TSC_ERFMode *PTSC_ERFMode;

282

539.1261/3 Version 5.02

27 June 2012


240 TSC_TypeAndCapabilities

TCR Twin Safe TSAPI Interface Description

This data structure is used with de TSC_FGetTypeAndCapabilities. typedef struct { BOOL ERFCapability; int NumberOfRSM; TSC_ERFMode ERFMode; TSC_MachineType MachineType; TSC_RSType RSType; TSC_NHType NHType; char pad[-]; } TSC_TypeAndCapabilities; typedef TSC_TypeAndCapabilities *PTSC_TypeAndCapabilities; MachineType: Machine type. RSType: Roll storage type. NHType: Note handling type. ErfCapabilities: ERF capabable. ErfMode: current ERF mode. typedef enum { TSC_TS, TSC_TSF, TSC_ES, TSC_ECO, TSC_TSFERF } TSC_MachineType; typedef enum { TSC_NH_CLASSIC, TSC_NH_TS, TSC_NH_ERF } TSC_NHType; typedef enum { TSC_RS_CLASSIC, TSC_RS_TS, TSC_RS_ES } TSC_RSType; Memory Alignment: Type BOOL int TSC_ERFMode TSC_MachineType Name ERFCapability NumberOfRSM ERFMode MachineType Win32 Size Offset 4 0 4 4 4 8 4 12 Win16 Size Offset 2 0 2 2 2 4 2 6 Size 4 4 1 1 OS/2 Offset 0 4 8 9 283

// // // // // //

TCR Classic TCR Twin Safe TCR Twin Safe ES TCR Twin Safe ECO TCR Twin Safe ERF upgraded Type of TCR

// // // //

Classic type TS type Erf capable type Type of Note Handling

// // // //

Classic type TS type ES type Type of Roll Storage

27 June 2012

539.1261/03 DRAFT Version 5.02

TCR Twin Safe TSAPI Interface Description TSC_RSType TSC_NHType char Structure size RSType NHType pad[-] 4 4 8 32 16 20 24 2 2 4 16 8 10 12 1 1 4 16

10 11 12

284

539.1261/3 Version 5.02

27 June 2012


241 TSC_RSM_ASSIGN Definition:

TCR Twin Safe TSAPI Interface Description

This data structure is used to retrieve the consultation information for each RSM.

typedef struct TTSC_RSM_ASSIGN { long noteValue[MAX_NUMBER_OF_RSM]; int moduleAvailability[MAX_NUMBER_OF_RSM]; int numberOfNotes[MAX_NUMBER_OF_RSM]; int RSMType[MAX_NUMBER_OF_RSM]; char currencyCode[MAX_NUMBER_OF_RSM][ASCOM_CURRENCY_LEN+1]; } TSC_RSM_ASSIGN; Memory alignment: Type long int Name noteValue[8] moduleAvailability[8] moduleAvailability[0] moduleAvailability[1] moduleAvailability[7] numberOfNotes[8] RSMType[8] currencyCode[8][6] Win32 Size Offset 8*4 0 8*4 32 4 32 4 4 8*4 8*4 48 * 1 6*1 6*1 6*1 176 36 60 64 96 128 128 134 170 Win16 Size Offset 8*4 0 8*2 32 2 32 2 2 8*2 8*2 48 * 1 6*1 6*1 6*1 128 34 46 48 64 80 80 86 122 OS/2 Size Offset 8*4 0 8*4 32 4 32 4 4 8*4 8*4 48 * 1 6*1 6*1 6*1 176 36 60 64 96 128 128 134 170

int int char

currencyCode[0] currencyCode[1] currencyCode[7] Structure size

27 June 2012

539.1261/03 DRAFT Version 5.02

285

TCR Twin Safe TSAPI Interface Description 242 TSC_RSM_ASSIGN_2 This data structure is used to retrieve the consultation information for each RSM. Definition: typedef struct TTSC_RSM_ASSIGN { long noteValue[MAX_NUMBER_OF_RSM]; int moduleAvailability[MAX_NUMBER_OF_RSM]; int numberOfNotes[MAX_NUMBER_OF_RSM]; int RSMType[MAX_NUMBER_OF_RSM]; int RSMState[MAX_NUMBER_OF_RSM]; int reserve1[MAX_NUMBER_OF_RSM]; int reserve2[MAX_NUMBER_OF_RSM]; int reserve3[MAX_NUMBER_OF_RSM]; int reserve4[MAX_NUMBER_OF_RSM]; int reserve5[MAX_NUMBER_OF_RSM]; char currencyCode[MAX_NUMBER_OF_RSM][ASCOM_CURRENCY_LEN+1]; } TSC_RSM_ASSIGN; RSMState : State description State value Memory alignment: Type long int Name noteValue[8] moduleAvailability[8] moduleAvailability[0] moduleAvailability[1] moduleAvailability[7] numberOfNotes[8] RSMType[8] RSMState[8] reserve1[8] Reserve2[8] Reserve3[8] Reserve4[8] Reserve5[8] currencyCode[8][6] Win32 Size Offset 8*4 0 8*4 32 4 32 4 4 8*4 8*4 8*4 8*4 8*4 8*4 8*4 8*4 48 * 1 6*1 6*1 6*1 368 36 60 64 96 128 160 192 224 256 288 320 326 332 362 Win16 Size Offset 8*4 0 8*2 32 2 32 2 2 8*2 8*2 8*2 8*2 8*2 8*2 8*2 8*2 48 * 1 6*1 6*1 6*1 224 34 46 48 64 80 96 112 128 144 160 176 176 182 218

Ok 0

Full 1

High 2

Empty 3

Low 4

OS/2 Size Offset 8*4 0 8*4 32 4 32 4 4 8*4 8*4 8*4 8*4 8*4 8*4 8*4 8*4 48 * 1 6*1 6*1 6*1 368 36 60 64 96 128 160 192 224 256 288 320 326 332 362

int int int int int int int int char

currencyCode[0] currencyCode[1] currencyCode[7] Structure size

286

539.1261/3 Version 5.02

27 June 2012


243 TSC_RSM_ASSIGNMENT Definition: typedef struct TTSC_RSM_ASSIGNMENT { int noteID; int decisionResult; int orientation; int quality; int rsmNum; int pad[3]; } TSC_RSM_ASSIGNMENT; Memory alignment: Type int int int int int int Structure Name noteID decisionResult orientation quality rsmNum pad[3] size Win32 Size Offset 4 0 4 4 4 8 4 12 4 16 3*4 20 32

TCR Twin Safe TSAPI Interface Description

This data structure is used to retrieve the assignment information for a RSM.

Win16 Size Offset 2 0 2 2 2 4 2 6 2 8 3*2 10 16

OS/2 Size Offset 4 0 4 4 4 8 4 12 4 16 3*4 20 32

244

TSC_RSM_ASSIGNMENT_LIST This data structure is used to retrieve information for each assigned RSM. The variable entry contains the assignment information of each assigned RSM. The variable numEntries contains the number of assigned RSMs. The variable numRSMs contains the total number of RSMs. And the variable typeRSM contains the RSM type for each RSM. Definition: typedef struct TTSC_RSM_ASSIGNMENT_LIST { TSC_RSM_ASSIGNMENT entry[MAX_RSM_ASSIGNMENTS]; int numEntries; int numRSMs; TSC_LAST_RSM_MODES typeRSM[MAX_NUMBER_OF_RSM]; char pad[-]; } TSC_RSM_ASSIGNMENT_LIST;

27 June 2012

539.1261/03 DRAFT Version 5.02

287

TCR Twin Safe TSAPI Interface Description Memory alignment: Type TSC_RSM_ASSIGNMENT Name entry[128] entry[0] entry[1] entry[127] numEntries numRSMs typeRSM[8] typeRSM[0] typeRSM[1] typeRSM[7] pad[-] Win32 Size Offset 128 * 32 0 32 32 32 4 4 8*4 4 4 4 8 4144 0 32 4064 4096 4100 4104 4104 4108 4132 4136 Win16 Size Offset 128 * 16 0 16 16 16 2 2 8*2 2 2 2 12 2080 0 16 2032 2048 2050 2052 2052 2054 2066 2068

OS/2 Size Offset 128 * 32 0 32 0 32 32 32 4 4 8*1 1 1 1 4112 4064 4096 4100 4104 4104 4105 4111 4112

int int TSC_LAST_RSM_MODES

char Structure size

288

539.1261/3 Version 5.02

27 June 2012


245 TSC_RSM_ECO_ASSIGNMENT Definition: typedef struct TTSC_RSM_ECO_ASSIGNMENT { int noteID; int noteID_mask; int presentation; int presentation_mask; int identification; int identification_mask; int fitness; int fitness_mask; int authentication; int authentication_mask; int rsmNum; int pad[-]; } TSC_RSM_ECO_ASSIGNMENT; Memory alignment: Type int int int int int int int int int int int int Structure 246 Name noteID noteID_mask presentation presentation_mask identification identification_mask fitness fitness_mask authentication authentication_mask rsmNum pad[-] size Win32 Size Offset 4 0 4 4 4 8 4 12 4 16 4 20 4 24 4 28 4 32 4 36 4 40 4 44 48

TCR Twin Safe TSAPI Interface Description

This data structure is used to retrieve the assignment information for a RSM.

Win16 Size Offset 2 0 2 2 2 4 2 6 2 8 2 10 2 12 2 14 2 16 2 18 2 20 5*2 22 32

OS/2 Size Offset 4 0 4 4 4 8 4 12 4 16 4 20 4 24 4 28 4 32 4 36 4 40 4 44 48

TSC_RSM_ECO_ASSIGNMENT_LIST This data structure is used to retrieve information for each assigned RSM. The variable entry contains the assignment information of each assigned RSM. The variable numEntries contains the number of assigned RSMs. The variable numRSMs contains the total number of RSMs. And the variable typeRSM contains the RSM type for each RSM. Definition: typedef struct TTSC_RSM_ECO_ASSIGNMENT_LIST { TSC_RSM_ECO_ASSIGNMENT entry[MAX_RSM_ASSIGNMENTS]; int numEntries; int numRSMs; TSC_LAST_RSM_MODES typeRSM[MAX_NUMBER_OF_RSM]; char pad[-]; } TSC_RSM_ECO_ASSIGNMENT_LIST; typedef TSC_RSM_ECO_ASSIGNMENT_LIST *PTSC_RSM_ECO_ASSIGNMENT_LIST; Memory alignment:

27 June 2012

539.1261/03 DRAFT Version 5.02

289

TCR Twin Safe TSAPI Interface Description Win32 Size Offset 128 * 48 0 48 48 48 4 4 8*4 4 4 4 8 6192 0 48 6096 6144 6148 6152 6152 6156 6180 6184 Win16 Size Offset 128 * 32 0 32 32 32 2 2 8*2 2 2 2 12 4128 0 32 4064 4096 4098 4100 4100 4102 4114 4116

OS/2 Size Offset 128 * 48 0 48 0 48 48 48 4 4 8*1 1 1 1 6160 6096 6144 6148 6152 6153

Type TSC_RSM_ECO_ASSIGNMENT

int int TSC_LAST_RSM_MODES

Name entry[128] entry[0] entry[1] entry[127] numEntries numRSMs typeRSM[8] typeRSM[0] typeRSM[1] typeRSM[7] pad[-]

char Structure size

6159 6160

290

539.1261/3 Version 5.02

27 June 2012


247 TSC_RSM_NOTESTACK_DETAILS Definition:

TCR Twin Safe TSAPI Interface Description

This data structure is part of the TSC_RSM_NOTESTACK_DETAILS_LIST .

typedef struct TTSC_RSM_NOTESTACK_DETAILS { double noteValue; unsigned long bandPosition; int stackIndex; int noteId; int noteWidth; int noteGap; int fitnessLevel; char szIsoCurrencyCode[TSC_CURRENCY_LEN+1]; char pad[-]; } TSC_RSM_NOTESTACK_DETAILS; fitnessLevel: fitness level. 0: ATM fit 1: Recycling fit 2: Storage fit 3: Storage unfit Memory alignment: Type double unsigned long int int int int int char char Structure size Name noteValue bandPosition stackIndex noteId noteWidth noteGap fitnessLevel szIsoCurrencyCode[6] pad[-] Win32 Size Offset 8 0 4 8 4 12 4 16 4 20 4 24 4 28 6*1 32 10 * 1 38 48 Win16 Size Offset 8 0 4 8 2 12 2 14 2 16 2 18 2 20 6*1 22 4*1 28 32 OS/2 Size Offset 8 0 4 8 4 12 4 16 4 20 4 24 4 28 6*1 32 10 * 1 38 48

248

TSC_RSM_NOTESTACK_DETAILS_LIST This data structure is used to retrieve the note stack details information for one. rsmId contains the RSM identifiaction numberOfValidItem contains the number of valid TSC_RSM_NOTESTACK_DETAILS in the table. Definition:
typedef struct TTSC_RSM_NOTESTACK_DETAILS_LIST { TSC_RSM_NOTESTACK_DETAILS noteStackItem[TSC_MAX_NUMBER_OF_NOTESTACK_DETAILS_ITEM]; int rsmId; int numberOfValidItem; char pad[-]; } TSC_RSM_NOTESTACK_DETAILS_LIST; typedef TSC_RSM_NOTESTACK_DETAILS_LIST *PTSC_RSM_NOTESTACK_DETAILS_LIST;

Memory alignment: Win32

27 June 2012 539.1261/03 DRAFT Version 5.02

Win16

OS/2 291

TCR Twin Safe TSAPI Interface Description Name noteStackItem[700] rsmId numberOfValidItem pad[-] Size 700 * 48 4 4 8 33616 Offset 0 33600 33604 33608 Size 700 * 32 2 2 12 22416 Offset 0 22400 22402 22404

Size 700 * 48 4 4 8 33616 Offset 0 33600 33604 33608

ype SC_RSM_NOTESTACK_DETAILS nt nt har tructure size

292

539.1261/3 Version 5.02

27 June 2012


249 TSC_DOWNLOAD_SW_INFO Definition: typedef struct TTSC_DOWNLOAD_SW_INFO { char *filename; char *destination; char pad[8]; } TSC_DOWNLOAD_SW_INFO; Memory alignment: Type char* char* char Structure size Name filename destination pad[8] Win32 Size Offset 4 0 4 4 8 8 16

TCR Twin Safe TSAPI Interface Description

This data structure is used to specify a destination module and a source file.

Win16 Size Offset 4 0 4 4 8 8 16

OS/2 Size Offset 4 0 4 4 8 8 16

250

TSC_DOWNLOAD_LANGUAGE_INFO This data structure is used to specify a language name, a slot number and a source file. Definition:

typedef struct TTSC_DOWNLOAD_LANGUAGE_INFO { char *language; char *filename; int slot; char pad[-]; } TSC_DOWNLOAD_LANGUAGE_INFO;

27 June 2012

539.1261/03 DRAFT Version 5.02

293

TCR Twin Safe TSAPI Interface Description Memory alignment: Type char* char* int char Structure size Name language filename slot pad[-] Win32 Size Offset 4 0 4 4 4 8 4 12 16 Win16 Size Offset 4 0 4 4 2 8 6 10 16

OS/2 Size Offset 4 0 4 4 4 8 4 12 16

251

TSC_UPLOAD_PARAMETERFILE_INFO This data structure is used to specify a section, a source file,. the append flag and the data type. Definition: typedef struct TTSC_UPLOAD_PARAMETERFILE_INFO { char *section; char *filename; int flag; int dataType; char pad[-]; } TSC_UPLOAD_PARAMETERFILE_INFO; Memory alignment:

Type char* char* int int char Structure size

Name section filename flag dataType pad[-]

Win32 Size Offset 4 0 4 4 4 8 4 12 16

Win16 Size Offset 4 0 4 4 2 8 2 10 4 12 16

OS/2 Size Offset 4 0 4 4 4 8 4 12 16

252

TSC_UPLOAD_PARAMETER This data structure is used to retrieve a pointer of a buffer and the size of the parameter string. Definition: typedef struct TTSC_UPLOAD_PARAMETER { char *parameter; int size; char pad[-]; } TSC_UPLOAD_PARAMETER; Memory alignment:

Type char* int char 294

Name parameter size pad[-]

Win32 Size Offset 4 0 4 4 8 8

Win16 Size Offset 4 0 2 4 10 6

OS/2 Size Offset 4 0 4 4 8 8

539.1261/3 Version 5.02

27 June 2012


Structure size 16 16

TCR Twin Safe TSAPI Interface Description 16

27 June 2012

539.1261/03 DRAFT Version 5.02

295

TCR Twin Safe TSAPI Interface Description 253 TSC_TSCounterResponse

This data structure holds results of the counting function (TSC_FCounter). The structure holds the number of counted denominations, an array of TSC_TSCOUNTERNOTEDATA which contains information about the denominations, number of double notes counted and number of error notes. Definition: typedef struct { TSC_TSCOUNTERNOTEDATA noteData[MAX_NUMBER_OF_COUNTERNOTEDATA]; int NumberNoteData; int NotesUnassigned; int NotesDouble; int Pad[-]; } TSC_TSCounterResponse; typedef TSC_TSCounterResponse *PTSC_TSCounterResponse ; Memory alignment: Name noteData[16] noteData[0] noteData[1] noteData[15] NumberNoteData NotesUnassigned NotesDouble Pad[-] Win32 Size Offset 16 * 32 0 32 32 32 4 4 4 4 528 0 32 480 512 516 520 524 Win16 Size Offset 16 * 16 0 16 0 16 16 16 2 2 2 5*2 272 240 256 258 260 262 OS/2 Size Offset 16 * 32 0 32 32 32 4 4 4 4 528 0 32 480 512 516 520 524

Type TSC_TSCOUNTERNOTEDATA

int int int int Structure size

254

TSC_TSCOUNTERNOTEDATA This data structure is part of the TSC_TSCounterResponse structure. The structure contains information about one denomination counted with the counting function. The structure has fields for the note id, the currency code of the note, the note value and the number of counted notes. Definition: typedef struct { long TSCDenominationType int char char } TSC_TSCOUNTERNOTEDATA; Memory alignment: Win32 Size Offset 4 0 4 4 4 8 Win16 Size Offset 4 0 4 4 2 8 OS/2 Size Offset 4 0 4 4 4 8

noteValue; numberOfNotes; noteID; szCurrencyCode[ASCOM_CURRENCY_LEN+1]; pad[-];

Type long TSCDenominationType int 296

Name noteValue numberOfNotes noteID

539.1261/3 Version 5.02

27 June 2012


char char Structure size szCurrencyCode[6] pad[-] 6*1 14 * 1 32

TCR Twin Safe TSAPI Interface Description 12 18 6*1 16 10 6*1 14 * 1 32 12 18

27 June 2012

539.1261/03 DRAFT Version 5.02

297

TCR Twin Safe TSAPI Interface Description 255 TSC_ReservationData

This data structure holds results of the get reservation state function (TSC_FGetReservationState). The structure holds the reservation state of the machine and the user name which took the reservation. cSide contains the information which side has reserved the machine. Possible values are R (right side), L (left side) and S (service). The port from which the reservation was taken is stored in iPort. This attribute can have the values 0 (service port), 1 (user port 1), 2 (user port 2) or 3 (PC port). Information about the purpose of the reservation can received from iReason. iReason can be 1 (TCR TS reserved for a deposit), 2 (withdrawal) and 3 (other functions). Definition: typedef struct { BOOL bReserved; int iPort; int iReason; char szUserid[ASCOM_USER_ID_LEN+1]; char cSide; char pad[-]; } TSC_ReservationData; typedef TSC_ReservationData *PTSC_ReservationData ; Memory alignment: Type BOOL int int char char char Structure size Name bReserved iPort iReason szUserid[10] cSide pad[-] Win32 Size Offset 4 0 4 4 4 8 10 * 1 12 1 22 9 23 32 Win16 Size Offset 2 0 2 2 2 4 10 * 1 6 1 16 15 17 32 OS/2 Size Offset 4 0 4 4 4 8 10 * 1 12 1 22 9 23 32

256

TSC_NoteStack This data structure is used in TSC_ExtDepositNoteStack function. The NumberOfStackEntries attribute holds the number of entries which are stored in the noteStack array. This array contains details for each denomination. Definition: typedef struct { TSC_NoteStackData int int } TSC_NoteStack; typedef TSC_NoteStack

noteStack[MAX_NUMBER_OF_NOTESTACK]; NumberOfStackEntries; pad[-]; *PTSC_NoteStack;

298

539.1261/3 Version 5.02

27 June 2012


Memory alignment: Type TSC_NoteStackData Name noteStack[50] noteStack[0] noteStack[1] noteStack[49] NumberOfStackEntries pad[-] Win32 Size Offset 50 * 32 0 32 32 32 4 3*4 1616 0 32 1568 1600 1604

TCR Twin Safe TSAPI Interface Description

Win16 Size Offset 50 * 32 0 32 32 32 2 7*2 1616 0 32 1568 1600 1602

OS/2 Size Offset 50 * 32 0 32 0 32 32 32 4 3*4 1616 1568 1600 1604

int int Structure size

257

TSC_NoteStackData This structure is part of the TSC_NoteStack structure. It holds the details for each denomination stored in a currency RSM during a deposit. Definition: typedef struct { long TSCDenominationType int int char char } TSC_NoteStackData; Memory alignment:

noteValue; numberOfNotes; rsmNum; noteID; szCurrencyCode[ASCOM_CURRENCY_LEN+1]; pad[-];

Type long TSCDenominationType int int char char Structure size

Name noteValue numberOfNotes rsmNum noteID szCurrencyCode[6] pad[-]

Win32 Size Offset 4 0 4 4 4 8 4 12 6*1 16 10 * 1 22 32

Win16 Size Offset 4 0 4 4 2 8 2 10 6*1 12 14 * 1 18 32

OS/2 Size Offset 4 0 4 4 4 8 4 12 6*1 16 10 * 1 22 32

258

TSC_LogInfo Definition: typedef struct { TSC_LogLineNumber NumberOfLines; TSC_LogLineNumber FirstLine; TSC_LogLineNumber LastLine; TSC_LogLineLength LineLength; char pad[2]; } TSC_LogInfo; typedef TSC_LogInfo *PTSC_LogInfo ;

27 June 2012

539.1261/03 DRAFT Version 5.02

299

TCR Twin Safe TSAPI Interface Description Memory alignment: Type TSC_LogLineNumber TSC_LogLineNumber TSC_LogLineNumber TSC_LogLineLength char Structure size Name NumberOfLines FirstLine LastLine LineLength pad[2] Win32 Size Offset 4 0 4 4 4 8 2 12 2 14 16 Win16 Size Offset 4 0 4 4 4 8 2 12 2 14 16 Size 4 4 4 2 2 16

OS/2 Offset 0 4 8 12 14

259

TSCTSLANGUAGE Definition: typedef struct TTSCTSLANGUAGE { char systemlanguage[LANGUAGELENGTH+1]; char language[TSC_MAX_NUMBER_OF_LANGUAGES] [LANGUAGELENGTH+1]; } TSCTSLANGUAGE; typedef TSCTSLANGUAGE *PTSCTSLANGUAGE; Memory alignment: Type char Name systemlanguage[4 ] char language[3][4] language[0] language[1] language[2] Structure size Win32 Size Offset 4*1 0 12 * 1 4*1 4*1 4*1 16 4 4 8 12 Win16 Size Offset 4*1 0 12 * 1 4*1 4*1 4*1 16 4 4 8 12 OS/2 Size Offset 4*1 0 12 * 1 4*1 4*1 4*1 16 4 4 8 12

260

TSC_TSDLSTDATA Definition: typedef struct { ASCOM_DateTime ASCOM_Time } TSC_TSDLSTDATA; Memory alignment:

DateTime; ShiftTime;

Type ASCOM_DateTime ASCOM_Time Structure size

Name DateTime ShiftTime

Win32 Size Offset 32 0 16 32 48

Win16 Size Offset 32 0 16 32 48

OS/2 Size Offset 32 0 16 32 48

300

539.1261/3 Version 5.02

27 June 2012


261 TSC_TSDLSTResponse Definition:

TCR Twin Safe TSAPI Interface Description

typedef struct { TSC_TSDLSTDATA DLSTimes[MAX_NUMBER_OF_DLSTIMES]; int NumberDLSTimes; char pad[-] } TSC_TSDLSTResponse; typedef TSC_TSDLSTResponse * PTSC_TSDLSTResponse; Memory alignment: Type TSC_TSDLSTDATA int char Structure size Name DLSTimes[60] NumberDLSTimes pad[-] Win32 Size Offset 60 * 48 0 4 2880 12 2884 2896 Win16 Size Offset 60 * 48 0 2 2880 14 2882 2896

OS/2 Size Offs 60 * 48 4 288 12 288 2896

262

TSC_CommConfig Definition: typedef struct { long long long long long long long BOOL BOOL BOOL int PORT PARITY STOPBITS CASHIER char char } TSC_CommConfig; typedef TSC_CommConfig

baudrate; waitAfterCommand; guardTol; tranTimeout; ackTimeout; procWaitTimeout; numRetries; used; doBlock; sharePort; databits; commPort; parity; stopbits; cashierSide; stationAddress[ASCOM_STN_ADDR_LEN + 1]; pad[-]; *PTSC_CommConfig;

27 June 2012

539.1261/03 DRAFT Version 5.02

301

TCR Twin Safe TSAPI Interface Description Memory alignment: Type long long long long long long long BOOL BOOL BOOL int PORT PARITY STOPBITS CASHIER char char Structure size Name baudrate WaitAfterCommand guardTol tranTimeout ackTimeout procWaitTimeout numRetries used doBlock sharePort databits commPort parity stopbits cashierSide stationAddress[5] pad[-] Win32 Size Offset 4 0 4 4 4 8 4 12 4 16 4 20 4 24 4 28 4 32 4 36 4 40 4 44 4 48 4 52 4 56 5*1 60 15 * 1 65 80 Win16 Size Offset 4 0 4 4 4 8 4 12 4 16 4 20 4 24 2 28 2 30 2 32 2 34 2 36 2 38 2 40 2 42 5*1 44 15 * 1 49 64

OS/2 Size Offset 4 0 4 4 4 8 4 12 4 16 4 20 4 24 4 28 4 32 4 36 4 40 1 44 1 45 1 46 1 47 5*1 48 11 * 1 53 64

263

TSC_DLLConfig Definition: typedef struct { TSC_CommConfig unsigned long long BOOL BOOL BOOL BOOL BOOL BOOL BOOL int unsigned short unsigned short char char char char } TSC_DLLConfig; typedef TSC_DLLConfig

commConfig[MAX_COMM_PORTS_SUPPORTED]; appID; traceFileSizeMaxKB; debug; useTCP; sumDenominations; packDenominations; keepCommOpen; traceUDP; allowAsyncOverwrite; trace; portNr; tracePortNr; ipAddress[256]; traceFile[256]; traceIPAddress[256]; pad[4]; *PTSC_DLLConfig;

302

539.1261/3 Version 5.02

27 June 2012


Memory alignment: Type TSC_CommConfig Name commConfig[2] commConfig[0] commConfig[1] appID traceFileSizeMaxKB debug useTCP sumDenominations packDenominations keepCommOpen traceUDP allowAsyncOverwrite trace portNr tracePortNr ipAddress[256] traceFile[256] traceIPAddress[256] pad[4] Win32 Size Offset 2 * 80 0 80 80 4 4 4 4 4 4 4 4 4 4 2 2 256 * 1 256 * 1 256 * 1 4 976 0 80 160 164 168 172 176 180 184 188 192 196 200 202 204 460 716 972

TCR Twin Safe TSAPI Interface Description

Win16 Size Offset 2 * 64 0 64 64 4 4 2 2 2 2 2 2 2 2 2 2 256 * 1 256 * 1 256 * 1 4 928 0 64 128 132 136 138 140 142 144 146 148 150 152 154 156 412 668 924

OS/2 Size Offset 2 * 64 0 64 64 4 4 4 4 4 4 4 4 4 4 2 2 256 * 1 256 * 1 256 * 1 4 944 0 64 128 132 136 140 144 148 152 156 160 164 168 170 172 428 684 940

unsigned long long BOOL BOOL BOOL BOOL BOOL BOOL BOOL Int unsigned short unsigned short char char char char Structure size

27 June 2012

539.1261/03 DRAFT Version 5.02

303

TCR Twin Safe TSAPI Interface Description

264

STATUS CODES
The values for these status codes are all defined in the header file TSCons.h. The table below explains the status codes generated by the FLAPI. These status codes are DLL internal events and are not the same as the TCR Twin Safe event numbers.

Code Nr 0x00000000 0xF0000000 0xF0000001 0xF0000002

Code syntax TSC_SUCCESS ERR_RESPONSE ERR_TIME_OUT ERR_NAK

0xF0000003

ERR_INVALID_RESPONSE

0xF0000004

ERR_CHECKSUMM

0xF0000005

ERR_HEADER

0xF0000006 0xF0000007 0xF0000010 0xF0000011 0xF0000012 0xF0000013 0xF0000014 0xF0000015 0xF0000100 0xF00000101 0xF00000103

ERR_COMM_PORT_BLOCK_ TIMEOUT ERR_ACK_TIME_OUT ERR_OPEN_LOG ERR_NO_PORT_OPEN ERR_BUSY ERR_COMM_EXTERNAL_AB ORT ERR_MAX_SUPPORTED_CO MM_PORTS_REACHED ERR_LOG_FILE_NOT_OPEN ERR_CAL_NOT_IDLE ERR_CAL_BLOCKED_BY_O THER_PROC ERR_NO_VALID_MUTEX

Code explanation FLAPI call successfully finished No response by the TCR Twin Safe Communication timeout during execution of a command TCR Twin Safe has not acknowledged the request. (maybe the communication setup is wrong, or the connection to the TwinSafe is disturbed) Received invalid response from the TCR Twin Safe (maybe the communication setup is wrong, or the connection to the TwinSafe is disturbed) Received an invalid checksum (maybe the communication setup is wrong, or the connection to the TwinSafe is disturbed) Received an invalid telegram header (maybe the communication setup is wrong, or the connection to the TwinSafe is disturbed) CommPort seems to be blocked by another process. (Try again later) No Acknolewdge to a command from TCRTS . Cannot open LogFile Cannot open Communication Port Another transaction process on this CommPort is still active Communication aborted by an external event Maximum number of supported CommPorts has been reached (Max 2 Com port) Function Add text to log called but no log file open ? This communication socket is actually in use by another process TSDLL hasnt been able to get a valid Mutex handle for this communication socket (maybe low on resources) TSDLL has detected an illegal reference onto a communication socket (maybe low on memory) No response data buffer found for the specified Teller (asynchronous calls) The specified response data buffer is too small (asynchronous

Error allocation TCR TWIN SAFE LAN COMM TCR TWIN SAFE LAN-PC RS232

TCR TWIN SAFE LAN-PC RS232

TCR TWIN SAFE LAN-PC RS232 TCR TWIN SAFE LAN-PC RS232

LAN error / other terminal on RS232 same port busy Cable not connected or TCRTS not switched on DLL error RS232 communication down Communication 2 users try to access the same side of TCR TS DLL internal error Configuration handler.ini is wrong Configuration wrong Application SW Error or LAN error Application SW Error Reboot Windows in

0x0F000104 0xF0000105 0xF00000106

ERR_NO_VALID_SOCKET ERR_NO_TRANSACTION_R ESPONSE ERR_DATA_BUFFER_TO_S MALL

Network Interface Unit out of order Application SW Error Application SW Error

304

539.1261/3 Version 5.02

27 June 2012


0xF00000107 0xF00000108 0xF00000200 0xF00000201 0xF00000202 ERR_INPUT_BUFFER_TO_S MALL ERR_THREAD_NOT_START ED ERR_LAN_NO_ADDRESS_D EFINED ERR_LAN_NO_PORT_DEFIN ED ERR_LAN_NO_SERVER_FO UND

TCR Twin Safe TSAPI Interface Description

calls) An internal TSDLL buffer is too small for the given request (please contact DeLaRue) The internal worker thread for the asynchronous function cannot be started. Error in handler.ini. IP address is missing Error in handler.ini. Port Number is missing TSServer is not found or not running at this IP address

Application SW Error System error Check handler.ini Check handler.ini Embedded PC off or defect. Check handler.ini

27 June 2012

539.1261/03 DRAFT Version 5.02

305