FB_XmlRead - - Funktionsübersicht
|
Typ |
Funktionsbaustein |
|
Verfügbar ab |
V1.0.8.0 |
|
Übernommen aus |
- |
|
Implementiert |
- |
Der Funktionsbaustein FB_XmlRead ermöglicht das Lesen (Parsing) einer XML-Datei, die sich im Dateisystem der Steuerung oder in einem erweiterten Speicher (z. B. SD-Speicherkarte) befindet. Informationen zum Dateisystem finden Sie im Kapitel zur Flash-Speicheranordnung im Programmierhandbuch Ihrer Steuerung.
Der Inhalt der XML-Datei, d. h. die XML-Elemente mit den zugehörigen Attributen und Werten, wird in einem Array des Typs XmlItems im Anwendungsspeicher der Steuerung abgelegt. Sie müssen dieses Array deklarieren und dem verknüpften Eingang i_refXmlItems am Funktionsbaustein zuweisen.
HINWEIS: Zu Beginn jedes Lesevorgangs wird der Inhalt dieses Arrays gelöscht.
Bei der Ausführung des Funktionsbausteins wird der Eingang i_refXmlItems intern zur weiteren Verwendung gespeichert. Wenn während der Ausführung des Funktionsbausteins (q_xBusy = TRUE) eine Online-Änderung erkannt wird, werden die intern verwendeten Variablen mit dem aktuellen Wert des Eingangs aktualisiert.
HINWEIS: Weisen Sie i_refXmlItems während der Funktionsbausteinausführung keiner anderen Variablen zu.
Die Anzahl der Einheiten (Summe der Elemente und Attribute), die im Array gespeichert werden können, wird vom Parameter Gc_udiXmlMaxNumOfItems in der GPL vorgegeben.
Das Array enthält Felder des Typs STRING zur Speicherung der Namen und Werte der Elemente und Attribute. Sie können die Länge dieser STRINGs über den globalen Parameter Gc_uiXmlLengthOfString festlegen. Wenn ein in der Datei zu lesender Wert die vorgegebene Länge überschreitet, wird der ursprüngliche Wert abgeschnitten. Wenn mindestens ein Wert abgeschnitten wurde, wird das über den Ausgang q_xWarnValueTruncated signalisiert.
HINWEIS: Der Ausgang q_xWarnValueTruncated ist nur gültig, wenn der Ausgang q_xDone auf TRUE steht.
Die hierarchische Struktur der Elemente aus der XML-Datei wird vom Parameter uiParentIndex für jede Array-Einheit des Typs XmlItems angegeben. Weitere Informationen finden Sie unter uiParentIndex - Beispiel für die von uiParentIndex angegebenen hierarchischen Beziehungen.
|
Eingang |
Datentyp |
Beschreibung |
|---|---|---|
|
i_xExecute |
BOOL |
Der Funktionsbaustein führt bei steigender Flanke an diesem Eingang einen Lesevorgang für die angegebene XML-Datei durch. Siehe auch das Kapitel Verhalten der Funktionsbausteine mit dem Eingang i_xExecute. |
|
i_sFilePath |
STRING[255] |
Dateipfad der zu lesenden XML-Datei. Wenn ein Dateiname ohne Dateierweiterung angegeben wird, fügt der Funktionsbaustein die Erweiterung .xml hinzu. |
|
i_sXPathItemToRead |
STRING[255] |
XPath-Ausdruck zur Adressierung der aus der XML-Datei auszulesenden Elemente. Standardwert: '//*' |
|
i_xReadElementsOnly |
BOOL |
Wenn dieser Eingang den Wert TRUE aufweist, werden die Namen und Werte der Elemente gelesen und im Anwendungspuffer gespeichert. Wenn dieser Eingang den Wert FALSE aufweist, werden ebenfalls die Attribute mit den zugehörigen Werten gelesen und im Anwendungspuffer gespeichert. |
|
i_refXmlItems |
REFERENCE TO XmlItems |
Der von der Anwendung bereitgestellte Puffer zur Speicherung der aus der angegebenen XML-Datei ausgelesenen Elemente. Der Puffer wird bei jeder Ausführung des Funktionsbausteins gelöscht. |
|
Ausgang |
Datentyp |
Beschreibung |
|---|---|---|
|
q_xDone |
BOOL |
Wenn dieser Ausgang auf TRUE gesetzt wird, wurde die Ausführung erfolgreich abgeschlossen. |
|
q_xBusy |
BOOL |
Wenn dieser Ausgang auf TRUE gesetzt wird, bedeutet das, dass der Funktionsbaustein ausgeführt wird. |
|
q_xError |
BOOL |
Wenn dieser Ausgang auf TRUE gesetzt wird, wurde ein Fehler identifiziert. Für weitere Informationen, siehe q_etResult und q_etResultMsg. |
|
q_etResult |
ET_Result |
Stellt Diagnose- und Statusinformationen in Form numerischer Werte bereit. Wenn q_xBusy = TRUE, dann gibt der Wert den Status an. Wenn q_xDone oder q_xError = TRUE, dann entspricht der Wert dem Ergebnis. |
|
q_sResultMsg |
STRING[80] |
Stellt zusätzliche Diagnose- und Statusinformationen in Form von Textmeldungen bereit. |
|
q_udiNumOfItemsRead |
UDINT |
Verweist auf die Gesamtanzahl der aus der XML-Datei ausgelesenen Elemente und Attribute. |
|
q_xWarnValueTruncated |
BOOL |
Wenn dieser Ausgang den Wert TRUE aufweist, wurde mindestens ein Wert abgeschnitten. HINWEIS: Der Ausgang wird gemeinsam mit q_xDone aktualisiert. |
Weitere Informationen zum Signalverhalten der Basiseingänge und -ausgänge finden Sie im Kapitel Verhalten der Funktionsbausteine mit dem Eingang i_xExecute.
Verwendung von Variablen des Typs POINTER TO … oder REFERENCE TO …
Der Funktionsbaustein POINTER stellt Eingänge und/oder Ein-/Ausgänge vom Typ POINTER TO… oder REFENCE TO… bereit. Mithilfe eines derartigen Zeigers bzw. einer derartigen Referenz greift der Funktionsbaustein auf den adressierten Speicherbereich zu. Bei einer Online-Änderung kann es vorkommen, dass die Speicherbereiche zu neuen Adressen verschoben wurden. Infolgedessen ist ein Zeiger bzw. eine Referenz dadurch ungültig. Um Fehler in Verbindung mit ungültigen Zeigern zu vermeiden, müssen Variablen des Typs POINTER TO… oder REFERENCE TO… zyklisch aktualisiert werden oder zumindest am Anfang des Zyklus, in dem sie verwendet werden.
XPath-Ausdrücke zur Definition des zu lesenden Inhalts
Um nur ein einzelnes Element oder eine ganze Gruppe von Elementen aus der XML-Datei auszulesen, verwenden Sie die Syntax der XPath-Sprache (XML Path). Der zu lesende Inhalt wird vom Eingang i_XpathItemToRead vorgegeben.
HINWEIS: Der Funktionsbaustein FB_XmlRead unterstützt eine Teilgruppe der mit den XPath-Ausdrücken bereitstehenden Funktionen.
Die nachstehende Tabelle enthält die unterstützten XPath-Ausdrücke:
|
XPath-Ausdruck |
Beschreibung |
|---|---|
|
//* |
Ermöglicht die Auswahl aller Elemente im Dokument. |
|
/ |
Gibt den absoluten Pfad eines Elements an. |
|
/…/child::* |
Ermöglicht die Auswahl aller untergeordneten Elemente eines Knotens. |
|
/…/descendant::* |
Ermöglicht die Auswahl aller von einem Knoten abstammenden Elemente. |
|
/…/<elementname> |
Ermöglicht die Auswahl aller Elemente eines Knotens mit dem angegebenen Namen. |
|
/…/<elementname>[<n>] |
Ermöglicht die Auswahl des n. Elements des Knotens mit dem angegebenen Namen. |
|
/…/<elementname>[@<attribut>] |
Ermöglicht die Auswahl aller Elemente des Knotens mit dem angegebenen Namen und Attribut. |
|
/…/<elementname>[@<attribut>=<wert>] |
Ermöglicht die Auswahl aller Elemente des Knotens mit dem angegebenen Namen, Attribut und Wert. |
HINWEIS: Den Aussagen, d. h. den Ausdrücken in eckigen Klammern [], kann ein Schrägstrich / zusammen mit einem Elementnamen folgen, wenn das nächste untergeordnete Element adressiert werden soll.
Beispiel: /…/<elementname>[<n>]/<elementname>
