Knihovna XmlLib TXV 003 63.01 druhé vydání říjen 2012 změny vyhrazeny

Knihovna XmlLib TXV 003 63.01 druhé vydání říjen 2012 změny vyhrazeny 1 TXV 003 63.01

Historie změn Datum Vydání Popis změn Prosinec 2010 1 První vydání, popis odpovídá XmlLib_v13 Říjen 2012 2 Druhé vydání, popis odpovídá XmlLib_v15 OBSAH 1 Úvod...3 2 Datové typy...4 3 Konstanty...5 4 Globální proměnné...6 5 Funkce...6 5.1 Funkce SetAttributeValue...7 5.2 Funkce GetAttributeValue...8 6 Funkční bloky...9 6.1 Funkční blok fbparserlinexml...9 6.2 Funkční blok fbcomposerlinexml...11 7 Příklad použití...13 2 TXV 003 63.01

1 ÚVOD Knihovna XmlLib je standardně dodávaná jako součást programovacího prostředí Mosaic. Knihovna obsahuje funkční bloky umožňující práci s daty ve formátu Extensible Markup Language (XML). 1 2 3 4 5 <tag attribute= value >Text</tag> Obecná struktura XML 1 tag 2 atribut 3 hodnota atributu 4 text (obsah tagu) 5 ukončení tagu XmlLib ve verzi 1.3 nepokrývá kompletně všechny možnosti zápisu XML dat. Omezení knihovny jsou následující: - Komentáře jsou ignorovány - Maximální délka názvu tagu, atributu nebo obsahu tagu či atributu je 80 znaků - Maximální počet atributů pro jeden tag je deset - Není podporována sekce CDATA - Nejsou podporovány zástupné xml entity Následují obrázek ukazuje strukturu knihovny XmlLib v prostředí Mosaic Pokud chceme funkce z knihovny XmlLib použít v aplikačním programu PLC, je třeba nejprve přidat tuto knihovnu do projektu. Knihovna je dodávaná jako součást instalace prostředí Mosaic od verze v2.0.25. Knihovna je závislá na knihovně SysLib. 3 TXV 003 63.01

2 DATOVÉ TYPY V knihovně XmlLib jsou definovány následující datové typy: Datový typ TlineXML je struktura obsahující informace o aktuálně načteném elementu XML dokumentu. Význam jednotlivých položek je následující: Identifikátor Typ Význam TlineXML STRUCT Popis elementu XML.tag STRING Jméno tagu včetně klíčových znaků?, /, atd..txt STRING Text před vlastním tagem.atr.val ARRAY [1..10] OF STRING ARRAY [1..10] OF STRING Názvy prvních deseti atributů Hodnoty prvních deseti atributů 4 TXV 003 63.01

3 KONSTANTY V knihovně XmlLib jsou definovány následující konstanty: Konstanty se využívají při zpracování XML dokumentu. Význam konstant je následující: Identifikátor Typ Hodnota Význam XML_NULL_ USINT 16#00 konec řetězce XML_TAB_ USINT 16#09 tabelátor XML_LF_ USINT 16#0A novy řádek XML_CR_ USINT 16#0D konec řádku XML_SPACE_ USINT 16#20 ' ' znak 'mezera' XML_EXCLAMTION_ USINT 16#21 '!' znak 'vykřičník' XML_QUOTATION_MARKS_ USINT 16#22 '"' znak 'uvozovky' XML_DASH_ USINT 16#2D '-' znak 'pomlčka' XML_SLASH_ USINT 16#2F '/' znak 'lomítko' XML_LESS_THEN_ USINT 16#3C '<' znak 'menší než' XML_EQUAL_ USINT 16#3D '=' znak 'rovná se' XML_GREAT_THEN_ USINT 16#3E '>' znak 'větší než' XML_QUESTION_ USINT 16#3F '?' znak 'otazník' XML_MAX_STR_LEN UINT 80 max. velikost řetězce tagu/textu/atributu/hodnoty v XML XML_MAX_NUM_ATR UINT 10 max. počet atributu v XML řádků 5 TXV 003 63.01

4 GLOBÁLNÍ PROMĚNNÉ V knihovně XmlLib nejsou definovány žádné globální proměnné. 5 FUNKCE V knihovně XmlLib jsou definovány následující funkce. Funkční blok GetAttributeValue SetAttributeValue Popis Přečte hodnotu atributu daného jména Zapíše hodnotu do atributu daného jména 6 TXV 003 63.01

5.1 Funkce SetAttributeValue Knihovna : XmlLib Funkce SetAttributeValue pracuje nad strukturou popisující element XML dokumentu TlineXml, která se předává na vstupu linexml. V této struktuře nalezne podle zadaného jména na vstupu Name příslušný atribut a nastaví mu hodnotu předávanou na vstupu Value. Vstup AttrCnt udává počet platných atributů ve struktuře TlineXML. Pokud funkce nalezne požadovaný atribut a nastaví jeho hodnotu vrací TRUE. V případě, že atribut nebyl nalezen vrací FALSE. Popis proměnných : Proměnná Typ Význam VAR_INPUT Name STRING Jméno atributu Value STRING Nová hodnota atributu AttrCnt UINT Počet atributů ve struktuře linexml popisující element VAR_IN_OUT linexml TlineXML Popis zpracovaného XML elementu SetAttributeValue Návratová hodnota BOOL Pokud funkce nalezne požadovaný atribut a nastaví jeho hodnotu vrací TRUE. 7 TXV 003 63.01

