Developers Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 296

Download
Open PDF In Browser	View PDF

EZForecourt Developers Manual

Version 2.3.0.1

EZForecourt
Developers
Manual

Page 1

EZForecourt Developers Manual

Version 2.3.0.1

Version History ............................................................................................................................... 7
1. Introduction.............................................................................................................................. 7
2. Concepts ................................................................................................................................. 8
3. System Architecture .............................................................................................................. 12
4. Installation ............................................................................................................................. 14
5. INI file configurations ............................................................................................................. 14
5.1.
EZServer INI file .......................................................................................................... 16
5.2.
EZClient INI file ........................................................................................................... 22
5.3.
EZDriver INI file ........................................................................................................... 22
5.4.
EZLicense INI file ........................................................................................................ 26
5.5.
EZATG INI file ............................................................................................................. 26
6. Developer’s Kit contents ........................................................................................................ 28
6.1.
The EZSim pump simulator ......................................................................................... 28
6.1.1. EZSim INI file .......................................................................................................... 29
6.2.
Sample applications .................................................................................................... 30
6.2.1. EZDemoPos ............................................................................................................ 30
6.2.2. EZClientCSharp ...................................................................................................... 30
6.2.3. EZClientCpp. ........................................................................................................... 30
6.2.4. EZClientDelphi7 / EXClientDelphiXe2. .................................................................... 31
7. API reference ........................................................................................................................ 32
7.1.
API Components ......................................................................................................... 32
7.2.
Data types ................................................................................................................... 33
7.3.
Object based architecture............................................................................................ 35
8. API Definition......................................................................................................................... 36
8.1.
Connection .................................................................................................................. 36
8.1.1. ClientLogon(Ex) ...................................................................................................... 36
8.1.2. DllVersion ................................................................................................................ 38
8.1.3. ServerVersion ......................................................................................................... 39
8.1.4. ClientLogoff ............................................................................................................. 40
8.1.5. ClientStatus............................................................................................................. 41
8.1.6. TestConnection ....................................................................................................... 42
8.1.7. LicenseStatus.......................................................................................................... 43
8.1.8. GetLicenseType ...................................................................................................... 44
8.1.9. GetIniValue ............................................................................................................. 45
8.1.10.
SetIniValue ......................................................................................................... 46
8.1.11.
GetClientsCount ................................................................................................. 47
8.1.12.
SetDateTime ....................................................................................................... 48
8.1.13.
GetDateTime ...................................................................................................... 49
8.1.14.
ResultString ........................................................................................................ 50
8.1.15.
CheckSocketClosed............................................................................................ 51
8.2.
Events ......................................................................................................................... 52
8.2.1. ProcessEvents ........................................................................................................ 52
8.2.2. GetEventsCount ...................................................................................................... 54
8.2.3. GetNextEventType .................................................................................................. 55
8.2.4. DiscardNextEvent ................................................................................................... 56
8.2.5. GetNextPumpEvent(Ex, Ex2, Ex3) / StatusEvent ................................................... 57
8.2.6. GetNextDeliveryEvent(Ex, Ex2, Ex3, Ex4) / DeliveryEvent ..................................... 61
8.2.7. GetNextServerEvent / ServerEvent......................................................................... 64
8.2.8. GetNextClientEvent/ClientEvent ............................................................................. 65
8.2.9. FireClientEvent........................................................................................................ 66
8.2.10.
GetNextDBLogEvent/DBLogEvent ..................................................................... 67

Page 2

EZForecourt Developers Manual

Version 2.3.0.1

8.2.11.
GetNextDBLogDeliveryEvent / DBLogDeliveryEvent .......................................... 68
8.2.12.
GetNextDBClearDeliveryEvent / DBClearDeliveryEvent..................................... 70
8.2.13.
GetNextDBStackDeliveryEvent / DBStackDeliveryEvent .................................... 71
8.2.14.
GetNextDBHoseETotalsEvent(Ex) / DBHoseETotalsEvent(Ex) ......................... 72
8.2.15.
GetNextDBTriggerEvent/DBTriggerEvent ........................................................... 74
8.2.16.
GetNextDBAttendantLogonEvent / DBAttendantLogonEvent ............................. 75
8.2.17.
GetNextDBAttendantLogoffEvent / DBAttendantLogonEvent ............................. 76
8.2.18.
GetNextDBTankStatusEvent(Ex,Ex2) / DBTankStatusEvent(Ex,Ex2) ................ 77
8.2.19.
GetNextCardReadEvent / CardReadEvent ......................................................... 79
8.2.20.
GetNextLogEventEvent/LogEventEvent ............................................................. 80
8.2.21.
GetNextZeroDeliveryEvent ................................................................................. 82
8.2.22.
GetNextZB2GStatusEvent .................................................................................. 83
8.3.
Pumps ......................................................................................................................... 84
8.3.1. GetPumpsCount...................................................................................................... 84
8.3.2. GetPumpByName ................................................................................................... 85
8.3.3. GetPumpByNumber ................................................................................................ 86
8.3.4. GetPumpByOrdinal ................................................................................................. 87
8.3.5. GetPumpProperties(Ex) .......................................................................................... 88
8.3.6. SetPumpProperties(Ex) .......................................................................................... 91
8.3.7. DeletePump ............................................................................................................ 93
8.3.8. GetPumpHosesCount/GetHosesCount ................................................................... 94
8.3.9. GetPumpHoseByNumber/GetHoseByNumber ........................................................ 95
8.3.10.
GetPumpStatus(Ex, Ex2) .................................................................................... 96
8.3.11.
PumpStateString ................................................................................................. 98
8.3.12.
EnablePump ....................................................................................................... 99
8.3.13.
DisablePump .................................................................................................... 100
8.3.14.
SetPumpDefaultPriceLevel ............................................................................... 101
8.3.15.
GetDensity ........................................................................................................ 102
8.3.16.
ScheduleBeep .................................................................................................. 103
8.3.17.
FlashLEDS........................................................................................................ 104
8.4.
Pump prepay deliveries ............................................................................................. 105
8.4.1. PrepayReserve ..................................................................................................... 105
8.4.2. PrepayCancel........................................................................................................ 107
8.4.3. PrepayAuthorise.................................................................................................... 108
8.5.
Pump preauth deliveries ............................................................................................ 110
8.5.1. PreauthReserve .................................................................................................... 110
8.5.2. PreauthCancel ...................................................................................................... 112
8.5.3. PreauthAuthorise .................................................................................................. 113
8.6.
Pump payment deliveries .......................................................................................... 115
8.6.1. PaymentReserve................................................................................................... 115
8.6.2. PaymentCancel ..................................................................................................... 117
8.6.3. PaymentAuthorise ................................................................................................. 118
8.7.
Pump authorization ................................................................................................... 120
8.7.1. AttendantAuthorise................................................................................................ 120
8.7.2. Authorise ............................................................................................................... 121
8.7.3. CancelAuthorise .................................................................................................... 122
8.7.4. TempStop ............................................................................................................. 123
8.7.5. TerminateDelivery ................................................................................................. 124
8.7.6. ReAuthorise .......................................................................................................... 125
8.7.7. LoadPreset ............................................................................................................ 126
8.7.8. TagAuthorise ......................................................................................................... 128
8.7.9. LoadPresetWithPrice ............................................................................................ 130
8.8.
Global functions......................................................................................................... 132
8.8.1. AllStop................................................................................................................... 132

Page 3

EZForecourt Developers Manual

Version 2.3.0.1

8.8.2. AllStopIfIdle ........................................................................................................... 133
8.8.3. AllAuthorise ........................................................................................................... 134
8.8.4. AllReAuthorise ...................................................................................................... 135
8.8.5. GetAllPumpStatuses ............................................................................................. 136
8.8.6. ReadAllTanks ........................................................................................................ 137
8.9.
Deliveries................................................................................................................... 138
8.9.1. GetDeliveriesCount ............................................................................................... 138
8.9.2. GetDeliveryByOrdinal............................................................................................ 139
8.9.3. GetDeliveryProperties(Ex, Ex2, Ex3, Ex4) ............................................................ 140
8.9.4. SetDeliveryProperties(Ex, Ex2, Ex3, Ex4) ............................................................ 142
8.9.5. LockDelivery.......................................................................................................... 145
8.9.6. UnlockDelivery ...................................................................................................... 146
8.9.7. ClearDelivery......................................................................................................... 147
8.9.8. LockAndClearDelivery........................................................................................... 148
8.9.9. SetNextDeliveryID ................................................................................................. 150
8.9.10.
AckDeliveryDBlog ............................................................................................. 151
8.9.11.
GetDeliveryIDByOrdinalNotLogged .................................................................. 152
8.9.12.
GetDeliveriesCountNotLogged ......................................................................... 153
8.9.13.
AckDeliveryVolLog ............................................................................................ 154
8.9.14.
GetDeliveryIDByOrdinalNotVolLogged ............................................................. 155
8.9.15.
GetDeliveriesCountNotVolLogged .................................................................... 156
8.9.16.
GetAllDeliveriesCount ....................................................................................... 157
8.9.17.
GetAllDeliveryByOrdinal ................................................................................... 158
8.9.18.
GetDeliverySummary(Ex, Ex2, Ex3) ................................................................. 159
8.9.19.
GetDeliveryExt .................................................................................................. 162
8.9.20.
SetDeliveryExt .................................................................................................. 163
8.9.21.
GetPumpDeliveryProperties(Ex, Ex2, Ex3, Ex4) .............................................. 164
8.9.22.
ReserveTypeString ........................................................................................... 166
8.9.23.
GetDuration ...................................................................................................... 167
8.9.24.
StackCurrentDelivery ........................................................................................ 168
8.9.25.
DeliveryTypeString............................................................................................ 169
8.9.26.
DeliveryStateString ........................................................................................... 170
8.10.
Hoses ........................................................................................................................ 172
8.10.1.
GetHosesCount ................................................................................................ 172
8.10.2.
GetHoseByOrdinal ............................................................................................ 173
8.10.3.
GetHoseProperties(Ex, Ex2) ............................................................................. 174
8.10.4.
SetHoseProperties(Ex, Ex2) ............................................................................. 176
8.10.5.
DeleteHose ....................................................................................................... 178
8.10.6.
GetHosePrices.................................................................................................. 179
8.10.7.
GetHoseSummary(Ex) ...................................................................................... 180
8.10.8.
SetHoseETotals ................................................................................................ 182
8.10.9.
SetHosePrices .................................................................................................. 183
8.11.
Grades....................................................................................................................... 185
8.11.1.
GetGradesCount ............................................................................................... 185
8.11.2.
GetGradeByNumber ......................................................................................... 186
8.11.3.
GetGradeByName ............................................................................................ 187
8.11.4.
GetGradeByOrdinal .......................................................................................... 188
8.11.5.
GetGradeProperties(Ex) ................................................................................... 189
8.11.6.
SetGradeProperties(Ex).................................................................................... 190
8.11.7.
DeleteGrade ..................................................................................................... 191
8.11.8.
SetGradePrice .................................................................................................. 192
8.11.9.
GetGradePrice .................................................................................................. 193
8.12.
Tanks......................................................................................................................... 194
8.12.1.
GetTanksCount ................................................................................................. 194

