Description fonctionnelle du bloc FB_XmlRead
|
Type : |
Bloc fonction |
|
Disponible à partir de la version : |
V1.0.8.0 |
|
Hérite de : |
- |
|
Met en œuvre : |
- |
Le bloc fonction FB_XmlRead permet de lire (analyser) un fichier XML stocké dans le système de fichiers du contrôleur ou dans la mémoire étendue (une carte SD, par exemple). Pour obtenir des informations sur le système de fichiers, reportez-vous au chapitre Organisation de la mémoire Flash du guide de programmation de votre contrôleur.
Le contenu du fichier XML, à savoir les éléments XML ainsi que leurs attributs et valeurs, est stocké dans un tableau de type XmlItems, dans la mémoire du contrôleur dédiée aux applications. Vous devez déclarer ce tableau et l'affecter à l'entrée associée i_refXmlItems au niveau du bloc fonction. Le contenu du tableau est effacé au début de chaque opération de lecture.
Lors de l’exécution du bloc fonction, l’entrée i_refXmlItems est stockée en interne pour une utilisation ultérieure. Si une modification en ligne est détectée lors de l’exécution du bloc fonction (q_xBusy = TRUE), les variables utilisées en interne sont mises à jour avec la valeur actuelle de l’entrée.
NOTE : Ne réattribuez pas i_refXmlItems à une autre variable lors de l’exécution du bloc fonction.
Le paramètre Gc_udiXmlMaxNumOfItems de la liste GPL indique le nombre d'éléments (éléments + attributs) pouvant être stockés dans le tableau.
Les noms et les valeurs des éléments et attributs sont stockés dans des champs de type STRING. Vous pouvez définir la longueur de ces champs STRINGs avec le paramètre global Gc_uiXmlLengthOfString. Lorsque la valeur à lire dans le fichier dépasse cette longueur, la valeur d'origine est tronquée. Dès qu'une valeur au moins est tronquée, l'information est communiquée par la sortie q_xWarnValueTruncated.
NOTE : La sortie q_xWarnValueTruncated est valide à condition que la sortie q_xDone soit sur TRUE.
La structure hiérarchique des éléments du fichier XML est indiquée par le paramètre uiParentIndex pour chaque élément du tableau correspondant au type XmlItems. Pour plus d'informations, reportez-vous à la sectionExemple de relations hiérarchiques indiquées par uiParentIndex.
|
Entrée |
Type de données |
Description |
|---|---|---|
|
i_xExecute |
BOOL |
Le bloc fonction exécute l'opération de lecture concernant le fichier XML indiqué sur un front montant de cette entrée. Reportez-vous également au chapitre Comportement des blocs fonction avec l'entrée i_xExecute. |
|
i_sFilePath |
STRING[255] |
Chemin d'accès au fichier XML qui doit être lu. Lorsque le nom de fichier est indiqué sans extension, le bloc fonction ajoute l'extension .xml. |
|
i_sXPathItemToRead |
STRING[255] |
Expression XPath pour l'adressage des éléments à lire dans le fichier XML. Valeur par défaut : '//*' |
|
i_xReadElementsOnly |
BOOL |
Si cette entrée a la valeur TRUE, les noms d'éléments et leurs valeurs sont lus et stockés dans la mémoire tampon de l'application. Si cette entrée a la valeur FALSE, les attributs et leurs valeurs sont également lus et stockés dans la mémoire tampon de l'application. |
|
i_refXmlItems |
REFERENCE TO XmlItems |
Mémoire tampon fournie par l'application pour le stockage des éléments lus dans le fichier XML indiqué. La mémoire tampon est effacée à chaque exécution du bloc fonction. |
|
Sortie |
Type de données |
Description |
|---|---|---|
|
q_xDone |
BOOL |
Si cette sortie est TRUE, l'exécution s'est effectuée correctement. |
|
q_xBusy |
BOOL |
Si cette sortie est TRUE, le bloc fonction est en cours d'exécution. |
|
q_xError |
BOOL |
Si cette sortie est TRUE, une erreur a été détectée. Pour plus d'informations, reportez-vous à q_etResult et q_etResultMsg. |
|
q_etResult |
ET_Result |
Fournit des informations de diagnostic et d'état sous la forme d'une valeur numérique. q_xBusy = True, la valeur indique l'état. Si q_xDone ou q_xError = True, la valeur indique le résultat. |
|
q_sResultMsg |
STRING[80] |
Fournit des informations de diagnostic et d'état sous la forme d'un message textuel. |
|
q_udiNumOfItemsRead |
UDINT |
Nombre total d'éléments et d'attributs lus dans le fichier XML. |
|
q_xWarnValueTruncated |
BOOL |
Si cette sortie prend la valeur TRUE, une valeur au moins a été tronquée. NOTE : La sortie est mise à jour en même temps que q_xDone. |
Pour plus d'informations sur les signaux des entrées et sorties basiques, reportez-vous au chapitre Comportement des blocs fonction avec l'entrée i_xExecute.
Utilisation des variables de type POINTER TO … ou REFERENCE TO …
Le bloc fonction fournit des entrées et/ou des entrées/sorties de type POINTER TO… ou REFENCE TO…. En utilisant ce type de pointeur ou référence, le bloc fonction a accès à la zone de mémoire adressée. En cas de modification en ligne, les zones de mémoire peuvent être déplacées aux nouvelles adresses et par conséquent un pointeur ou une référence peut devenir non valide. Pour éviter les erreurs liées à des pointeurs non valides, les variables de type POINTER TO… ou REFERENCE TO… doivent être mises à jour régulièrement, au moins au début du cycle où elles sont utilisées.
Expressions XPath définissant le contenu à lire
Pour lire un élément ou un groupe d'éléments dans le fichier XML, utilisez la syntaxe du langage XPath (XML Path). Le contenu à lire est défini par l'entrée i_XpathItemToRead.
NOTE : Le bloc fonction FB_XmlRead prend en charge une partie des fonctions fournies par les expressions XPath.
Le tableau suivant répertorie les expressions XPath prises en charge :
|
Expression XPath |
Description |
|---|---|
|
//* |
Sélectionne tous les éléments du document. |
|
/ |
Indique un chemin d'accès absolu à un élément. |
|
/…/child::* |
Sélectionne tous les éléments enfants du nœud. |
|
/…/descendant::* |
Sélectionne tous les éléments descendants du nœud. |
|
/…/<nom_élément> |
Sélectionne tous les éléments du nœud qui correspondent au nom indiqué. |
|
/…/<nom_élément>[<n>] |
Sélectionne le nème élément du nœud qui correspond au nom indiqué. |
|
/…/<nom_élément>[@<attribut>] |
Sélectionne tous les éléments du nœud qui correspondent au nom et à l'attribut indiqués. |
|
/…/<nom_élément>[@<attribut>=<valeur>] |
Sélectionne tous les éléments du nœud qui correspondent au nom et à la paire attribut/valeur indiqués. |
NOTE : Les prédicats, ou expressions entre crochets ([]), peuvent être suivis d'une barre oblique (/) et d'un nom d'élément pour identifier l'élément enfant suivant.
Exemple : /…/<nom_élément>[<n>]/<nom_élément>
