Documentation about the DFComDLL.dll
(Version 04.03.06)

Content:

1   Introduction
1. 1   What are channel numbers and bus numbers?
1. 1. 1   What is a channel number (ChannelID)?
1. 1. 2   What is a bus number (DeviceID)?
1. 2   Exemplary program structure
1. 3   Alternations of the version
1. 4   Mode of operation of the DLL
1. 5   General information
1. 5. 1   Lists of the setup
1. 5. 2   Data types
1. 5. 3   Errors
1. 5. 4   Background logging
1. 5. 5   Setting the time
1. 5. 6   Transmission of Timeboy lists
1. 5. 7   Transmission of device data (DFCUpload)
1. 5. 8   IP address and hostname
1. 6   Active Connection
1. 6. 1   Introduction
1. 6. 2   Rough overview
1. 6. 3   Short comparison of the instruction execution without and with "Active Connection"
1. 6. 4   Start, stop and initialisation of the "Active Connection"
1. 6. 5   Messaging of data records
1. 6. 6   Bringing into service and checking
2   Exported functions
2. 1   General functions
2. 1. 1. 1 DFCComInit Initialise serial interface for AEIII+.
2. 1. 1. 2 DFCComOpenSerial Initialise serial interface for AEIII+.
2. 1. 1. 3 DFCComOpen Initialise TCP/IP interface for AEIII+.
2. 1. 1. 4 DFCComOpenSocket Initialise TCP/IP interface for AEIII+.
2. 1. 2   DFCComOpenIV Initialise serial or TCP/IP for MasterIV.
2. 1. 3   DFCComClose Close the interface opened before.
2. 1. 4. 1 DFCCheckAE Check availability.
2. 1. 4. 2 DFCCheckDevice Check availability.
2. 1. 5   DFCComSetTime Write date and time.
2. 1. 6   DFCComGetTime Read date and time.
2. 1. 7   DFCComSendMessage Send a display message.
2. 1. 8   DFCComSendInfotext Send a background message.
2. 1. 9   DFCGetSeriennummer Read the serial number.
2. 1. 10. 1 DFCLogOn Of no further use.
2. 1. 10. 2 DFCSetLogOn Activate logging.
2. 1. 11. 1 DFCLogOff Of no further use.
2. 1. 11. 2 DFCSetLogOff Deactivate logging.
2. 1. 12   DFCSetCallBack Release the recall function.
2. 1. 13   DFCSetLogFileName Set the name of the logging file.
2. 1. 14   DFCGetErrorText Convert the error number into the error text.
2. 1. 15   DFCSetGlobVar Change the value of a variable.
2. 1. 16   DFCGetGlobVar Establish the value of a variable.
2. 1. 17   DFCCloseRelay Close the relay for a definable period of time.
2. 1. 18   DFCGetRelayState Query the state of the relay.
2. 1. 19   DFCOpenRelay Open the relay.
2. 1. 20   DFCGetDevicePollRetry Establish the number of establishing tries.
2. 1. 21   DFCGetComPort Return of the interface handle.
2. 1. 22   DFCSetComPort Setting of the interface handle.
2. 1. 23   DFCWrite Write on the channel.
2. 1. 24   DFCRead Read out of the channel.
2. 1. 25   DFCUpload Load the device data (firmware).
2. 1. 26   DFCGetVersionFirmware Read the version of the device software.
2. 1. 27   DFCGetVersionFirmwareFromFile Read the version of the device software file.
2. 1. 28   DFCGetInfo Query information about a module.
2. 1. 29   DFCOpenComServerMode Activate the transparent mode.
2. 1. 30   DFCCloseComServerMode Deactivate the transparent mode.
2. 1. 31   DFCIsChannelOpen A communication connection exists.
2. 1. 32   DFCUploadModule Load the module data (firmware).
2. 1. 33   DFCGetOptionFirmware Read extended options for firmware.
2. 1. 34   DFCSetOptionFirmware Write extended options for firmware.
2. 1. 35   DFCReset Reset of Terminal in different modes.
2. 1. 36   DFCSetFontType Set font size and type for SendMessage and SendInfotext.
2. 1. 37   DFCSetPassword Set password for communication.
2. 1. 38   DFCGetPasswordKey Query replace key to generate substitute password.
2. 1. 39   DFCPressVirtualKey Choose function keys (F1 - F15)
2. 1. 40   DFCGetFlashStatus Query current state for flash.
2. 2   Functions for the setup
2. 2. 1   DFCSetupLaden Transmit the setup file to the device.
2. 2. 2   DFCDownload Write the setup data of the device on a file.
2. 2. 3   DFCModifyStudioFile Change the setup data in the setup file.
2. 3   Functions for lists and access lists (version 2)
2. 3. 1   DFCOpenTable Open a table.
2. 3. 2   DFCCloseTable Close a table.
2. 3. 3   DFCSetFilter Set the filter criterion.
2. 3. 4   DFCGetFilter Read the current filter criterion.
2. 3. 5   DFCClearFilter Remove the filter criterion
2. 3. 6   DFCSkip Move the data record pointer.
2. 3. 7   DFCSetField Change the value of a data record field.
2. 3. 8   DFCGetField Establish the value of a data record field.
2. 4   Functions for data
2. 4. 1   DFCComClearData Reset the data pointer in the device.
2. 4. 2   DFCComCollectData Start the process of data collection.
2. 4. 3   DFCComGetDatensatz Establish the data record.
2. 4. 4   DFCLoadDatensatzbeschreibung Establish the data record description from the device setup.
2. 4. 5   DFCDatBCnt Number of established data record descriptions.
2. 4. 6   DFCDatBDatensatz Get the basic data of an established data record description.
2. 4. 7   DFCDatBFeld Get the basic data of an established data record description field.
2. 4. 8   DFCReadRecord Read the next pending data record.
2. 4. 9   DFCQuitRecord Quit the data record read before (delete).
2. 4. 10   DFCRestoreRecords Set pointer of records on first available.
2. 5   Functions for lists
2. 5. 1   DFCMakeListe Import the raw data of a list.
2. 5. 2   DFCLoadListen Write the imported list data on the device.
2. 5. 3   DFCClrListenBuffer Delete the list buffer for an import.
2. 5. 4   DFCLoadListenbeschreibung Establish list descriptions from a device setup.
2. 5. 5   DFCListBCnt Number of established list descriptions.
2. 5. 6   DFCListBDatensatz Get the basic data of an established list description.
2. 5. 7   DFCListBFeld Get the basic data of an established list description field.
2. 6   Functions for access control lists (version 1)
2. 6. 1   DFCMakeEntranceList Import the raw data of a list.
2. 6. 2   DFCLoadEntranceList IWrite the imported list data on the device.
2. 6. 3   DFCClearEntranceListBuffer Delete the list buffer for an import.
2. 7   Functions for access control lists (version 2)
2. 7. 1   DFCMakeEntrance2List Import the raw data of a list.
2. 7. 2   DFCLoadEntrance2List Write the imported list data on the device.
2. 7. 3   DFCClearEntrance2ListBuffer Delete the list buffer for an import.
2. 7. 4   DFCEntrance2Identification Carry out an access control via DLL.
2. 7. 5   DFCEntrance2OnlineAction Activate the access module via DLL.
2. 7. 6   DFCAccessControlIdentification Carry out an access control via DLL on devices with more than one access bus.
2. 7. 7   DFCAccessControlOnlineAction Activate the access module via DLL on devices with more than one access bus.
2. 8   Functions for the fingerprint
2. 8. 1   DFCFingerprintAppendRecord Append a finger template.
2. 8. 2   DFCFingerprintGetRecord Establish the data of a finger template.
2. 8. 3   DFCFingerprintDeleteRecord Delete finger templates.
2. 8. 4   DFCFingerprintList Liste mit allen enthaltenen PID-FIDs erstellen.
2. 8. 5   DFCFingerprintBackup Backup aller enthaltener Fingertemplates erstellen.
2. 8. 6   DFCFingerprintRestore Ein vorhandenes Backup von Fingertemplates wiederherstellen.
2. 9   Functions for Timeboy lists
2. 9. 1   DFCMakeTimeboyList Import the raw data of a list.
2. 9. 2   DFCLoadTimeboyList Write the imported list data on the device.
2. 9. 3   DFCClearTimeboyListBuffer Delete the list buffer for an import.
2. 10   Functions for the Active Connection
2. 10. 1   DFCStartActiveConnection Start of the DLL module for the active connection establishment.
2. 10. 2   DFCStopActiveConnection Stop of the DLL module for the active connection account.
2. 10. 3   DFCGetFirstActiveChannelID Establish the number of the first "Active" connected channel.
2. 10. 4   DFCGetNextActiveChannelID Establish the number of the following "Active" connected channels.
2. 10. 5   DFCGetInfoActiveChannel Query information about the "Active" connected channel.
2. 10. 6   DFCSetRecordAvailable Activate/ Deactivate the account of the message "Data record available".
2. 10. 7   DFCRecordAvailable Access to the queue of the message "Data record available".
2. 10. 8   DFCBindDeviceToChannel Link a device to this channel number.
3   Data structure
3. 1   Structure of the data records in the byte array
3. 2   Date and time in the byte array
4   System variables
4. 1   Variables for the mobile communication, prefix: _MODEM_MC35i / MOBILE
4. 2   Variables for the operation, prefix: SERVICE
4. 3   Variables for the access, prefix: ACCESS
4. 4   Variables for Bluetooth, prefix: BTH
4. 5   Variables for digital inputs/ outputs, prefix: IO
4. 6   Variables for the prefix: POWER
4. 7   Variables for the Active Connection, prefix: COM
4. 8   Variables for sending records per Http, prefix: HTTP
4. 9   Variables for the System, prefix: SYSTEM

1     1 Introduction

The DLL "DFComDLL.dll" provides the basic functions for the communication via RS232 or rather RS485 as well as TCP / IP. It is used 100% by the DatafoxStudioIV / AESetup from version 2.0.0 on. The available AEIII+ techniques were transmitted to the MasterIV hardware, which can be activated via a special initialisation routine.

1.1     What are channel numbers and bus numbers?

  Multithreading is not allowed on a channel object. Only one thread per channel !!

 
Figure 1

Figure 1 shows a possible hardware structure with Datafox devices. We want to use this example to clarify the terms channel and bus number. The channel number (ChannelID) is comparable to a street name. The bus number (DeviceID) is comparable to the house number of a building (it is used in the RS485 network). In the pictured example there are altogether three channels (ChannelIDs).

A device of figure 1 can be defined clearly via the following rates (address):
Address of device Achannel: 1, bus number: 1
Address of device Cchannel: 1, bus number: 3
Address of device Dchannel: 2, bus number: 1
Address of device Fchannel: 3, bus number: 254, IP: 192.168.123.2, Port: 8000 **
**(special case: bus number always 254)

In order to send information to the devices it is necessary to open the respective channel (ChannelID) before. In analogy to our street example this is comparable to opened gates.

It is not necessary to close the used channel (ChannelID) each time, when the communication with a device was finished (a gate is also not closed after each car that passed the road). The communication channels can be opened, when starting the program (see 1.2 Exemplary program structure). Closing the communication channels (ChannelID) is usually not necessary before the program is closed; but sometimes it is required in special situations. Closing a channel is necessary after an interruption of the communication with TCP/IP connections and modem connections.

1.1.1     What is a channel number (ChannelID)?

The channel number (ChannelID) is comparable to a street name. Each device belongs to exactly one communication channel. The number of possible channels is set to at most 250 (permitted range of value: 1-250). A number of devices (see bus number) of up to 1..n singles devices (terminals) is possible for each channel.

 Tabelle 1
 Scheme of connection  Mode of connection  from - to  Maximum number of devices per channel  Bus number to be used for function calls
  RS232 RS232  directly   RS232-RS232  n = 1  always 254 !!
  RS232 RS485  via converter       RS232-RS485  n = 31  from 1 to 31
  TCP/IP TCP/IP  directly  TCP/IP-TCP/IP  n = 1  always 254 !!
  TCP/IP RS485  via COM server  TCP/IP-RS485  n = 31  from 1 to 31
  TCP/IP RS232  via COM server  TCP/IP-RS232  n = 1  always 254 !!

1.1.2     What is a bus number (DeviceID)?

The bus number (DeviceID) is comparable to the house number of a building. This number is used to address a certain device. When using RS485 networks (bus systems) each terminal needs a clear number. This number (bus number) can be set in the BIOS of each device. The number of devices is limited to at most 31 (permitted bus numbers: 1-31 and 254*).

  The bus number 254 has a special meaning. It must not be used in RS485 networks. Via this bus number each device of the RS232 mode can be activated. If no RS485 bus is activated, the bus number (DeviceID) 254 always has to be set (if necessary) for function calls.

 From version 04.00.21 of the PZE-MasterIV on setting the bus number is only possible, if:
 
  • the device is equipped with the RS485 option,
  • the RS485 communication was selected for the device under communication / interface of the BIOS

If the communication mode RS485 is not selected (from version 04.00.21 of the PZE-MasterIV on), the bus number of the device is set to 254 automatically.

1.2  Exemplary program structure


Figure 2

The adjoining scheme (figure 2) shows a possible basic structure of a program for the hardware structure shown in figure 1. In principle a programming project should be structured like the adjoining scheme. After starting the program all necessary channels (ChannelIDs) are initialised. Usually it is sufficient, if the opened channels (ChannelIDs) are closed when closing the program. After initialising the channels, the terminals can be activated as often as required. A renewed initialisation would be necessary only in case of a communication interruption. In that case the concerned channel has to be closed at first via the function DFComClose (explicitly!). Only then a reopening via an initialisation function is permitted.

 

E.g. via the function DFCGetComPort you can check whether a certain channel number (ChannelID) was already opened (or rather is still opened). Cpp Example: Check whether channel 2 is opened if (DFCGetComPort( 2 ) != -1) { printf("Channel 2 already opened.\n"); } else { printf("Channel 2 not opened.\n"); }

1.3     Alternations of the version

Date Version Alternation
08.12.01 1.1.0 Inclusion of functions for lists.
26.01.02 1.1.c Clearance of errors when reading large data amounts.
12.02.02 1.1.e Clearance of errors, if no data records are available in the device. NEW: Read date/ time.
29.04.02 1.1.f Inclusion of the function DFCComSendInfotext.
14.06.02 1.1.g Switch-off of the creation of a log file.
04.07.02 1.1.h Log file can be switched on/ off via the functions DFCLogOn, DFCLogOff.
09.09.02 1.1.i Reading data record descriptions and list descriptions out of the device.
09.10.02 1.1.j Checking the availability of the device. Reading the serial number and transmitting a setup file.
 Version 2
21.02.03 02.00.00 Controlled conclusion of the first technique. Introduction of a new technique, including the reading of separate data records, the reading out of the device and the recall function.
24.02.03 02.00.01 Clearance of the error when loading the setup under Win9X and WinMe.
01.03.03 02.00.02 Support of firmware states under FW 2.0. Also the old data record technique.
27.03.03 02.00.03 Adjustment of the export interface to Talk. Support of FW >=3.0
13.05.03 02.00.04 Inclusion of setting and reading global variables via DFCSetGlobVar and DFCGetGlobVar.
20.05.03 02.00.05 SClosing, state query and opening the internal and the IO module – relay. Importing and loading the list data for the access control.
11.06.03 02.00.06 Support of AESetup for 02.00.00
15.07.03 02.00.07 Communication with the old firmware (V1.14) stabilised.
07.08.03 02.00.08 Revision of DFCComSetTime. Parameters of the device last after manual alternation and setup setting.
11.08.03 02.00.09 Inclusion of the device parameter "Keypad tone"; the other parameters, which cannot be set via the setup program, are retained from firmware version 3.1.2 on.
05.09.03 02.00.10 Inclusion of the function DFCComOpenIV, used to activate the MasterIV devices.
12.09.03 02.00.11 Revision of the error mapping for PZE-MasterIV. Revision of the function DFCSetupLaden, used to allocate global variables with default values of the setup data (setup from V03.01.07 on).
16.09.03 02.00.12 Bugfix of DFCSetupLaden and installation of TCP/IP in DFCComOpenIV.
17.09.03 02.00.13 Alternation to input firmware files for PZE-MasterIV via TCP/IP.
29.09.03 02.00.14 Port of DLL project to Linux (SuSE 7.3).
24.10.03 02.00.15 Inclusion of background logging for all function calls.
08.12.03 02.00.16 Revision of DFCSetGlobVar and DFCGetGlobVar for AESetup.
29.01.04 02.00.17 Revision of the functions DFCMakeEntranceList and DFCLoadEntranceList, because the personnel number was increased from 12 up to 13 digits.
24.02.04 02.00.17 Inclusion of the functions DFCGetComPort and DFCSetComPort to the documentation.
29.04.04 02.00.18 Adding of DFCWrite, DFCRead, DFCUpload and increasing the size of data packets for the communication with PZE-MasterIV devices. Adding of DFCGetVersionFirmware, supported from firmware 04.00.19 on.
20.07.04 02.00.19 Clearance of the errors at internal sorting of the permanent access staff. Increase of the number of channel classes from 10 up to 250. List data are loaded in the background for PZE-MasterIV from firmware 04.00.21 on.
08.10.04 02.00.20 Clearance of errors; for unlisted internal communication version numbers the error message (no ready signal of the device) was delivered, although this command actually was not supported by the device. Query of the firmware version possible via DFCGetFirmwareVersion, also for AEIII+. DFCComInit higher than COM9 possible.
02.02.05 02.00.21 Adding of the function DFCGetFirmwareVersionFromFile to read the firmware version out of a device file. Support of the Bootloader version 2.2.
18.02.05 02.00.22 Increase of the list size up to about 256 kbyte. The list data of this size can be imported via the function DFCMakeListe. When inputting the list data via DFCLoadListen, it might be possible, that the error message 13 is delivered (because of the firmware version); in that case the list size is not supported by the firmware version. Revision of the functions DFCListBDatensatz, DFCListBFeld, so that also the structure of the access control lists version 1 can be queried.