Page 4

EZForecourt Developers Manual

Version 2.3.0.1

8.12.2.
GetTankByNumber ........................................................................................... 195
8.12.3.
GetTankByName .............................................................................................. 196
8.12.4.
GetTankByOrdinal ............................................................................................ 197
8.12.5.
GetTankProperties(Ex) ..................................................................................... 198
8.12.6.
SetTankProperties(Ex)...................................................................................... 200
8.12.7.
DeleteTank ....................................................................................................... 202
8.12.8.
GetTankSummary(Ex) ...................................................................................... 203
8.13.
Ports .......................................................................................................................... 205
8.13.1.
GetPortsCount .................................................................................................. 205
8.13.2.
GetPortByNumber............................................................................................. 206
8.13.3.
GetPortByName ................................................................................................ 207
8.13.4.
GetPortByOrdinal .............................................................................................. 208
8.13.5.
GetPortProperties ............................................................................................. 209
8.13.6.
SetPortProperties ............................................................................................. 210
8.13.7.
RemovePort ...................................................................................................... 212
8.13.8.
GetZB2GConfig ................................................................................................ 213
8.13.9.
GetSerialNo ...................................................................................................... 214
8.13.10.
GetDeviceDetails .............................................................................................. 215
8.13.11.
ResetDevice ..................................................................................................... 216
8.13.12.
RequestVersion ................................................................................................ 217
8.14.
Attendants ................................................................................................................. 218
8.14.1.
GetAttendantsCount ......................................................................................... 218
8.14.2.
GetAttendantByNumber .................................................................................... 219
8.14.3.
GetAttendantByName ....................................................................................... 220
8.14.4.
GetAttendantByOrdinal ..................................................................................... 221
8.14.5.
GetAttendantProperties(Ex) .............................................................................. 222
8.14.6.
SetAttendantProperties(Ex) .............................................................................. 223
8.14.7.
DeleteAttendant ................................................................................................ 225
8.14.8.
AttendantLogon ................................................................................................ 226
8.14.9.
AttendantLogoff ................................................................................................ 227
8.14.10.
GetAttendantState ............................................................................................ 228
8.15.
Card Clients............................................................................................................... 229
8.15.1.
GetCardClientsCount ........................................................................................ 229
8.15.2.
GetCardClientByNumber .................................................................................. 230
8.15.3.
GetCardClientByName ..................................................................................... 231
8.15.4.
GetCardClientByOrdinal ................................................................................... 233
8.15.5.
GetCardClientProperties(Ex,Ex2) ..................................................................... 234
8.15.6.
SetCardClientProperties(Ex, Ex2) .................................................................... 236
8.15.7.
DeleteCardClient .............................................................................................. 238
8.16.
Card Reads ............................................................................................................... 239
8.16.1.
GetCardReadsCount ........................................................................................ 239
8.16.2.
GetCardReadByNumber ................................................................................... 240
8.16.3.
GetCardReadByOrdinal .................................................................................... 241
8.16.4.
GetCardReadByName ...................................................................................... 242
8.16.5.
GetCardReadProperties ................................................................................... 243
8.16.6.
SetCardReadProperties .................................................................................... 244
8.16.7.
DeleteCardRead ............................................................................................... 245
8.16.8.
GetCardType .................................................................................................... 246
8.17.
ZigBee devices .......................................................................................................... 247
8.17.1.
GetZigBeeCount ............................................................................................... 247
8.17.2.
GetZigBeeByNumber ........................................................................................ 248
8.17.3.
GetZigBeeByName ........................................................................................... 249
8.17.4.
GetZigBeeByOrdinal ......................................................................................... 250
8.17.5.
GetZigBeeProperties ........................................................................................ 251

Page 5

EZForecourt Developers Manual

Version 2.3.0.1

8.17.6.
SetZigBeeProperties ......................................................................................... 252
8.17.7.
DeleteZigBee .................................................................................................... 253
8.18.
Sensors ..................................................................................................................... 254
8.18.1.
GetSensorsCount ............................................................................................. 254
8.18.2.
GetSensorByNumber ........................................................................................ 255
8.18.3.
GetSensorByName ........................................................................................... 256
8.18.4.
GetSensorByOrdinal ......................................................................................... 257
8.18.5.
GetSensorProperties ........................................................................................ 258
8.18.6.
SetSensorProperties ......................................................................................... 259
8.18.7.
GetSensorStatus .............................................................................................. 260
8.18.8.
SetSensorStatus ............................................................................................... 261
8.18.9.
DeleteSensor .................................................................................................... 262
8.19.
Logged events ........................................................................................................... 263
8.19.1.
GetLogEventCount ........................................................................................... 263
8.19.2.
GetLogEventByOrdinal ..................................................................................... 265
8.19.3.
GetLogEventProperies...................................................................................... 266
8.19.4.
SetLogEventProperties ..................................................................................... 268
8.19.5.
DeleteLogEvent ................................................................................................ 270
8.19.6.
ClearLogEvent .................................................................................................. 271
8.19.7.
AckLogEvent..................................................................................................... 272
9. Appendices.......................................................................................................................... 273
9.1.
Appendix 1 – Pump states......................................................................................... 273
9.2.
Appendix 2 – Pump reserves types ........................................................................... 275
9.3.
Appendix 3 – Delivery types ...................................................................................... 276
9.4.
Appendix 4 – Delivery states ..................................................................................... 277
9.5.
Appendix 5 – Event types .......................................................................................... 278
9.6.
Appendix 6 – Pump display formats .......................................................................... 280
9.7.
Appendix 7 – Pump authorization modes .................................................................. 281
9.8.
Appendix 8 – Pump delivery stack (memory) modes ................................................ 282
9.9.
Appendix 9 – Pump limit types .................................................................................. 282
9.10.
Appendix 10 – Permitted hoses mask ....................................................................... 282
9.11.
Appendix 11 – Device Types ..................................................................................... 283
9.12.
Appendix 12 – Tank Types ........................................................................................ 283
9.13.
Appendix 13 – Error messages ................................................................................. 284
9.14.
Appendix 14 – Client event types .............................................................................. 288
9.15.
Appendix 15 – Client type.......................................................................................... 288
9.16.
Appendix 16 – Remote device type ........................................................................... 289
9.17.
Appendix 17 – Price Control ...................................................................................... 289
9.18.
Appendix 18 – Price Type ......................................................................................... 290
9.19.
Appendix 19 – Price Duration Type ........................................................................... 290
9.20.
Appendix 20 – Log Event Device Type ..................................................................... 291
9.21.
Appendix 21 – Log Event Level ................................................................................. 291
9.22.
Appendix 22 – Log Event Type ................................................................................. 292
9.23.
Appendix 23 – Tank State ......................................................................................... 294
9.24.
Appendix 24 – Attendant Type .................................................................................. 294
9.25.
Appendix 24 – Alarms Mask ...................................................................................... 295
9.26.
Appendix 26 – Card Read Types .............................................................................. 295
9.27.
Appendix 27 – Card Types ........................................................................................ 296
9.28.
Appendix 28 – Entry Types ....................................................................................... 296

Page 6

EZForecourt Developers Manual

Version 2.3.0.1

Version History
Version 1.0.0.0 ………………………………………………………………………....... August 2005
Version 1.2.0.0 …………................................................................................... November 2005
Version 1.3.0.0 ………….…………………………………………………………………… July 2006
Version 2.1.0.0 ………….…………………………………………………………………… May 2013
Version 2.3.0.0…………….…………………………………………………………….…....May 2016
Version 2.3.0.1 …………….…………………………………………………………..….August 2016

1. Introduction
The EZForecourt product is a forecourt controller designed to work in conjunction with third party
windows XP/7/8 based POS systems, and possesses the following characteristics.

USB interface.
It utilizes a simple and small, USB based, forecourt interface module (EZMod) to easily connect a
windows XP/2000 based server to common gas station forecourt devices. The use of the USB
standard does away with the need to install any additional proprietary hardware in the host
server.

Self-reliant device.
The EZMod module is a self-powered USB device which has the ability to buffer up to 2950
deliveries if the connection to the host is lost, hence providing redundancy and independence
from the server.

Generic high level interface.
It can control and manage many common types and makes of Petrol pumps in a transparent
fashion, all the host application sees is a generic pump device.

Electronic tank gauge support.
It also interfaces to many different types and makes of electronic tank gauges, providing a
generic and simple interface for both alarms and tank statistics.

ActiveX .NET and DLL client interfaces.
The interface between EZForecourt and the host system/application is done via two ActiveX
controls, EZClient.SO.1 and a .NET package EZTech.dll which contains EZTech.EZClient and
EZTech.EZPump, or a standard windows a DLL, EZClient.DLL. Which of the three options is
utilized will depend on the capabilities and requirements of the host system.

TCP/IP client server interface.
The interface between the EZForecourt server and client applications is done via TCP/IP sockets,
hence the clients and the server need not be running on the same physical machine, but can be
anywhere on the same local TCP/IP based network.
.

Page 7

EZForecourt Developers Manual

Version 2.3.0.1

2. Concepts
Prior to starting an integration of EZForecourt, it is necessary that a few of the basic concepts be
clarified, to ensure that the more technical information be interpreted correctly. The following
terms will be used many times in the API and data base sections later on in this document.

Post-pay delivery
Deliveries on a forecourt generally follow the Post pay sequence of events, the hose is pulled on
the pump and the pump is either authorized automatically or manually by a shop or forecourt
attendant. When the delivery is completed the customer either pays the attendant for the delivery
or pays for it in the shop. This is referred to as a post pay delivery, i.e. a delivery that is paid for
after it is taken.

Prepay delivery
An alternative to paying for the delivery after it is taken is paying for it before. In this case the
customer goes into the shop, pays a predetermined amount for fuel on a specified pump, this is
usually an estimate on behalf of the customer, who then goes back to his car and takes the
delivery. When the hose is pulled from the specified pump, it is automatically authorized to
delivery up to the prepaid amount. If the delivery is terminated prior to the limit being reached, a
refund for the difference is automatically generated and the customer is then required to return to
the shop to collect the refund. If however there is no refund the customer is free to leave when
the hose is returned.

Preauth delivery
These days many systems give the customer the option of paying for the fuel delivery at the
pump, to do this, the pump must be fitted with a card terminal. The sequence of events in this
situation is, the customer passes their card thru the card terminal on the respective pump, and
then the card terminal starts a pre-authorization with the respective bank. Once this preauthorization is granted, the pump is authorized to delivery up to the limit returned with the preauthorization response. When the customer has completed the delivery the actual value of the
delivery is sent as part of a pre-authorization advice message billing the customer’s card with the
correct value. This is known as a preauth delivery.

Drive off delivery
Unfortunately there are also customers, who take a delivery at a pump and leave without paying,
this only occurs in post pay environments. These are politely referred to as drive off deliveries.

Test delivery
At times it is necessary for the various certification authorities to carry out tests on the pumps to
verify that their volume measurement conforms to the relevant regulations. When these deliveries
are completed the fuel is returned manually returned to the tank from which it came. These
deliveries must be treated differently and are referred to as test deliveries.

