|
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.
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:
All data items to be read and/or written are collected
and prepared (see Communication
preparation). Read and/or write operation is started (see Start of communication). 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: | Value | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Parameter | Meaning |
|---|
| 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: | Value | Meaning |
|---|
| 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: | Value | Meaning |
|---|
| 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) |
| 