02.03.06 02.00.23 The functions DFCReadRecord and DFCQuitRecord were uncovered. The functions DFCComCollectData and DFCComGetDatensatz use this functions internal and can be replaced by them.
Version 4.1 The versions 3.x and 4.0 were not assigned, in order to allow a version analogousness of the current firmware and the DatafoxStudioIV. The new functions of version 4.1 are not supported by AEIII+.
27.06.06 04.01.01 Adding of functions for the access control version 2: DFCClearEntrance2ListBuffer, DFCMakeEntrance2List, DFCLoadEntrance2List The functions DFCListBDatensatz, DFCListBFeld were revised, so that also the structure of the access control lists version 1 / version 2 can be queried. Adding of the functions DFCOpenTable, DFCCloseTable, DFCSetFilter, DFCGetFilter, DFCClearFilter, DFCSkip, DFCSetField, DFCGetField to access list columns and change their values.

11.08.06 04.01.02 The importable list size for firmware 04.00.xx was set wrongly. The CallBack call when using firmware 04.01.xx was not carried out for each communication function. The list buffer for default lists and access lists are managed dynamically. If necessary, these lists are sorted lexicographically before transmission. The function DFCComSendInfotext was activated for the BDE- /MDE-MasterIV.
13.12.06 04.01.03 see corresponding entries in the document "MasterIV, SoftwareVersionen Stand xxxx.xx.xx.pdf".
10.04.08 04.01.04 Extension of the functions DFCGetInfo, DFCEntrance2Identification, DFCOpenComServerMode, DFCCloseComServerMode, DFCFingerprintAppendRecord, DFCFingerprintGetRecord, DFCFingerprintDeleteRecord, DFCMakeTimeboyList, DFCLoadTimeboyList, DFCClearTimeboyListBuffer. The function DFCUpload (for inputting firmware files) accepts special zip archives (in Win32). A directory can be set under Linux.
22.10.08 04.01.05 Extension of the functions DFCStartActiveConnection, DFCStopActiveConnection, DFCGetFirstActiveChannelID, DFCGetNextActiveChannelID, DFCGetInfoActiveChannel, DFCSetRecordAvailable, DFCRecordAvailable, DFCModifyStudioFile, DFCEntrance2OnlineAction. From this version on the Active Connection is supported by Win32.
16.03.09 04.01.06 Extension of the functions DFCUpload, so that text data for the firmware can be input
22.01.10 04.01.07 Function DFCReset added for reset of Terminal. Function DFCSetFontType added for choosing font size and type. Functions DFCSetPassword, DFCGetPasswordKey added for communication password. Function DFCPressVirtualKey added to press function keys (virtual). Function DFCFingerprintList added to generate a list of all fid's in modul. Functions DFCFingerprintBackup and DFCFingerprintRestore added to generate backup and restore fingerprint templates. Function DFCGetFlashStatus added to query current flash state.
 Version 4.2 Support Hardware revision 3.
27.10.10 04.02.00 Support Active Connection under Linux. Use of version Firmware 04.02.xx and device Flex-MasterIV, Exklusiv-LineIV
28.01.11 04.02.01 Support device TimeboyIV and Timeboy-Mobil-PZE.
22.07.11 04.02.02 Supports Multidocking TimeboyIV and Timeboy-Mobil-PZE.
 Version 4.3 Support EVO-Line.
12.12.13 04.03.00 Supports EVO-Line 2.8, EVO-Line 4.3, IPC-Extension.
06.01.14 04.03.01 Supports firmware version 04.03.01.
20.03.14 04.03.02 Supports firmware version 04.03.02.
15.10.14 04.03.03 Supports firmware version 04.03.03.
19.01.15 04.03.04 Add functions DFCAccessControlIdentification and DFCAccessControlOnlineAction to support devices with more than one access bus.
22.07.15 04.03.05 Supports firmware version 04.03.05.
21.01.16 04.03.06 Supports firmware version 04.03.06.

 

1.4     Mode of operation of the DLL

The DLL is an interface between a software application and the AEIII+ / MasterIV devices. All functions concerning the devices are delivered to the DLL via the software application, there they are processed and then, if necessary, transmitted to the device that shall be activated.

Conditioning of data records

Before reading data records out of the device, the current communication interface has to be initialised successfully via one of the following functions: DFCComOpenSerial, DFCComOpenSocket (AEIII+) or DFCComOpenIV (MasterIV). At next the device (with the indicated bus number) is released via the method DFCComCollectData and the first data record (or all data, depending on the firmware version) is read out of the device. The function DFCComGetDatensatz confirms this data record (which was read out before via DFCComCollectData), sends the data to the data buffer (which has to be allocated) and, if indicated, reads the next data record out of the device buffer. This one is quit when the function DFCComGetDatensatz is called up again and then sent to the data buffer. That way, by sequenced calling up the function DFCComGetDatensatz single data records of the device are passed to the application. After carrying out all necessary communication commands the communication interface has to be closed via the function DFCComClose
A data record cannot get lost during the communication. But in case of an interruption of the communication it might be possible, that a data record is read out twice (valid for the firmware version > 2.0). From firmware version 03.01.20 (AEIII+) and 04.00.21 (PZE-MasterIV) on the data records are delivered in chronological order.

Annotation to the data record description and the list description (table definitions)

Several connections, so called channels, can be established at the same time by using different interfaces. For each channel an own internal buffer is used, which contains though the data record descriptions and the list descriptions of device, which was read out before via DFCLoadDatensatzbeschreibung and DFCLoadListenbeschreibung. That means, if you use different setup configurations in the devices, an update of the data record descriptions and list descriptions is necessary.

If you work with open channels please pay attention to the following:
If the connection between DLL and device was interrupted, this should be trapped with an error processing in this way (see also 1.2 Exemplary program structure).

1.5     General information

The C-Compiler decorates the names indicated in the function prototypes. The sign "_" is placed in front of the name and the number of transmitted parameters (in length byte) is postpositioned, separated by an "@". Therefore the decorated names are also indicated, in addition to the function prototype. When using Visual Basic or Delphi they are necessary e.g. for import.

When working with the DLL it might be helpful to use the tool "Depends" or "Dependency Walker". That way all functions, available in the DLL, and the expected parameter bytes can be displayed. This tool is provided with the Visual Studio 6.0. For each function this export is displayed beneath.

The file DFComDll.lib has to be registered in the project settings (under the options "Link" in Visual C++ projects under the object / library modules) and to be logged on the project directory (or on the path set under Settings) when compiling the project. The header file of the example code can be used when programming in C++. We also provide a module with the necessary export indications for Visual Basic.

1.5.1     Lists of the setup

Buffer management of the lists

Each channel manages its own buffer for 20 possible lists. For each list to be imported a dynamic buffer (according to its size) is reserved. All the reserved buffers are released to the relevant channel via the function DFCClrListenBuffer.

Caution: 
Please note, that MasterIV devices use a flash memory. According to the producer each buffer block (512 byte) can be written on at most 100.000 times. The firmware of the devices distributes the charge of access to the single buffer blocks and marks internally defect blocks. Despite this security mechanism we recommend to avoid immoderate transmissions of the list data. The application should primarily be used to transmit the lists in case of alternations, not cyclically or permanently.
Transmitting lists

The processing takes place in two steps. At first the buffer (DLL internal) is filled with list data by calling up the function DFCMakeListe for each list. Then these data are transmitted to the device via the function DFCLoadListen. Please note, that all lists, defined in the setup, are transmitted to the DLL buffer in succession via the function DFCMakeListe. By calling up the function DFCLoadListen all lists, imported before, are transmitted consecutively and the corresponding old lists are deleted in the device automatically.

Caution: 
It might be necessary to keep a waiting time between the single list transmissions. See also paragraph: Description of the application of lists.
Transmitting single lists

In order to transmit a single list you have to import it via DFCMakeListe and then to transmit it via DFCLoadListen. This function always transmits all lists imported before, whether you are transmitting a single list or several ones.

Caution: 
If you work with the MasterIV series, please note, that loading single lists is possible only from firmware states >= 04.01.00 on. With AE+++ always all lists have to be transmitted, loading single lists is impossible.
Caution: 
It might be necessary to keep a waiting time between the single list transmissions. See also paragraph: Description of the application of lists.
Deleting lists

It is impossible to delete single lists completely. That only takes place after the transmission of a setup file. By calling up the function DFCMakeListe (number of data records 0) the list in the DLL is imported as empty list and then transmitted via the function DFCLoadListen.

Description of the application of lists

Description of how the list application of the firmware works. The list application of the setup is a bit differing, depending on the selected operating mode "Normal, MDE" or "PZE Mode 1,2".

Lists for the operating mode "Normal, MDE"

After transmitting one or several lists, these are applied to the following situations:

Lists for the operating mode "PZE Mode 1, 2"

In addition to the situations of the operating mode "Normal, MDE" (which are also valid in this case) there is an adjustable keypad timeout. If the device is not operated within the set keypad timeout, the device runs through the main menu necessarily and thereby the list data are transmitted.

Lists for access control

After transmitting one or several access lists, the access control is stopped and the list data are applied to the system. Afterwards the access control is resumed.

Lists for Timeboys

After transmitting one or several lists for Timeboys, these are applied immediately – provided that there is no active transmission of the available lists to a Timeboy. In that case the current transmission is finished, before the new list data are applied.

AEIII+ and MasterIV firmware versions < 04.01.00

Here all defined lists of the setup always have to be imported and transmitted. The DLL internal buffer is carried out separately for each "ComNum". Therefore also the list data have to be established separately for each used "ComNum".

If several devices, which need different lists, are connected to one "ComNum", these list data have to be reloaded to the DLL buffer before the transmission to the appropriate bus number (whose device has a differing list structure) can be started.

Process of Loading lists:

Testing software for the lists, enclosed in the following files: 

The testing list contains of 3 names: Mueller, Maier and Schmidt with the personnel numbers: 101, 102 and 103.

1.5.2     Data types

In general the data types are used unsigned.
The following data types are used:

Type Description
int Whole number 4 byte.
char One sign is equivalent to one byte.
int* Pointer on an int. Contains 4 byte.
char* Pointer on a sign (array). Contains 4 byte.
unsigned char* Pointer on a data byte (array). Contains 4 byte.

1.5.3     Errors

Most of the functions display an error logging about the error argument, after you have failed with an "if (DFCxxx == 0)" query. The following errors may occur with these error parameters:

Nummer
(in Var. "Error") 
Meaning
0 No error indicated.
1 Incorrect CRC (check sum) of data.
2 Serial interface cannot be opened, e.g. allocated by another program or channel.
3 The channel for the necessary communication has not yet been opened.
4 General error of communication with AEIII+ / MasterIV.
5 AEIII+ / MasterIV does not answer the query.
6 Error at sending.
7 Error at receiving.
8 Response of incorrect device or of no sense in context.
9 Invalid bus number. Range of value: (1 – 31, 254)
10 Channel object not available. Channel object not contrivable. Range of value: (1 – 250)
11 Opening a file is failed. In general not existent.
12 Incorrect format of the setup data. Often relating to the setup.
13 Error at processing the list data.
14 Incompatible firmware version of the device to be activated.
15 There are still some data records available in the device, which would become unusable.
16 Instruction execution was aborted by the user.
17 No data record description loaded to the relevant channel.
18 No list description loaded to the relevant channel.
19 Error at programming the flash, firmware.
20 Function parameters out of their validity range.
21 Global Variable not defined.
22 Query although there are no data.
23 Duplicates of data records trapped.
24 Device file incompatible with Bootloader version.
25 Firmware file incompatible with Bootloader version.
26 Value of a variable could not be set.
27 Function not available in the present case.
28 Error of the application layer at instruction execution. (Command was transmitted successfully from the device to the DLL, but the requested execution could not take place, e.g. the device does not support the requested function or is not ready to carry out the function at that moment.)
29 Unidentified device type. Software update required.
30 The indicated device file does not correspond to the present hardware. Or, there is no corresponding device file available in the ZIP archive for the present hardware. Used with DFCUpdate.
31 Incorrect device type, e.g. tried input of setup file for PZE-MasterIV to BDE-MasterIV.
32 Present file extension is not supported.
33 Undefined table name or column name.
34 A set handle is invalid.
35 The filter to be used would not deliver data records.
36 Jump turned to the base of the table (Base of File).
37 Jump turned to the end of the table (End of File).
38 Set value is incorrect.
39 Access control is deactivated.
40 Memory overflow during a data transmission.
41 No data available.
42 Command was transmitted, but there is an error in the data.
43 The activated module is blocked by another process at that time.
44 Error of loading an XML file.
45 Unknown elements in an XML file.
46 Incorrect data content of an XML file.
47 Error of applying or using the data.
48 Allocate memory fail.
49 This version of firmware file are to actual for routine.
50 Prozessing of file data fail.
51 This firmware file don't support current device. Or: No firmware file for device support found.
52 Fail to load firmware file (archive).
53 Active Connection is started.
54 Active Connection is stopped.
55 Listen socket is in use.
56 Active Report of records is deaktivated.
57 Common Error by start Active Connection.
58 Wrong password. Password needed.
59 Exceeded trie count for password setting. Device is locked for 60 seconds.
60 Fail to write in file.
61 Fail to read out file.
62 Data fail. Check of Data per CRC result in wrong value.
63 No more memory available. For example: Maximum count of finger templates reached.
64 Data in file are wrong. For example: Data in file are finger templates for type Idencom-Compact, but needed is DIN.
65 No more flash memory available.
66 Module is not available in Device.
67 In the Setup file extensions are used, which require a newer firmware version.
68 The task to be executed is not supported by the present firmware version.
69 The task to be executed is not supported by these devices configuration.
77 The addressed Timeboy is no model of MasterIV series.
80 The setup file assumes a not reached the minimum version of the DFComDLL.
81 The setup file requires a not reached target version of DFComDLL.
82 The setup file is not supported by the present firmware version 04.01.xx.
83 The setup file assumes a not reached the minimum version of the firmware 04.01.xx.
84 The setup file assumes a not reached, but recommend version of the firmware 04.01.xx.
85 The setup file is not supported by the present firmware version 04.02.xx.
86 The setup file requires a not reached minimum version of firmware 04.02.xx.
87 The setup file assumes a not reached, but recommend version of the firmware 04.02.xx.
88 The device requires an Encrypted communication. The communication password must be set. (DFCSetCommunicationPassword).

1.5.4     Background logging

There is a log mechanism for background logging installed in the DLL, which writes all function calls on files (default: YYYY_MM_DD_DFComDLL_ChannelID.log), logged on a created folder (by default: DFComLog). This background logging is activated by default and can be controlled via the initialisation file "DFCom.ini". The last successive fife days of use are recorded. These data cover a data volume of about . 300 MB on average.

Structure of the log entries
Via the file name date and channel are known. The time of the function call is the first logged information; at next the name of the function with the parameter values transmitted in each case, separated by a tab stop. The last information is the return value (if available) in brackets. For parameters, released via pointers (e.g. error object or data buffer), the transmitted values (not the address!) are always written down. If there are no values available, the tab stops are delivered nevertheless, so that it is possible to use this file for further processing. After setting the elapse key the duration of execution is displayed in squared brackets, indicating the time, the DLL function needs to work through the command (depending on the used interface timeout).
 Example: 2007_02_05_DFComDLL_1.log
11:14:57	DFCComOpenSerial	1	COM1	38400	150	(1) [0.1]
Initialisation file
File name to be used: DFCom.ini

Meaning of the values: 0=Off, 1=On
Meaning of the key values in the section Log:

 Example:
[Log]
Enable=1
Path=.\
Folder=DFComLog
Erase=1
Elapse=0
List=0

1.5.5     Setting the time

The clock of the terminal should be set regularly to avoid deviations, particularly if several terminals are used. We recommend setting the clock at least once a day. The optimum point in time is 4:00 am, because that is also the time of clock change.
The firmware versions < 04.00.23 do not possess an automatic clock change. For this an application is necessary. Possibly the automatic clock change of the operating system has to be activated. Please use the function DFCComSetTime for setting the clock.

1.5.6     Transmission of Timeboy lists

 Caution: 
This feature is only valid from MasterIV firmware version 04.01.04 on and for TimeboyIII devices. Furthermore your MasterIV device has to be equipped with the option to activate Timeboy devices. The memory requirement of the Timeboy lists reduces the memory capacity for the MasterIV lists.
GroupID