Monitor deliveries
In a lot of countries gas station forecourts are run fully attended and the customer does not even
have to exit the car to fill up the tank. A forecourt attendant takes the delivery on behalf of the
customer and the customer pays the attendant directly after the delivery is completed. In this
mode the forecourt controller is in essence only monitoring the forecourt activity, and is usually

Page 8

EZForecourt Developers Manual

Version 2.3.0.1

used to prevent fraud or theft by the forecourt attendants. These deliveries are referred to as
monitor deliveries.

Offline deliveries
At times the communications with the pumps are lost; this could be because the pumps are
turned off, switched into local mode or because of technical faults. When the pumps are returned
to normal function and communications are re-established, an offline delivery is generated which
is the sum of all of the deliveries which were done while the pump was offline. This total is
difference between the last known electronic totals before it stopped responding and the
electronic totals retrieved immediately after the pump started to respond. The purpose of this
delivery type is to ensure that the electronic and theoretical totals still tally.

Temp stop
Pump deliveries can be controlled remotely via EZForecourt, imagine a situation where someone
is smoking near a pump, and due to safety reasons it is necessary to stop the fuel delivery, this is
called a ‘Temp stop’. A temp stop remains in place until the pump is re-authorized manually via
EZForecourt. All of the pumps can be stopped in single operation; this is called an ‘All Stop’, and
can be reversed by an ‘All Re-authorize’.

Pump authorize
EZForecourt permits pumps to run in several authorization modes, the first and most simple is
auto authorize. In this mode the pump will start delivering, without intervention, when the hose is
pulled. When EZForecourt is running in monitor mode the pumps are also auto authorize. The
other mode is compulsory authorize, in this mode when the hose is pulled, the pump will call for
authorization, it will only start delivering when a forecourt or shop attendant manually authorizes
the pump. If a limit is placed on the number of unpaid deliveries, auto authorize pumps will not
automatically authorize, if this limit has been reached. One or more of the unpaid deliveries will
need to be processed first. This does not however apply to monitor mode.

Electronic totals
Most pump types keep electronic totals in non-volatile memory; these totals are accumulative
totals of both volume and value, for each of the hoses on the pump. These totals are zeroed
when the pump is installed or when the pump electronics are reset. These totals (when present)
are interrogated remotely by EZForecourt and are continually monitored to determine if deliveries
are lost etc.

Mechanical totals
Most pump types also have mechanical totals for both volume and value for each hose present
on the pump. Unlike the electronic totals these cannot be reset, or interrogated remotely.
EZForecourt permits the manual entry of these totals. This is yet another total to be reconciled
against the EZForecourt totals.

Theoretical totals
Besides the mechanical and electronic totals maintained by the pumps, EZForecourt also
maintains a theoretical total for both value and volume for each of the hoses configured. This is
maintained by simply accumulating the individual delivery totals as they are completed.
Reconciling the theoretical, electronic and mechanical totals is ones best defense against theft or
fraud.

Price level
Most modern pump types today support more than one price per grade, this was originally
intended to be used in credit or cash situations, however it can also be used for full vs. selfservice etc. Even though most pumps do not display both prices on the pump displays, they are

Page 9

EZForecourt Developers Manual

Version 2.3.0.1

saved internally and can be changed and selected remotely. EZForecourt supports multiple
prices per grade and up to two prices per hose.
It is assumed that the reader is familiar with windows XP/2000 and general programming
concepts and as such there is no explanation of this here.

Page 10

EZForecourt Developers Manual

Version 2.3.0.1

Page 11

EZForecourt Developers Manual

Version 2.3.0.1

3. System Architecture

Page 12

EZForecourt Developers Manual

Version 2.3.0.1

The EZForecourt system architecture is as
follows:

EZClient application

EZClient.DLL

EZForecourt server

EZServer
windows
XP/2000 service

EZClient.SO.1 or
EZTech.EZClient

EZServer
driver
process
EZServer
driver
process
EZServer
driver
process

EZForecourt
USB driver
EZForecourt
USB driver
EZForecourt
USB driver

EZTech.EZPump

USB
cables

EZTech.EZPump

EZForecourt Interface module(EZMod)

Page 13

EZForecourt Interface module(EZMod)

EZForecourt Developers Manual

Version 2.3.0.1

As can be seen from the diagram above, EZForecourt supports more than one EZMod module.
This may be required if there is more than eight physical pumps or a mixture of pump types
(different manufacturers) that cannot be hosted on the same EZMod module.
It also clearly demonstrates how the optional back office and database fit into the overall
structure. If the integrator decides to use their own existing back office or develop a new one,
then a similar structure will be required.
It may not be evident here but the links between the BackOffice and EZServer are also via the
EZClient.DLL, and in the interests of speed and data integrity it is a requirement that the
BackOffice and EZServer be hosted on the same machine. Other EZClients (POSes etc.) do not
need to be on the same machine, but can be anywhere on the same TCP/IP network.

4. Installation
For a detailed description of how to install the EZForecourt product refer to the EZForecourt
Installers Manual.

5. INI file configurations
Each of the EZForecourt software components is individually configured with a windows
format INI file. These INI files all follow a standard format and are easily edited using the
EZIniEditor utility provided. These INI files are installed per-configured and should only be
edited under the direct instructions of EZTech support.
All of these INI files are located in the \EZForecourt directory. To edit an INI file simply open
up a command window, change to the EZForecourt directory and then type EZIniEditor
followed by the name of the INI file (with or without the INI extension). This will result in a
screen similar to the following being presented:

Page 14

EZForecourt Developers Manual

Version 2.3.0.1

If the INI file was located successfully, the name of the INI file will be displayed with a plus
symbol beside the full file name, clicking the plus symbol will expand it to show all of the
sections contain in the INI file. Clicking the plus symbol beside each of the sections will
expand it to show all of the individual configuration parameters.
The value for the currently highlighted configuration parameter is displayed in the text box at
the bottom of the window. To change the currently selected configuration value, simply edit it
in the text box, saving is done automatically when a different configuration parameter is
selected or the application is exited by clicking the OK button.
There are some sections and configuration values which are common to all of the
EZForecourt INI files these are as follows.

Section
[Application]

Parameter
Name

[Server]

IniVersion
Name

Description
The name of the application to which this
INI file applies.
The version number for this INI file
The machine name of the machine hosting
the EZServer service, if the service is on
the same machine then the value
can be used.
The TCP/IP port number that is used by
EZClients to access the server. This

CallPort

Page 15

EZForecourt Developers Manual

Version 2.3.0.1

number must be the same for all EZClients
and the EZServer.
The TCP/IP port number that is used by
the EZClients to receive events. This
number must be the same for all of the
EZClients and the EZServer.
The timeout value in milliseconds for
clients when calling the server, if the
server does not respond within this time
the call will return with a
SERVER_TIMEOUT result.
A 0 or 1 (0=no,1=yes) flag used to
determine if diagnostic information is sent
to the screen, this is only of use when
running the server in debug mode and is
reserved for internal EZTech use.
A 0 or 1 (0=no, 1=yes) flag used to
determine if diagnostic information is sent
to a log file. By default this is 1 and should
be left that way, unless instructed to
change it by EZTech. Diagnosing faults is
considerably more difficult if this flag is
turned off.
A 0 or 1 (0=no, 1=yes) flag used to
determine if diagnostic information is sent
to a TCP/IP socket. This feature is
currently unsupported, but is reserved for
future use.

EventsPort

CallTimeout

[Log]

Screen

File

Socket

5.1.

EZServer INI file

The EZServer INI file contains all of the configurable parameters for the EZServer
service. This INI file contains the standard parameters listed above along with the specific
parameters listed below.

Section
[Parameters]

Parameter
ManualAuthedTimeout

Type
Numeric,
Seconds

TagAuthedTimeout

Numeric,
Seconds

PrepayAuthedTimeout

Numeric

Page 16

Description
The amount of time, in
seconds, that a compulsory
authorized pump will remain
authorized after manual
authorization.
The amount of time, in
seconds, that an EZID
authorized pump will remain
authorized after Mifare card
is read authorization.
The amount of time, in
seconds, that a pump will
remain authorized for a
prepay delivery, before a
prepay refund is

EZForecourt Developers Manual

Version 2.3.0.1

PreauthAuthedTimeout

Numeric

PrepayReservedTimeout

Numeric

PreauthReservedTimeout

Numeric

MonitorDeliveryTimeout

Numeric

DeliveryDriveoffTimeout

Numeric

PrepayRefundTimeout

Numeric

Page 17

automatically generated. It
the pump starts to deliver
before this time is up it will
be treated as a prepay
delivery.
The amount of time, in
seconds, that a pump will
remain authorized for a
preauth delivery, before the
preauth reserve is
automatically removed. It the
pump starts to deliver before
this time is up it will be
treated as a preauth
delivery.
The amount of time, in
seconds, that a pump will
remain reserved for a prepay
delivery before the prepay
reserve is automatically
removed. If the pump is
prepay authorized before
this time is up, it will change
to the prepay authorized
state.
The amount of time, in
seconds, that a pump will
remain reserved for a
preauth delivery before the
preauth reserve is
automatically removed. It the
pump is preauth authorized
before this time is up, it will
change to the preauth
authorized state.
The amount of time, in
seconds, that a Post-pay
delivery will remain on a
pump, configured in monitor
mode, before it is cleared
automatically as a monitor
delivery. It can be taken as a
Post-pay delivery prior to
timing out.
The amount of time, in
seconds, that a Post-pay
delivery can remain on a
pump until it is flagged as a
potential drive off delivery.
The amount of time, in
seconds, that a prepay
refund remains on a pump
before it is automatically

EZForecourt Developers Manual

Version 2.3.0.1

DeliveringTimeout

Numeric

HoseOutTimeout

Numeric

LeaveAuthedTimeout

Numeric

NotRespondingTimeout

Numeric

MinimumPresetValue

Numeric

MinimumDeliveryValue

Numeric

MinimumDeliveryVolume

Numeric

MaxStackSize

Numeric

AutoClearOffline

Numeric

Page 18

cleared from the pump. If
this delivery is cleared
manually prior to this timeout
expiring, the pump will
remain locked out for the
remainder of this timeout.
The amount of time, in
seconds, that a delivering
pump can remain delivering
before a warning is
generated.
The amount of time, in
seconds, that a pump hose
can be left out, not
delivering, before a warning
is generated.
The time in seconds to leave
a pump in the authorized
state before canceling it.
The maximum time in
seconds that a pump can
stop and start responding
without being initialized.
The minimum value
accepted by the server for a
preset, prepay or preauth
delivery.
The minimum delivery value
accepted by the server for a
valid delivery, deliveries with
values smaller than this are
discarded.
The minimum delivery
volume accepted by the
server for a valid delivery,
deliveries with volumes
smaller than this are
discarded.
The maximum number of
unpaid deliveries permitted
on a pump before the server
will stop authorizing the
pump. If the server is in
standalone mode, or the
pumps are in monitor mode,
this limit is ignored.
A yes or no value, that
determines whether offline
deliveries are automatically
cleared by the server, or
must be taken manually as a
Post-pay delivery like any
other.

EZForecourt Developers Manual

Version 2.3.0.1
MinOfflineDeliveryVolume

Numeric

MaxOfflineDeliveryVolume

Numeric

Standalone

