1 General notes...............................................................................................................................................4
1.1 Use of the manual..................................................................................................................................4
1.2 Explanation of symbols..........................................................................................................................4
1.3 Requirements on the user .....................................................................................................................4
1.4 System requirements.............................................................................................................................4
2 Support information, installing and uninstalling .....................................................................................5
3 The EKS Ethernet ActiveX
3.1 EKS type library .....................................................................................................................................6
3.2 EKS control ............................................................................................................................................6
3.3 Overview of the methods, properties and events in the EKS Ethernet ActiveX
3.4.1 Open ..........................................................................................................................................8
3.4.2 Close ..........................................................................................................................................8
102030-02-10/12 Subject to technical modifications Page 3/20
Page 4
Manual EKS ActiveX® Module Ethernet TCP/IP
1 General notes
This ActiveX® module supports the integration of the Electronic-Key-System (EKS) Electronic-Key adapter with
Ethernet interface into your PC application. EKS can thus be used, e. g., in conjunction with process
visualization software. Data communication takes place using the TCP/IP protocol. The ActiveX
used here as a protocol driver.
With the aid of the EKS Ethernet ActiveX
EUCHNER Electronic-Key-System (EKS) from programming environments that support ActiveX (e. g. Microsoft
Visual Basic
®
) or user programs (e. g. Microsoft Excel®). For this purpose the ActiveX® module must be installed
®
module, communication can be straightforwardly established with the
and integrated into the related programming environment.
1.1 Use of the manual
This manual explains the functions of the EKS Ethernet ActiveX® module (order no. 100 665), from version
1.0.3.0.
1.2 Explanation of symbols
The following symbols are used in this manual to identify important instructions and useful information:
®
module is
Information!
Important information is provided to the user here.
Attention!
Risk of loss of data.
1.3 Requirements on the user
To be able to use the EKS Ethernet ActiveX® module correctly, you must have knowledge of the utilization of
ActiveX
must have read and understood the manual for the Electronic-Key adapter.
®
modules. To be able to straightforwardly integrate the EKS hardware into your overall system, you
1.4 System requirements
Hardware: Standard PC, with network connection
Software: TCP/IP protocol must be installed.
Operating system: Windows
Windows
Windows
Windows
Windows
Windows
®
XP
®
7 32-Bit
®
7 64-Bit
®
Server 2008 32-Bit
®
Server 2008 64-Bit
®
Server 2008 R2 64-Bit
Page 4/20 Subject to technical modifications 102030-02-10/12
Page 5
Manual EKS ActiveX® Module Ethernet TCP/IP
2 Support information, installing and uninstalling
To be able to use the EUCHNER EKS Ethernet ActiveX® module, you must first install it. Execute the
corresponding installation file, depending on the present operating system.
For Windows
For Windows
Information!
During the installation you will be prompted to enter an installation folder. Once the installation is
complete this folder will contain:
the ActiveX
this manual in Acrobat PDF format
The installation CD contains:
the programs EKS_Ethernet_ActiveX_Module.msi and EKS_Ethernet_ActiveX_Module_x64.msi
this manual in Acrobat PDF format
programming examples for various programming environments
To uninstall the ActiveX
®
32-Bit: EKS_ActiveX_Module.msi
®
64-Bit: EKS_ActiveX_Module_x64.msi
®
module
®
module or to obtain support information, proceed as follows:
1. In the operating system select Settings | Control Panel | Add/Remove Programs.
2. In the list of programs installed select the entry EUCHNER EKS Ethernet ActiveX Module. You can also
display support information here.
Information!
Always have the support information at hand when contacting EUCHNER.
3. To uninstall, click Change/Remove and follow the instructions in the uninstall dialog box.
102030-02-10/12 Subject to technical modifications Page 5/20
Page 6
Manual EKS ActiveX® Module Ethernet TCP/IP
3 The EKS Ethernet ActiveX® module
3.1 EKS type library
Description EUCHNER EKS Ethernet ActiveX module
Library EKSEthLib
File name ekseth.ocx
GUID { 36B62232-F5C4-4b46-BA4A-4B1F3F2C7974 }
Control EKSETH
3.2 EKS control
Control name EKSETH
File name ekseth.ocx
GUID { 72484DED-F77A-487c-9DC7-5751D10DBF17 }
Methods 6
Properties 13
Events 3
®
Before you can use the EKS Ethernet ActiveX
your project. To use an application that makes use of the ActiveX
computer.
module in your application, you must add the file ekseth.ocx to
®
module, you must install the module on your
Page 6/20 Subject to technical modifications 102030-02-10/12
Page 7
Manual EKS ActiveX® Module Ethernet TCP/IP
3.3 Overview of the methods, properties and events in the EKS Ethernet
ActiveX
The EKS Ethernet ActiveX® module contains methods, properties and events that can be integrated into your
programming environment.
Methods are used for establishing the connection and transferring data between the user program and the
EKS Electronic-Key adapter.
Properties are used for settings, reflect states and contain data read from the Electronic-Key or that are to
be written to the Electronic-Key.
Events report the completion of a method or signal an event (e. g. Electronic-Key inserted).
All methods, properties and events for the EKS object are listed in the following table.
Methods Section
Open 3.4.1 Open
Close 3.4.2 Close
Read 3.4.3 Read
Write 3.4.4 Write
getData 3.4.5 getData
setData 3.4.6 setData
Properties Section
Port 3.5.1 Port
IPAddress 3.5.2 IPAddress
KeyType 3.5.3 KeyType
LastState 3.5.4 LastState (ReadOnly)
StartAdress 3.5.5 StartAdress
CountData 3.5.6 CountData
Opening 3.5.7 Opening
Reading 3.5.8 Reading
Writing 3.5.9 Writing
KeyState 3.5.10 KeyState
Version 3.5.11 Version
Data 3.5.12 Data
Debug 3.5.13 Debug
102030-02-10/12 Subject to technical modifications Page 7/20
Page 8
Manual EKS ActiveX® Module Ethernet TCP/IP
3.4 Methods
3.4.1 Open
Description Opens the connection to the EKS with the properties set (IPAddress, Port, KeyType,
StartAdress, CountData ...).
Syntax Boolean = object.EKS.Open;
Comments The EKS must be connected and ready for operation before this method is used. The
method returns the value True (error-free execution) or False (status message has been
generated). If a status message has been generated the cause can be determined
using the property LastState. You will find an overview on the status messages for the
ActiveX
event OnKey is triggered. To obtain the actual state of the method Open, the property Opening can be polled. At the end of a program any open connection must be closed
again by calling the method Close.
Information!
The method Open starts a background process which establishes the communication with the device.
The return value True signals only, that the background process could be started. Hereby a physical
connection to the device is not checked.
®
module in section 3.5.4. On completion of the asynchronous execution the
3.4.2 Close
Description Closes the connection to the EKS.
Syntax Boolean = object.Close ();
Comments This method must be run at the end of the user program to clear the PC's interface.
3.4.3 Read
Description Method for reading data from the Electronic-Key (start address is defined in the property
StartAdress and the number of bytes of data in the property CountData)
Syntax Boolean = object.Read ();
Comments If the method returns True, the data will be read from the EKS. These data are to be
found in the property Data after the event OnRead is triggered. If False is returned it
was not possible to start the read request without errors. In this case the status number
is given in the property LastState. You will find an overview on the status messages for
the ActiveX
Information!
If you only want to read the data on the Electronic-Key, you do not need to explicitly call the method
Read. As soon as the event OnKey is triggered and the property KeyState = EKS_KEY_IN, the data on the actual key are available in the property Data. Prior to triggering the event OnKey the method
Read is executed internally in the ActiveX
®
module in section 3.5.4.
®
module.
3.4.4 Write
Description Method for writing data to the Electronic-Key (start address is defined in the property
StartAdress and the number of bytes of data in the property CountData)
Syntax Boolean = object.Write ();
Comments If the method returns True, the data will be written to the Electronic-Key. The write
request is complete after the event OnWrite is triggered. If False is returned it was not
possible to start the write request without errors. In this case the status number is given
in the property LastState. You will find an overview on the status messages for the
ActiveX
Page 8/20 Subject to technical modifications 102030-02-10/12
®
module in section 3.5.4
Page 9
Manual EKS ActiveX® Module Ethernet TCP/IP
3.4.5 getData
Description Reading access to the internal memory area of the ActiveX® module in which data read
by the method Read or the event OnKey are stored.
Syntax short =object.getData (short ByteIndex);
®
Comments With the method getData, the internal memory area of the ActiveX
Upon triggering the events OnRead or OnKey, the key data are available in the internal
memory and can be read using getData. In the properties StartAdress and CountData,
the range is defined from which byte data shall be read (method Read).
module can be read.
Information!
This is an additional way of accessing the internal memory of the ActiveX
®
module. This method can
be used in programming environments which do not offer array support. Usually, the internal memory
area is accessed via the property Data, see section 3.5.12.
3.4.6 setData
Description Writing access to the internal memory area of the ActiveX® module in which data to be
written by the method Write are stored.
Syntax object.setData (short ByteIndex, short DataValue);
®
Comments With the method setData, the internal memory area of the ActiveX
written. Upon triggering the event OnWrite, the data are written from the temporary
storage to the key. In the properties StartAdress and CountData, the range is defined
from which byte data shall be written (method Write).
Information!
This is an additional way of accessing the internal memory of the ActiveX
®
module. This method can
be used in programming environments which do not offer array support. Usually, the internal memory
area is accessed via the property Data, see section 3.5.12.
module can be
102030-02-10/12 Subject to technical modifications Page 9/20
Page 10
Manual EKS ActiveX® Module Ethernet TCP/IP
3.5 Properties
3.5.1 Port
Description Selects the port for the TCP connection
Syntax object.Port = String Value;
Comments Possible values are:
2444
2445
…
This property is applied by calling the method Open. The value must match the setting
on the EKS.
Data type String
Default value 2444
3.5.2 IPAddress
Description Selects the IP address for the TCP connection
Syntax object.IPAddress = String Value;
Comments Possible values are:
192.168.1.1
…
This property is applied by calling the method Open. The value must match the setting
on the EKS.
Data type String
Default value 192.168.1.1
3.5.3 KeyType
Description Defines the type of Electronic-Key used (read-only Electronic-Key* or read/write
Electronic-Key)
*Earlier transponder type. We do not recommend using this transponder type in new installations.
Syntax object.KeyType = KeyTypeConstants Value;
Comments Possible values are:
EKS_KEY_READWRITE = 1
EKS_KEY_READONLY = 8
This property is applied by calling the method Open.
Data type KeyTypeConstants (Enumeration)
Default value EKS_KEY_READWRITE
Page 10/20 Subject to technical modifications 102030-02-10/12
Page 11
Manual EKS ActiveX® Module Ethernet TCP/IP
3.5.4 LastState (ReadOnly)
Description Status of the last method called (0=OK or status number)
Syntax long =object.LastState;
Comments After a method is run (Read, Write, …) or after an event (OnKey, OnRead, ...), you can
determine here whether the method was run correctly. Status numbers in the range
from 0 to 127 (0
manual for the EKS Electronic-Key adapter. Status numbers between 128 and 255
(80
hex
to FF
) are generated by the ActiveX® module.
hex
Data type long
List of status numbers for the ActiveX
Attention!
Immediately after a method has been called or an event has been triggered you should poll the value
in the property LastState. Otherwise the property LastState could be overwritten by another method,
as only the status message from the last method run is given in the property LastState. This warning
also applies to internal methods that run in the background and that are not started by you.
Value Description
hex dec
0x90 144
0xA0 160
0xB0 176
0xB1 177
0xB2 178
0xC0 192
0xC1 193
0xE0 224
0xE1 225
0xE8 232
0xE9 233
0xEA 234
0xEB 235
0xEC 236
0xFF 255
WrongParam
The TCP port given in the property Port is not is the range >1024 und <65535
DeviceNotOpened
The connection to the EKS has not been opened, please run the method Open.
ReadTimeOut
It was not possible to correctly complete the method Read, the method has timed out.
WriteTimeOut
It was not possible to correctly complete the method Write, the method has timed out.
TimeOut
An internal method in the ActiveX
NothingToRead
The number of bytes of data to be read, as defined by the property CountData, is 0.
NothingToWrite
The number of bytes of data to be written, as defined by the property CountData, is 0.
OpenFailed
The method Open failed.
OpenActive
The method Open is still active.
Suspend
The computer will be placed in the suspend mode.
ResumeSuspend
The suspend mode has been terminated.
ConnectionTimeOut
Connection timeout to the EKS. It was not possible to establish a connection to the EKS in the time specified.
ConnectionLost
The connection to the EKS has been interrupted.
Reconnect
The connection to the EKS has been re-established.
Busy
The ActiveX
®
module is busy processing a method, the request cannot be run.
to 7F
hex
®
module:
®
) are generated by the EKS and are documented in the
hex
module has timed out.
102030-02-10/12 Subject to technical modifications Page 11/20
Page 12
Manual EKS ActiveX® Module Ethernet TCP/IP
3.5.5 StartAdress
Description The start address for the memory area on the Electronic-Key from which data are to be
read (Read) respectively from which data are to be written (Write).
Syntax object.StartAdress = short Value;
Comments Defines the start address for the data to be read using the method Read as well as the
start address for the data to be written using the method Write. Once the read method
has been completed successfully, the data will be available in the property Data. The
data to be written must also be saved there. The property StartAdress must be set prior
to calling the method so that the start address can be used for the subsequent call.
Information!
On the Electronic-Key read/write with 116 bytes freely programmable, the memory is organized in 4byte blocks. This means the start address must be given in the range byte number 0 to byte number
112, always in 4-byte steps (byte number 0, 4, 8 ... 112). Also the blocks written must always be a
multiple of 4-byte blocks (4, 8, 12 ... 116 bytes)!
However, during reading it is possible to access the memory byte-by-byte without the above mentioned
restriction for writing.
The Electronic-Key read/write also contains a unique 8-byte serial number. This number is written by
laser during the Electronic-Key production process and can never be changed or deleted. The serial
number can therefore not be changed. The serial number is used for secure distinction of every single
Electronic-Key. It is necessary that all 8 bytes are completely evaluated for reliable differentiation. The
serial number is appended to the freely programmable memory. The serial number can be read by
entering the start address byte number 116 and the number of bytes 8.
Data type short
Default value 0
3.5.6 CountData
Description The number of bytes of data to be written or read.
Syntax object.CountData = short Value;
Comments Defines the number of bytes of data to be read using the method Read as well as the
number of bytes of data to be written using the method Write. Once the read method
has been completed successfully, the data will be available in the property Data. The
data to be written must also be saved there. The property CountData must be set prior
to calling the methods so that the number of bytes of data to be read/written can be
used for the subsequent call.
Information!
On the Electronic-Key read/write with 116 bytes freely programmable, the memory is organized in 4byte blocks. This means the start address must be given in the range byte number 0 to byte number
112, always in 4-byte steps (byte number 0, 4, 8 ... 112). Also the blocks written must always be a
multiple of 4-byte blocks (4, 8, 12 ... 116 bytes)!
However, during reading it is possible to access the memory byte-by-byte without the above mentioned
restriction for writing.
The Electronic-Key read/write also contains a unique 8-byte serial number. This number is written by
laser during the Electronic-Key production process and can never be changed or deleted. The serial
number can therefore not be changed. The serial number is used for secure distinction of every single
Electronic-Key. It is necessary that all 8 bytes are completely evaluated for reliable differentiation. The
serial number is appended to the freely programmable memory. The serial number can be read by
entering the start address byte number 116 and the number of bytes 8.
Data type short
Default value 4
Page 12/20 Subject to technical modifications 102030-02-10/12
Page 13
Manual EKS ActiveX® Module Ethernet TCP/IP
3.5.7 Opening
Description State of the method Open
Syntax bool =object.Opening;
Comments If the property Opening returns the value True, the method Open is currently active. As
long as this method is active it is not possible to call any other methods
Data type bool
Default value false
3.5.8 Reading
Description State of the method Read
Syntax bool = object.Reading;
Comments If the property Reading returns the value True, the method Read is currently active. The
data on the Electronic-Key are not yet available in the property Data. As long as this
method is active it is not possible to call any other methods.
Data type bool
Default value false
3.5.9 Writing
Description State of the method Write
Syntax bool =object.Writing;
Comments If the property Writing returns the value True, the method Write is currently active. The
write request is still active and the data have not yet been completely written to the
Electronic-Key. As long as this method is active it is not possible to call any other
methods.
Data type bool
Default value false
3.5.10 KeyState
Description Returns the status of the last event.
Syntax bool =object.KeyState;
Comments Possible parameters are:
EKS_KEY_IN = 1
EKS_KEY_OUT = 2
EKS_KEY_OTHER = 3
Data type KeyStateConstants (Enumeration)
Default value EKS_KEY_OUT
3.5.11 Version
Description Returns the actual version of the EKS Ethernet ActiveX® module
Syntax String Value = object.Version;
Data type String
102030-02-10/12 Subject to technical modifications Page 13/20
Page 14
Manual EKS ActiveX® Module Ethernet TCP/IP
3.5.12 Data
Description Memory area in which data read by the method Read or the event OnKey, or data to be
written using the method Write, are stored.
Syntax short =object.Data (short ByteIndex);
Comments The property Data represents a cache for all data that are read from the Electronic-Key
and that are to be written to the Electronic-Key. The data for the key are provided or
assigned in bytes. After the event OnRead or OnKey is triggered, the data on the Key
are available in the property Data. Once the event OnWrite has been triggered the data
have been written from the property Data to the Key. In the properties StartAdress and
CountData, the range is defined from which byte data shall be read (method Read)
respectively data shall be written (method Write).
Data type short
Default value -12851 (CDCD
The default value is present if no data have been read from the Electronic-Key or there
is no Electronic-Key in the Electronic-Key adapter.
3.5.13 Debug
Description If the property Debug is set to the value true, the method Close is called for all instances
at the end of a debug session in a programming environment.
Syntax bool =object.Debug;
Comments The ActiveX
some programming environments. The property Debug must, e. g., be set to true in
Microsoft Visual Basic
that the TCP connection is closed at the end of the debug session without explicitly
calling the method Close. If a debug session is terminated before the method Close is
called, the connection to the EKS remains open. If the property Debug is true, then the
TCP connections for all ActiveX
Data type bool
Default value false
Information!
Please ensure you only set the property Debug to true during the debug session. If one control is
destructed on the use of several instances of the ActiveX
closed in all other instances.
)
hex
®
module is not correctly destructed at the end of the debug session in
®
and Microsoft Excel® for the development of the application so
®
instances are closed at the end of the debug session.
®
module, the connection to the EKS will be
Page 14/20 Subject to technical modifications 102030-02-10/12
Page 15
Manual EKS ActiveX® Module Ethernet TCP/IP
3.6 Constants
This section lists all constants that are used in the properties for the EKS Ethernet ActiveX® module. The
constants are also listed in the description of the properties and methods in which they are used.
KeyStateConstants (used in the property KeyState)
Value Constant
1 EKS_KEY_IN
2 EKS_KEY_OUT
3 EKS_KEY_OTHER
KeyTypeConstants (used in the property KeyType)
Value Constant
1 EKS_KEY_READWRITE
8 EKS_KEY_READONLY
102030-02-10/12 Subject to technical modifications Page 15/20
Page 16
Manual EKS ActiveX® Module Ethernet TCP/IP
3.7 Events
3.7.1 OnKey
Description This event must be defined in the user program and is called by the ActiveX® module.
Syntax Private Subobject_OnKey ()
Comments To use this event, a method with the name OnKey must be defined in the user program.
This method is called by the ActiveX
(Electronic-Key inserted /Electronic-Key removed, etc.). The user can then poll which
event has occurred in the user program (EKS_KEY_IN, EKS_KEY_OUT,
EKS_KEY_OTHER). The event OnKey with the property KeyState=EKS_EVENT_KEYIN is triggered when there is a new Electronic-Key in the
EKS. The user can then read the data on the key from the property Data without
calling the method Read. The event OnKey with the property
KeyState=EKS_KEY_OUT is triggered on the removal of the Electronic-Key. The event
OnKey with the property KeyState=EKS_KEY_OTHER is triggered when the ActiveX
module detects a status. The related status number can be read in the property
LastState.
Information!
The recognition, if a key is present or not, is signalled via a network telegram (see manual of the
Electronic-Key adapter EKS Ethernet TCP/IP). The telegram is sent immediately from the key adapter
to the presently connected ActiveX
®
client after placement or removal of the key.
®
module as soon as there is a change in the EKS
®
3.7.2 OnRead
Description This event must be defined in the user program and is called by the ActiveX® module.
Syntax Private Subobject_OnRead ()
Comments To use this event a method with the name OnRead must be defined in the user
program. This method is called by the ActiveX
completed in the ActiveX
®
module. The related status number can be read in the
®
module as soon as the method Read is
property LastState.
3.7.3 OnWrite
Description This event must be defined in the user program and is called by the ActiveX® module.
Syntax Private Subobject_OnWrite ()
Comments To use this event a method with the name OnWrite must be defined in the user
program. This method is called by the ActiveX
completed in the ActiveX
®
module. The related status number can be read in the
property LastState.
®
module as soon as the method Write is
Page 16/20 Subject to technical modifications 102030-02-10/12
Page 17
Manual EKS ActiveX® Module Ethernet TCP/IP
4 Examples
Information!
The installation CD contains examples for the integration of the EKS Ethernet ActiveX
various programming environments.
®
module in
4.1 Establishing connection with EKS Electronic-Key adapter
The following example shows how the method Open can be used. The values shown correspond to the default
settings for the properties. It may be necessary to change these values for your application.
1. Set required values in the properties. These settings can also be made in the programming tool (e.g. Visual
EKS.Port = "2444"
EKS.KeyType = EKS_KEY_READWRITE
2. Set the required read/write parameters (can also be set after opening the interface):
EKS.StartAdress = 0
EKS.CountData = 4
3. Open interface:
EKS.Open
®
) using the properties of the object EKS:
Basic
Information!
If the default values shown are used, it is sufficient to use just the one line with the call EKS.Open.
102030-02-10/12 Subject to technical modifications Page 17/20
Page 18
Manual EKS ActiveX® Module Ethernet TCP/IP
4.2 Example event call in Visual Basic®
Private Sub EKS_OnKey( )
Select Case KeyState
Case EKS_EVENT_KEYIN
User functions KeyIn
' e. g. Read key data from the EKS Electronic-Key
' Attention! It is not necessary to call the Read method!
for i=0 to 123
KeyData = KeyData & EKS.Data(i)
Next i
Case EKS_EVENT_KEYOUT
User functions KeyOut
' e. g. Delete Electronic-Key data in the user software
KeyData = "-"
Case EKS_EVENT_OTHER
User functions Other
' e. g. Poll status number
StatusNumber = EKS.LastState
End Select
End Sub
Page 18/20 Subject to technical modifications 102030-02-10/12