That is the number logged on the Timeboy. By default it is set to 0, optionally it can be set via the TbSetup. Timeboys can be subdivided into groups with the help of these numbers and via the DLL functions they can be provided with separate lists.
Example for explanation:
Problem: You use three Timeboys equipped with the same setup. Now you want to input an own order list to each Timeboy. Solution: You define an clear GroupID for each Timeboy and transmit the lists, valid for all devices, with the GroupID 0 and the order list, relevant for only one Timeboy, with its GroupID.

1.5.7     Transmission of device data (DFCUpload)

 Please note for PZE-MasterIV 
In order to carry out an update from a firmware version lower 04.00.23.769 to a version >= 04.01.xx, you have to input a version of the series 04.00 >= 04.00.769 first. A downgrade of the version series 04.01 (or higher) to the version series 04.00 has to be checked first (because of possible incompatibilities to the used hardware) and, if possible, to be avoided .
Inputting a firmware version of the series 04.00 must take place to PZE-MasterIV with a revision 2.0. You may find the revision on the type label; if it is 2.0, it is missed behind the device name. In the example on the left the revision is framed in red.
 Please note the following for updating via the device file archive (*.dfz). 
By now the following options can be added by the user:
  • External reader series (PHG or Datafox).
  • IOModule connected to device.
  • Timeboy connected to device.
  • Keep present setup and lists after firmware update (only Mobil-MasterIV).
These information are (if available) drawn on by the update routine to select the desired device file from the device file archive (*dfz).

These settings are assumed by the DLL, if the options are not defined in the device:
  • External reader series: Datafox
  • IOModule connected to device: No
  • Timeboy connected to device: Mobil-MasterIV: Yes. Otherwise: No.
  • Keep present setup and lists after firmware update. (only Mobil-MasterIV): No
When updating via the DatafoxStudioIV you are requested automatically to set the options, if they are not defined. When updating via the DLL, the default settings (listed above) are used. Changing the options is possible via the DatafoxStudioIV.
 General hints for all MasterIV devices 
The switch-over to the Bootloader mode is explained in the appropriate manual.
In the Bootloader mode the device uses the communication type RS232 (fixed).
After inputting a firmware version via the Bootloader mode its communication type is used. After restarting, the "old" communication type (used before switching over to the Bootloader mode) is used.
A downgrade has to be carried out via the Bootloader mode on principal.
After inputting a firmware version via GSM / GPRS the device redials with the remote access data used before. These do not get lost while inputting a firmware version.
Setup file and list data have to be transmitted anew after each input of a firmware version. Exception: Mobil-MasterIV with a version >= 04.01.53 and a set option to keep the data.
 Common problems and their correction 
After transmitting a firmware version no texts and graphics are displayed (for devices with display). Please transmit the same firmware version again.

1.5.8     IP address and hostname

Notation of an IP address (point notation):
IP-AdresseDescription
"4.3.2.16"Decimal notation
"004.003.002.020"Octal notation
"0x4.0x3.0x2.0x10"Hexadecimal notation
"4.003.002.0x10"Mix
Please note, that leading zeros lead to an octal notation!!

Notation of hostnames, e.g. www.datafox.de

1.6     Active Connection

1.6.1     Introduction

In the following paragraph there is explained how the concept of the "Active Connection" works and how it can be used. We relate to the version 4.1.5 of the firmware, DFComDLL and DatafoxStudioIV.

1.6.2     Rough overview

At the "Active Connection" the devices establish a connection to the DLL. This connection persists the whole runtime and is ensured via Alive Pings. That means, the devices re-establish the connection automatically in case of a connection abort or interruption.

Each established "Active Connection" has a clear channel number available, which can be queried via the appropriate DLL functions. By using this channel number each DLL function can be carried out as normal. The current bus number is always 254 in that case.

In addition to the "Active Connection" an "Active Data Record Message" can be configured. In that case the devices deliver a message to the DLL, whether there are data records available.

1.6.3    Short comparison of the instruction execution without and with "Active Connection"

DLL without "Active Connection"

  1. Call up DFCComOpenIV for the connection establishment
  2. Carry out the desired command, e.g. DFCGetSeriennummer
  3. Call up DFCComClose for the disconnection
DLL with "Active Connection"
  1. Call up DFCGetFirstActiveChannelID, DFCGetNextActiveChannelID, DFCGetInfoActiveChannel for the device detection,
  2. Carry out the desired command, e.g. DFCGetSeriennummer

1.6.4     4 Start, stop and initialisation of the "Active Connection"

The DLL module for the "Active Connection" is started via the DLL function DFCStartActiveConnection. Then the DLL creates a list socket, which the devices can request for connection. Via DFCStopActiveConnection the DLL module for the "Active Connection" is stopped. All established connections are disconnected then.

Within the device the activation / deactivation takes place via the system variable COM.ACTIVE.

The connection data, to be logged on the device, can be set via system variables. You may find a list of all necessary system variables for the prefix COM in chapter 4.7.

System variables can be set or rather read via the function DFCSetGlobVar and DFCGetGlobVar.

The system variables for the prefix COM can be set via the DatafoxStudioIV. For this please note the according dialogue under "Communication -> Active Connection – Configuration".

1.6.5     Messaging of data records

By default the messaging of data records after starting the "Active Connection" (via DFCStartActiveConnection) is activated. Therefore the DLL processes all messages of the devices. By calling up the function DFCSetRecordAvailable this message processing of the DLL can be activated / deactivated.

Within the device the activation / deactivation takes place via the system variable COM.NOTIFY.

If there is at least one data record available in the device, it is messaged to the DLL automatically via the device. The message is enqueued to a priority queue of the DLL and can be called up via the function DFCRecordAvailable. Via this function call the "Active Channel Number" is delivered (amongst others). Furthermore it can be used to query data records by calling up DFCReadRecords.

1.6.6     Bringing into service and checking

Both Active Connection and messaging data records can be checked and brought into service via the DatafoxStudioIV. For this an own communication point is available under "Communication -> Settings". Please note, that an Active Channel has to be selected before carrying out a communication to a device.

2.0     Exported functions

The following functions are provided by the DLL.

2.1     General functions

Basic functions for connection establishment and communication, as well as for logging the connection process.

2.1.1.1     DFCComInit ( RS232 / RS 485 )

 Caution: 
This function is exclusive for the AEIII+.
Because of the used timeout it cannot be used for modem connections.
Calls up the function DFCComOpenSerial internally.
Supported from firmware version on:
Infinite
Declaration: 
extern "C" __declspec(dllexport)
int __stdcall DFCComInit(int iChannelNum);

Exported: _DFCComInit@4
Parameters: 
int iChannelNum Channel to be initialised (of the interface COM1, COM2, …) is used according to its number.
Return value: 
0 Error at initialising (see also: Error processing and Exemplary program structure).
1 Interface initialised
Description: 
Initialises the serial interface ("COM1" - "COM4" oder "/dev/ttyS0" - "/dev/ttyS3") via: DFCComOpenSerial(iChannelNum, szCom, 38400, 150). (Explanation: szCom = "COM1" , etc.). When using RS232 or rather RS485 the function has to be called up successfully, before you can work with the communication functions. From DLL version 04.01.00 on the default timeout was increased from 150 up to 800.

 

2.1.1.2     DFCComOpenSerial ( RS232 / RS 485 )

 Caution: 
This function is exclusive for the AEIII+.
Supported from firmware version on:
Infinite
Declaration: 
extern "C" __declspec(dllexport) 
int __stdcall DFCComOpenSerial(int iChannelNum, char *szComPort, 
int iBaudRate, int iTimeOut);

Exported: _DFCComOpenSerial@16
Parameters: 
int iChannelNum Channel to be initialised. Range of value: (1 - 250)
char *szComPort String for the interface. "COM1" .. "COM4", "/dev/ttyS0" .. "/dev/ttyS3"
int iBaudRate Transfer rate of the interface in Baud. (presetting: 38400bd)
int iTimeOut TimeOut for the reading of the interface in milliseconds. (presetting: 800ms). At least 1500ms recommended for modem.
Return value: 
0 Error at initialising (see also Error processing and Exemplary program structure)
1 Interface initialised
Description: 
Initialises the channel for the serial interface (COM1 – COM4). When using RS232 or rather RS485 the function has to be called up successfully, before you can work with the communication functions.

 

2.1.1.3     DFCComOpen ( TCP/IP )

 Caution: 
This function is exclusive for the AEIII+. After a connection abort no automatic reconnection is carried out. In that case please note the Error processing and solution explained under Exemplary program structure.
Calls up the function DFCComOpenSocket internally.
Supported from firmware version on:
Infinite
Declaration: 
extern "C" __declspec(dllexport)
int __stdcall DFCComOpen(int iChannelNum, char *szHost);

Exported: _DFCComOpen@8
Parameters: 
int iChannelNum Channel number. Range of value: (1 - 250) The channel number is used to identify the TCP/IP connection in case of further commands. If you use RS232 connections at the same time, the number must not coincide with another communication number in use. Example: In a server COM1: and COM2: are used. For the TCP/IP connections you should use the numbers 3, 4, 5, … 10 then.
char *szHost IP address (e.g. "192.168.123.99") or hostname.
Return value: 
0 Error at initialising (see also Error processing and Exemplary program structure)
1 Interface initialised.
Description: 
Initialises the channel for the Socket (TCP / IP) interface to the Com – server via: DFCComOpenSocket(iChannelNum, szHost, 8000, 3000). When using TCP / IP the function has to be called up successfully, before you can work with the communication functions. From the DLL version 04.01.00 on the default timeout was increased from 3000 to 5000.

 

2.1.1.4     DFCComOpenSocket ( TCP/IP )

 Caution: 
This function is exclusive for the AEIII+.
After a connection abort no automatic reconnection is carried out. In that case please note the Error processing and solution explained under Exemplary program structure.
Supported from firmware version on:
Infinite
Declaration: 
extern "C" __declspec(dllexport) 
int __stdcall DFCComOpenSocket(int iChannelNum, char *szRemoteIP, 
int iPortNum, int iTimeOut);

Exported: _DFCComOpenSocket@16
Parameters: 
int iChannelNum Channel number. Range of value: (1 - 250) The channel number is used to identify the TCP/IP connection in case of further commands. If you use RS232 connections at the same time, the number must not coincide with another communication number in use. Example: In a server COM1: and COM2: are used. For the TCP/IP connections you should use the numbers 3, 4, 5, … 10 then.
char *szRemoteIP IP address (point notation) or hostname.
int iPortNum Port number of the COM - Server. W&T-Standard: 8000
int iTimeOut TimeOut for reading the interface in milliseconds (presetting: 5000ms)
Return value: 
0 Error at initialising (see also Error processing and Exemplary program structure)
1 Interface initialised.
Description: 
Initialises the channel for the Socket (TCP / IP) interface to the Com server. When using TCP / IP the function has to be called up successfully, before you can work with the communication functions.

 

2.1.2     DFCComOpenIV ( RS232 / RS 485 / Funk( BIM2 ) / TCP-IP )

 Caution: 
This function is exclusive for the MasterIV series. After a connection abort no automatic reconnection is carried out. In that case please note the Error processing and the solution explained under Exemplary program structure. The function initialises the channel to be used with a Multimaster protocol. For that reason you cannot use an AEIII+ and a MasterIV in one and the same RS485 network, because the AEIII+ works with a protocol, which is incompatible with the MasterIV!
Supported from firmware version on:
04.00.00
Declaration: 
extern "C" __declspec(dllexport) 
int __stdcall DFCComOpenIV(int iChannelNum, int iBusNum, int iType, 
char *szComString, int iComValue, int iComTimeOut);

Exported: _DFCComOpenIV@24
Parameters: 
int iChannelNum Channel to be initialised. Range of value: (1 - 250)
int iBusNum Bus number of the DLL. Multimaster approach: The DLL is a communication member like all the other devices and can be activated by these ones directly. The bus number has to be clear within the network and must not coincide with another one's. Range of value: (1 - 31, 254)
int iType Type of interface to be used.
ValueMeaning
1RS232 directly or via converter (RS232 <-> RS485)
2Radio communication via converter (RS232 <-> BIM2) without own controller.
3TCP / IP connection.
char *szComString Depending on the type of interface:
iTypeMeaning
1, 2Pointer on the string for the interface.
3Pointer on the string with IP address or hostname.
int iComValue Depending on the type of interface:
iTypeMeaning
1, 2Transfer rate of the interface in milliseconds. (presetting: 38400bd)
3Port number of the TCP / IP interface. (presetting: 8000)
int iComTimeOut Depending on the type of interface:
iTypeMeaning
1, 2Timeout for reading the interface in milliseconds (presetting: 800ms) At least 1500ms recommended for modem.
3Timeout for reading the Socket in milliseconds. (presetting: 5000ms)
Return value: 
0 Error at initialising (see also Error processing and Exemplary program structure)
1 Interface initialised.
Description: 
Initialises the channel. Depending on the indicated type a different initialisation process is used, to convert following function calls according to the exported functions correctly. The function has to be called up successfully, before you can work with the communication functions. Caution: After a connection abort (TCP / IP) no automatic reconnection is carried out. In that case please note the Error processing and the solution explained under Exemplary program structure.

 

2.1.3     DFCComClose

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCComClose(int iChannelNum);

Exported: _DFCComClose@4
Parameters: 
int iChannelNum Channel to be closed. Range of value: (1 - 250)
Return value: 
No (see also Error processing and Exemplary program structure)
Description: 
Closes the channel of the serial interface or rather of the TCP / IP connection.

 

2.1.4.1     DFCCheckAE

Calls up the function DFCCheckDevice internally.
Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCCheckAE(int iChannelNum, int iBusNum);

Exported: _DFCCheckAE@8
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
Return value: 
0 Error at execution. No device with this bus number available. (see also Error processing and Exemplary program structure)
1 Set bus number is available.
Description:
Checks whether the device is connected to the bus. This function uses the DFCCheckDevice function.

 

2.1.4.2     DFCCheckDevice

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCCheckDevice(int iChannelNum, int iBusNum, 
int *piError, int iDevicePollRetry);

Exported: _DFCCheckDevice@16
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int *piError Error contains an error number according to table 1.5.3.
int iDevicePollRetry Repetitions for availability.
Return value: 
0 Error at execution. No device with this bus number available, the error code keeps its value transmitted before. (see also Error processing and Exemplary program structure)
1 Set bus number is available.
Description:
Check whether the device is connected to the bus.

 

2.1.5     DFCComSetTime

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCComSetTime(int iChannelNum, int iBusNum,
unsigned char *pucDateTime);

Exported: _DFCComSetTime@12
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250))
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
unsigned char *pucDateTime Pointer on the DateTime field of 7 byte. Exact structure, see: Date and time in the byte array. If you use a DLL with a version number higher than 2.0.7, you can transmit NULL (value: 0) here. That way the routine uses the current system date and the current system time.
Return value: 
0 Error at setting the time.
1 Time set successfully.
Description: 
Sets date and time of the device.
 Beispiel:
27.02.1981 15:30:13
0 Date hundreds (0..255) 19
1 Date ones (0..99) 81
2 Month (0..12) 2
3 Day (1..31) 27
4 Hour (0..23) 15
5 Minute (0..59) 30
6 Second (0..59) 13
// Of course the interface to the device 
// has to be opened.
unsigned char Buffer[7];

Buffer[0] = 19;
Buffer[1] = 81;
Buffer[2] = 2;
Buffer[3] = 27; // 27.02.1981 Date
Buffer[4] = 15;
Buffer[5] = 30;
Buffer[6] = 13; // 15:30:13 Time

// Errors are not pointed out here !!! (see Return value)
// Send the DateTime - array 
// via channel 1 to the device with the bus number 2
DFCComSetTime(1, 2, Buffer);

 

2.1.6     DFCComGetTime

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCComGetTime(int iChannelNum, int iBusNum,
unsigned char *pucDateTime);

Exported: _DFCComGetTime@12
Parameters: 
int iChannelNum  Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
unsigned char *pucDateTime Pointer on a field of 7 byte, which date and time are written on. Exact structure: see Date and time in the byte array.
Return value: 
0 Error at reading the time.
1 Time read successfully and logged to the field "Time".
Description: 
Reads date and time of the device.
Beispiel:
27.2.1981 15:30:13
0 Date hundreds (0..255) 19
1 Date ones (0..99) 81
2 Month (0..12) 2
3 Day (1..31)  27
4 Hour (0..23) 15
5 Minute (0..59) 30
6 Second (0..59) 13
// Of course the interface to the device
// has to be opened.
unsigned char Buffer[7];
Buffer[0] = 19;
Buffer[1] = 81;
Buffer[2] = 2;
Buffer[3] = 27; // 27.02.1981 Date
Buffer[4] = 15;
Buffer[5] = 30;
Buffer[6] = 13; // 15:30:13 Time

// Establish current date and time via channel 1 of the device
// with the bus number 2.
// Errors are not pointed out here !!! (see Return value)
DFCComGetTime(1, 2, Buffer); 

// Deliver data.
printf("Year: %02d%02d\n", Buffer[0], Buffer[1]);
printf("Month: %02d\n",    Buffer[2]);
printf("Day: %02d\n",      Buffer[3]);
printf("Hour: %02d\n",   Buffer[4]);
printf("Minute: %02d\n",   Buffer[5]);
printf("Second: %02d\n",  Buffer[6]); 

 