Boolean

NonVolObjects

Boolean

NonVolTotals

Boolean

LogDeliveries

Boolean

MaxDeliveryVolumeDiff

Numeric

MaxDeliveryValueDiff

Numeric

MinimalPumpEvents

Boolean

Page 19

The minimum volume for an
offline delivery, if an offline
delivery is detected with less
than this volume, it is
ignored.
The maximum volume for an
offline delivery, if an offline
delivery very is detected with
more than this it is ignored.
This is used to discard
offline deliveries generated
when used pumps are first
connected to the system.
A yes or no value to
determine if the forecourt
interface modules are
allowed authorize pumps
and buffer deliveries when
the server is not running.
This is only of use in a pump
monitoring environments,
and hence is of little use in a
self-service situation.
A yes or no value to
determine if the objects in
the EZServer are nonvolatile or not.
A yes or no value to
determine if the hose
electronic totals and tank
gauge values are saved to
the non-vol store or not, it is
recommended that it be yes.
A yes or no value to
determine if the individual
deliveries are logged to a
separate log file.
The maximum delivery
volume difference between
the reported delivery volume
and the volume electronic
totals difference before an
offline delivery is generated.
The maximum delivery value
difference between the
reported delivery value and
the value electronic totals
difference before an offline
delivery is generated.
If set to yes this suppresses
various pump events
including running total
events. This should be no.

EZForecourt Developers Manual

Version 2.3.0.1
ExtendedDeliveryProperties

Boolean

RunningTotalRate

Numeric

ConfirmDeliveryLog

Boolean

MinimumKeepDeliveries

Numeric

ForceDeliveryLock

Boolean

VolumetricDLL

String

ZigBeePanID

Numeric

GetDeliveryTimeout

Numeric

GetETotalsTimeout

Numeric

DelMinimumDuration

Numeric

TagAuthType

Numeric

Page 20

A flag to determine if the
DeliveryEvent or
DeliveryEventEx event is
generated.
The minimum running total
update rate for pumps in
milliseconds.
Set this to Yes if you want to
use EZLogger of equivalent
to extract all of the cleared
deliveries to a database etc.
The minimum number of
cleared deliveries that are
retrained in the EZserver
database, these can be seen
in the EZMonitor deliveries
history.
Set to true to force the
server to re-fire pump calling
status event every 10
seconds.
The full path and file name
for the DLL used to do the
volumetric logging.
The PAN ID used for the
ZigBee network.
The time in seconds that the
EZServer waits after the
pump has finished delivering
for the EZRemotes to log the
delivery.
The time in seconds the
EZServer waits for the
EZRemote waits for the
EZRemote to log the e-totals
after the delivery has been
logged.
The minimum time in
seconds that a pump must
be in the delivering state to
be considered a valid
delivery.
The type of tag
authorization.
0 - Authorizes one fueling
point only, and can be
authorized prior to pulling
the hose for
TagAuthedTimeout seconds.
1 – Authorizes one fueling
point only, and only if the
hose is already pulled.
2 – Authorizes up to two

EZForecourt Developers Manual

Version 2.3.0.1

TagCacheOn

Boolean

PortsReadOnly

Boolean

GradesReadOnly

Boolean

TanksReadOnly

Boolean

PumpsReadOnly

Boolean

ZigBeeReadOnly

Boolean

HosesReadOnly

Boolean

PricesReadOnly

Boolean

AttendantsReadOnly

Boolean

ClientsReadOnly

Boolean

SensorsReadOnly

Boolean

Page 21

fueling points (sides 1 and 3
or 2 and 4). Will authorize
the un-authorized hose that
has been pulled for the
longest time.
The pump attendant cache
in the EZRemotes enabled,
default is yes.
Whether the ports
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the grades
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the tanks
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the pumps
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the EZRemotes
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the hoses
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the fuel prices
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the attendants
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the Card Clients
coinfiguration can be edited
in the EZConfig application,
the default is yes.
Whether the Sensors
coinfiguration can be edited
in the EZConfig application,
the default is yes.

EZForecourt Developers Manual

Version 2.3.0.1
5.2.

EZClient INI file

The EZClient INI file contains all of the configurable parameters for all of the EZServer
clients (EZClients). This INI file contains the entire standard parameters listed above but
has no specific parameters. The main parameter of interest here is the name parameter
in the Server section, in order to configure a remote client this parameter must be set to
the machine name of EZServer service host machine.

Section
N/A

5.3.

Parameter

Type

Description

EZDriver INI file

This INI file is also used by the EZServer service; more specifically it is use by the driver
DLLs loaded at start up. The parameters in this INI are all pre-configured and should only
be altered under specific instructions from EZTech. The following documentation is
provided for information purposes only. Under some of the protocol and pump type
sections you will find parameters which are not listed here, these are driver specific
parameters, for details of these parameters please contact EZTech technical support.
This INI file contains the standard parameters listed above along with the specific
parameters listed below.
Section
[Protocolnnn]

Parameter
Name

Type
String

DAL

String

Driver

String

LoopType

String

Baudrate

Numeric

Page 22

Description
The name of the protocol,
nnn is from 001 to 999, and
corresponds to the
ProtocolID column in the
Protocols table of the
EZDB database.
The name of the DAL
(Driver Abstraction Layer)
DLL, this will be
PumpDrv.DLL or
TankDrv.DLL depending
on the device type.
The name of the DLL file
which is the driver for this
protocol, note it must be a
fully qualified file name,
this is only used by
TankDrv.DLL
The loop type for this
connection COM or
SOCKET, this is only used
by TankDrv.DLL
The BPS (bits per second)
communications rate use
for this protocol, any value
from 300 to 38400 is valid,

EZForecourt Developers Manual

Version 2.3.0.1

[PumpTypennn]

DataBits

Numeric

Parity

String

StopBits

Numeric

NotRepsondingPollingRate

Numeric

MaxNoResposes

Numeric

ResponseTimeout

Numeric

IntercharTimeout

Numeric

StatusPollRate

Numeric

AlarmsPollRate

Numeric

TCPIPPort

Numeric

AfterReadDelay

Numeric

SensorPollRate

Numeric

Name

String

Protocol

Numeric

Page 23

only valid for LoopType
COM.
The number of data bits
per character. The options
are 7 or 8, only valid for
LoopType COM.
The parity bit type. The
options are O, E or N, for
odd, even or none
respectively, only valid for
LoopType COM.
The number of stop bits
trailing each character. The
options are 1 or 2, only
valid for LoopType COM.
The delay in milliseconds
inserted between polls to
devices which are currently
not responding.
The maximum number of
sequential no responses
from a device, before this
device is flagged as not
responding.
The response timeout in
milliseconds.
The inter character timeout
in milliseconds.
The delay in milliseconds
between polls for the tank
status.
The delay in milliseconds
between polls for the tank
alarms.
The TCPIP port number for
LoopType = SOCKET.
The delay in seconds after
each poll.
The rate in seconds that
the leak detection sensors
are polled.
The pump type name,
where nnn can be from 001
to 999, this is the Pump
type name as shown in the
EZConfig application.
The ProtocolID used to
communicate with this
pump; this links this pump
type to the appropriate
[Protocolnnn] section. For
the PumpDrv this is always
003.

EZForecourt Developers Manual

Version 2.3.0.1
Driver

String

ProtocolType

Numeric

LoopType

String

Baudrate

Numeric

DataBits

Numeric

Parity

Numeric

StopBits

Numeric

MaxHoses

Numeric

PriceLevels

Numeric

InterPollDelay

Numeric

InterCharDelay

Numeric

ForceValue

Boolean

ForceVolume

Boolean

ResponseDelay

Numeric

Page 24

The name of the DLL file
which is the driver for this
protocol, note it must be a
fully qualified file name.
The protocol type ID, this
number is hard coded and
is used by the EZMOD and
EZRemote to determine
the type of polling for this
device.
The type of physical
connection and hence
driver card necessary for
this type of pump. The
options are CL20 (20ma
current loop), CL40 (40ma
current loop), RS485,
TOKHEIM and NZP.
The BPS (bits per second)
communications rate use
for this protocol, any value
from 300 to 38400 is valid.
The number of data bits
per character. The options
are 7 or 8.
The parity bit type. The
options are O, E or N, for
odd, even or none
respectively.
The number of stop bits
trailing each character. The
options are 1 or 2.
The maximum number of
hoses supported by this
pump type.
The maximum number of
price levels supported by
this pump.
The delay in milliseconds
inserted between polls by
the EZMods
The delay in milliseconds
inserted between
characters by the EZMods
Yes or No, to force the
delivery value to the
difference in the electronic
totals.
Yes or No, to force the
delivery volume to the
difference in the electronic
totals.
A delay in milliseconds

EZForecourt Developers Manual

Version 2.3.0.1

TotalsRollOver

ExtendedTotals

Boolean

4HoseProtocol

Boolean

BrazilCorrection

Boolean

ValueMultiple

Numeric

VolumeETotDecimals

Numeric

ValueETotDecimals

Numeric

VolumeDecimals

Numeric

VolumeDecimals

Numeric

PriceDecimals

Numeric

Page 25

inserted before the MUX
responds to a poll.
Yes or No, to maintain
electronic the part of the
totals greater than
1,000,000.00 in the
EZServer.
Does this protocol support
e-totals greater than a
million.
Wayne specific flag
whether it is the newer 4
hose or older three hose
protocol
Wayne specific flag to
cover a bug in some
Brazilian Wayne pumps.
The numeric multiple that
is the step size in the
delivery total, in cents.
The number of decimals
that the volume e-totals
has for this pump type, if
not present the pump
volume display format is
used.
The number of decimals
that the value e-totals has
for this pump type, if not
present the pump value
display format is used.
The number of decimals
that the delivery volume
has for this pump type, if
not present the pump
volume display format is
used.
The number of decimals
that the delivery value has
for this pump type, if not
present the pump value
display format is used.
The number of decimals
that the delivery price has
for this pump type, if not
present the pump price
display format is used.

EZForecourt Developers Manual

Version 2.3.0.1

5.4.

EZLicense INI file

The EZLicense INI file is used by various EZForecourt modules, it should contain a valid
license key as issued by EZTech, this will determine which of the modules are licensed to
run and until which date. This INI only contains one application specific configuration key.
Section
[Application]

5.5.

Parameter
LicenseKey

Type

SerialNo

String

ExpirationDate

Date

Description
A 24 hex digit license key as supplied
by EZTech.
The numeric part of the serial number
used to generate this license key
The expiration date for this license
key.

EZATG INI file

If the EZForecourt is licensed for ATG functionality the following table is to determine is
functionality of the ATG software module.

Section
[Parameters]

Parameter
ConfirmEventLog

Type
Boolean

MaxLogEvents

Numeric

LogConfigChanges

Boolean

AutoClearTimeout

Numeric

StoppedRespondingTimeout

Numeric

PercentProductHiAlarm

Numeric

PercentProductHiWarning

Numeric

PercentProductLowWarning

Numeric

Page 26

