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 IO/USB
- 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's name is
'dldrv.dll'. Just copying of this file to the target
directory is enough to install the control.
- registration in the Windows Registry
The Active X 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's DLL 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 /u dldrv.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 Active X 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's name (called ProgId). While CLSID is definitely unique,
the ProgId is much easier to type and remember.
Active X control for DataLab IO/USB can be referred by the following
identifiers:
- ProgId (name)
ControlWeb.DrvAxDlUsb
- CLSID (128-bit globally unique number)
{45D4DCAF-DCE7-4484-9321-8E12C7B7E8DB}
So it is possible to create the instance of the control
using these identifiers: in the HTML page: | <head>
<object id="DataLab" classid="clsid:45D4DCAF-DCE7-4484-9321-8E12C7B7E8DB"></object>
</head> | in VBScript: | set DataLab = CreateObject( "ControlWeb.DrvAxDlUsb" ) | in JScript: | DataLab = new ActiveXObject( "ControlWeb.DrvAxDlUsb" ); |
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 IO/USB 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/O device to computer) and/or writing (data transfer from
computer to I/O device) 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/O requests 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 Active X 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 IO/USB driver for
Control Web documentation. Here is a short
example just to demonstrate the concept:
[device]
status_channel = 99
[module_a]
module_type = digital_output
first_channel = 100
control_channel = 200 This file defines the device status
(information) data channel with handle 99 and also defines that
there is only one digital output module in the device
slot A with data channel handles 100 to 107 (the digital
output module has 8 digital outputs). One more data channel with
handle 200 is defined as a module control channel (see the module
specification for the purpose of the control channel). If the control is
initialized with this parameter file, data channels indexed 99,
100–107 a 200
can be read or written.
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. |
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 IO/USB
Dim DataLab
set DataLab = CreateObject("ControlWeb.DrvAxDlUsb")
sub Init()
DataLab.LoadPARFile "dl.par", ""
end sub
sub WriteOutputs()
DataLab.MarkOutput 200, State
DataLab.WriteOutputs()
end sub
sub DataLab_OnOutputWritten( CommunicationStatus, Index, ErrorCode )
alert "Written: " + CStr( Index ) + " with status: " + CStr( CommunicationStatus )
end sub
sub ReadAnalog()
DataLab.MarkInput 500
DataLab.ReadInputs()
end sub
sub DataLab_OnInputRead( CommunicationStatus, Index, ErrorCode, Value )
alert "Read: " + CStr( Index ) + " with status: " + CStr( CommunicationStatus ) + " as value: " + CStr( Value )
end sub
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 IO/USB 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 |
Value | Meaning |
---|
65537 | device unplugged: DataLab IO/USB is without power (applicable to externally
powered devices only) or the USB cable is unplugged. This error
cannot occur on the DataLab IO/USB devices
embedded to DataLab PC computers,
because their wiring is internal. | 65538 | bad module: There is a different module in the
particular slot than stated in the parameter file. | 65539 | module does not support reading of the control
channel: an attempt to read control channel of module which
does not support this function. | 65540 | module does not support writing of the control
channel: an attempt to write control channel of module
which does not support this function. |
|