2.1.7     DFCComSendMessage

 Caution: 
In the following the entry about "Freigabe: 12.11.04, Firmwareversion 04.00.22 aus dem Dokument PZE-MasterIV, SoftwareVersionen Stand 2004-12-02.pdf"
  • The SendMessage function at online mode was revised. After collecting from the server "online" a message of the server is awaited. If no message shall be sent, a dummy message (display duration: 0 second) has to be sent. Otherwise an error message is displayed to the user on the terminal. SendMessage for the online mode was released from this version on.
Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCComSendMessage(int iChannelNum, int iBusNum,
unsigned char ucDelayTime, unsigned char ucAction,
unsigned char ucAudio, char *szMessage, int iLength);

Exported: _DFCComSendMessage@28
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum  Bus number to be used. Range of value: (1 - 31, 254)
unsigned char ucDelayTime Duration of the message display in seconds. For AEIII+: By transmitting 255 the message can be displayed until a user confirms it via Enter or ESC. AEIII+ range (1 – 255) AEIV range (0 – 254)
unsigned char ucAction
ValueMeaning
0Continuing as usually
unsigned char ucAudio
SymbolMeaning
+50ms Sound on
-50ms Silent
ValueTone sequence
0
-                 Off
1
++++++++          Ok
2
+++++-----+++++   Error
3
+++++
4
++--+++++
5
++--++
6
+++++--+++++
7
++--++--++
8
+++++--+++++--+++++
9
++--+++++--++
10
+++++--++--+++++
11
+
12
+-+
13
+-+-+
14
++++++++++++++++
15
++++++++--------++++++++--------++++++++
char *szMessage Pointer on the string to be displayed.
int iLength Sign length of the message. At most 242. (PZE-MasterIV, see description)
Return value: 
0 Error at sending.
1 Message sent successfully.
Description: 
Sends a message to the device with the set bus number. The message can be used as optical confirmation of the entered user data at online mode. Because the message is integrated to the device operation, it is available by the next input at the latest.

Only AEIII+
The AEIII+ can display at most 19 characters each line, because the 20th is reserved for the status ticker. Please note, that special characters and mutated vowels cannot be displayed correctly because of the preallocated character set. If you want to include a word-wrap, you have to fill the display line with 19 space characters. That way an automatic word-wrap to the next line is reached. The message display while the device is within an input chain, is possible from the firmware with the major version >= 2 on.

Only MasterIV
Word-wraps have to be pasted via the sign (Dec. 13). Because of the proportional character set the number of characters each line is depending on the line content and the line is cut in case of a margin exceeding.
The sent character sequence subjects the following fragmentation:

Heading line 3\rHeading line 4\rBox heading\rBox line 1\rBox line 2 etc.
"\r" has to be replaced by a word-wrap (Dec. 13). If you do not wish a heading line, you have to paste a space character with successive word-wrap for each heading line, so that a fragmentation following the scheme above can take place. Displaying more than fife box lines is not yet supported by the firmware version 04.00.22. Furthermore the total number of characters (including zero-termination) within the box must not exceed 128.

Beispiel:
char *Buffer = "HELLO WORLD !";

DFCComSendMessage(1, 254, 255, 0, 2, Buffer, 26);

 

2.1.8     DFCComSendInfotext

Supported from firmware version on:
02.02.00, 03.01.00, BDE.04.01.02, MDE.04.01.02
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCComSendInfotext(int iChannelNum, int iBusNum,
char *szMessage, int iLength);

Exported: _DFCComSendInfotext@16
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
char *szMessage Pointer on the string to be displayed.
int iLength String length of the message. At most 242.
Return value:
0 Error at sending.
1 Message sent successfully.
Description:
Sends an info text to the device of the set bus number. The info text is logged on the buffer of the device and is therefore always available. It can be reached out of the main menu via the left arrow key. Reaching the info display is blocked in the PZE mode, because of the input fixing for the first entries in the main menu (F1 / F2). Therefore the info picture cannot be used in the PZE mode meaningfully. The AEIII+ can display at most 19 characters each line, because the 20th is reserved for the status ticker. Please note, that special characters and mutated vowels cannot be displayed correctly because of the preallocated character set. If you want to include a word-wrap, you have to fill the display line with 19 space characters. That way an automatic word-wrap to the next line is reached.
Beispiel:
char *Buffer = "HELLO WORLD !";

DFCComSendInfotext(1, 254, Buffer, 26);

 

2.1.9     DFCGetSeriennummer

Supported from firmware version on:
02.02.00, 03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetSeriennummer(int iChannelNum, int iBusNum,
int *piError, int *piSerialNum); 

Exported: _DFCGetSeriennummer@16
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int *piError Error contains an error number according to table 1.5.3.
int *piSerialNum Pointer on the variable which contains the serial number.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description: 
Reads the serial numbers of the activated device.

 

2.1.10.1     DFCLogOn

Of no further use.

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCLogOn(char *szFileName);

Exported: _DFCLogOn@4
Parameters: 
char* szFileName String with file name of the log file (including path).
Return value: 
0 Function not implemented.
Description: 
The implementation was deleted!!! Please convert to DFCSetLogOn.

 

2.1.10.2     DFCSetLogOn

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCSetLogOn(int iChannelNum);

Exported: _DFCSetLogOn@4
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250).
Return value: 
No
Description: 
Logging function is activated and log file is opened. All data, read out of the device, are saved binary. Before the data bytes are saved, a byte with the number of data bytes is saved. This byte is not counted. Example: A data record contains 20 byte. The prepended byte has the value 20. The total number of saved bytes for this data record (including the length byte) is 21. Afore you have to name the file via DFCSetLogFileName.

 

2.1.11.1     DFCLogOff

 Of no further use. 

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCLogOff(void);

Exported: _DFCLogOff@0
Parameters: 
No  
Return value: 
No  
Description: 
Implementation was deleted!!! Please convert to DFCSetLogOff.

 

2.1.11.2     DFCSetLogOff

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCSetLogOff(int iChannelNum);

Exported: _DFCSetLogOff@4
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
Return value: 
No  
Description: 
Logging function is switched of for the set channel.

 

2.1.12     DFCSetCallBack

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCSetCallBack(int iChannelNum, int (*CBFunction)());

Exported: _DFCSetCallBack@8
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int (*CBFunction)() Pointer on the function,that shall be opened.
Return valueMeaning
0Instruction execution is aborted.
1Command is still processed.
Return value: 
No  
Description: 
With the help of a CallBack function there is the possibility to realise a progress display. The CallBack function, transmitted to the DLL via this function, is accessed cyclically when transmitting major data blocks. Via the returned value e.g. the transmission of a setup file or a device file (firmware) can be terminated. Calling up this function does not give any information about the data amount to be transmitted, in order to calculate with percentages.

 

2.1.13     DFCSetLogFileName

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCSetLogFileName(int iChannelNum, 
const unsigned char *szLogFileName);

Exported: _DFCSetLogFileName@8
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
const unsigned char *szLogFileName File to be used for logging.
Return value: 
No  
Description: 
Sets the file for the logging function in the relevant channel.

 

2.1.14     DFCGetErrorText

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCGetErrorText(int iChannelNum, int iError, 
int iLanguage, char *szText, int iLength);

Exported: _DFCGetErrorText@20
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iError Error code, which is returned by most of the parameters.
int iLanguage Not yet in use. Everything in German.
char *szText Pointer on the usable string.
int iLength Length of the reserved buffer on the string.
Return value: 
No  
Description: 
Converts the error number, returned by different functions, according to table 1.5.3.

 

2.1.15     DFCSetGlobVar

Supported from firmware version on:
02.02.20, 03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetGlobVar(int iChannelNum, int iBusNum,
unsigned char *pucVar, int iType, unsigned char *pucValue, int *piError);

Exported: _DFCSetGlobVar@24
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
unsigned char *pucVar Name or number of the variable.
int iType
ValueMeaning
0pucVar shows the byte, which represents the variable number. Valid range: 1 – 8. In the AESetup on the page for the global variables this is in accordance with the placement 1 – 4 from top to down on the left side and 5 – 8 from top to down on the right one.
1pucVar shows the scheduled string, which represents the name. Upper and lower case are distinguished; a length of at most 16 ASCII characters is possible.
2pucVar shows the scheduled string, which represents the name of a system variable, e.g. "_MODEM_MC35i.PHONE". See also the chapter System variables.
unsigned char *pucValue Shows the scheduled string, which represents the value. With the supporting firmware at most 20 ASCII characters (major number 2) or rather 60 ASCII characters (major number 3) are possible.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Sets the value of a global variable.

 

2.1.16     DFCGetGlobVar

Supported from firmware version on:
02.02.20, 03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetGlobVar(int iChannelNum, int iBusNum,
unsigned char *pucVar, int iType, unsigned char *pucValue, 
int iValueLength, int *piError);

Exported: _DFCGetGlobVar@28
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
unsigned char *pucVar Name or number of the variable.
int iType
ValueMeaning
0pucVar shows the byte, which represents the variable number. Valid range: 1 – 8. In the AESetup on the page for the global variables this is in accordance with the placement 1 – 4 from top to down on the left side and 5 – 8 from top to down on the right one.
1pucVar shows the scheduled string, which represents the name. Upper and lower case are distinguished; a length of at most 16 ASCII characters is possible.
2pucVar shows the scheduled string, which represents the name of a system variable, e.g. "_MODEM_MC35i.PHONE". See also the chapter System variables.
unsigned char *pucValue If the execution was successful, the buffer contains the established string (indicated by the pointer) for the value of the variable. With the supported firmware at most 20 ASCII characters (major number 2) or rather 60 ASCII characters (major number 3) are possible.
int iValueLength Length of the reserved buffer, which is referred to via the pucValue. Please note, that the zero-termination is integrated into the value. That means, if you set a length of 1, an empty string is delivered, because no sufficient buffer range for the data is reserved.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Reads the value of a global variable.

 

2.1.17     DFCCloseRelay

Supported from firmware version on:
02.02.20, 03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCCloseRelay(int iChannelNum, int iBusNum, int iNum, 
int iTime, int *piError); 

Exported: _DFCCloseRelay@20
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int iNum Number of the relay to be activated. Number "1" switches the internal Open-Collector output. The range "1 – 8" is used for the four (42V) and the four (230V) relays of the IO module.
int iTime Time specification (in seconds), that the output (relay) shall be switched at (1 .. 65535).
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Closes an output or a relay for a definable period of time.

 

2.1.18     DFCGetRelayState

Supported from firmware version on:
02.02.20, 03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetRelayState(int iChannelNum, int iBusNum, int iNum, 
int *piState, int *piTime, int *piError);

Exported: _DFCGetRelayState@24
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int iNum Number of the relay to be activated. Number "1" switches the internal Open-Collector output. The range "1 – 8" is used for the four (42V) and the four (230V) relays of the IO module.
int *piState Contains the current relay state. "1" means closed.
int *piTime Residual time specification (in seconds), that the output (relay) shall be switched at (1 .. 65535).
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Reads the current state of an output or a relay.

 

2.1.19     DFCOpenRelay

Supported from firmware version on:
02.02.20, 03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCOpenRelay(int iChannelNum, int iBusNum, int iNum,
int *piError);

Exported: _DFCOpenRelay@16
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int iNum Number of the relay to be activated. Number "1" switches the internal Open-Collector output. The range "1 – 8" is used for the four (42V) and the four (230V) relays of the IO module.
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Opens an output or a relay.

 

2.1.20     DFCGetDevicePollRetry

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetDevicePollRetry(int iChannelNum);

Exported: _DFCGetDevicePollRetry@4
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
Return value: 
Anzahl Necessary number of tries for the DFCCheckDevice – default.
Description:
Via the function DFCCheckDevice a parameter is transmitted, which indicates the possible number of tries. This function delivers the number of necessary queries, until the function sends a confirmation message.

 

2.1.21     DFCGetComPort

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
HANDLE __stdcall DFCGetComPort(int iChannelNum);

Exported: _DFCGetComPort@4
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
Return value: 
Handle Interface handle (serial) or socket of the last channel initialisation. The value (-1 = INVALID_HANDLE_VALUE / INVALID_SOCKET) is delivered, if the return fails. In C the type HANDLE is equivalent to a pointer on void.
Description:
A use of this function is only necessary in case of a direct access to the interface, e.g. in case of a modem initialisation, when the connecting passage has to be established, before the other DLL functions can be used as usual. Please note: Via DFCComClose the DLL does not close any modem connections, that where opened before via AT commands. The returned HANDLE is exclusive for the interface, which was opened before, and it is valid during its existence.

 

2.1.22     DFCSetComPort

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetComPort(int iChannelNum, HANDLE hComPort, 
int iType, int iComValue, int iTimeOut);

Exported: _DFCSetComPort@20
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
HANDLE hComPort Interface handle (serial) or socket, that shall be set. In C the type HANDLE is equivalent to a pointer on void.
int iType The value indicates, which type of interface is available:
ValueMeaning
0DFCComOpenSerial, DFComInit
1DFCComOpenSocket, DFCComOpen
2DFCComOpenIV for serial connection.
3DFCComOpenIV for TCP/IP connection.
int iComValue For serial connections this parameter indicates the baud rate (presetting: 38400bd) and for TCP/IP connections it indicates the port number (presetting: 8000).
int iTimeOut This parameter indicates the interface timeout, that shall be used (in milliseconds). For serial connections you have to set 150ms by default, for TCP/IP 3000ms by default.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Using this function is necessary only in a few cases, e.g. to set another interface timeout, while the interface is already opened or to transfer a handle to the DLL, which was used elsewhere.

 

2.1.23     DFCWrite

 Caution: 
This function should be used only in special cases (e.g. modem initialisation)! If it is used incorrectly, bugs may occur.
Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCWrite(int iChannelNum, char *pBuf, int iLength,
int *piWriteLength, int *piError);

Exported: _DFCWrite@20
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
char *pBuf Pointer on the characters to be sent.
int iLength Number of characters, that shall be sent.
int *piWriteLength (Return) Number of sent characters.
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Writes the transmitted data on the channel, depending on the used interface.

 

2.1.24     DFCRead

 Caution: 
This function should be used only in special cases (e.g. modem initialisation)! If it is used incorrectly, bugs may occur.
Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCRead(int iChannelNum, char *pBuf, int iLength,
int *piReadLength, int *piError);

Exported: _DFCRead@20
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
char *pBuf Pointer on the character buffer for the characters to be received.
int iLength Number of characters to be read. (size character buffer)
int *piReadLength (Return) Number of read characters.
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Reads the data at issue out of the channel, depending on the used interface.
Hint:
 

It is important to check not only the value of the return parameter. Determining whether an error occurred is not possible without the returned error code. If there were no data to be read available (in case of a serial connection), the function delivers a return value of 1. But in case of a TCP/IP connection a return value of 0 is delivered, if there where no data available. For error processing we recommend to use the error code in principle (if 0an error occurred).

Connection Return value ReadLength Error State  Description
serial =1 =0 =0 Ok read successfully, number of read characters was 0
serial =1 >0 =0 OK read successfully, number of read characters was >=1
TCP/IP =0 =0 =0 Ok read successfully, number of read characters was 0
TCP/IP =1 >0 =0 Ok read successfully, number of read characters was >=1
serial
TCP/IP
=0 >=0 0 Error not read successfully, in ReadLength the number of characters are logged and in Buf the characters that were read until the error occurred.

!! Important: The relevant functions of the DLL for the Timeboy show the reversed characteristics, if there are no data to be read !!

 

 

 

2.1.25     DFCUpload

 Caution: 
Further information about transmitting device data (DFCUpload).
Supported from firmware version on:
04.00.08
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCUpload(int iChannelNum, int iBusNum, char *szFileName,
int *piError);

