Moravian instruments, Inc., source: https://www.mii.cz/art?id=302&lang=409, printed: 19.06.2024 21:22:36

Main pageProductsDataLab industrial input/output systemDataLab - Industrial input/output devices

Active X control for DataLab IF/EIB
 Active X control for DataLab can be used to easily read from and/or write to the DataLab IF/EIB industrial input/output devices.

List of sections:

Installation and Active X component access
Principles of the component operation
Communication preparation
Start of communication
Processing of communication results
Example of the VBScript code communicating with DataLab IF/EIB
Some values of the ErrorCode parameter of OnInputRead and OnOutputWritten event procedures

Active X control is a component with the programmatic interface complying to the Microsoft COM (Component Object Model) specifications. It is possible to use it in all programs, browsers and development tools, which are compatible with this standard, e.g. Microsoft Internet Explorer, Visual Basic, C#, all programs capable to run Visual Basic Script, Java Script or C# script etc.

Remark:

The DataLab IF/EIB devices are fully supported in the Control Web rapid application development system. The DataLab IF/EIB driver for Control Web is highly optimized and carefully tested. Because the Control Web driver interface is very simple and efficient, the Active X control is designed to bridge the Control Web driver code on one side and the COM Automation clients on the other side.

This is why this documentation does not duplicate number of topics covered by DataLab IF/EIB driver for Control Web documentation.

For instance it is necessary to configure the software prior to the first communication. The configuration for each particular device (e.g. used modules, numbers of communication channels, input ranges etc.) is defined in the text configuration file called parameter file and it is necessary to load this file first (see Setup chapter).

Installation and Active X component access

Every COM component must be properly installed to enable the COM subsystem to offer the component to all clients who require it. Proper installation contains two steps:

component binary file (DLL—Dynamic Link Library) placement

The DLL file can ge placed almost anywhere in the file system, but there is one limitation—it is not possible to move the DLL file after the component is registered. The COM subsystem searches the DLL file in the directory defined in the system Registry database so it could not find the file if it is moved after the registration.

If it is necessary to move the DLL file, the COM component must be unregistered first. Then the file can be moved to another directory and registered again.

The DLL file is contained on the installation CD-ROM; it'sname is 'dldrv.dll'. Just copying of this file to the target directory is enough to install the control.

registration in the Windows Registry

The ActiveX control cannot work properly without registering in the Windows Registry database. It is necessary to register the control after copying it to the destination directory.

Registration is quite simple, because the control contains routines to register itself. These routines can be called by the Windows standard command-line utility regsvr32.exe. It is necessary to open the Windows Command Prompt ('cmd.exe'), change directory to the location where the control'sDLL is copied and run the regsvr32 tool:

c:\Documents And Settings\User\Documents>cd \Directory\With\DLL

c:\Directory\With\DLL>regsvr32 dldrv.dll

c:\Directory\With\DLL>

The regsvr32 utility can also unregister the control, just add the /u(un-install) command-line parameter:

c:\Documents And Settings\User\Documents>cd \Directory\With\DLL

c:\Directory\With\DLL>regsvr32 /udldrv.dll

c:\Directory\With\DLL>

When the component is copied to the destination directory and properly registered, it can be used by any COM Automation clients. All COM components (including ActiveX controls) are identified by the Globally Unique Identifiers (often referred as GUIDs). GUID is 128-bit long number, guaranteed to be globally unique (no other component uses the same GUID). The GUID identifying control base class are also called CLSID (CLaSs IDentifier). It is also possible to refer the component by it'sname (called ProgId). While CLSID is definitely unique, the ProgId is much easier to type and remember.

Active X control for DataLab IF/EIB can be referred by the following identifiers:

ProgId (name)

ControlWeb.DrvAxDlIfEib

CLSID (128-bit globally unique number)

{5D9DAB98-D82D-4090-984A-C017768BE03C}

So it is possible to create the instance of the control using these identifiers:

in theHTML page:
<head>
  <object id="DataLab" classid="clsid:5D9DAB98-D82D-4090-984A-C017768BE03C"></object>
</head>
in VBScript:
set DataLab = CreateObject( "ControlWeb.DrvAxDlIfEib" )
inJScript:
DataLab = new ActiveXObject( "ControlWeb.DrvAxDlIfEib" );

Obviously different programs or languages uses different ways to create the control instance. Refer to the particular program/language reference how to do it. The Active X control for DataLab IF/EIB fully complies to the COM standard, so it can be handled like any other COM component.

Principles of the component operation

The Active X control for DataLab IO/USB Automation (formerly OLE Automation) interface is quite simple. Reading (data transfer from I/Odevice to computer) and/or writing (data transfer from computer to I/Odevice) are always performed in three steps:

  1. All data items to be read and/or written are collected and prepared (see Communication preparation).

  2. Read and/or write operation is started (see Start of communication).

  3. Read/write operation results are handled (see Processing of communication results).

These three steps are performed in batches. When all I/Orequests are collected and the communication (data transfer to/from the device) is started, it is not possible to start another communication until the first one finishes. In other words the communication cannot start until all data items requested in the previous batch are read or written. But is possible to prepare next communication batch (mark data items) while the current batch is in progress.

The ActiveX control follows the Control Web convention to assign a unique numeric handle (index) to all data items. This handle identifies the particular item. Generally any unsigned integer number can be used to identify each data item, but these numbers must be defined in the configuration file (called parameter file and usually with the 'PAR' extension).

Parameter file is ordinary text file following the INI file conventions. Thorough description of the parameter file syntax can be found in the DataLab IF/EIB driver for Control Web documentation. Here is a short example just to demonstrate the concept:

[device]
id = 2401290
status_channel = 1
output_queue_length_channel = 2

[interface]
address = 1.1.3
ACK_method = all

[objects]
objects = transmitter_with_status, scaling255, 1/0/0..1/0/1
objects = transmitter_with_status, string, 2/0/0..2/0/1

The Active X component Automation interface methods can be divided into three groups—methods for device setup and control, methods for starting of communication and methods for communication results handling.

Majority of methods uses enumeration type TCommunicationState to inform the program about communication state and results. Possible values of this data type are:

ValueMeaning
csSuccess (0)

success, communication OK

csPending (1)

communication in progress (communication either started or this channel already marked for read or write)

csNotRunning (2)

Active X control not initialized, the LoadPARFile method was not called

csFailure (3)

communication failed, e.g. invalid data was read etc.

csBadIndex (4)

channel with this index (handle) was not defined in the parameter file

csBadDirection (5)

an attempt to write to input channel or to read output channel

Communication preparation

(procedures are described using MS Visual Basic syntax)

Function LoadPARFile( ByVal PARFilePath As String, ByRef ErrorMessage As String ) As Integer

The first procedure, which must be called to properly initialize the Active X component. The passed parameter file named 'PARFilePath' will be processed and the component will be configured according to this file.

Parameter description:

ParameterMeaning
PARFilePath

Path to parameter file. Because the current directory can vary, it is recommended to specify the file name including full path (disk letter and directories).

ErrorMessage

Parameter contains error message if the parameter file cannot be read. The string contents remains unchanged otherwise.

return value

If the parameter file is found and parsed properly, the return value is 1 (true). The 0 (false) is returned if the function fails.

Sub Run()

procedura, kter spoj Active X komponentu sEIB sbrnic. Dokud nen tato procedura zavolna, nen mon se sbrnic komunikovat a komunikan procedury vracej chyby komunikace. Proceduru m smysl volat jen po pedel spn konfiguraci Active X prvku procedurou LoadParFile.

Procedura pracuje vpru sprocedurou Stop(), take je mon ji (stejn jako Stop()) volat opakovan a podle poteby komunikaci se sbrnic zen navazovat i ukonovat.

Sub Stop()

