Active X control pro DataLab IF/EIB

Hlavní stránka▹Produkty▹Průmyslový počítačový systém DataLab▹Jednotky vstupů a výstupů DataLab	20.9.2011 \|

Active X control pro DataLab IF/EIB

Active X control pro DataLab IF/EIB slouží k jednoduchému zpřístupnění toku dat (vstupů i výstupů) uvnitř systémové instalační sběrnice EIB.

Active X control je komponenta s programovým rozhraním odpovídajícím standardu Microsoft COM (Coponent Object Model), a lze ji proto použít ve všech nástrojích, prohlížečích a vývojových prostředcích, které s touto technologií umějí pracovat. To je například Internet Explorer, MS Visual Basic, MS C# a všechny programy, které umějí spustit Visual Basic Script, Java Script nebo C# script.

Poznámka:

Jednotky DataLab IF/EIB jsou plně programově podporovány v systému rychlého vývoje vizualizačních a řídicích aplikací Control Web. Active X prvek tvoří most mezi rozhraním ovladače pro systém Control Web na jedné straně a technologií COM na straně druhé. Z tohoto důvodu tato dokumentace nepopisuje řadu témat, která jsou již zahrnuta v popisu ovladače DataLab IF/EIB pro Control Web. Pro pochopení práce s jednotkami DataLab IF/EIB jsou ale tyto informace důležité.

Například aby bylo možno s jednotkou DataLab IF/EIB komunikovat, je nutné ji správně konfigurovat (definovat čísla komunikačních kanálů, nastavit měřicí rozsahy apod.). Konfigurace je uložena v tzv. parametrickém souboru (s příponou '.PAR') a před první komunikací je nutno specifikovat ve kterém souboru je žádaná konfigurace uložena (viz sekci Příprava ke komunikaci).

Doporučujeme proto nejprve se seznámit s vlastní dokumentací ovladače.

Instalace a přístup k Active X komponentě

Aby mohl operační systém všem zájemcům Active X komponentu správně poskytnout, musí být komponenta v systému korektně nainstalována. To představuje zajištění dvou věcí:

přístup k DLL komponenty

DLL může být v zásadě umístěna zcela kdekoli. Pro její umístění existuje pouze jediné omezení — jakmile je komponenta jednou zapojena do registru, nesmí být její DLL přemístěna. Operační systém by pak podle záznamů v registru hledal DLL na chybném místě a nic by samozřejmě nenašel.

Je-li proto potřeba DLL někam přemístit, je neprve nutné odstranit informace z registru. Teprve pak lze DLL přemístit a celý přesun se posléze ukončí novým zápisem informací do registru.

DLL komponenty je přímo obsahem instalace; její jméno je 'dldrv.dll'. Pro úspěšnoou funkci stačí tuto DLL nakopírovat na cílové místo.

záznamy v registru operačního systému

bez záznamů v registru není koponenta schopna práce. Po výběru místa a po okopírování DLL komponenty na to místo je proto nutné komponentu zaregistrovat.

To je jednoduché, protože komponenta má standardní rozhraní nutné pro registraci, takže pro tuto akci lze použít program regsvr32.exe, který je přímo součástí operačního systému. Pro registraci komponenty je třeba spustit příkazový řádek, přepnout se do adresáře s DLL a následně použitím regsvr32 komponentu zaregistrovat:

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

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

c:\Directory\With\DLL>

Opačná operace, zrušení registrace, se provede velmi podobně. Pouze se volání programu regsvr32 rozšíří o volbu /u (uninstall):

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

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

c:\Directory\With\DLL>

Jakmile je komponenta na správném místě a správně zaregistrována, nebrání již jejímu vytvoření a použití vůbec nic. Základní prostředek, jak komponentu vytvořit, je použít některou z jejích identifikací. Lze použít buď jméno (ProgId) komponenty, nebo unikátní identifikátor (GUID).

Active X control pro DataLab IF/EIB má následující identifikátory:

ProgId (jméno)	`ControlWeb.DrvAxDlIfEib`
GUID (číslo)	`{5D9DAB98-D82D-4090-984A-C017768BE03C}`

Tedy, pomocí těchto identifikátorů lze komponentu vytvořit například následovně:

v HTML stránce

<head>
  <object id="DataLab" classid="clsid:5D9DAB98-D82D-4090-984A-C017768BE03C"></object>
</head>

ve VBScriptu

set DataLab = CreateObject( "ControlWeb.DrvAxDlIfEib" )

v jScriptu

DataLab = new ActiveXObject( "ControlWeb.DrvAxDlIfEib" );