Exported: _DFCUpload@16
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
char *szFileName File name of the device or text data file, if necessary with path indication.
  1. Firmware with additional data (ending: *.hex), with archive (ending: *.dfz) Under Win32 a device file archive (ending: *.dfz/*.zip) can be set. Under Linux a directory with the contained device files (ending: *.hex) can be set.
  2. Text files of the firmware (ending: *.dfl)
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Transmits the necessary device data, which consist of character set-, graphic-, text-, "firmware" data etc. and which are delivered as a file (ending *.hex). Under Win32 the device data can also be logged on a zip archive. In that case the routine selects the device file (appropriate to the current hardware) out of the zip archive. Caution: Under Linux the zip archive has to be depacketised and the directory has to be set. Further information about transmitting device data (DFCUpload). Transmitting the text data to the firmware. The data are provided as a file with the ending *.dfl ([D]ata[f]ox [L]anguage). The file can only be created with the DatafoxStudioIV.

 

2.1.26     DFCGetVersionFirmware

Supported from firmware version on:
04.00.19, 03.01.21
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetVersionFirmware(int iChannelNum, int iBusNum,
char *szVersion, int *piError);

Exported: _DFCGetVersionFirmware@16
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
char *szVersion Pointer on the string for the version number. At least 32 characters.
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Reading the device software version in text format. e.g. 04.00.19

 

2.1.27     DFCGetVersionFirmwareFromFile

Supported from firmware version on:
04.00.23
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetVersionFirmwareFromFile(int iChannelNum, 
char *szFileName, char *szVersion, int *piError);

Exported: _DFCGetVersionFirmwareFromFile@16
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
char *szFileName File name of the device file, if necessary with path indication. ("Firmware" with additional data, ending: *.hex)
char *szVersion Pointer on the string for the version number. At least 32 characters.
int *piError Error contains an error number according to table 1.5.3. If a value of 1 is delivered, the checksum of the header or the contained firmware data are dissonant.
Return value: 
0 Error at execution.
>7 Number of characters copied to the buffer "szVersion".
Description:
Reads the device software version in text format, e.g. 04.00.23 directly out of the firmware file.

 

2.1.28     DFCGetInfo

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetInfo(int channelID, int deviceID, char *name, char *params, 
char *info, int *len, int *piError);

Exported: _DFCGetInfo@28
Parameters: 
int channeID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
char *name Name of the information to be accessed. (z.B. "ACCESS.MODULE")
The name consists of two components, connected via dot.
The first part indicates the range. The following character strings are available:
RangeDescription
ACCESSfor access control
FINGERPRINTfor fingerprint
USBHOSTfor USB-Host
The second part indicates the name of the component to be accessed. The following character strings are available:
RangeComponendDescription
ACCESSMODULEAccessmodule / -reader
FINGERPRINTMODULEFingerprint module firmware version
USBHOSTMODULEUSB-Host firmware version (e.g. "3.62-000VDAP").
char *params Pointer on the parameter list, which has to be indicated possibly, as character string. The single parameters have to be separated via a CR (decimal 13).
The parameter list to be indicated is structured as follows (according to the appropriate name):
NameParameterDescription
ACCESS.MODULE 1 Door module number according to the column "TM" of the access list "Reader". The value always has to contain 3 digits. You may find more detailed information in the manual in chapter "Access control 2".
2 Optional. Bus-Id for systemen with more than 1 access-bus. The first is assumed if not specified.
FINGERPRINT.MODULE 1empty
USBHOST.MODULE 1empty
char *info Pointer on the string for the information string. The single parts are separated via the functional character CR ('\r').


The information string for the ACCESS.MODULE is structured as follows:

ValuePositionDescription
State1Returns the current state of the module. You may find more detailed information in the manual in the sub-chapter "Status messages of the access control" under "Access control 2".
Name2Returns the designation of the activated module.
Firmware version3Returns the firmware version of the activated module.
.........
...nNot yet defined, but thinkable.
int *len As input: length of the reserved buffer, which the pointer *info refers to; as output: length of the transmitted string.
int *piError Error contains an error number according to table 1.5.3
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Reads the information of a given module. The returned information is delivered in a string, which can contain different information, depending on the queried module. If necessary, this information string has to be depacketised to its components for further processing (in that case the single parts have to be separated via CR (decimal 13) character.) Please note also, that the name consists of two components: the range designator (e.g. ACCESS to activate the access module) and the designation of the "Component" to be activated in this range. If you want to query e.g. information about the connected attendance clock on the door module with the bus number 2, you need both the "name" "ACCESS.MODULE\0" and the appropriate "params" parameter list "021\0". After successful execution of the function the delivered information are provided in the string, which refers to "info" (the symbol '\0' represents the zero-termination of the string).

 

2.1.29     DFCOpenComServerMode

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCOpenComServerMode(int channelID, int deviceID, char *comm, int baudRate, 
int byteSize, int parity, int stopBits, int flags,int timeoutToClose, int *error);

Exported: _DFCOpenComServerMode@40
Parameters: 
int channeID Channel to be used. Range of value: (1 - 250)
int deviceD Indicates the bus number. For the current implementation it always has to be set on 254, because the "transparent mode" is not allowed in an RS485 network.
char *comm Pointer on the string for the virtual COM port, that shall be opened
StringMeaning
COM5
DeviceInterface
BDE-MasterIVCOM3 (see manual)
Mobil-MasterIVCOM2 (see manual)
MDE-BoxIVCOM2 (see manual)
AE-MasterIVCOM2 (see manual)
Other devicesNot available.
COM6
DeviceInterface
PZE-MasterIVCOM1 (see manual)
ZK-MasterIVCOM1 (see manual)
BDE-MasterIVCOM2 (see manual)
Mobil-MasterIVCOM1 (see manual)
MDE-BoxIVCOM1 (see manual)
AE-MasterIVCOM1 (see manual)
Other devicesNot available.
int baudRate Baud rate of the interface to be used.
ValueMeaning
96009600bd
1920019200bd
3840038400bd
int byteSize Number of "bits per byte"of the interface to be used.
ValueMeaning
44 Bit
55 Bit
66 Bit
77 Bit
88 Bit (presetting)
int parity
ValueMeaning
0Do not carry out parity check. (presetting)
1Carry out parity check.
int stopBits Number of stop bits to be used.
ValueMeaning
01 Stop bit (presetting)
11,5 Stop bits
22 Stop bits
int flags Additional information to influence the Com-Server mode:
Bit No.Meaning
0After a buffer overflow the data transmission is switched off in both directions (in case of a set bit)
...Of no use. Please always 0.
int timeoutToClose Period of time, which the COM port is closed after, if no data transmission takes place.
ValueMeaning
0Not closed automatically.
1..255Closed automatically, if no data flow was available within the set time (in seconds).
int *error Error contains an error number according to table 1.5.3
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Activates an "transparent mode" in an activated device between the currently opened channel and a COM port of the device. After connecting a COM port of the device with the channel, it is possible e.g. to send a file to a connected CDC machine directly. That means, all following data are transmitted in 1:1 between the device-COM-port and the opened channel, only the command to close the "transparent mode" (DFCCloseComServerMode) is trapped.
In order to write data directly on the channel, the function DFCWrite is available; to read out return data (if necessary) the function DFCRead is available. Another option is to determine the DLL-won interface handle by using the function DFCGetComPort. That way you work with own writing/ reading routines, which can be connected to the Timeboy-DLL, if necessary.
note, that the device-internal buffer contains 51 byte for each communication direction. Therefore an overflow may occur if irregular transmission rates are used. E.g. if you transmit data via a TCP/IP interface (57600bd) to a COM port (9600bd), the total data flow has to be stopped each 512 byte for ca. 400ms.
An overflow is messaged via the function DFCCloseComServerMode.

 

2.1.30     DFCCloseComServerMode

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCCloseComServerMode(int channelID, int deviceID, int *error);

Exported: _DFCCloseComServerMode@12
Parameters: 
int channeID Channel to be used. Range of value: (1 - 250)
int deviceD Indicates the bus number. For the current implementation it has to be set to 254, because the "transparent mode" is not indented for an RS485 network.
int *error Error contains an error number according to table 1.5.3
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Deactivates the possibly set "transparent mode" of an activated device. See also the function DFCOpenComServerMode to open the connection. If a device-internal buffer overflow occurs during data transmission, the function returns the error code 40.

 

2.1.31     DFCIsChannelOpen

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCIsChannelOpen(int channelID);

Exported: _DFCIsChannelOpen@4
Parameters: 
int channeID Channel to be analysed. Range of value: (1 - 250)
Return value: 
-1 Channel object not exists.
0 Channel is not opened.
1 Channel is opened.
Description:
Checks whether the channel is opened. The function does not assure, that a connected device can also be activated.

 

2.1.32     DFCUploadModule

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCUploadModule(int iChannelNum, int iBusNum, int type, char *szFileName,
int *piError);

Exported: _DFCUploadModule@20
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int type Type of module to use.
0 -> Biokey3000.
char *szFileName File name for update file.
File extension by type = 0 must be *.upd.
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Transfer Update files for included devices in MasterIV device.

 

2.1.33     DFCGetOptionFirmware

Supported from firmware version on:
04.01.06
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetOptionFirmware(int channelID, int deviceID, int *mask, int *options,
int *error);

Exported: _DFCGetOptionFirmware@20
Parameters: 
int channeID Channel to be used. Range of value: (1 - 250)
int deviceD Bus number to be used. Range of value: (1 - 31, 254)
int *mask Mask witch options are valid.
ValueMeaning
0x00000001External Reader type
0x00000002IO-Modul connection support
0x00000004Timeboy connection support
0x00000008Com-Server support
0x00000010Menue to write values on tags
0x00000020Send Records over HTTP-Protocol support
0x00000040Support for Update Biokey Module
0x00000080Support for digital IO
int *options Current values for individual Options.
ValueMeaning
External Reader type0 = Datafox-TMR33, 1 = PHG (VOXIO, Relino,...)
IO-Modul connection support0 = No, 1 = Yes
Timeboy connection support0 = No, 1 = Yes
Com-Server support.0 = No, 1 = Yes
Menue to write values on tags.0 = No, 1 = Yes
Send Records over HTTP-Protocol support.0 = No, 1 = Yes
Support for Update Biokey Module.0 = No, 1 = Yes
Support for digital IO.0 = No, 1 = Yes
int *error Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Read actual settings.

 

2.1.34     DFCSetOptionFirmware

Supported from firmware version on:
04.01.06
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetOptionFirmware(int channelID, int deviceID, int mask, int options,
int *error);

Exported: _DFCSetOptionFirmware@20
Parameters: 
int channeID Channel to be used. Range of value: (1 - 250)
int deviceD Bus number to be used. Range of value: (1 - 31, 254)
int mask Mask whitch option to be set.
ValueMeaning
0x00000001External reader type
0x00000002IO-Modul connection support
0x00000004Timeboy connection support
0x00000008Com-Server support
0x00000010Menue to write value on tags
0x00000020Send Records over HTTP-Protocol support
0x00000040Support for Update Biokey Module
0x00000080Support for digital IO
int options flags for options to set.
WertBedeutung
External reader support0 = Datafox-TMR33, 1 = PHG (VOXIO, Relino,...)
IO-Modul connection support0 = No, 1 = Yes
Timeboy Anbindung0 = No, 1 = Yes
Com-Server Funktionalität.0 = No, 1 = Yes
Menue to write value on tags0 = No, 1 = Yes
Send Records over HTTP-Protocol support0 = No, 1 = Yes
Support for Update Biokey Module0 = No, 1 = Yes
Support for digital IO0 = No, 1 = Yes
int *error Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Replace and set aktual settings.

 

2.1.35     DFCReset

Supported from firmware version on:
04.01.07
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCReset(int channelID, int deviceID, int mode, int *error);

Exported: _DFCReset@16
Parameters: 
int channeID Channel to be used. Range of value: (1 - 250)
int deviceD Bus number to be used. Range of value: (1 - 31, 254)
int mode What type of reset.
ValueMeaning
1Warm start
2Format flash memory. (You have to transfer Setup and List after reboot!)
3Delete Setup. (You have to transfer Setup and List after reboot!)
...Unbenutzt
int *error Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Reset of device. Device reboots.

 

2.1.36     DFCSetFontType

Supported from firmware version on:
04.01.07
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetFontType(int channelID, int deviceID, int iType, int *error);

Exported: _DFCSetFontType@16
Parameters: 
int channeID Channel to be used. Range of value: (1 - 250)
int deviceD Bus number to be used. Range of value: (1 - 31, 254)
int iType Type of font.
ValueMeaning
0Standard font
116 Pixel (7 display rows)
216 Pixel,feste breite(7 display rows)
319 Pixel(6 display rows)
419 Pixel,feste breite(6 rows)
521 Pixel(5 display rows)
621 Pixel,feste breite(5 rows)
...unused
int *error Error contains an error number according to table 1.5.3.
Rückgabewert: 
0 Error at execution.
1 Carried out successfully.
Description:
Set type of Font to use for display Messages per DFCComSendMessage or DFCComSendInfotext. Setting is valid till terminal restart.

 

2.1.37     DFCSetPassword

Supported from firmware version on:
04.01.07
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetPassword(int channelID,
char *password, int *piError);

Exported: _DFCSetPassword@12
Parameters: 
int channelID Channel to be used. Range of value: (1 - 250)
char *password String of password key. Maximum 16 chars.
int *piError Error contains an error number according to table 1.5.3.
Rückgabewert: 
0 Error at execution.
1 Carried out successfully.
Description:
Set password for communication. The password is transfered with setup data and activ direct after transfer.

 

2.1.38     DFCGetPasswordKey

Supported from firmware version on:
04.01.07
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetPasswordKey(int channelID, int deviceID,
char *key, int *len, int *piError);

Exported: _DFCGetPasswordKey@20
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
char *key String of password key. Is 16 char in length.
int *len As input, length of buffer key. As output, length of chars copied to key. minimum length of key, should be 17.
int *piError Error contains an error number according to table 1.5.3.
Rückgabewert:
0 Error at execution.
1 Carried out successfully.
Description:
If youre communication password lost, over this funktion you can get an alternate key. this key should be send to datafox and datafox generate an replacement password for your one.

2.1.39     DFCPressVirtualKey

Supported from firmware version on:
04.01.07
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCPressVirtualKey(int channelID, int deviceID, int virtualKey,
 int flags, int *piError);

Exported: _DFCPressVirtualKey@20
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int virtualKey Value for key:
WertBedeutung
112F1 -> Equal to press function key 1
113F2 -> Equal to press function key 2
114F3 -> Equal to press function key 3
115F4 -> Equal to press function key 4
116F5 -> Equal to press function key 5
117F6 -> Equal to press function key 6
118F7 -> Equal to press function key 7
119F8 -> Equal to press function key 8
120F9 -> Equal to press function key 9
121F10 -> Equal to press function key 10
122F11 -> Equal to press function key 11
123F12 -> Equal to press function key 12
124F13 -> Equal to press function key 13
125F14 -> Equal to press function key 14
126F15 -> Equal to press function key 15
...Not used
int flags Extended options for key pressed:
BitnumberValueMeaning
10, 1Press key only if terminal in main menu state.
......Not used
int *piError Error contains an error number according to table 1.5.3.
Rückgabewert: 
0 Error at execution.
1 Carried out successfully.
Description:
With this funktion you can generate key press.

 

2.1.40     DFCGetFlashStatus

Supported from firmware version on:
04.01.07
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetFlashStatus(int channelID, int deviceID, int *status,
 int *piError);

Exported: _DFCGetFlashStatus@16
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int *status Variable to get current status.
Flag with the follow meaning:
BitValueMeaning
11Service: Flash memory has reached its maximum write cycle. Substitute flash memory.
22Warning: CRC Error in Record or List scope. Please transfer setup and or list data to repair.
34Error: Flash memory is defect.
......Unused
int *piError Error contains an error number according to table 1.5.3.
Rückgabewert: 
0 Error at execution.
1 Carried out successfully.
Description:
This is a service funktion to get information for current flash memory status.

 

2.2     Functions for the setup

Konfigurationsdaten mit dem Gerät abgleichen.

2.2.1     DFCSetupLaden

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetupLaden(int iChannelNum, int iBusNum,
char *szFileName, int *piError);

Exported: _DFCSetupLaden@16
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
char *szFileName File name of the setup file (if necessary, with path).
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description: 
Reads the setup data out of the file (*.aes) and transmits them to the device.

 

2.2.2     DFCDownload

Wird unterstützt ab Firmwareversion:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCDownload(int iChannelNum, int iBusNum,
char *szFileName, int *piError);

Exported: _DFCDownload@16
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
char *szFileName File name of the setup file (if necessary, with path).
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description: 
Reads the setup data out of the device and transmits them to a file (*.aes).

 

2.2.3     DFCModifyStudioFile

Wird unterstützt ab Firmwareversion:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCModifyStudioFile(char *sourceFile, char *destFile,
char *changeData, int flags, int *piError);

Exported: _DFCModifyStudioFile@20
Parameters: 
char *sourceFile Source file: File name of the setup file with data to be changed (if necessary, with path).
char *destFile Destination file: File name of the setup file with changed data (if necessary, with path).
char *changeData Either text buffer with xml-data (starts with <?xml) or file name of the XML-file with the appropriate data.
int flags Reserved.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description: 
Modifies and saves the data of a setup file (*.aes).
 Example of the XML-data:
<?xml version="1.0" ?>
<modify>

	<password>
		<system>
			<value>1234</value>
		</system>
		<user>
			<value>2345</value>
		</user>
		<menu_item>
			<name>MEID_003</name>
			<value>4711</value>
		</menu_item>
	</password>

	<fingerprint>
		<security_level>20</security_level>
		<image_quality>70</image_quality>
		<minutiae_count>20</minutiae_count>
	</fingerprint>

	<replace>
		<name>
			<search>MID_001</search>
			<replacement>PZE Setup</replacement>
		</name>
		<name>
			<search>MEID_001</search>
			<replacement>Kommt:</replacement>
		</name>
		<name>
			<search>MEID_002</search>
			<replacement>Geht:</replacement>
		</name>
		<name>
			<search>MEID_003</search>
			<replacement>Abwesend</replacement>
		</name>
	</replace>

</modify>

 

2.3     Functions for lists and access lists (version 2)

Accessing to the lists on the device.

2.3.1     DFCOpenTable

Supported from firmware version on:
PZE-MasterIV, ZK-MasterIV, MDE-MasterIV: 04.01.01.30
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCOpenTable(int channelID, int deviceID, char *name, int options, 
int *handle, char *reserved, int *piError); 

Exported: _DFCOpenTable@28
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
char *name Name of the table to be opened. The device tables are divided into various fields, which can be activated via a name prefix. LIST. -> list descriptions of the setup. (e.g. LIST.PermanentStaff) ACCESS. -> lists for access control version 2
int options Out of use at present. Please always transmit 0.
int *handle Handle contains a clear number, which has to be used for all further function calls.
char *reserved Reserved. Please always transmit an empty string.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Opens a list and returns a handle for it. All further list functions, explained in this chapter, operate with this handle. In order to open the list, it has to be transmitted to the device first via the function DFCLoadListen. In order to open the list "Permanent staff" of the setup, the name "LIST:PermanentStaff" has to be used. In order to open the list "Identification" of the access control, the name "ACCESS. Identification" has to be used.

 

2.3.2     DFCCloseTable

Supported from firmware version on:
PZE-MasterIV, ZK-MasterIV, MDE-MasterIV: 04.01.01.30
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCCloseTable(int channelID, int deviceID, int handle, int *piError); 

Exported: _DFCCloseTable@16
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int handle List handle. Handle of the previous call of DFCOpenTable.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Closes the list, which was opened before via DFCOpenTable.

 

2.3.3     DFCSetFilter

Supported from firmware version on:
PZE-MasterIV, ZK-MasterIV, MDE-MasterIV: 04.01.01.30
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetFilter(int channelID, int deviceID, int handle, 
char *filter, int *piError); 

Exported: _DFCSetFilter@20
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int handle List handle. Handle of the previous call of DFCOpenTable.
char *filter Filter string following this scheme: Column name = 'Column value' The column value can be set in single or double quotes
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Sets a filter to the indicated list. After calling up this function, the data record pointer has to be set on a valid data record via DFCSkip.

 

2.3.4     DFCGetFilter

Supported from firmware version on:
PZE-MasterIV, ZK-MasterIV, MDE-MasterIV: 04.01.01.30
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetFilter(int channelID, int deviceID, int handle, 
char *filter, int *len, int *piError); 

Exported: _DFCGetFilter@24
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int handle List handle. Handle of the previous call of DFCOpenTable.
char *filter Filter contains the determined string of the filter criterion. Following this scheme: Column name = 'Column value'
int *len As input: length of the reserved buffer, that the pointer *filter refers to; as output: length of the transmitted string.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Determines the currently set filter criterion of the list.

 

2.3.5     DFCClearFilter

Supported from firmware version on:
PZE-MasterIV, ZK-MasterIV, MDE-MasterIV: 04.01.01.30
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCClearFilter(int channelID, int deviceID, int handle, int *piError);

Exported: _DFCClearFilter@16
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int handle List handle. Handle of the previous call of DFCOpenTable.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Removes the set filter from the list. After calling up this function, the data record pointer has to be set on a valid data record via DFCSkip.

 

2.3.6     DFCSkip

Supported from firmware version on:
PZE-MasterIV, ZK-MasterIV, MDE-MasterIV: 04.01.01.30
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSkip(int channelID, int deviceID, int handle, 
int offset, int origin, int *piError);

Exported: _DFCSkip@24
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int handle List handle. Handle of the previous call of DFCOpenTable.
int offset Number of data records to be offset. The value can also be negative.
int origin Reference of the offset:
ValueMeaning
0Start of list.
1Current position in list.
2End of list.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Moves the data record pointer of a list.

 

2.3.7     DFCSetField

 Caution: 
When using sorted lists, the sorting column (key field) must not be changed, because an automatic sorting is not intended.
Supported from firmware version on:
PZE-MasterIV, ZK-MasterIV, MDE-MasterIV: 04.01.01.30
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetField(int channelID, int deviceID, 
int handle, char *name, char *value, int *piError); 

Exported: _DFCSetField@24
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int handle List handle. Handle of the previous call of DFCOpenTable.
char *name Field name.
char *value Value to be set.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Sets a field value.

 

2.3.8     DFCGetField

Supported from firmware version on:
PZE-MasterIV, ZK-MasterIV, MDE-MasterIV: 04.01.01.30
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetField(int channelID, int deviceID, int handle, 
char *name, char *value, int *len, int *piError);

Exported: _DFCGetField@28
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int handle List handle. Handle of the previous call of DFCOpenTable.
char *name Field name.
char *value Value contains the read data fields.
int *len As input: length of the buffer, that the pointer *value refers to; as output: number of transmitted data.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Reads a field value.

 

2.4     Functions for data

Collecting of incurred data out of the device and interpreting of the delivered information by adjusting them with the device configuration.

2.4.1     DFCComClearData

 Caution: 
It is not necessary to use this function. We even advise against using it, because currently input data might be deleted accidentally.
Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCComClearData(int iChannelNum, int iBusNum);

Exported: _DFCComClearData@8
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
Return value:
0 An error occurred at instruction execution.
1 Function carried out successfully.
Description:
Deletes all data on the device. Resets the writing and reading pointer to the buffer start.

 

2.4.2     DFCComCollectData

Ruft intern die Funktion DFCReadRecord auf.
Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCComCollectData(int iChannelNum, int iBusNum, 
int *piError);

Exported: _DFCComCollectData@12
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int *piError Error contains an error number according to table 1.5.3.
Return value:
-1 Error at execution.
0 No data available
1 Offline data available.
2 Online data available.
Description:
Reads all available data out of the device and saves them on the internal DLL buffer. For all firmware versions >=2 (major version) only one data record is read out of the device and the bus number is set for further data record queries via DFCComGetDatensatz. The data records are differed between Online and Offline. Online data are data, that were just input. Their time domain (time, that was needed to read the data out of the DLL) is within the defined server timeout. Online data can be checked and the user can be requested for an anew input via messaging (see DFCComSendMessage). Offline data were collected after the server timeout.

 

2.4.3     DFCComGetDatensatz

Ruft intern die Funktionen DFCQuitRecord, DFCReadRecord auf.
Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCComGetDatensatz(int iChannelNum, unsigned char *pucBuf,
int *piLength, int *piError); 

Exported: _DFCComGetDatensatz@16
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
unsigned char *pucBuf Buffer, that the data are logged on.
 int *piLength Buffer, where the length of the currently received data shall be saved
int *piError Error contains an error number according to table 1.5.3.
Return value:
-1 Error at execution.
0 No data available.
1 Further data available.
2 Last data record.
Description:
Returns exactly one data record to the called up application. If there is one Online data record among several data records, that one is transmitted at last from the DLL to the application (it is also that one, which was input last). The data structure, contained in the data record, is explained in chapter 3. For the firmware >=2 (major version) the data record, which was read last, is transmitted and quitted, then the next one is read out of the device (if available). That way the data records are read out of the device one by one. If an Online data record was indicated (by calling up the function DFCComCollectData at first), that one is delivered first.

 

2.4.4     DFCLoadDatensatzbeschreibung

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCLoadDatensatzbeschreibung(int iChannelNum, int iBusNum,
int *piError);

Exported: _DFCLoadDatensatzbeschreibung@12
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Reads of the data record description out of the device. The data record descriptions are logged on the DLL on a buffer. They can be analysed via the functions DFCDatB...

 

2.4.5     DFCDatBCnt

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCDatBCnt(int iChannelNum); 

Exported: _DFCDatBCnt@4
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
Return value:
Number of data record descriptions, that were found in the device
Description:
Number of read data record descriptions (only valid, if the function DFCLoadDatensatzbeschreibung was called up before).

 

2.4.6     DFCDatBDatensatz

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCDatBDatensatz(int iChannelNum,
int iDataNum, unsigned char *szName, int *piFieldCount);

Exported: _DFCDatBDatensatz@16
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iDataNum Number of the data record description of the setup. (counted from 0 on)
unsigned char *szName Name of the data record description. (The buffer for the name has to have at least 17 byte)
int *piFieldCount Number of fields of the data record description.
Return value:
0 Data record description not available in the device.
1 Data were transmitted.
Description:
Queries the data of a data record description (only valid, if the function DFCLoadDatensatzbeschreibung was called up before). Within the device the data record descriptions can be saved in different formats. In the setup program the data records are set under "Datensatzbeschreibungen" The first data record description of the setup tree gets the number 0, the second one gets number 1 ...

 

2.4.7     DFCDatBFeld

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCDatBFeld(int iChannelNum, int iDataNum,
int iField, unsigned char *szName, int *piType, int *piLength);

Exported: _DFCDatBFeld@24
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iDataNum Number of the data record description (counted from 0 on).
int iField Field of the data record description according to the order in the setup (counted from 0 on).
unsigned char *szName Name of the field (The buffer for the name has to have at least 17 byte).
int *piType Data type of the field, as defined in the setup:
ValueMeaning
1unsigned long 4 Byte
2Date und Time 7 Byte
3Like type 4, but only digits are permitted
4Alpha-numeric ASCII
5Date 4 byte Y100,Y,M,D
6Time 3 byte (Hour, Minute, Second)
int *piLength Length of the field in byte. For type 3 and 4 the concluding "0" is also counted. e.g. ASCII field 15 characters, Length = 15 + 1 = 16 byte
Return value:
0 Data record description or field number not available in the device.
1 Data were transmitted.
Description:
Queries the data of a field of a data record description (only valid, if the function DFCLoadDatensatzbeschreibung was called up before).

 

2.4.8     DFCReadRecord

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCReadRecord(int channelID, int deviceID, 
char *buf, int *length, int *err);

Exported: _DFCReadRecord@20
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
char *buf Buffer, where the data shall be logged on.
int *length Buffer, where the length of the just received data shall be saved.
int *err Error contains an error number according to table 1.5.3.
Return value:
-1 Error at execution.
0 No data records available.
1 Data of an Online data record were read.
2 Data of an Online data record were read repeatedly.
3 Data of an Offline data record were read.
4 Data of an Offline data record were read repeatedly.
Description:
Reads the data of the data record at issue. After reading the data record, it has to be quitted via DFCQuitRecord. After successful delete the next data record can be read by calling up the function DFCReadRecord anew.

 

2.4.9     DFCQuitRecord

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCQuitRecord(int channelID, int deviceID, int *err);

Exported: _DFCQuitRecord@12
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254).)
int *err Error contains an error number according to table 1.5.3.
Return value:
-1 Error at execution.
0 Quitting not necessary.
1 Data of an Online data record quitted.
2 Data of an Online data record quitted repeatedly.
3 Data of an Offline data record quitted.
4 Data of an Offline data record quitted repeatedly.
Description:
Quits the data, which were read before via DFCReadRecord.

 

2.4.10     DFCRestoreRecords

Supported from firmware version on:
04.01.06
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCRestoreRecords(int channelID, int deviceID, int *piError);

Exported: _DFCRestoreRecords@12
Parameters: 
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int *piError Error contains an error number according to table 1.5.3.
Return value: 
0 Error at execution.
1 Carried out successfully.
Description:
Reset internal data pointer of device. After successfully execution all records can read out again.

 

2.5     Functions for lists

Preparing of list data and loading to the devices.

2.5.1     DFCMakeListe

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCMakeListe(
int iChannelNum, int iListNum, int iLineCount, int iListSize,
unsigned char *pucBuf, int iListMemSizeNum);

Exported: _DFCMakeListe@24
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iListNum  Number of the list according to the list description in the setup. The first list description of the setup has the number "0".
int iLineCount Number of lines (data records) of the list.
int iListSize Total size of the list in byte. Calculated from "iLineCount" multiplied by the number of byte each line.
unsigned char *pucBuf Pointer on the list data.
int iListMemSizeNum Size of the memory for the lists. For AEIII+ it always has to be set to "0" (taken over by the Timeboy). For the lists are set fixedly: 100kbyte / (256kbyte - 12kbyte management data => 244kbyte).
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Writes the list data on the internal buffer of the DLL.

The list data always have to correspond exactly to the list description in the setup. Strings have to be filled with NULL (hexadecimal value 0x00, different to the ASCII character "0", hexadecimal value 0x30) to the length, scheduled by the setup. Furthermore, do not forget the concluding NULL.
If a string of 16 characters was created in the setup, the field length is exactly 17 byte. Separators between fields and lines are not used.

Example:
List of 2 fields:
Personnel number string (only digits) 4 byte;
Name string (ASCII characters) 16 characters.
In that case one line consists of 4 + 1 + 16 + 1 = 22 byte. If three lines shall be created, exactly 3*22 = 66 byte are necessary.

 

2.5.2     DFCLoadListen

 Caution: 
Please note, that MasterIV devices use a flash memory. According to the producer each buffer block (512 byte) can be written on at most 100.000 times. The firmware of the devices distributes the charge of access to the single buffer blocks and marks internally defect blocks. Despite this security mechanism we recommend to avoid immoderate transmissions of the list data. The application should primarily be used to transmit the lists in case of alternations, not cyclically or permanently.
Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCLoadListen(int iChannelNum, int iBusNum, 
int *piError);

Exported: _DFCLoadListen@12
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Loads the list data from the internal DLL buffer to the device. Upload of the list data, that were created before via DFCMakeListe. If the firmware version does not support the imported amount of list data, the error message 13 (see table 1.5.3) is returned. The firmware states of the AEIII+, as well as these of the PZE-MasterIV up to 04.00.23 support 100 kbyte list buffer, versions later than 04.00.23 about 256 kbyte.

 

2.5.3     DFCClrListenBuffer

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCClrListenBuffer(int iChannelNum);

Exported: _DFCClrListenBuffer@4
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
Return value:
No  
Description:
Deletes the list data in the DLL buffer.

 

2.5.4     DFCLoadListenbeschreibung

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCLoadListenbeschreibung(int iChannelNum, int iBusNum,
int *piError);

Exported: _DFCLoadListenbeschreibung@12
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Reads the list descriptions out of the device. The list descriptions are logged on a buffer in the DLL and can be analysed via the functions DFCListB... .

 

2.5.5     DFCListBCnt

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCListBCnt(int iChannelNum);

Exported: _DFCListBCnt@4
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
Return value:
Number Number of list descriptions, that were found in the device.
Description:
Number of established list descriptions (only valid, if the function DFCLoadListenbeschreibung was called up before).

 

2.5.6     DFCListBDatensatz

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCListBDatensatz(int iChannelNum, int iDataNum,
unsigned char *szName, int *piFieldCount, int *piVar);

Exported: _DFCListBDatensatz@20
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iDataNum Number of the list description in the setup. (counted from 0 on).

From DLL - Version 02.00.22 on, Range:
100 - 103 for access lists version 1. (e.g. 102 for the list "Permanent staff")
Offset numbers of the lists see DFCMakeEntranceList.

From DLL - Version 04.01.00 on, Range:
200 - 206 for access lists version 2. (e.g. 203 for the list "Time")
Offset numbers of the lists see DFCMakeEntrance2List.

unsigned char *szName Name of the list description. (The buffer of the name has to have at least 17 byte).
int *piFieldCount Number of fields of the list.
int *piVar Whether variable list. Always 0. (existent because of the compatibility with the Timeboy).
Return value:
0 List description not available in the device.
1 Data were transmitted.
Description:
Calls up the data of a list description (only valid, if the function DFCLoadListenbeschreibung was called up; not necessary for access lists). Within the device the lists can be saved in various formats. In the setup program the lists are set under "List descriptions". The first list description of the setup tree gets the number 0, the second one number 1 ...

 

2.5.7     DFCListBFeld

Supported from firmware version on:
Infinite
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCListBFeld(int iChannelNum, int iDataNum,
int iField, unsigned char *szName, int *piType, int *piLength);

Exported: _DFCListBFeld@24
Parameters: 
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iDataNum Number of the list description of the setup. (counted from 0 on).

From DLL - Version 02.00.22 on, Range:
100 - 103 for access lists version 1. (e.g. 102 for the list "Permanent staff")
Offset numbers of the lists see DFCMakeEntranceList.

From DLL - Version 04.01.00 on, Range:
200 - 206 for access lists version 2. (e.g. 203 for the list "Time")
Offset numbers of the lists see DFCMakeEntrance2List.

int iField Field of the list description according to the order in the setup. (counted from 0 on).
unsigned char *szName Name of the field. (The buffer of the name has to have at least 17 byte).
int *piType Data type of the field, as defined in the setup:
ValueMeaning
1unsigned long 4 Byte
2Date und Time 7 Byte
3like type 4, but only digits are permitted.
4Alpha numerisch ASCII.
5Date 4 byte Y100,Y,M,D.
6Time 3 byte (Hour, Minute, Second).
int *piLength Length of the field in byte (as defined in the setup). For type 3 and 4 the concluding "0" is also counted. e.g.: ASCII field 15 characters, Len = 15 + 1 = 16 byte
Return value: 
0 List description or field number not available in the device
1 Data were transmitted.
Description:
Queries the data of a field of a list description (only valid, if the function DFCLoadListenbeschreibung was called up before; not necessary for access lists).

 

2.6     Functions for access control lists (Version 1)

Preparing and loading of list data for the access control.

2.6.1     DFCMakeEntranceList

Supported from firmware version on:
03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCMakeEntranceList(
int iChannelNum, int iListNum, int iLineCount, int iListSize,
unsigned char *pucBuf, int *piError);

Exported: _DFCMakeEntranceList@24
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iListNum  Number of the list according to the list description in the setup under the tree input. The first list description of this input has the number "0".
int iLineCount Number of lines (data records) of the list.
int iListSize Total size of the list in byte. Calculated from the iLineCount multiplied by the number of byte each line
unsigned char *pucBuf Pointer on the list data.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Writes a list on the internal buffer of the DLL.
The list data always have to correspond exactly to the list description in the setup. Strings have to be filled with NULL (hexadecimal value 0x00, different to the ASCII character "0", hexadecimal value 0x30) to the length, that is scheduled by the setup. Furthermore, do not forget the concluding NULL.
If a string of 16 characters was created in the setup, the field length is exactly 17 byte. Separators between fields and lines are not used.

Example:
List of 2 fields:
Personnel number string (only digits) 4 byte;
Name string (ASCII characters) 16 characters.
In that case one line consists of 4 + 1 + 16 + 1 = 22 byte. If 3 three lines shall be created, exactly 3*22 = 66 byte are necessary.

In the DLL the list data are compressed for the device and prepared (sorted), so that calling up a staff list (5120 entries) may take up to 7 seconds (in the worst case).

The meaning of the parameter iListNum is:
0: Time zones (22 byte) "at most 16 DR possible for compressed (6 byte)"
1: Time models (35 byte) "at most 32 DR possible for compressed (3 byte)"
2: Permanent staff (19 byte) "at most 5120 DR possible for compressed (16 byte)"
3: Holidays (16 byte) "at most 64 DR possible for compressed (6 byte)"

 

2.6.2     DFCLoadEntranceList

 Caution: 
Please note, that MasterIV devices use a flash memory. According to the producer each buffer block (512 byte) can be written on at most 100.000 times. The firmware of the devices distributes the charge of access to the single buffer blocks and marks internally defect blocks. Despite this security mechanism we recommend to avoid immoderate transmissions of the list data. The application should primarily be used to transmit the lists in case of alternations, not cyclically or permanently.
Supported from firmware version on:
03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCLoadEntranceList(int iChannelNum, int iBusNum, 
int iListNum, int *piError);

Exported: _DFCLoadEntranceList@16
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int iListNum Number of the list according to the list description in the setup under the tree input Access control. The first list description of this input has the number "0". Via "-1" all lists are activated.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Loads list data from the internal DLL buffer on the device. Upload of list data, which were created before. By setting the list number "-1" all list buffers are transmitted (the import of all lists should be finished yet).

 

2.6.3     DFCClearEntranceListBuffer

Supported from firmware version on:
03.01.00, 04.00.00
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCClearEntranceListBuffer(int iChannelNum, int iListNum);

Exported: _DFCClearEntranceListBuffer@8
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iListNum Number of the list according to the list description in the setup under the tree input Access control. The first list description of this input has the number "0". Via "-1" all lists are activated.
Return value:
No  
Description:
Deletes the buffer for the list data. By setting the list number "-1" all buffers, that are available for the access control, are deleted.

 

2.7     Functions for access control lists (version 2)

Preparing and loading of list data for the access control.

2.7.1     DFCMakeEntrance2List

Supported from firmware version on:
04.01.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCMakeEntrance2List(
int iChannelNum, int iListNum, int iLineCount, int iListSize,
unsigned char *pucBuf, int *piError);

Exported: _DFCMakeEntrance2List@24
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iListNum  Number of the list according to the list description in the setup under the tree input Access control. The first list description of this input has the number "0".
int iLineCount Number of lines (data records) of the list.
int iListSize Total size of the list in byte. Calculated from the iLineCount multiplied by the number of byte each line.
unsigned char *pucBuf Pointer on the list data.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Writes a list on the internal buffer of the DLL.

The list data always have to correspond exactly to the list description in the setup. Strings have to be filled with NULL (hexadecimal value 0x00, different to the ASCII character "0", hexadecimal value 0x30) to the length scheduled by the setup. In addition, do not forget the concluding NULL.
If a string of 16 characters was created in the setup, the field length is exactly 17 byte. Separators between fields and lines are not used.

Example:
List of 2 fields:
Personnel number string (only digits) 4 byte;
Name string (ASCII characters) 16 characters.
In that case one line consists of 4 + 1 + 16 + 1 = 22 byte. If three lines shall be created, exactly 3*22 = 66 byte are necessary.

The meaning of the parameter iListNum is:
0: Reader (33 byte)
1: Identification (64 byte)
2: Location (20 byte)
3: Time (25 byte)
4: Holiday (21 byte)
5: Events (17 byte)
6: Action (21 byte)

 

2.7.2     DFCLoadEntrance2List

 Caution: 
Please note, that MasterIV devices use a flash memory. According to the producer each buffer block (512 byte) can be written on at most 100.000 times. The firmware of the devices distributes the charge of access to the single buffer blocks and marks internally defect blocks. Despite this security mechanism we recommend to avoid immoderate transmissions of the list data. The application should primarily be used to transmit the lists in case of alternations, not cyclically or permanently.
Supported from firmware version on:
04.01.00
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCLoadEntrance2List(int iChannelNum, int iBusNum, 
int iListNum, int *piError);

Exported: _DFCLoadEntrance2List@16
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int iListNum Number of the list according to the list description in the setup under the tree input Access control 2. The first list description of this input has the number "0". Via "-1" all lists (imported before) are activated.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Loads list data from the internal DLL buffer on the device. Upload of list data, that were created before. By setting the list number "-1" all allocated list buffers are transmitted.

 

2.7.3     DFCClearEntrance2ListBuffer

Supported from firmware version on:
04.01.00
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCClearEntrance2ListBuffer(int iChannelNum, int iListNum);

Exported: _DFCClearEntrance2ListBuffer@8
Parameters:
int iChannelNum Channel to be used. Range of value: (1 - 250)
int iListNum Number of the list according to the list description in the setup under the tree input Access control 2. The first list description of this input has the number "0". Via "-1" all lists are activated.
Return value:
No  
Description:
Deletes the buffer for the list data. By setting "-1" as list number all buffers, that are available for the access control, are deleted.

 

2.7.4     DFCEntrance2Identification

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCEntrance2Identification(int channelID, int deviceID, 
char *TM, char *Id, char *Pin, char *status, int *len, int *piError);

Exported: _DFCEntrance2Identification@32
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
char *TM The value of the string, which this pointer refers to, has to correspond to the format of the field "TM" of the "Reader" list: It always has to have a length of 3 digits.
char *Id The value of the string, which this pointer refers to, has to correspond to the format of the field "Id" of the "Identification" list: It can have a length of at most 20 characters.
char *Pin The value of the string, which this pointer refers to, has to correspond to the format of the field "Pin" of the "Identification" list: It can have a length of at most 8 digits.
char *status Pointer on the string, which gets the state Access control after processing the function. You should plan a length of at least 5 characters.
int *len As input: length of the buffer, which the pointer *status refers to; as output: transmitted number of characters.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
By calling up this function an access booking via DLL can be carried out. In the interest of security this function can only be used for cards, with which were set the value "2" or "9" to the field ActiveGeneral of the "Identification" list. Further information about both the field values to be transmitted (TM, Id, Pin) and the returned state you may find in the appropriate manual in the chapter "Access control 2" and the sub-chapter "Status messages of the access control".

 

2.7.5    DFCEntrance2OnlineAction

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCEntrance2OnlineAction(int channelID, int deviceID, 
char *TM, int mask, int type, int duration, int *piError);

Exported: _DFCEntrance2OnlineAction@28
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
char *TM The value of the string, which this pointer refers to, has to correspond to the format of the field "TM" of the "Reader" list: It always has to have a length of 3 digits.
int mask Contains the value of the components to be switched:
Bit No.Meaning
0For set bit, the buzzer is activated.
1For set bit, the green LED is activated.
2For set bit, the red LED is activated.
3For set bit, the first relay is activated.
4For set bit, the second relay is activated.
...Of no use. Please always 0.
int type
No.Meaning
0Off
1On
2Change (600ms on, 600ms off)
3Changing 3 times (400ms on, 400ms off)
int duration Duration; only valid for type = 1. Meaning: 0 = on (permanent), 1 - 40 = seconds on.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully
Description:
By calling up this function the buzzer, an LED or a relay can be switched on the access module via DLL.

 

2.7.6     DFCAccessControlIdentification

Supported from firmware version on:
04.03.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCAccessControlIdentification(int channelID, int deviceID, 
int masterId, char *TM, char *Id, char *Pin, char *status, int *len, int *piError);

Exported: _DFCAccessControlIdentification@36
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int masterId MasterId for the address of access bus. (Default: 1) Range: (1 - 9999)
char *TM The value of the string, which this pointer refers to, has to correspond to the format of the field "TM" of the "Reader" list: It always has to have a length of 3 digits.
char *Id The value of the string, which this pointer refers to, has to correspond to the format of the field "Id" of the "Identification" list: It can have a length of at most 20 characters.
char *Pin The value of the string, which this pointer refers to, has to correspond to the format of the field "Pin" of the "Identification" list: It can have a length of at most 8 digits.
char *status Pointer on the string, which gets the state Access control after processing the function. You should plan a length of at least 5 characters.
int *len As input: length of the buffer, which the pointer *status refers to; as output: transmitted number of characters.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
By calling up this function an access booking via DLL can be carried out. In the interest of security this function can only be used for cards, with which were set the value "2" or "9" to the field ActiveGeneral of the "Identification" list. Further information about both the field values to be transmitted (masterId, TM, Id, Pin) and the returned state you may find in the appropriate manual in the chapter "Access control 2" and the sub-chapter "Status messages of the access control".

 

2.7.7    DFCAccessControlOnlineAction

Supported from firmware version on:
04.03.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCAccessControlOnlineAction(int channelID, int deviceID, 
int masterId, char *TM, int mask, int type, int duration, int *piError);

Exported: _DFCAccessControlOnlineAction@32
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int masterId MasterId for the address of access bus. (Default: 1) Range: (1 - 9999)
char *TM The value of the string, which this pointer refers to, has to correspond to the format of the field "TM" of the "Reader" list: It always has to have a length of 3 digits.
int mask Contains the value of the components to be switched:
Bit No.Meaning
0For set bit, the buzzer is activated.
1For set bit, the green LED is activated.
2For set bit, the red LED is activated.
3For set bit, the first relay is activated.
4For set bit, the second relay is activated.
...Of no use. Please always 0.
int type
No.Meaning
0Off
1On
2Change (600ms on, 600ms off)
3Changing 3 times (400ms on, 400ms off)
int duration Duration; only valid for type = 1. Meaning: 0 = on (permanent), 1 - 40 = seconds on.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully
Description:
By calling up this function the buzzer, an LED or a relay can be switched on the access module via DLL.

 

2.8     Functions for the fingerprint

Accessing to the finger templates of a possibly installed fingerprint module.

2.8.1     DFCFingerprintAppendRecord

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCFingerprintAppendRecord(int channelID, int deviceID, 
int type, unsigned char *fingertemplate, int size, int *piError);

Exported: _DFCFingerprintAppendRecord@24
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int type Type of template that is transmitted.
ValueMeaning
0DIN V66400 (161 byte)
Byte No.Designation
1..8PID (The byte 1 to 4, as 32bit value, are used.)
9FID
10Quality
11Number Minutiae
12X1
13Y1
14W1
15X2
16Y2
17W2
.....
.....
159X50
160Y50
161W50
1Idencom-Compact (216 byte)
Byte Nr.Designation
1..8PID (The byte 1 to 4, as 32bit value, are used.)
9FID
10Quality
11Number Minutiae
12X1
13Y1
14W
15XN1
16YN1
.....
.....
214W
215YN41
216WN41
2Idencom-Standard (561 Byte)
Byte Nr.Designation
1..8PID (The byte 1 to 4, as 32bit value, are used.)
9FID
10Quality
11Number Minutiae
12,13X1
14,15Y1
16,17W1
18V1
19,20XN1
21,22YN1
.....
.....
555, 556W50
557V50
558, 559XN50
560, 561YN50
... 
unsigned char *fingertemplate Pointer on the template data.
int size Length of the buffer, which the pointer *fingertemplate refers to.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Appends a finger template to the data table of the fingerprint.

 

2.8.2     DFCFingerprintGetRecord

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCFingerprintGetRecord(int channelID, int deviceID, 
int type, int pid, int fid, unsigned char *fingertemplate,int *size int *piError);

Exported: _DFCFingerprintGetRecord@32
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int type Type of template, that is transmitted.
ValueMeaning
0DIN V66400 (161 Byte)
Byte No.Designation
1..8PID (The byte 1 to 4, as 32bit value, are used.)
9FID
10Quality
11Number Minutiae
12X1
13Y1
14W1
15X2
16Y2
17W2
.....
.....
159X50
160Y50
161W50
1Idencom-Compact (216 byte)
Byte No.Designation
1..8PID (The byte 1 to 4, as 32bit value, are used.)
9FID
10Quality
11Number Minutiae
12X1
13Y1
14W
15XN1
16YN1
.....
.....
214W
215YN41
216WN41
2Idencom-Standard (561 Byte)
Byte Nr.Designation
1..8PID (The byte 1 to 4, as 32bit value, are used.)
9FID
10Quality
11Number Minutiae
12,13X1
14,15Y1
16,17W1
18V1
19,20XN1
21,22YN1
.....
.....
555, 556W50
557V50
558, 559XN50
560, 561YN50
... 
int pid Personal Id of the template to be read.
int fid Finger Id of the template to be read. Range of value: (1 - 10)
unsigned char *fingertemplate Pointer on the template data.
int *size As input: length of the buffer, which the pointer *template refers to; as output: number of transmitted characters.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Reads a finger template. By combining PID and FID clearly the appropriate template data can be established via this function.

 

2.8.3    DFCFingerprintDeleteRecord

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCFingerprintDeleteRecord(int channelID, int deviceID, 
int pid, int fid, int *piError);

Exported: _DFCFingerprintDeleteRecord@20
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int pid Personal Id of the template to be deleted.
int fid Finger Id of the template to be deleted. Range of value: (0, 1 - 10)
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Deletes finger templates. By setting the appropriate pid,fid pair you can delete single templates. By setting a pid and fid = 0 all finger templates of this pid are deleted; by setting pid = 0 and fid = 0 all finger templates are deleted.

 

2.8.4    DFCFingerprintList

Supported from firmware version on:
04.01.07
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCFingerprintList(int channelID, int deviceID,
int flags, int *piError);

Exported: _DFCFingerprintList@16
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
int flags
Bit NumMeaning
0If bit is set (Decimal 1), result of function is count of records from generated list FINGERPRINT.IDLIST.
When no data on modul available, call results in error. There is not record count 0 therefore.
...Unused.
int *piError Error contains an error number according to table 1.5.3.
Rückgabewert:
0 Error at execution.
1 Carried out successfully. Or if flag (bit 0) is set, count of records in generated list (1 .. n).
Description:
Generate a list with name "FINGERPRINT.IDLIST".  the list has 2 columns, first one with name and content PID, second with name and content FID. To access List data see Section 2.3.

 

2.8.5    DFCFingerprintBackup

Supported from firmware version on:
04.01.04
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCFingerprintBackup(int channelID, int deviceID,
char *backupFile, int flags, int *piError);

Exported: _DFCFingerprintBackup@20
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
char *backupFile String of file name to use for backup file.
int flags Current not used. Default 0.
int *piError Error contains an error number according to table 1.5.3.
Rückgabewert:
0 Error at execution.
1 Carried out successfully.
Description:
Read all fingerpint templates from modul and write these in backup file. If file is existing it would be overritten. To transfer file into modul use function DFCFingerprintRestore.

 

2.8.6    DFCFingerprintRestore

Supported from firmware version on:
04.01.04
Deklaration:
extern "C" __declspec(dllexport)
int __stdcall DFCFingerprintRestore(int channelID, int deviceID,
char *backupFile, int flags, int *piError);

Exported: _DFCFingerprintRestore@20
Parameters:
int channelID Channel to be used. Range of value: (1 - 250)
int deviceID Bus number to be used. Range of value: (1 - 31, 254)
char *backupFile String to file name to use.
int flags
BitMeaning
0Is bit set (Value 1); all templates should be maintained. If Bit not set (Value 0) all templates should be deletet befor transfer file data.
...Unused. Default 0.
int *piError Error contains an error number according to table 1.5.3.
Rückgabewert:
0 Error at execution.
1 Carried out successfully.
Description:
Tranfer data of backup file to fingerprint modul. Generate backup file with function DFCFingerprintBackup.

 

2.9     Functions for Timeboy lists

Preparing and loading of list data for the connected Timeboy devices.

2.9.1     DFCMakeTimeboyList

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCMakeTimeboyList(int iChannelNum, int iGroupID, int iListNum, 
int iLineCount, int iListSize, unsigned char *pucBuf, int flags, int *piError);

Exported: _DFCMakeTimeboyList@32
Parameters:
int iChannelNum >Channel to be used. Range of value: (1 - 250)
int iGroupID  Ist die Timeboy GroupID. When using 0 as GroupID, the transmitted list is valid for all groups. A possibly available global list may be super-imposed on a GroupID > 0.
int iListNum  Number of the list according to the list description in the Timeboy setup under the tree input List descriptions. The first list description of this input has the number "0".
int iLineCount Number of lines (data records) of the list.
int iListSize Total size of the list in byte. Calculated from the iLineCount multiplied by the number of byte each line.
unsigned char *pucBuf Pointer on the list data.
int flags
Bit No.Meaning
0For a set bit (value 1) this list is deleted on the Mobil-MasterIV. Possibly transmitted data are ignored.
...Of no use. Please always 0.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Writes a list on the internal buffer of the DLL.

The list data always have to correspond exactly to the list description in the setup. Strings have to be filled with NULL (hexadecimal value 0x00, different to the ASCII character "0", hexadecimal value 0x30) to the length scheduled by the setup. In addition, do not forget the concluding NULL.
If a string of 16 characters was created in the setup, the field length is exactly 17 byte. Separators between fields and lines are not used.

Example:
List of 2 fields:
Personnel number string (only digits) 4 byte;
Name string (ASCII characters) 16 characters.
In that case one line consists of 4 + 1 + 16 + 1 = 22 byte. If three lines shall be created, exactly 3*22 = 66 byte are necessary.

 

2.9.2     DFCLoadTimeboyList

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCLoadTimeboyList(int iChannelNum, int iBusNum, 
int iGroupID, int iListNum, int reserve, int *piError);

Exported: _DFCLoadTimeboyList@24
Parameters:
int iChannelNum >Channel to be used. Range of value: (1 - 250)
int iBusNum Bus number to be used. Range of value: (1 - 31, 254)
int iGroupID  Ist die Timeboy GroupID. When using 0 as GroupID, the transmitted list is valid for all groups. A possibly available global list may be super-imposed on a GroupID > 0.
int iListNum  Number of the list according to the list description in the Timeboy setup under the tree input List descriptions. The first list description of this input has the number "0".
int reserve  Reserved. Please always transmit 0.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Loads the list data from the internal DLL buffer on the device. Upload of list data, which were created before. By setting the list number "-1" all allocated list buffers are transmitted.

 

2.9.3    DFCClearTimeboyListBuffer

Supported from firmware version on:
04.01.04
Declaration:
extern "C" __declspec(dllexport)
void __stdcall DFCClearTimeboyListBuffer(int iChannelNum, 
int iGroupID, int iListNum);

Exported: _DFCClearTimeboyListBuffer@12
Parameters:
int iChannelNum >Channel to be used. Range of value: (1 - 250)
int iGroupID  Ist die Timeboy GroupID. When using 0 as GroupID, the transmitted list is valid for all groups. A possibly available global list may be super-imposed on a GroupID > 0.
int iListNum  Number of the list according to the list description in the Timeboy setup under the tree input List descriptions. The first list description of this input has the number "0".
Return value:
Nor  
Description:
Deletes the buffer for the list data. By setting the GroupID "-1" all list buffers of this GroupID are deleted; by setting the list number "-1" all list buffers of this list number are deleted (by considering the GroupID).

 

2.10     Functions for the Active Connection

Routines for initialisation and working with Active Connections.

2.10.1     DFCStartActiveConnection

Hint: 
System variables (special variables for the Active Connection), prefix COM, are provided for the installation of the Active Connection.
Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCStartActiveConnection(char *ip, int port, int deviceID, 
int timeout, int aliveTO, int maxConnections, int infoFlags, int reserved, int *piError);

Exported: _DFCStartActiveConnection@36
Parameters:
char *ip Address of the network interface card, which receives the incoming connection (presetting: 0.0.0.0, means all)
int port Port, which has to receive the incoming requests for connection. (presetting: 8000)
int deviceID Bus number of the DLL. (presetting: 31, valid for all channels)
int timeout Interface timeout for the reading of data. Unit: Milliseconds. (presetting: 3000ms)
int aliveTO Timeout to secure the established connection (even if no communication takes place) (Alive-Ping) (Also transmitted to the device via the appropriate system variable.)
int maxConnections Maximum number of connections, that were established at the same time. (presetting: 50, at most 200 are possible)
int infoFlags
Bit No.Meaning
1Version firmware (eg. 04.03.03.PZE)
2Used IP and port. (eg. 192.168.0.1:8000)
3Mac-Aedress. (eg. 00-20-4a-e7-1c-25).
...Of no use. Please always transmit 0.
int reserved Reserved parameter. (presetting 0)
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Starts the DLL module for the Active Connection. After successful execution the set list socket is checked and processed for incoming requests of connection. The acceptance of "Datensatzmeldungen" is activated by default and can be set as desired by calling up the function DFCSetRecordAvailable.
Use infoFlags value 7 (1 + 2 + 4) to get Version Firmware, used ip and port and mac.

 

2.10.2     DFCStopActiveConnection

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCStopActiveConnection(int *piError);

Exported: _DFCStopActiveConnection@4
Parameters:
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Stops the DLL module for the Active Connection. All established Active Connections are closed via the DLL.

 

2.10.3     DFCGetFirstActiveChannelID

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetFirstActiveChannelID();

Exported: _DFCGetFirstActiveChannelID@0
Parameters:
  No
Return value:
-1 No Active Channel available.
... Channel number of the first Active Channel.
Description:
Establishes and returns the first channel number for established Active Connections. By repeated calling up the function DFCGetNextActiveChannelID all Active Channels can be established.

2.10.4     DFCGetNextActiveChannelID

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetNextActiveChannelID(int prev);

Exported: _DFCGetNextActiveChannelID@4
Parameters:
int prev Channel number of the previous Active Channel. See also DFCGetFirstActiveChannelID.
Return value:
-1 No further Active Channel.
... Channel number of the next Active Channel.
Description:
Returns the channel number of an Active Channel to the next possibly available one. By repeated calling up all Active Channels can be established.

 

2.10.5     DFCGetInfoActiveChannel

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCGetInfoActiveChannel(int channelID, char *info, int *infoStringLength);

Exported: _DFCGetInfoActiveChannel@12
Parameters:
int channelID Number of the Active Channel, which the information shall be queried for.
char *info Pointer on the string, which contains the information string. The string contains a value string, separated via CR (decimal 13).
PositionDescription
1Device type.
0PZE-MasterIV
1ZK-MasterIV
2BDE-MasterIV
3Mobil-MasterIV
4MDE-BoxIV
5AE-MasterIV
6TimeboyIV
7Exklusiv-LineIV
8Flex-MasterIV
9Timeboy-Mobil-PZE
10EVO-Line 2.8
11EVO-Line 4.3
12IPC-Extension A
13IPC-Extension B
14IPC-Extension C
15IO-Box
16ZK-Box
2Seriennummer.
3Version firmware (eg. 04.03.03.PZE)
4Used IP and port. (eg. 192.168.0.1:8000)
5Mac-Aedress. (eg. 00-20-4a-e7-1c-25).
...Not yet in use. Refers to the parameter infoFlags of DFCStartActiveConnection
int *infoStringLength As input: length of the reserved buffer, which the pointer *info refers to; as output: length of the transmitted string. Recommended length: 200
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Returns an information string to an Active Channel number. It consists of various values and can be extended by further information via the parameter infoFlags when starting the DLL module for the Active Connection.

 

2.10.6     DFCSetRecordAvailable

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCSetRecordAvailable(int enable);

Exported: _DFCSetRecordAvailable@4
Parameters:
int enable Activation/ Deactivation of the processing of event messages "Data record available" (presetting: On).
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Sets whether the DLL shall analyse the event message "Data record available" and whether the function DFCRecordAvailbale shall be provided.

 

2.10.7     DFCRecordAvailable

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCRecordAvailable(int *channelID, int *deviceID, char *infoString, int *infoStringLength, int *piError);

Exported: _DFCRecordAvailable@20
Parameters:
int *channelID Pointer on the variable, which contains the channel number of the available Active Connection.
int *deviceID Pointer on the variable, which contains the bus number of the available device.
char *info See parameter info for the function DFCGetInfoActiveChannel.
int *infoStringLength As input: length of the reserved buffer, which the pointer *info refers to; as output: length of the transmitted string.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Via this function the message of the available data records can be queried (without communicating with the device). The message, that there are data records available in the device (delivered by the devices), is set to a priority queue and can be called up via this function. After calling up the message is removed from the queue; when calling up again, the next message is delivered. With the help of the delivered parameter values a selective query of the data records is possible. Process of a query task (in principle): Via DFCRecordAvailable it is checked, whether there are any data records available (no direct communication with the device necessary). Via DFCReadRecord, DFCQuitRecord all data records are queried (direct communication with the device necessary).

 

2.10.8     DFCBindDeviceToChannel

Supported from firmware version on:
04.01.05
Declaration:
extern "C" __declspec(dllexport)
int __stdcall DFCBindDeviceToChannel(int channelID, int deviceType, int deviceSerial,
 char *deviceIp, int *piError);

Exported: _DFCBindDeviceToChannel@20
Parameters:
int channelID Channel number, that the device shall be connected to.
int deviceType Type of the device to be connected; also serial number (next parameter) necessary for this indication. For a list of the assigned number of the device type see info-parameter of the function DFCGetInfoActiveChannel. A possible connection to the channel is deleted, if a value of -1 is transmitted and if no deciveIp is available.
int deviceSerial Serial number of the device to be connected.
char *deviceIp IP address of the device to be connected.
int *piError Error contains an error number according to table 1.5.3.
Return value:
0 Error at execution.
1 Carried out successfully.
Description:
Via this function an Active connecting device can be connected to a set channel number. Either device type and serial number or only the IP address need to be set. Via this function the connection can also be deleted.

 

3. Data structure

The used data structures are explained in the following.

3.1     Structure of the data records in the byte array

Each data record carries the appropriate data record description of the setup.
A use of the carried data record looks as follows:

Byte - number: 0 1 2 3... (length-1)
Byte - content:   DataNum Data of the data recrod.

All fields of a data record are delivered sequenced and with the field length (defined in the setup), possibly plus a termination symbol. Please note, that all fields, defined as ASCII fields, contain an additional termination symbol. Therefore a field, defined in the setup with a size of 1 byte, contains 2 byte in the "Data of the data record".

With the help of the analysing function for data record descriptions and list descriptions the "Data of the data record" can be interpreted. The termination symbol is contained in the indication of the field length of the relevant data record field.

 

3.2 Date and time in the byte array

The DateTime field of a data record looks as follows:

Byte - number Meaning Example: 27.02.1981 15:30:13
0 Date hundredth (0..255) 19
1 Date ones (0..99) 81
2 Month (0..12) 2
3 Day (1..31) 27
4 Stunde (0..23) 15
5 Minute (0..59) 30
6 Second (0..59) 13

 

4. System variables

The used system variables refer to various software fields. Each software field is activated via an appropriate prefix; separated via dot the name of the system variable follows. If necessary, they can be written or read via the DLL functions DFCSetGlobVar and DFCGetGlobVar.

4.1    Variables for the mobile communication, prefix: _MODEM_MC35i or MOBILE

Name Information
PHONE Telephone number for dial-in: up to 23 ASCII characters. Presetting: No
GPRS oder APN Access Point Name. Range: up to 49 ASCII characters. Presetting: No
USER User name for the internet remote access. Range: up to 20 ASCII characters. Presetting: No
PASSWORD Password for the internet remote access. Range: up to 20 ASCII characters. Presetting: No
HOST Destination IP or hostnames. Range: up to 59 ASCII characters. Presetting: No
PORT Destination Port. Range: 1 to 65535 digits. Presetting: No
HTTPSEND Destination path (sending prefix). Range: up to 39 ASCII characters. Presetting: No
ALIVE Seconds between two Alive data records. Range: 0 = off, 60 to 65500, number in seconds. Presetting: No
HTTPTIMEOUT Waiting period for the server reply after HTTP packet transmission. Range: 5000 to 65000, number in milliseconds. Presetting: No
HTTPTYPE Type of the used HTTP protocol. (1.0, 1.1, off) Range: 3 characters [1.0, 1.1, off] ASCII. Presetting: No
SIMPIN PIN to be set (temporary value). Range: 0 = Do not transmit, 1 to 999999999 digit. Presetting: No
SIMPUK PUK to be set (temporary value). Range: 0 = Do not transmit, 1 to 999999999 digit. Presetting: No
ROAMING Indication if posible to use foreign mobile-networks. Range: 0 = not allowed, 1 = allowed, number. Presetting: allowed
RESETTRIGGER This value set how many times the mobile-status should be 40, before the device makes an complete new dialing. Range: 1 to 32 Zahl. Presetting: 32
ATTACH Count, how often the device may make an calling betwen 00:00 - 23:59 clock to the Provider. Range: 3 - 50 digits, number. Presetting: 32
ERRORLEVEL Reaction behavior if errors occur. 0 = standard, 1 = ignore close from web server between records. Range: 5 digits, number. Presetting: 0
SMSKEY Password for incoming short messages, these will only processed if password matches. Could be generate over DatafoxStudioIV. Range: 42 hex-digit. Presetting: none

4.2    Variables for the operation, prefix: SERVICE

Name Information
DBLINPUT Time for anti-repeat lock for bookings. Range: 0 = Deactivated, 1 to 65499, number in seconds. Presetting: 60
DEMANDTIMER Timeout for keyboard shift. Range: 5 to 60, number in seconds. Presetting: 10

4.3    Variables for the access, prefix: ACCESS

Name Informationen
MASTERID The used Id of the Master of the column Reader:ZM. Range: 1 to 9999 digit. Presetting: 1

4.4    Variables for Bluetooth, prefix: BTH

Name Information
MODEL Name of the Bluetooth module.
VERSION Version of the module.
NAME Indicated name of the module.
ADDRESS Address of the module.
AUTH Authentication number.
MODE Mode of the module.

4.5    Variables for digital inputs/ outputs, prefix: IO

Name Information
INPUT.[0-7].Count Counter splitter of the digital input 0-7. Example. IO.INPUT.0. Count for the first digital input. Range: 0 to 4294967295, number in impulses. Presetting: From setup data.
INPUT.[0-7].Timeout Timeout of the digital input 0-7. Example: IO.INPUT.1.Timeout for the second digital input. Range: 0 to 65535, number in seconds. Presetting: From setup data.
INPUT.[0-7].Cycle Cycle of the digital input 0-7. Example: IO.INPUT.2.Cycle for the third digital input. Range: 0 to 65535, number in seconds. Presetting: From setup data.
INPUT.[0-7].Cavity Gibt die Kavität (pro Impuls n-Teile) des digitalen Eingangs 0-7 an. Beispiel: IO.INPUT.3.Cavity für vierten digital Eingang. Bereich: 0 bis 65535, Zahl in Sekunden. Vorgabe: Aus Setupdaten.
INPUT.[0-7].Strokes Gibt die Hubzahl (n-Impulse pro Teil) des digitalen Eingangs 0-7 an. Beispiel: IO.INPUT.4.Strokes für fünften digital Eingang. Bereich: 0 bis 65535, Zahl in Sekunden. Vorgabe: Aus Setupdaten.

4.6    Variables for the prefix: POWER

Name Information
BATTERY Current battery condition. Range: ok (= everything is alright) unknown (=check not available) low (=battery has to be replaced in order to guarantee the correct functionality).
LOW Indication of voltage for the low voltage disconnect. Range: 0 to 255, number in volt, the last digit represents the first position after decimal place (45 are 4.5V, 126 are 12.6V). Presetting: 0.
VOLTAGE Current supply voltage. Range: 0 to 36, floating point number with one position after decimal place and unit in Volt. e.g. 12.6V

4.7    Variables for the Active Connection, prefix: COM

Name Information
ACTIVE Activating/ Deactivating the Active Connection. Range: 0=off, 1=on, digit. Presetting: 0
NOTIFY Activating/ Deactivating the data record messaging. Range: 0=off, 1=on, digit. Presetting: 1
PRIO Priority of the device, for the queue in the DLL. Range: 0 to 65535, digit. Presetting: 0
HOST Address of the remote server for the Active Connection. Range: IP/Host. Presetting: 0.0.0.0
PORT Port number of the remote server. Range: 0 to 65535, digit. Presetting: 8000
RETRY Number of retries for connection establishment. Range: 0 to 65535, digit. Presetting: 3
TIMEOUT Timeout between the retry blocks (RETRY). Range: 0 to 4294967295, number in seconds. Presetting: 900
REPEAT Timeout for repeated data record messaging, if it was not queried. Range: 0 to 4294967295, number in seconds. Presetting: 60
HTTP Send records per HTTP with (W)LAN. Range: 0 = off, 1 = on, bool. Presetting: 0
KEY Password and modus für encrypted communication. Range: 42 hex-digits, hex-string. Presetting: empty
DNS1 IP from DNS-Servers to use name resolution in LAN/WLAN. Range: Ip in format ###.###.###.###. Presetting: 130.149.17.5
GROUPID To use with TimeboyIV devices. Using, please see: Transmission of Timeboy lists. Range: 0 to 19, number. Presetting: 0

4.8    Variables for sending records per Http, prefix: HTTP

Name Informationen
KEY Password for encrypt every field of HTTP-record. Could be generate over DatafoxStudioIV. Range: 42 hex-digit. Presetting: none

4.9    Variables for the system, prefix: SYSTEM

Name Informationen
STATUS Gives an infostring for the system status. READ-ONLY. Range: variable length (ca. 800), Text. Presetting: none