5.2 Funkce GetAttributeValue Knihovna : XmlLib Funkce GetAttributeValue pracuje nad strukturou popisující element XML dokumentu TlineXml, která se předává na vstupu linexml. V této struktuře nalezne podle zadaného jména na vstupu Name příslušný atribut a vrátí jeho hodnotu. Popis proměnných : Proměnná Typ Význam VAR_INPUT Name STRING TRUE začne procházet od začátku XML dat, FALSE pokračuje tam, kde se minule skončilo AttrCnt UINT Počet atributů ve struktuře linexml popisující element VAR_IN_OUT linexml TlineXML Popis zpracovaného XML elementu GetAttributeValue Návratová hodnota STRING Hodnota atributu 8 TXV 003 63.01

6 FUNKČNÍ BLOKY V knihovně XmlLib jsou definovány následující funkční bloky: Funkční blok fbparserlinexml fbcomposerlinexml Popis Zpracovává elementy XML dokumentu Zapisuje elementy XML dokumentu 6.1 Funkční blok fbparserlinexml Knihovna : XmlLib Funkční blok fbparserlinexml slouží k rozebírání XML dokumentu po jednotlivých elementech. Na začátku rozebírání je nutné nastavit proměnnou start na hodnotu TRUE a proměnnou size na velikost proměnné, ve které je uložen XML dokument. Vlastní proměnná s XML dokumentem se předává na vstupu sourcexml. Výsledek zpracování se vrací ve struktuře TlineXML na vstupu linexml. Následující volání s proměnnou start nastavenou na hodnotu FALSE vrací další elementy XML v pořadí, jak za sebou v dokumentu následují. Výstupy funkčního bloku dávají další informace o načteném elementu. Výstup numatr udává počet atributů načteného tagu (0 až 10). Příznaky starttag a endtag v sobě nesou informaci o tom jestli se jedná o počáteční nebo koncový tag. Pokud mají oba příznaky hodnotu TRUE jedná se o nepárový tag. Výstup EOD je nastaven v případě, že byly přečteny všechny elementy XML dokumentu. 9 TXV 003 63.01

Popis proměnných : Proměnná Typ Význam VAR_INPUT start BOOL TRUE začne procházet od začátku XML dat, FALSE pokračuje tam, kde se minule skončilo size UDINT Velikost XML dokumentu v bytech VAR_IN_OUT sourcexml USINT První byte proměnné obsahující XML dokument linexml TlineXML Popis zpracovaného XML elementu VAR_OUTPUT numatr BOOL Počet atributů aktuálně načteného tagu starttag BOOL TRUE znamená začátek párového tagu (např. <ROOT>) endtag BOOL TRUE znamená konec párového tagu (např. </ROOT>) EOD BOOL Konec dat, dokument byl přečten až do velikosti udané proměnnou size Příklad použití (komentář... je potřeba nahradit zpracováním XML tagů) : VAR_GLOBAL xmltemplate : ARRAY [0..3] OF STRING := ['<data>', '<date></date>', '<value valid=""></value>', '</data>']; PROGRAM prgxmlexample VAR ParserLineXML : fbparserlinexml; linexml : TlineXML; VAR_TEMP i : UINT; ParserLineXML(start := 1, size := SIZEOF(xmlTemplate), sourcexml := void(xmltemplate), linexml := linexml); IF linexml.tag = 'data' THEN WHILE NOT ParserLineXML.EOD AND linexml.tag <> '/data' DO ParserLineXML(start := 0, sourcexml := void(xmltemplate), linexml := linexml); (*... *) END_WHILE; END_IF; END_PROGRAM 10 TXV 003 63.01

6.2 Funkční blok fbcomposerlinexml Knihovna : XmlLib Funkční blok fbcomposerlinexml slouží k zápisu XML dokumentu do proměnné. Na začátku zápisu je nutné nastavit proměnnou start na hodnotu TRUE a proměnnou size na velikost proměnné, ve které je bude výsledný XML dokument. Cílová proměnná se předává na vstupu destxml. Následující volání s proměnnou start nastavenou na hodnotu FALSE zapisuje další elementy XML za poslední zapsaný. Výsledný zápis je ovlivněn příznaky pairtag a numatr. Vstup numatr udává počet atributů zapisovaného tagu (0 až 10). Příznaky pairtag určuje zda bude zapsán tag jako párový (hodnota TRUE) nebo mu bude přidán na konec znak nepárového tagu (hodnota FALSE). Popis proměnných : Proměnná Typ Význam VAR_INPUT start BOOL TRUE začne ukládat od začátku XML dat, FALSE pokračuje tam, kde se minule skončilo pairtag BOOL Jedná se o párový tag numatr UINT Počet atributů size UINT Velikost proměnné pro XML dokument VAR_IN_OUT destxml USINT První byte proměnné pro vytvářený XML dokument linexml TlineXML Popis elementu, který bude zapsán do XML VAR_OUTPUT sizexml BOOL Aktuální velikost XML sizeerr BOOL Nedostatek místa pro zápis elementu 11 TXV 003 63.01