procedura, kter odpoj Active X komponentu od EIB sbrnice. Jakmile je tato procedura zavolna, nen mon se sbrnic komunikovat a komunikan procedury vracej chyby komunikace. Proceduru m smysl volat jen po pedel spn konfiguraci Active X prvku procedurou LoadParFile a pedelm sputn procedurou Run().

Procedura pracuje vpru sprocedurou Run(), take je mon ji (stejn jako Run()) volat opakovan a tak podle poteby komunikaci se sbrnic navazovat i ukonovat.

Start of communication

(procedures are described using MS Visual Basic syntax)

Function MarkInput( ByVal InputIndex As Integer ) As TCommunicationState

Calling of this procedure marks the particular input for reading (input with the InputIndex will be entered to the read request queue). Note call of this procedure does not start reading!

Parameter description:

ParameterMeaning
InputIndex

Index of the input channel as defined in the parameter file. If the passed index is not valid, the call will return with csBadIndex return value.

return value

Result of the call, usually csSuccess, csPending or csNotRunning.

Inputs not marked with this procedure will not be read by the Active X control.

If the marked input is already included into currently communicated batch of input channels, the call will return csPending (1) and the channel will not be communicated in the next batch. Otherwise the marked input will be read during the next communication.

Sub ReadInputs() As TCommunicationState

This procedure will actually start the communication batch. All input channels previously successfully marked for reading (using MarkInput) will be included into communication batch and the batch will be started (read request will be sent to the device).

Parameter description:

ParameterMeaning
return value

Result of the call, usually csSuccess if the read operation was initiated and also successfully finished or csPending if the read operation is already in progress or if the read operation was initiated but has not finished yet.

Function MarkOutput( ByVal OutputIndex As Integer, ByVal Value As String ) As TCommunicationState

Calling of this procedure marks will mark the particular output channel for writing (output with the OutputIndex will be entered to the write request queue). Note call of this procedure does not start writing!

Parameter description:

ParameterMeaning
OutputIndex

Index of the output channel as defined in the parameter file. If the passed index is not valid, the call will return with csBadIndex return value.

Value

Value which should be written. The string should contain numerical values (10.00), logical values (true) or arbitrary strings according to the channel type.

return value

Result of the call, usually csSuccess, csPending or csNotRunning.

Outputs not marked with this procedure will not be written by the Active X control.

If the marked output is already included into currently communicated batch of output channels, the call will return csPending (1) and the channel will not be communicated in the next batch. Otherwise the marked output will be written during the next communication.

Sub WriteOutputs() As TCommunicationState

This procedure will actually start the communication batch. All output channels previously successfully marked for writing (using MarkOutput) will be included into communication batch and the batch will be started (write request will be sent to the device).

Parameter description:

ParameterMeaning
return value

Result of the call, usually csSuccess if the write operation was initiated and also successfully finished or csPending if the write operation is already in progress or if the write operation was initiated but has not finished yet.

Processing of communication results

(procedures are described using MS Visual Basic syntax)

Event OnInputRead( ByVal CommunicationState As TCommunicationState, ByVal InputIndex As Integer, ByVal ErrorCode As Integer, ByVal Value As String )

Event procedure called by Active X component when the read operation is finished. Note this procedure is called in both success and failure cases. From the time this procedure is invoked the particular input channel can be again marked for read (using MarkInput).

Parameter description:

ParameterMeaning
CommunicationState

Communication result: csSuccess if the read succeeded, csFailure if the read operation failed.

InputIndex

Index of input channel which read finished.

ErrorCode

Error code. This parameter is non-zero only if the CommunicationState = csFailure.

Value

Read value. This parameter is valid only if CommunicationState = csSuccess.

Event OnOutputWritten( ByVal CommunicationState As TCommunicationState, ByVal InputIndex As Integer, ByVal ErrorCode As Integer )

Event procedure called by Active X component when the write operation is finished. Note this procedure is called in both success and failure cases. From the time this procedure is invoked the particular output channel can be again marked for writing (using MarkOutput).