Description
A flag to determine if
LogEvents require
acknowledgement by a
third party software, prior
to deletion.
The maximum number of
log events stored in the
EZForecourt.
Log changes in the
EZForecourt
configuration.
The timeout in seconds
for alarms to be autocleared.
The timeout in seconds
before a tank probe or
pump not responding
generates an alarm.
The percentage of the
tank capacity that above
which will generate a high
product alarm.
The percentage of the
tank capacity that above
which will generate a high
product warning.
The percentage of the
tank capacity that below

EZForecourt Developers Manual

Version 2.3.0.1

PercentProductLowAlarm

Numeric

WaterLevelHiAlarm

Numeric

WaterLevelHiWarning

Numeric

TankReadingInterval

Numeric

StrappingTableStep

Numeric

DampingFactor

Numeric

WeightedReadings

Numeric

VolumeLevelTolerance

Numeric

MinimumLeakVolume

Numeric

MinimumCalibrationErrorVolume

Numeric

MinimumTankDropVolume

Numeric

NotRespondingIsIdle

Boolean

LeakTimeout

Numeric

ExtendedLogs

Boolean

Page 27

which will generate a low
product warning.
The percentage of the
tank capacity that below
which will generate a
product low alarm.
The height in mm, that
above which will generate
a high water alarm
The height in mm, that a
water level above which
will generate a high water
alarm.
The interval in minutes
between logging the tank
readings as a log event, a
multiple of this value must
be 60.
The distance in meters
between strapping table
items.
The number of sequential
readings that are
averaged together to get
the weighted readings.
The number of sequential
weighted readings that
are used to detect tank
drops etc.
The tolerance in meters
between readings that
the readings are treated
as equal.
The minimum
discrepancy volume in
liters that will generate a
leak volume.
The minimum
discrepancy volume in
liters that will be treated
as a tank calibration
error.
The minimum volume in
liters that will be treated
as a tank drop.
Flag to determine of a
non-responding pump is
treated as idle or not.
The timeout in seconds
for a static tank to clear a
leaking alarm.
Flag to turn extended
logs on/off

EZForecourt Developers Manual

Version 2.3.0.1

6. Developer’s Kit contents
The developer’s kit is shipped with a full version of EZForecourt as well as sample programs,
pump simulator, USB RS485 adapter, and cable to connect the USB RS845 adapter to the
EZMod. The pump simulator requires the USB RS485 adapter and cable in order to function. To
install the USB RS485 adapter simply plug it into any available USB port and when the new
hardware found dialog appears point it to the \FTDI directory on the install CD.

6.1.

The EZSim pump simulator

The Pump simulator is used to assist with developing the host system, when a real pump is
not available. It is a windows application that simulates a real pump. The EZSim pump
appears as follows:

Page 28

EZForecourt Developers Manual

Version 2.3.0.1

In order for the pump simulator to work the server must be configure to use the EZSim
protocol for the EZMod in question and the pump types must all be set to EZSim.
To start a delivery simply click on any of the enabled hose, to end the delivery simply click the
hose button again.

6.1.1. EZSim INI file
This EZSim INI file is used by the EZSim pump simulator, as this is not an EZClient it
does not have a [Server] or [Log] section. A lot of the parameters for the EZSim
application are updated by the application when it is exited; as such editing them is of
little benefit. The application specific configuration parameters are as follows.
Section
[Parameters]

Parameter
NumberOfPumps

Type

PriceDecimals

ValueDecimals

VolumeDecimals

CommPort
SlowRate

FastRate

DelTimerInterval

PumpsPerRow

Page 29

Description
The number of pumps
currently configured for
the simulator this can be
from 1 to 16.
The number of decimal
places used for the price
display and price fields in
the communications
protocol.
The number of decimal
places used for the value
display and value fields in
the communications
protocol.
The number of decimal
places used for the
volume display and
volume fields in the
communications protocol.
The com port used by this
simulator
The amount added to the
delivery volume every
time a DelTimeInterval is
passed when the pump is
in slow flow mode.
The amount added to the
delivery volume every
time a DelTimeInterval is
passed when the pump is
in fast flow mode.
The amount of time in
milliseconds that is used
between updates of the
volume delivered when
the pump is delivering.
The number of pumps
display per row in the

EZForecourt Developers Manual

Version 2.3.0.1

HorizontalSpace

VerticalSpace

[PumpNNHoseY]

VolumeETot
Value1ETot

Price1
Value2ETot

Price2

6.2.

EZSim window.
The number of pixels
between each of the
pump simulators
horizontally.
The number of pixels
between each of the
pump simulators
vertically.
The electronic volume
total for pump NN hose Y
The electronic value total
for pump NN hose Y price
level 1
The current price for price
level 1
The electronic value total
for pump NN hose Y price
level 2
The current price for price
level 2

Sample applications

The developer’s kit is shipped with three demonstration applications to assist in the
integration of the EZForecourt into the host system. These applications have no copyrights
applied to them and can be copied or modified as desired. EZTech are adding example
applications all the time, if your requirements are not covered by the following samples, enter
into contact with EZTech support.

6.2.1. EZDemoPos
The EZDemoPos is a VB.net application that acts as a POS terminal and demonstrates
all of the functions that are possible with EZForecourt. It uses the EZTech.DLL .NET
package.

6.2.2. EZClientCSharp
The EZClientCSharp is a more basic example and was also developed in VS 2008 C#, it
demonstrates how to call the EZClient DLL directly.

6.2.3. EZClientCpp.
The EZClientCpp application is an example developed in VS 2008 cpp and it calls the
EZClient.DLL directly. There is also a Linux version which uses GNU Gcc and calls the
EZClient.SO.1 shared object.

Page 30

EZForecourt Developers Manual

Version 2.3.0.1

6.2.4. EZClientDelphi7 / EXClientDelphiXe2.
The EZClientDelphi applications are examples developed in Delphi 7 and Xe2 and call
the EZClient.DLL directly.

Page 31

EZForecourt Developers Manual

Version 2.3.0.1

7. API reference
7.1.

API Components

The API (application interface) for the EZForecourt product consists of five components:









EZClient.DLL, a DLL which exposes the complete API to all types of applications. This
DLL is not a COM DLL and as such does not require registering or require COM
support capabilities of its host. The API for this is defined in the EZClient.h and
EZClient.lib files included with the developer’s kit.
EZTech.EZClient .NET control contained in the EZTech.DLL .NET package this control
exposes the complete API to .NET applications such as VB.NET, C#, and C++ .NET
with the managed C++ extensions.
EZTech.EZPump a visual .NET control contained in the EZTech.DLL .NET package,
this control exposes the pump specific parts of the API. It requires that the
EZTech.EZClient control also be hosted in the same application. This control is a visual
control, and has a limited user interface of its own. The is also the EZTech.EZTank
visual control which exposes the tank specific parts of the API
There are 64 bit versions of the EZTech.DLL and EZClient.DLL, For the EZClient.DLL it
is the EZCLient64.DLL for the EZTech.DLL it is the DLL found in the \EZForecourt\x64
directory.
There is 32 bit EZTech.SO.1 for Linux applications. It exposes the same APIs as the
EZClient.DLL
There is also a Web Service interface as defined in the file EZSoap.wsdl

The API calls are largely common across all five components and will be addressed just once in
this document; any differences between the five interfaces will be highlighted.

Page 32

EZForecourt Developers Manual

Version 2.3.0.1

7.2.

Data types

The API to the EZForecourt was designed using data types that are supported across as many
platforms and development environments as possible. The basic data types are as follows:32 bit Integer, range –2,147,483,648 to 2,147,483,647
16 bit Integer, range –32,768 to 32,767
64 bit Integer, range -9,223,372,036,854,775,808 to
9,223,372,036,854,775,807
64 bit floating point value representing the number of days
since January 1, 100. It has an approximate resolution of 1
millisecond up to December 31, 9999.
64 bit standard floating point type
Variable length Unicode strings , i.e. 16 bit characters

Int32
Int16
Int64
DateTime

Double
String

The declaration of these data types varies depending on the development platform.

Int64

C#
Windows
Int64

C/C++
Windows
__int64

Int64*

ref Int64

__int64*

Int32

long

Int32*

ref Int32

long*

Int16

short

Int16*

ref Int16

short*

double

Double

double

double*

ref Double

double*

String

BSTR

String*

ref String

PBSTR

DateTime

DATE

DateTime*

ref
DateTime

DATE*

Delphi
Int64

VB.net

ByVal
Int64
PInt64
ByRef
Int64
Integer
ByVal
Int32
PInteger
ByRef
Int32
Smallint
ByVal
Int16
PSmallint
ByRef
Int16
Double
ByVal
Double
PDouble
ByRef
Double
WideString
ByVal
String
PWideString ByRef
String
DateTime
ByVal
Date
PDateTime ByRef
Date

Page 33

C/C++
Linux
long long
long long*
long
long*
short
short*
double
double
wchar_t*
wchar_t*
time_t
time_t*

EZForecourt Developers Manual

Version 2.3.0.1

The API is object based, with all objects having a unique identifier. These IDs are of type long
and a value of -1 is designated as the NULL ID. The IDs are only unique to the specific object
type; as such to identify a specific object the type and ID are required.

Page 34

EZForecourt Developers Manual

Version 2.3.0.1

7.3.

Object based architecture

The EZserver software was developed from the ground up using an object based architecture. All
object types have three keys, they are as follows.


ID – a private unique 32 bit integer that is allocated to the object when it is created. This
key cannot be changed during the life of the object. All relationships between objects are
based on this key, and is hidden from the user.



Number – a public 32 bit integer that is used by the user to identify the object, such as
Pump number.



Name – a public 20 character string this is used by the user to identify the object such as
grade name.

All objects types have the following APIs to create, find, update and delete the objects, where
???? is the object type.


Get????sCount – To retrieve the number of objects in the internal EZServer list.



Get????ByOrdinal – To get the ID of an object in a specific position in the internal
EZServer list.



Get????ByNumber – To get the private ID of an object from is public number.



Get????ByName – To get the private ID of an object from is public name.



Get????Properties – To retrieve all of the properties of the object for a given ID, this
includes the number and name.



Set????Properties – To update the properties of an object for a given ID, if this ID does
not exist, a new object of this type is created and appended to the internal EZserver list
and its properties assigned.



Delete???? – To delete an object with a given ID.

Some objects types such as Deliveries, Card Reads, Logged events are created dynamically by
the EZServer, the ID for these object is generated automatically.

Page 35

EZForecourt Developers Manual

Version 2.3.0.1

8. API Definition
8.1.

Connection

The connection APIs are provided to facilitate the log on, log off from the server and verification of
the connection.

8.1.1. ClientLogon(Ex)
Availability – EZClient.DLL, EZClient.SO.1 and EZTech.EZClient

Parameters
Parameter
ClientID

Type
Int32

API
All

ClientType

Int16

All

ServerName

String

All

CallPortNo

Int16

All

EventsPortNo

Int16

CallTimeout

Int32

EventHandle

Int32

All

hWnd

Int32

All

wMsg

Int32

All

