tsapi interface description

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

1

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.

2

539.1261/3 Version 5.02

27 June 2012

Table of Contents


1 INTRODUCTION..................................................................................................... 8 2 ABOUT THE FLAPI DEFINITION...........................................................................9 3 USING THE FLAPI...............................................................................................104 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...........................................................2312 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............................................................................................ 2620 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.......................................................8127 June 2012 539.1261/03 DRAFT Version 5.02

3


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 4539.1261/3 Version 5.02 27 June 2012


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............................................................21127 June 2012 539.1261/03 DRAFT Version 5.02

5


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................................................................244206 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 6539.1261/3 Version 5.02 27 June 2012


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


7


1

INTRODUCTIONThe 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.

8

539.1261/3 Version 5.02

27 June 2012

2 ABOUT THE FLAPI DEFINITION


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


9


34

USING THE FLAPIOverview 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 workstationWindows 32bits or OS/2 Warp4


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 ApplicationFunction processingMarshalling

LAN IP Socket

LAN PCWindows 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


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 returnTSAPI

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


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 configurationTeller A workstation


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


15

TCR Twin Safe TSAPI Interface Description TCP/IP configuration

Teller B workstation Teller C workstation Administratorremote or local

Teller A workstation

Left side

Right side

Right side

Left side

Branch LANTCP/IP

TCR Twin Safe with TSServer on the embedded PC2X 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


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


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:


[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


21


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 = 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

1112 13


USING AND INTEGRATING THE TSAPISystem 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


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


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


25


19

FLAPI FUNCTIONSThis 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


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


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


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


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 30539.1261/3 Version 5.02 27 June 2012

Additional information None. Cross-references None.


27 June 2012


31


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


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


33


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



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


35


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



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


37


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


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


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


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


41


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



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


43


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


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


45


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


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


47


31

Get event

tsapi interface description

Documents