Parameter description:

ParameterMeaning
CommunicationState

Communication result: csSuccess if the writing succeeded, csFailure if the write operation failed.

OutputIndex

Index of output channel which writing finished.

ErrorCode

Error code. This parameter is non-zero only if the CommunicationState = csFailure.

Example of the VBScript code communicating with DataLab IF/EIB

<html>

<head>
  <title>DataLab IF/EIB ActiveX sample</title>
  <!-- "object" variant which allows using of events -->
  <object id="DataLabIFEIB" classid="clsid:5D9DAB98-D82D-4090-984A-C017768BE03C"></object>
</head>

<script language="VBScript">

<!-- HTML part -->
Dim Value

<!-- DataLabIFEIB part -->
sub Init()
  rem Start timer to write value periodically
  window.SetInterval "OnInterval", 100
  rem REPLACE SOMEWHERE WITH VALID LOCAL PATH
  DataLabIFEIB.LoadPARFile "SOMEWHERE\example.par", ""
  DataLabIFEIB.Run()
end sub

sub OnInterval()
  rem ReadInput() -- use it for requested read
  WriteOutputs()
end sub

sub WriteOutputs()
  DataLabIFEIB.MarkOutput 100000, Value
  DataLabIFEIB.WriteOutputs()
end sub

sub DataLabIFEIB_OnOutputWritten( CommunicationStatus, Index, ErrorCode )
  Value = Value + 1
  If Value >= 256 Then
    Value = 0
  End If
end sub

sub ReadInput()
  DataLabIFEIB.MarkInput 100001
  DataLabIFEIB.ReadInputs()
end sub

sub DataLabIFEIB_OnInputRead( CommunicationStatus, Index, ErrorCode, Value )
  If ( Index = 100001 ) and ( CommunicationStatus = 0 ) Then
    AnalogBar.style.width = CLng( Value ) / 255 * 500
  End If 
end sub

Init()
</script>

<body>

<form>
  Read scaling value (group 1/0/1): <span id="AnalogBar" style="background: red;"></span>
</form>

</body></html>

Another example can be found on the installation CD-ROM in the file 'dltest.htm'. This file demonstrates inserting of the control to the HTML page and communication with DataLab IF/EIB from the Internet Explorer application.

Warning:

It is necessary to initialize the Active X control with the proper parameter file to successfully run the examples. This can be ensured by updating the parameter file path in the call of LoadPARFile procedure. Otherwise the examples will not work properly.

Some values of the ErrorCode parameter of OnInputRead and OnOutputWritten event procedures

Common errors:

ValueMeaning
ecCommunicationTimeout (1)

the device did not respond for defined time

ecValueProcessing (2)

error occurred when converting channel value types

ecUnknownElement (3)

the device does not contain requested channel

ecBadDirection (4)

an attempt to read output or to write to input

ecValueTruncated (5)

the value was truncated when converting channel value types

Error codes specific for DataLab IF/EIB device:

ValueMeaning
65537 (ecDeviceUnplugged)

the unit is disconnected —DataLab IF/EIB either does not have supply connected (the USB cable is disconnected) or the serial number of the correctly connected unit does not correspond to the parameter setting id of the parametric file

65538 (ecNoEIBConnection)

EIB bus is not connected —DataLab IF/EIB there is no connection with the EIB network

65539 (ecUnACKed)

the sent EIB package was not confirmed by any receiving unit.

65540 (ecReadResponseTimeout)

the request to read value from EIB network expired, the device did not respond in defined time

65541 (ecLineBusy)

the writing of data was unsuccessful, as the EIB network is busy

65542 (ecTransceiverFault)

the writing of data was unsuccessful, as the data was not transmitted by hardware

65543 (ecOutputQueueOverflow)

the writing of data was unsuccessful, as the limited length of output queue was reached (the error can occur only if the length of the output queue is limited)