Description
A unique identifier to identify this client, this same value must
be used by the EZClient.DLL in future calls to identify the
source. This value must be between 1 and 99.
Any combination of the following
0x01 = Calls client, i.e. can call all non-DB API functions
0x02 = Events client, i.e. will receive all non-DB events
0x04 = DB client, i.e. can call all DB API functions and will
receive all DB related events, this identifies the client as the
client who is performing all the DB operations on behalf of
EZServer, see Appendix 15 – Client type
The IP address or network name of the EZServer service
host machine. This can be passed as ‘’ it is the on the
same machine as the client.
The IP Port number to use for calling the server, the default
value for this is
5123. This value can be changed in the EZServer.ini file if
required.
The IP Port number to use for receiving events from the, the
default value for this is 5124. This value can be changed in
the EZServer.ini file if required.
The timeout in ms for the EZServer service to respond to
calls. The default value for this is 10000.
A HANDLE to an event object that will be cleared when
events have been received. Call ProcessEvents to retrieve
the events for processing. Pass NULL or zero to disable this
feature. (EZClient.DLL parameter only)
A windows handle that will be posted with the wMsg
message when an event is received. Call ProcessEvents to
retrieve the events for processing. Pass NULL or zero to
disable this feature. (EZClient.DLL parameter only)
The message type that is posted to the hWnd handle when
events are received, it must be a value greater than 1024,
this value is ignored if hWnd is passed as NULL.

Page 36

EZForecourt Developers Manual

Version 2.3.0.1

Return value
Error code
OK_RESULT
ALREADY_LOGGED_ON_RESULT
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR

Error description
The call was successful.
A client with this client ID is already logged on.
The call to the server timed out, although a calls socket
was opened successfully.
A connection could not be established with the server, it
is most likely not running or inaccessible.
An unspecified internal error occurred; contact EZTech
technical support for assistance.

Remarks
This call is required to logon to the forecourt server (EZServer) before calling any other API
function. The last three parameters are provided as means for the DLL to signal the host
application that an event has occurred, either an event object handle(EventHandle) or window
handle (hWnd) and message type (wMsg) are passed, never both. Calling ProcessEvents after
receiving notification of the events will process the waiting events. None of these three
parameters are required for the EZClient.SO.1 or EZTech.EZClient APIs as all of the event
processing is handled internally. For ClientLogon the server address and port numbers are
retrieved from the ezclient.ini file, for EZClientLogonEx these values are passed directly.

See also
Erro! Fonte de referência não encontrada.

Page 37

EZForecourt Developers Manual

Version 2.3.0.1

8.1.2. DllVersion
Availability – EZClient.DLL EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
Version

Type
String*

API

Description
The returned value.

Return value
Error code
OK_RESULT

Error description
The call was successful.

Remarks
This API is called to get the software version of the EZClient.DLL.

See also

Page 52

EZForecourt Developers Manual

Version 2.3.0.1

GetEventsCount, GetNextEventType, DiscardNextEvent, GetNextPumpEvent(Ex, Ex2, Ex3)

Page 53

EZForecourt Developers Manual

Version 2.3.0.1

8.2.2. GetEventsCount
Availability – EZClient.DLL, EZClient.SO.1

Parameters
Parameter
Count

Type
Int32*

API

Description
The number of events waiting in the events queue.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE

Error description
The call was successful.
The client is not currently logged on.
The currently logged on client type, does not permit this call.

Remarks
This call is used to determine how many events are waiting in the internal events queue.

See also
ProcessEvents, GetNextEventType, DiscardNextEvent

Page 54

EZForecourt Developers Manual

Version 2.3.0.1

8.2.3. GetNextEventType
Availability – EZClient.DLL, EZClient.SO.1

Parameters
Parameter
Type

Type
Int16*

API

Description
The type of the event waiting at the head of the internal events
queue. See Appendix 14 – Client event types for more
information.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE

Error description
The call was successful.
The client is not currently logged on.
The currently logged on client type, does not permit this call.

Remarks
This call is used to determine what the type of the event at the head of the internal events queue
is. Once you have the type you can then determine which of the GetNext????Event calls to use.

See also
ProcessEvents, Appendix 14 – Client event types

Page 55

EZForecourt Developers Manual

Version 2.3.0.1

8.2.4. DiscardNextEvent
Availability – EZClient.DLL, EZClient.SO.1

Parameters
Parameter
N/A

Type

API

Description

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
OBJECT_DOES_NOT_EXIST_RESULT

Error description
The call was successful.
The client is not currently logged on.
The currently logged on client type, does not permit
this call.
The internal events queue is empty.

Remarks
This call removes the event from the head of the internal events queue; it is provided so that
those events of types that the host application is not interested in can be discarded.

See also
ProcessEvents, GetEventsCount, GetNextEventType

Page 56

EZForecourt Developers Manual

Version 2.3.0.1

8.2.5. GetNextPumpEvent(Ex, Ex2, Ex3) / StatusEvent
Availability –

EZClient.DLL and EZClient.SO.1 for GetNextPumpEvent,
EZTech.EZClient for PumpStatusEvent with no return value,
EZTech.EZPump for StatusEvent with no return value, these values are also
accessible via individual control properties.

Parameters
Parameter
PumpID

Type
Int32*

API
All

PumpNumber

Int16*
Int32*

All
Ex3,Ex3

State

Int16*

All

ReservedFor

ReservedBy

HoseID

HoseNumber

HosePhysicalNumber

Int16*

Int32*

Int16*
Int32*

Int32*

Description
The pump object identifier. This parameter
is not present for the StatusEvent on the
EZTech.EZPump controls.
The logical number of the pump. This
parameter is not present for the
StatusEvent on the EZTech.EZPump
controls.
The current state of the pump, see
Appendix 1 – Pump states for explanation.
EZTech.EZPump control property
PumpState().
The reserve state of the pump, see
Appendix 2 – Pump reserves for
explanation.

All

EZTech.EZPump control property
ReservedFor().
The ID of the client that has the reserve in
place or -1 if there is no reserve.

All

EZTech.EZPump control property
ReservedBy().
The ID of the currently pulled hose object
or -1 if there is no currently pulled hose.

All

Ex
Ex2,Ex3

Ex2,Ex3

Page 57

EZTech.EZPump control property
CurHoseID().
The logical number of the currently pulled
hose or 0 if there is no currently pulled
hose.
EZTech.EZPump control property
CurHoseNumber().
The PhysicalHoseNumber of the currently
pulled hose or -1 if there is no currently
pulled hose.

EZForecourt Developers Manual

Version 2.3.0.1
GradeID

Int32*

All

GradeNumber

Int32*

Ex3

GradeName

String*

All

ShortGradeName

PriceLevel

Price

Volume

Value

StackSize

PumpName
PhysicalNumber
Side
Address

String*

Int16*

Double*

Int16*

String*
Int32*
Int16*
Int16*

The ID of the grade for the currently pulled
hose or -1 if there is no currently pulled
hose.
EZTech.EZPump control property
CurGradeID().
The grade number for the currently pulled
hose or empty string if there is no currently
pulled hose.
The grade name for the currently pulled
hose or empty string if there is no currently
pulled hose.
EZTech.EZPump control property
CurGradeName().
The short grade name for the currently
pulled hose or empty string if there is no
currently pulled hose.

All

EZTech.EZPump control property
CurShortGardeName().
The current price level on the pump.

All

EZTech.EZPump control property
CurPriceLevel().
The selected price for the currently pulled
hose or zero if there is no currently pulled
hose.

All

EZTech.EZPump control property
CurPrice().
The in progress volume total of the
currently delivering pump, if it is not
currently delivering then it is zero.

All

EZTech.EZPump control property
CurVolume().
The in progress value total of the currently
delivering pump, if it is not currently
delivering then it is zero.
EZTech.EZPump control property
CurValue().
The number of stacked deliveries waiting
to be cleared on this fueling position.

All

Ex,Ex2,Ex3
Ex,Ex2,Ex3
Ex,Ex2,Ex3
Ex,Ex2,Ex3

Page 58

EZTech.EZPump control property
StackSize().
The fueling position name.
The fueling position number.
The fueling position side.
The fueling position address.

EZForecourt Developers Manual

Version 2.3.0.1
PriceLevel1

Int16*

Ex,Ex2,Ex3

PriceLevel2

Int16*

Ex,Ex2,Ex3

Type
PortID

Int16*
Int32*

Ex,Ex2,Ex3
Ex,Ex2,Ex3

AuthMode

Int16*

Ex,Ex2,Ex3

StackMode

Int16*

Ex,Ex2,Ex3

PrepayAllowed

Int16*

Ex,Ex2,Ex3

PreauthAllowed

Int16*

Ex,Ex2,Ex3

PriceFormat

Int16*

Ex,Ex2,Ex3

ValueFormat

Int16*

Ex,Ex2,Ex3

VolumeFormat

Int16*

Ex,Ex2,Ex3

Tag

Int64*

Ex2,Ex3

AttendantID

Int32*

Ex2,Ex3

AttendantNumber

Int32*

Ex2,Ex3

AttendantName

String*

Ex2,Ex3

AttendantTag

Int64*

Ex2,Ex3

CardClientID

String*

Ex2,Ex3

CardClientNumber

Int32*

Ex2,Ex3

CardClientName

String*

Ex2,Ex3

CardClientTag

Int64*

Ex2,Ex3

CurFlowRate

Double*

Ex3

PeakFlowRate

Double*

Ex3

The grade price level associated with price
level 1 on this fueling position
The grade price level associated with price
level 2 on this fueling position
The pump type
The port that this pump is connected to 1
USB 1
The current authorization mode for this
fueling position
The current stack mode for this fueling
position
A flag as to whether prepay deliveries are
permitted at this fueling point.
A flag as to whether pre authorize
deliveries are permitted at this fueling
point.
The format of the price display, see
Appendix 6 – Pump display formats
The format of the value/total display, see
Appendix 6 – Pump display formats
The format of the volume/total display, see
Appendix 6 – Pump display formats
An external tag associated with this
delivery in progress, or -1 if none
The ID of the pump attendant associated
with this delivery in progress, or -1 if none.
The number of the pump attendant
associated with this delivery in progress,
or 0 if none.
The name of the pump attendant
associated with this delivery in progress.
The tag of the pump attendant associated
with this delivery in progress, or -1 if none.
The ID of the card client associated with
this delivery in progress, or -1 if none.
The number of the card client associated
with this delivery in progress, or 0 if none.
The name of the card client associated
with this delivery in progress.
The tag of the card client associated with
this delivery in progress, or -1 if none.
The current flow rate in liters per minute if
the fueling point is delivering.
The peak flow rate in liters per minute of
the fueling point during the current
delivery.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE

Error description
The call was successful.
The client is not currently logged on.
The currently logged on client type, does not permit

Page 59

EZForecourt Developers Manual

Version 2.3.0.1

OBJECT_DOES_NOT_EXIST_RESULT

this call.
Either the internal events queue is empty, or the
event at the head of the queue is not of this type.

Remarks
This event is fired whenever the state of the pump changes, this could either be the pump state,
delivery state, delivery values, reserved state, and attendant or client details.

See also
ProcessEvents, GetEventsCount, GetNextEventType, Pumps

Page 60

EZForecourt Developers Manual

Version 2.3.0.1

8.2.6. GetNextDeliveryEvent(Ex, Ex2, Ex3, Ex4) / DeliveryEvent
Availability –

EZClient.DLL and EZClient.SO.1 for GetNextDeliveryEvent,
EZTech.EZClient for DeliveryEvent with no return value, EZTech.EZPump for
DeliveryEvent with return value,