Příklad programu s funkčním blokem fbcomposerlinexml: VAR_GLOBAL xmlresult : ARRAY [0..511] OF USINT; PROGRAM prgxmlexample VAR ComposerLineXML : fbcomposerlinexml; linexml : TlineXML; VAR_TEMP i : UINT; FOR i := 0 TO 5 DO CASE i OF 0 : linexml.tag := 'data'; ComposerLineXML.pairTAG := true; ComposerLineXML.numAtr := 0; 1 : linexml.tag := 'date'; 2 : linexml.tag := '/date'; linexml.txt := DT_TO_STRINGF(GetDateTime(), '%TYYYY/MM/DD-hh:mm:ss'); 3 : linexml.tag := 'value'; linexml.atr[1] := 'valid'; linexml.val[1] := BOOL_TO_STRING( NOT(r0_p3_AI0.STAT.UNR OR r0_p3_ai0.stat.ovr)); ComposerLineXML.numAtr := 1; linexml.txt := ''; 4 : linexml.tag := '/value'; linexml.txt := REAL_TO_STRINGF(r0_p3_AI0.ENG, '%5.2f'); ComposerLineXML.numAtr := 0; 5 : linexml.tag := '/data'; linexml.txt := ''; END_CASE; ComposerLineXML(start := i = 0, size := SIZEOF(xmlResult)-1, destxml := void(xmlresult), linexml := linexml); END_FOR; xmlresult[composerlinexml.sizexml] := 0; END_PROGRAM Výsledkem programu je následující XML dokument, který může vypadat například takto: <data><date>2010/11/11-10:39:25</date><value valid= 1 >12.5</value></data> 12 TXV 003 63.01

7 PŘÍKLAD POUŽITÍ Následující příklad ukazuje možnosti použití funkčních bloků fbparserlinexml a fb ComposerLineXML. Pomocí bloku fbparserlinexml je vyčtena struktura XML dokumentu z proměnné xmltemplate. Načtená struktura je doplňována programem a opět převáděna na XML dokument, blokem fbcomposerlinexml. Program nejprve zkontroluje, zda-li je počáteční tag <data>. Pokud ano, hledá koncoví tag </date> před, který přidá datum zformátovaný funkcí z knihovny ToStringLib. Když narazí na tag <value> zkusí vyhledat atribut valid, do kterého doplní stav z analogového vstupu. Při nalezení koncového tagu </value> je před něj doplněn text z hodnotou analogového vstupu. Po sestavení celého dokumentu je přidán na konec znak 0. 13 TXV 003 63.01

VAR_GLOBAL xmltemplate : ARRAY [0..3] OF STRING := ['<data>', '<date></date>', '<value valid=""></value>', '</data>']; xmlresult : ARRAY [0..511] OF USINT; PROGRAM prgxmlexample VAR ParserLineXML : fbparserlinexml; ComposerLineXML : fbcomposerlinexml; linexml : TlineXML; VAR_TEMP i : UINT; ParserLineXML(start := 1, size := SIZEOF(xmlTemplate), sourcexml := void(xmltemplate), linexml := linexml); IF linexml.tag = 'data' THEN ComposerLineXML(start := 1, pairtag := NOT (ParserLineXML.startTAG AND ParserLineXML.endTAG), numatr := 0, size := SIZEOF(xmlResult)-1, destxml := void(xmlresult), linexml := linexml); WHILE NOT ParserLineXML.EOD AND linexml.tag <> '/data' DO ParserLineXML(start := 0, sourcexml := void(xmltemplate), linexml := linexml); IF linexml.tag = '/date' THEN linexml.txt := DT_TO_STRINGF(GetDateTime(), '%TYYYY/MM/DD-hh:mm:ss'); END_IF; IF linexml.tag = 'value' THEN FOR i := 1 TO ParserLineXML.numAtr DO IF linexml.atr[i] = 'valid' THEN linexml.val[i] := BOOL_TO_STRING( NOT(r0_p3_AI0.STAT.UNR OR r0_p3_ai0.stat.ovr)); EXIT; END_IF; END_FOR; END_IF; IF linexml.tag = '/value' THEN linexml.txt := REAL_TO_STRINGF(r0_p3_AI0.ENG, '%5.2f'); END_IF; ComposerLineXML(start := 0, pairtag := NOT (ParserLineXML.startTAG AND ParserLineXML.endTAG), numatr := ParserLineXML.numAtr, destxml := void(xmlresult), linexml := linexml); END_WHILE; END_IF; xmlresult[composerlinexml.sizexml] := 0; END_PROGRAM 14 TXV 003 63.01

15 TXV 003 63.01

TXV 003 63.01 Výrobce si vyhrazuje právo na změny dokumentace. Poslední aktuální vydání je k dispozici na internetu www.tecomat.com 16 TXV 003 63.01