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
TCR Twin Safe TSAPI Interface Description
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
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
4539.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............................................................21127
June 2012 539.1261/03 DRAFT Version 5.02
5
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................................................................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
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
7
TCR Twin Safe TSAPI Interface Description
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
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
9
TCR Twin Safe TSAPI Interface Description
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
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 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
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 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
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 configurationTeller 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 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
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 = 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
TCR Twin Safe TSAPI Interface Description
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
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 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
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 30539.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