Parameters
Parameter
DeliveryID

Type
Int32*

API
All

PumpID

Int32*

All

PumpNumber

Int16*
Int32*

All
Ex3,Ex4

PumpName

String*

Ex3,Ex4

HoseID

Int32*

All

HoseNumber
HosePhysicalNumber

Int16*
Int32*
Int32*

Base,Ex
Ex3,Ex4
Ex3,Ex4

TankID
TankNumber
TankName
GradeID

Int32*
Int32*
String*
Int32*

Ex3,Ex4
Ex3,Ex4
Ex3,Ex4
All

GradeNumber

Int32*

All

GradeName

Int32*

All

GradeShortName

String*

Ex3,Ex4

GradeCode
PriceLevel
Price
Volume
Value
DeliveryState

String*
Int16*
Double*
Double*
Double*
Int16*

Ex3,Ex4
All
All
All
All
All

Page 61

Description
The delivery object identifier, this is
allocated by the server when the
delivery is completed.
The pumps object identifier of the pump
which dispensed this delivery. This
parameter is not present for the
StatusEvent on the EZTech.EZPump
controls.
The logical pump number of the pump
which dispensed this delivery. This
parameter is not present for the
StatusEvent on the EZTech.EZPump
controls.
The name of the fueling position for this
delivery.
The hose object identifier for the hose
which dispensed this delivery.
The hose number of the hose which
dispensed this delivery.
The physical number of the hose for this
delivery.
The ID of the tank for this delivery.
The number of the tank for this delivery.
The name of the tank for this delivery.
The grades object identifier for the
grade of this delivery.
The number of the grade for this
delivery.
The full name of the grade for this
delivery.
The short name of the grade for this
delivery.
The grade code for this delivery.
The price level used for this delivery.
The price used for this delivery.
The volume dispensed for this delivery.
The total value for this delivery.
The current state of this delivery, see
Appendix 4 – Delivery states for
explanation.

EZForecourt Developers Manual

Version 2.3.0.1
DeliveryType

Int16*

All

LockedBy

Int32*

All

ReservedBy

Int32*

All

Age

Int32*

All

CompletedDT

DateTime*

All

AttendantID

Int32*

All

VolumeETot

Double*

Volume2ETot

Double*

ValueETot

Double*

OldVolumeETot

Double*

Ex2,Ex3,Ex4

OldVolume2ETot

Double*

Ex2,Ex3,Ex4

OldValueETot

Double*

Ex2,Ex3,Ex4

NewVolumeETot

Double*

Ex2,Ex3,Ex4

NewVolume2ETot

Double*

Ex2,Ex3,Ex4

NewValueETot

Double*

Ex2,Ex3,Ex4

Duration

Int32*

Tag

Int64*

AttendentNumber

Int32*

Ex,Ex2,Ex3,
Ex4
Ex,Ex2,Ex3,
Ex4
Ex3,Ex4

AttendentName

String*

Ex3,Ex4

AttendentTag

Int64*

Ex3,Ex4

CardClientID

Int32*

Ex3,Ex4

CardClientNumber

Int32*

Ex3,Ex4

CardClientName

String*

Ex3,Ex4

CardClientTag

Int64*

Ex3,Ex4

Page 62

The type of the delivery, see Appendix 3
– Delivery types for explanation
The ID of the client who has locked this
delivery, if it is NULL ID then the
delivery is unlocked.
The ID of the client who has reserved
this delivery, if it is NULL ID then this
delivery was not reserved.
The age of the delivery in seconds since
it was completed.
The date and time the delivery
completed.
The ID of the pump Attendant that
authorized this delivery or was logged
onto the pump at the time the delivery
was done. If neither of these was the
case then this is NULL ID.
The electronic volume total for this hose
at the end of this delivery.
Always returned as zero. Reserved for
future use.
The electronic value total for this hose
at the end of this delivery.
The electronic volume total for this hose
at the start of this delivery.
Always returned as zero. Reserved for
future use.
The electronic value total for this hose
at the start of this delivery
The electronic volume total for this hose
at the end of this delivery.
Always returned as zero. Reserved for
future use.
The electronic value total for this hose
at the end of this delivery
The duration of the delivery in seconds.
External authorization tag associated
with this delivery.
The number of the pump attendant
associated with this delivery or 0
The name of the pump attendant
associated with this delivery
The tag of the pump attendant
associated with this delivery or -1
The ID of the card client that authorized
this delivery. If this was not the case
then this is NULL ID.
The number of the card client
associated with this delivery, or zero.
The name of the card client associated
with this delivery.
The card client tag associated with this

EZForecourt Developers Manual

Version 2.3.0.1

PeakFlowRate

Double*

Ex4

delivery, or -1.
The peak flow rate obtained during the
delivery in liters per minute.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This event is fired whenever the state of a delivery changes, that could be the delivery state, type,
locked by, reserved by properties, or when the delivery is completed.

See also
ProcessEvents, GetEventsCount, GetNextEventType, Deliver

Page 63

EZForecourt Developers Manual

Version 2.3.0.1

8.2.7. GetNextServerEvent / ServerEvent
Availability –

EZClient.DLL and EZClient.SO.1 as GetNextServerEvent,
EZTech.EZClient as ServerEvent (no return value)
For Events clients only

Parameters
Parameter
EventID
EventText

Type
Int32*
String*

API

Description
The ID of the server generated event.
The event description string.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This event is generated by the server, it can be ignored or simply displayed on the screen.

See also
ProcessEvents, GetEventsCount, GetNextEventType

Page 64

EZForecourt Developers Manual

Version 2.3.0.1

8.2.8. GetNextClientEvent/ClientEvent
Availability –

EZClient.DLL and EZClient.SO.1 for GetNextClientEvent,
EZTech.EZClient for ClientEvent with no return value,
For Events/DB clients only

Parameters
Parameter
ClientID
EventID
EventText

Type
Int32*
Int32*
String*

API

Description
The ID of the client which generated the event.
The ID of the client generated event.
The event description string.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This event is generated when another EZServer client calls FireClientEvent. The value of the
EventID and EventText are simply passed through.

See also
ProcessEvents, GetEventsCount, GetNextEventType, FireClientEvent

Page 65

EZForecourt Developers Manual

Version 2.3.0.1

8.2.9. FireClientEvent
Availability – EZClient.DLL, EZTech.EZClient, EZClient.SO.1

Parameters
Parameter
EventID
EventText

Type
Int32
String

API

Description
The ID of the client generated event
The event description string.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR

Remarks
Calling this API will result in all other EZServer clients receiving a ClientEvent. This API is
provided so that a client can send notifications to other clients.

See also

Page 115

EZForecourt Developers Manual

Version 2.3.0.1
PaymentCancel, PaymentAuthorise, ClearDelivery

Page 116

EZForecourt Developers Manual

Version 2.3.0.1

8.6.2. PaymentCancel
Availability – EZClient.DLL, EZClient.SO.1, Web Service, EZTech.EZClient

Parameters
Parameter
ID

Type
Int32

TermID
TermHash

Int32
String

API

Description
The ID of the pump that is being payment authorized. This
parameter is not present for the EZTech.EZPump controls.
The client ID that is cancelling the reservation.
Reserved for future use.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR

PUMP_NOT_RESERVED_FOR_CTF_RESULT
PUMP_NOT_RESERVED_BY_YOU_RESULT
PUMP_NOT_RESPONDING_RESULT
PUMP_IN_USE_RESULT

Remarks
This API cancels a previous PaymentReserve.

See also
PaymentReserve, PaymentAuthorise

Page 117

EZForecourt Developers Manual

Version 2.3.0.1

8.6.3. PaymentAuthorise
Availability – EZClient.DLL, EZClient.SO.1, Web Service, EZTech.EZClient

Parameters
Parameter
ID

Type
Int32

TermID
TermHash
AttendantID

Int32
String
Int32

AttendantTag

Int64

CardClientID

Int32

CardClientTag

Int64

AuthType
ExtTag
PriceLevel

Int16
Int64
Int16

Price

Double

GradeType

Int16

PriceType

Int16

PresetType

Int16

Value
Hose

Double
Int16

Odometer

Double

Odometer2

Double

Plate

String

ExtTransactionID

String

DriverID

String

Authorisation

String

API

Description
The ID of the pump that is being payment authorized. This
parameter is not present for the EZTech.EZPump controls.
The client ID that is authorizing the payment delivery.
Reserved for future use.
The ID of the pump attendant to be associated with this
delivery, or NULL ID.
The pump attendants RFiD tag to be associated with this
delivery or -1. This tag must belong to a configured pump
attendant.
The ID of the card client to be associated with this delivery,
or NULL ID.
The card clients RFiD tag to be associated with this
delivery or -1. This tag must belong to a configured pump
attendant.
An optional authorization type to be saved with the delivery.
An optional external tag to be saved with the delivery.
The predefined price level to be used for this delivery or
zero for none.
The price to be used for this delivery, the treatment of this
depends on the PriceType parameter.
The grade type permitted, or 0 for all. See EZATG INI file
and GetGradeProperties(Ex).
The form that the Price field is interpreted see Appendix 18
– Price Type
The form that the Value parameter is interpreted see
Appendix 9 – Pump limit types
The preset limit for this delivery.
The hose mask for permitted hoses, see Appendix 10 –
Permitted hoses mask
An optional odometer reading saved with the resulting
delivery.
A second optional odometer reading saved with the
resulting delivery.
An optional vehicle number plate saved with the resulting
delivery. Maximum 10 chars.
An optional external transaction ID saved with the resulting
delivery. Maximum 20 chars.
An optional driver ID string saved with the resulting
delivery. Maximum 10 chars.
An optional authorization ID string saved with the resulting
delivery. Maximum 10 chars.

Page 118

EZForecourt Developers Manual

Version 2.3.0.1

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR

OBJECT_DOES_NOT_EXIST_RESULT
INVALID_PRESET_TYPE_RESULT
INVALID_HOSE_MASK_RESULT
PUMP_NOT_RESPONDING_RESULT
PUMP_NOT_AVAILABLE_RESULT
PUMP_IN_USE_RESULT
PUMP_NOT_RESERVED_FOR_CTF_RESULT
PUMP_NOT_RESERVED_BY_YOU_RESULT
PUMP_IS_STOPPED_RESULT

Error description
The call was successful.
The client is not currently logged on.
The currently logged on client type,
does not permit this call.
The call to the server timed out.
The connection with the server was
lost.
An unspecified internal error occurred;
contact EZTech technical support for
assistance.
The object referenced does not exist.
The preset type requested is not
permitted for this type of authorize.
None of the permitted hoses are
configured on this pump.
The pump is not responding.
The pump is performing a price change
or a timeout after a prepay refund.
The pump is no longer idle.
The pump was not reserved for a
preauth.
The pump was not reserved by this
client.
The pump is currently temp stopped.

Remarks
This API is the final step in a payment delivery, it permits limiting the hose, grade and specifying a
temporary price. It also provides a means of saving additional information along with the delivery.
These optional fields can be retrieved with the GetDeliveryExt API after the delivery is completed.

See also
PaymentReserve, PaymentCancel, GetDeliveryExt

Page 119