Je zřejmé, že každé jiné prostředí může mít jiný způsob, jak komponentu vytvořit i použít, ale to je samozřejmě v každém z těchto prostředí dobře popsáno. Active X control pro DataLab IF/EIB je zcela standardní a budou pro něj proto platit všechna pravidla a postupy jako pro každý jiný COM objekt.

Princip práce komponenty

Programové rozhraní Active X komponenty je velmi jednoduché, neboť i princip práce s ním je jednoduchý. Operace čtení (neboli přenos dat z technologie či hardware do počítače — programu) i operace zápisu (opačný přenos dat z počítače — programu do technologie či hardware) vždy probíhají ve třech krocích:

shromáždění a připravení seznamu dat, která se mají číst nebo zapsat,
zahájení čtení nebo zápisu a průběh těchto operací,
zpracování informací o dokončení čtení nebo zápisu.

Tyto tři kroky komunikace probíhají dávkově. Po shromáždění požadavků se zahájí komunikace a dokud tato probíhající komunikace neskončí není možné zahájit komunikaci novou. Neboli, dokud nejsou dokončeny (přečteny nebo zapsány) všechny komunikace v dávce, nelze zahájit dávku novou; dovnitř jedné dávky nelze vsunout jinou. Avšak — jednotlivá čtení i zápisy lze i uvnitř běžící dávky připravovat pro dávku novou.

Tak jak je v ovladačích systému Control Web a vůbec v systému Control Web zvykem, jsou všechny jednotlivé měřené či zapisované body označeny číslem (indexem), pomocí kterých se identifikují. V principu je možné pro identifikaci použít jakákoli čísla, technicky jsou však všechna možná čísla omezena aktuálním nastavením hardware (tedy DataLab IF/EIB), které je přesně zapsáno v samostatném konfiguračním, parametrickém, souboru (takový soubor má obyčejně příponu 'PAR').

Přesný význam obsahu parametrického souboru je součástí základní dokumentace ovladače jednotek DataLab IF/EIB. Pro informaci, jak takový parametrický soubor může vypadat, viz ukázku:

[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

Procedury Active X komponenty lze rozdělit do třech skupin — procedury pro nastavení a řízení, procedury pro zahajování komunikace a procedury pro zpracování výsledků komunikace.

Většina procedur používá pro informování o stavu komunikace (chybách nebo výsledcích) výčtový typ TCommunicationState, jehož jednotlivé položky jsou tyto:

Hodnota	Význam
`csSuccess (0)`	úspěch, komunikace v pořádku
`csPending (1)`	komunikace stále probíhá (buď již začala, anebo je vstup již jednou ke čtení označen)
`csNotRunning (2)`	Active X control neběží, nebyla dosud zavolána procedura `LoadPARFile()`
`csFailure (3)`	komunikace skončila chybou — nikoli programovou chybou, ale chybou protokolu komunikace — například zařízení neodpovědělo, byla přečtena neplatná data, apod.
`csBadIndex (4)`	vstup či výstup s uvedeným indexem není znám, index neodpovídá konfiguraci určené parametrickým souborem
`csBadDirection (5)`	byl učiněn pokus zapsat do vstupu nebo pokus číst výstup, zvolený směr komunikace neodpovídá parametrickému souboru

Příprava ke komunikaci

(procedury jsou zapsány v notaci MS Visual Basic)

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

první procedura, kterou je nutné zavolat, aby Active X komponenta mohla korektně pracovat. Procedura se pokusí parametrický soubor 'PARFilePath' zpracovat a když zpracování skončí úspešně, zkonfiguruje komponentu podle obsahu tohoto souboru.

Význam parametrů a návratové hodnoty je následující:

Parametr	Význam
`PARFilePath`	cesta k parametrickému souboru. Vzhledem k tomu, že operační systém nezaručuje přesné nastavení aktuálního adresáře, je doporučeno uvádět tuto cestu kompletní, včetně disku a adresářů.
`ErrorMessage`	chybové hlášení. Parametr je naplněn zprávou o chybě, nepodaří-li se parametrický soubor korektně použít; v opačném případě zůstává hodnota tohoto parametru nezměněná.
`návratová hodnota`	výsledek konfigurace. Proběhlo-li načtení a konfigurace úspěšně, je návratová hodnota `1 (true)`. V opačném případě (když nastala chyba) je návratová hodnota funkce `0 (false)`.

Sub Run()

procedura, která spojí Active X komponentu s EIB sběrnicí. Dokud není tato procedura zavolána, není možné se sběrnicí komunikovat a komunikační procedury vracejí chyby komunikace. Proceduru má smysl volat jen po předešlé úspěšné konfiguraci Active X prvku procedurou LoadParFile.

Procedura pracuje v páru s procedurou Stop(), takže je možné ji (stejně jako Stop()) volat opakovaně a podle potřeby komunikaci se sběrnicí řízeně navazovat či ukončovat.

Sub Stop()

procedura, která odpojí Active X komponentu od EIB sběrnice. Jakmile je tato procedura zavolána, není možné se sběrnicí komunikovat a komunikační procedury vracejí chyby komunikace. Proceduru má smysl volat jen po předešlé úspěšné konfiguraci Active X prvku procedurou LoadParFile a předešlém spuštění procedurou Run().

Procedura pracuje v páru s procedurou Run(), takže je možné ji (stejně jako Run()) volat opakovaně a tak podle potřeby komunikaci se sběrnicí navazovat či ukončovat.

Zahájení komunikace

(procedury jsou zapsány v notaci MS Visual Basic)

Function MarkInput(ByVal InputIndex As Integer) As TCommunicationState

procedura, pomocí které se označí vstup k měření, volání této procedury zařadí vstup s indexem InputIndex do fronty požadavků čtení. Volání procedury nezpůsobuje (nezahajuje) čtení.

Význam parametrů a návratové hodnoty je následující:

Parametr	Význam
`InputIndex`	index vstupu (platný podle parametrického souboru). Není-li index platný, vrátí procedura návratovou hodnotu `csBadIndex`.
`návratová hodnota`	výsledek označení, typicky `csSuccess`, `csPending` nebo `csNotRunning`.

Vstupy, které nejsou pomocí této procedury označeny pro čtení, Active X control nebude číst.

Podle aktuálního stavu měření lze rozlišit dvě situace a tím i dvoje chování vstup — buď vstup je součástí probíhající dávky, pak procedura vrátí csPending (1), vstup neoznačí a následující dávka měření nebude tento vstup číst; anebo vstup není součástí probíhající dávky (například jeho čtení právě skončilo) a tehdy procedura vstup označí a vstup bude v následující dávce změřen.

Function ReadInputs() As TCommunicationState

procedura, která po označení vstupů (pomocí MarkInput) zahájí komunikaci (čtení) všech označených vstupů. Procedura zahajuje novou čtecí komunikační dávku.

Význam návratové hodnoty je následující:

Parametr	Význam
`návratová hodnota`	výsledek zahájení dávky, typicky `csSuccess` byla-li dávka zahájena a stihla se hned ukončit; nebo `csPending`, pokud již dávka probíhá či pokud dávka byla zahájena a nestihla se dosud ukončit.

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

procedura, pomocí které se označí výstup pro zápis, volání této procedury zařadí výstup s indexem OutputIndex do fronty požadavků zápisu. Volání procedury nezpůsobuje (nezahajuje) zápis.

Význam parametrů a návratové hodnoty je následující:

Parametr	Význam
`OutputIndex`	index výstupu (platný podle parametrického souboru). Není-li index platný, vrátí procedura návratovou hodnotu `csBadIndex`.
`Value`	hodnota, která má být zapsána. Podle typu výstupu lze do řetězce zadávat například čísla (`10.00`) nebo logické hodnoty (`true`) apod.
`návratová hodnota`	výsledek označení, typicky `csSuccess`, `csPending` nebo `csNotRunning`.

Vstupy, které nejsou pomocí této procedury označeny pro zápis, Active X control nebude zapisovat.

Podle aktuálního stavu zápisu lze rozlišit dvě situace a tím i dvě chování vstup — buď výstup je součástí probíhající dávky, pak procedura vrátí csPending (1), výstup neoznačí a následující dávka měření nebude tento výstup zapisovat; anebo výstup není součástí probíhající dávky (například jeho zápis právě skončil) a tehdy procedura výstup označí a výstup bude v následující dávce zapsán.

Function WriteOutputs() As TCommunicationState

procedura, která po označení výstupů (pomocí MarkOutput) zahájí komunikaci (zápis) všech označených výstupů. Procedura zahajuje novou zapisovací komunikační dávku.

Význam návratové hodnoty je následující:

Parametr	Význam
`návratová hodnota`	výsledek zahájení dávky, typicky `csSuccess` byla-li dávka zahájena a stihla se hned ukončit; nebo `csPending`, pokud již dávka probíhá či pokud dávka byla zahájena a nestihla se dosud ukončit.

Zpracování výsledků

(procedury jsou zapsány v notaci MS Visual Basic)

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

procedura (událost), kterou Active X vyvolá po dokončení čtení vstupu, ať již čtení skončilo úspěchem nebo chybou. Okamžikem volání této události lze vstup opětovně označit pro nové čtení (pomocí MarkInput).

Význam parametrů a návratové hodnoty je následující:

Parametr	Význam
`CommunicationState`	výsledek komunikace; skončilo-li čtení úspěchem má parametr hodnotu `csSuccess`, skončilo-li čtení komunikační chybou má parametr hodnotu `csFailure`.
`InputIndex`	index vstupu, jehož čtení skončilo.
`ErrorCode`	chyba komunikace; parametr má nenulovou hodnotu (neboli obsahuje kód chyby) pouze je-li `CommunicationState = csFailure`.
`Value`	přečtená hodnota. Parametr je platný pouze je-li `CommunicationState = csSuccess`.

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

procedura (událost), kterou Active X vyvolá po dokončení zápisu výstupu, ať již zápis skončil úspěchem nebo chybou. Okamžikem volání této události lze výstup opětovně označit pro nový zápis (pomocí MarkOutput).

Význam parametrů a návratové hodnoty je následující:

Parametr	Význam
`CommunicationState`	výsledek komunikace; skončil-li zápis úspěchem má parametr hodnotu `csSuccess`, skončil-li zápis komunikační chybou má parametr hodnotu `csFailure`.
`OutputIndex`	index výstupu, jehož zápis skončil.
`ErrorCode`	chyba komunikace; parametr má nenulovou hodnotu (neboli obsahuje kód chyby) pouze je-li `CommunicationState = csFailure`.

Ukázka kódu VBScript pro komunikaci s 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>

Další ukázku a příklad lze najít v instalaci v souboru 'VBStest.htm', který ukazuje přímé zapojení (včetně kousků programu uvedeného v ukázce) do akcí v rámcí HTML stránky.

Upozornění:

Pro správnou práci ukázky (a nejen pro ni) je nutné Active X prvku překládat správný parametrický soubor. To představuje především zápis správného umístění tohoto souboru do parametru procedury LoadPARFile. Proto asi nejspíše, bez úpravy dodané ukázky, nebude komponenta schopna práce. Teprve po zápisu správné cesty k parametrickému souboru do 'VBStest.htm' bude komponenta pracovat správně.

Některé hodnoty parametru `ErrorCode` událostí `OnInputRead` a `OnOutputWritten`

Obecné chyby:

Hodnota	Význam
`ecCommunicationTimeout (1)`	zařízení po stanovenou dobu neodpovědělo
`ecValueProcessing (2)`	při zpracování údajů z/pro zařízení došlo k převodní chybě
`ecUnknownElement (3)`	zařízení požadovaný prvek nezná
`ecBadDirection (4)`	pokus číst výstup nebo zapsat výstup
`ecValueTruncated (5)`	při zpracování údajů z/pro zařízení byla hodnota ořezána

Chyby specifické pro DataLab IF/EIB:

Hodnota	Význam
`65537 (ecDeviceUnplugged)`	jednotka odpojena — DataLab IF/EIB buď nemá připojené napájení (je rozpojen USB kabel) anebo sériové číslo správně zapojené jednotky neodpovídá nastavení parametru `id` parametrického souboru.
`65538 (ecNoEIBConnection)`	není připojena EIB sběrnice — DataLab IF/EIB nemá spojení s EIB sítí.
`65539 (ecUnACKed)`	odeslaný EIB paket nebyl žádnou přijímací jednotkou potvrzen.
`65540 (ecReadResponseTimeout)`	požadavek na řízení čtení hodnoty z EIB vypršel, zařízení nepodpovědělo do uplynutí stanovené doby.
`65541 (ecLineBusy)`	zápis dat se nezdařil, neboť EIB síť je zaneprázdněna
`65542 (ecTransceiverFault)`	zápis dat se nezdařil, neboť se nepodařilo odeslat data do EIB sítě
`65543 (ecOutputQueueOverflow)`	zápis dat se nezdařil, neboť vymezená délka výstupní fronty byla naplněna (chyba se může objevit pouze pokud je délka výstupní fronty omezena)

Instalace a přístup k Active X komponentě

Princip práce komponenty

Příprava ke komunikaci

Zahájení komunikace

Zpracování výsledků

Ukázka kódu VBScript pro komunikaci s DataLab IF/EIB

Některé hodnoty parametru ErrorCode událostí OnInputRead a OnOutputWritten

Některé hodnoty parametru `ErrorCode` událostí `OnInputRead` a `OnOutputWritten`