EZForecourt Developers Manual

Version 2.3.0.1

8.7.

Pump authorization

The pump authorization APIs provide the various methods by which fueling point can be
authorized etc.

8.7.1. AttendantAuthorise
Availability –

EZClient.DLL, EZClient.SO.1, Web Service,
EZTech.EZClient and EZTech.EZPump

Parameters
Parameter
ID

Type
Int32

AttendantID

Int32

API

Description
The ID of the pump being authorized. This parameter is not
present for the EZTech.EZPump controls.
The ID of the attendant authorizing the pump.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT
PUMP_NOT_RESPONDING_RESULT
PUMP_NOT_AVAILABLE_RESULT
PUMP_IN_USE_RESULT
PUMP_CANNOT_BE_AUTHED_RESULT
PUMP_ALREADY_RESERVED_RESULT
PUMP_IS_STOPPED_RESULT
HAS_CURRENT_DELIVERY_RESULT

Error description
The call was successful.
The client is not currently logged on.
The currently logged on client type, does not permit
this call.
The call to the server timed out.
The connection with the server was lost.
An unspecified internal error occurred; contact
EZTech technical support for assistance.
The object referenced does not exist.
The pump is not responding.
The pump is unavailable, it is either changing
prices or timing out after a prepay refund.
The pump is not idle.
The pump mode does not permit post pay
deliveries.
The pump is already reserved for a prepay, preauth
or payment delivery.
The pump is currently temp stopped.
The pump has a current delivery which cannot be
automatically stacked.

Remarks
This is API is used to manually authorize a pump without a limit, the resultant delivery is logged
against the authorizing attendant. If the delivery is not started within the configured manually
authorized timeout the pump reverts locked.

See also

Page 137

EZForecourt Developers Manual

Version 2.3.0.1

8.9.

Deliveries

Deliveries are the basic fuel delivery transaction. They may include links to the attendant and/or
client associated with the delivery.

8.9.1. GetDeliveriesCount
Availability – EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
Count

Type
Int32*

API

Description
The returned total number of delivery objects currently in the
server.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR

Remarks
This API is used determine the total number of deliveries currently in the server. Once this is
known, the IDs of the individual delivery objects can be obtained using GetDeliveryByOrdinal.

See also

Page 148

EZForecourt Developers Manual

Version 2.3.0.1
LockDelivery, UnlockDelivery, ClearDelivery

Page 149

EZForecourt Developers Manual

Version 2.3.0.1

8.9.9. SetNextDeliveryID
Availability –

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient
For DB clients only.

Parameters
Parameter
ID

Type
Int32

API

Description
The ID used to save the next delivery completed.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR

Remarks
As the EZServer captures the deliveries done on the pumps, they are associated with a unique
ID. This ID is generated by simply incrementing in internal long variable. However as the
EZServer has no knowledge of the deliveries already logged into the database, it is necessary for
the DB Client to give it a starting value. This would normally be the maximum logged delivery ID
plus one.

See also

Page 231

EZForecourt Developers Manual

Version 2.3.0.1
GetZigBeeByNumber, GetZigBeeByOrdinal, GetZigBeeCount

Page 232

EZForecourt Developers Manual

Version 2.3.0.1

8.15.4.
Availability –

GetCardClientByOrdinal

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
Index

Type
Int32

Int32*

API

Description
The index of the desired card client object, this can be
between 1 and the total number of card client, as returned by
GetCardClientsCount.
The returned ID of the card client object.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This API is used to retrieve the ID of a card client using its ordinal value in the EZServer’s internal
card client objects list. The card clients are ordered in this list by ID.

See also
GetCardClientsCount, GetCardClientByNumber, GetCardClientByName

Page 233

EZForecourt Developers Manual

Version 2.3.0.1

8.15.5.
Availability –

GetCardClientProperties(Ex,Ex2)

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
ID
Number
Name
Tag

Type
Int32
Int32*
String*
String*

API
All
All
All
All

Enabled
PriceLevel

Int16*
Int16*

All
Ex,Ex2

Plate
GradeType

String*
Int16*

Ex,Ex2
Ex2

CardType

Int16*

Ex2

LimitType

Int16*

Ex2

Limit

Double*

Ex2

EntryType

Int16*

Ex2

ExpirationDate
ParentID

Date*
long*

Ex2
Ex2

Description
The ID of the card client being queried.
The card client number.
The card client name.
The RFiD tag for this client as read form the RFiD
card.
A true/false flag to enable/disable this client.
The level of the price to be used for this card client,
this must be one of the levels defined for all of the
grades.
The vehicle number plate.
The type of grade permitted for this card client, or zero
for all, see EZATG INI file and
GetGradeProperties(Ex)
The card type of this card client, see Appendix 27 –
Card Types.
The delivery limit type, see Appendix 9 – Pump limit
types
The delivery volume of value limit to be applied for this
card, this depends on the LimitType field.
The type of additional manual data entry required for
this card, see Appendix 28 – Entry Types
The expiration date for this card.
If this is a secondary card type, this filed is the ID of
the primary card to which this is linked.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This API returns all the property values of a card client object for the given ID.

Page 234

EZForecourt Developers Manual

Version 2.3.0.1

See also
SetCardClientProperties(Ex, Ex2), EZATG INI file, GetGradeProperties(Ex)

Page 235

EZForecourt Developers Manual

Version 2.3.0.1

8.15.6.
Availability –

SetCardClientProperties(Ex, Ex2)

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient
For DB clients only.

Parameters
Parameter
ID
Number
Name
Tag
Enabled
PriceLeve

Type
Int32
Int32
String
String
Int16
Int16

API
All
All
All
All
All
Ex,Ex2

Plate
GradeType

String
Int16

Ex,Ex2
Ex2

CardType

Int16

Ex2

LimitType
Limit

Int16
Double

Ex2
Ex2

EntryType

Int16

Ex2

ExpirationDate
ParentID

Date
Long

Ex2
Ex2

Description
The ID of the card client being updated,
The card client number.
The card client name.
The RFiD tag for this client as read form the RFiD card.
A true/false flag to enable/disable this client.
The level of the price to be used for this card client, this
must be one of the levels defined for all of the grades.
The vehicle number plate.
The type of grade permitted for this card client, or zero for
all, see EZATG INI file and GetGradeProperties(Ex)
The card type of this card client, see Appendix 27 – Card
Types.
The delivery limit type, see Appendix 9 – Pump limit types
The delivery volume of value limit to be applied for this
card, this depends on the LimitType field.
The type of additional manual data entry required for this
card, see Appendix 28 – Entry Types
The expiration date for this card.
If this is a secondary card type, this filed is the ID of the
primary card to which this is linked.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
INVALID_OBJECT_PARAMETER_RESULT
TAG_ALREADY_IN_USE_ERROR_RESULT

Remarks
This API is provided so that card client objects can be created and maintained on the EZServer. If
the given card client ID already exists the properties for this object will be overwritten with the

Page 236

EZForecourt Developers Manual

Version 2.3.0.1

values passed, otherwise a new card client object with this ID is created and its properties set to
the values passed.

See also
GetCardClientProperties(Ex,Ex2), DeleteCardClient

Page 237

EZForecourt Developers Manual

Version 2.3.0.1

8.15.7.
Availability –

DeleteCardClient

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
ID

Type
Int32

API

Description
The ID of the card client object to delete.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT
OBJECT_HAS_DEPENDANCIES_RESULT

Remarks
The ID of the card client object to be deleted from the EZServer.

See also
SetCardClientProperties(Ex, Ex2)

Page 238

EZForecourt Developers Manual

Version 2.3.0.1

8.16.

Card Reads

The card read object is a temporary object created in the EZServer whenever an RFiD card is
read from one of the RFiD readers attached to the EZremotes or other devices. These objects
remain in the system until they are deleted by DeleteCardRead or timeout after 60 seconds.
These card reads can be received as events in GetNextCardReadEvent / CardReadEvent as
events of type CARD_READ_EVENT, or polled for using the GetCardReadsCount API etc. When
a card read is generated it is pre-consulted in the attendants and card clients lists to see if it is a
configured card.

8.16.1.
Availability –

GetCardReadsCount

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
Count

Type
Int32*

API

Description
The returned total number of card reads cached in the
EZServer.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR

Remarks
This API is used to determine of card reads currently waiting in the internal card reads cache in
the EZServer.

See also
GetCardReadByOrdinal, GetCardReadProperties, DeleteCardRead

Page 239

EZForecourt Developers Manual

Version 2.3.0.1

8.16.2.
Availability –

GetCardReadByNumber

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
Number
ID

Type
Int32
Int32*

API

Description
The number of the card read in question.
The ID of the card read returned.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This API is provided convert the card read number into its corresponding card ID. The number
parameter for a card read depends on the associated object, it will the pump attendant, card
client number or 0.

See also
GetCardReadByOrdinal, GetCardReadByName

Page 240

EZForecourt Developers Manual

Version 2.3.0.1

8.16.3.
Availability –

GetCardReadByOrdinal

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
Index

Type
Int32

Int32*

API

Description
The index of the desired card read object, this can be
between 1 and the total number of card reads, as returned by
GetCardReadsCount.
The returned ID of the card read object.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This API is used to retrieve the card read ID using its ordinal value in the EZServer’s internal card
reads objects list. The card reads are ordered in this list by ID.

See also
GetCardReadsCount, GetCardReadByNumber, GetCardReadByName

Page 241

EZForecourt Developers Manual

Version 2.3.0.1

8.16.4.
Availability –

GetCardReadByName

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient

Parameters
Parameter
Name

Type
String

Int32*

API

Description
The name of the card read object for which the ID is being
requested.
The returned ID of the card read object.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This API returns the ID of a card read for a given name. The name parameter of a card is
determined the parent object, either a pump attendant or card client name is required.

See also
GetCardReadByNumber, GetCardReadByOrdinal

Page 242

EZForecourt Developers Manual

Version 2.3.0.1

8.16.5.
Availability –

GetCardReadProperties

EZClient.DLL, EZClient.SO.1, Web Service and EZTech.EZClient
For DB clients only.

Parameters
Parameter
ID
Number

Type
Int32
Int32*

Name

String*

PumpID
Type

Int32*
Int16*

ParentID

Int32*

Tag
TimeStamp

Int64*
DateTime*

API

Description
The ID of the card read object being queried.
The number of the pump attendant or card client
associated with this card read.
The name of the pump attendant or card client associated
with this card read.
The ID of the fueling point, where this card was read.
The type of card read, see Appendix 26 – Card Read
Types
The ID of the parent object of this card read, this will either
be an Attendant or Card Client ID.
The tag of the RFiD card as read from the card.
The time and date that the card was read.

Return value
Error code
OK_RESULT
NOT_LOGGED_ON_RESULT
INVALID_CLIENT_TYPE
SERVER_TIMEOUT
CONNECTION_BROKEN
INTERNAL_SERVER_ERROR
OBJECT_DOES_NOT_EXIST_RESULT

Remarks
This API is used to query all of the attributes of this card read. When a card read object is created
the pump attendants and card client lists are consulted to see I this card is registered, if the
number, name, parentID and type fields are populated.

Developers Manual

Navigation menu

Versions of this User Manual:

Views

Navigation