FB_XmlRead Descrizione funzionale

Panoramica

Tipo:	Blocco funzione
Disponibile a partire da:	V1.0.8.0
Proveniente da:	-
Implementa:	-

Descrizione funzionale

Il blocco funzione FB_XmlRead consente di leggere (analizzare) un file XML ubicato nel file system del controller, oppure in una memoria estesa (ad esempio, una scheda di memoria SD). Per informazioni sul file system, consultare il capitolo Organizzazione della memoria flash nella Guida di programmazione del controller.

Il contenuto del file XML, gli elementi XML insieme con i relativi attributi e valori, viene memorizzato in un array di tipo XmlItems nella memoria applicazione del controller. È necessario dichiarare questo array e assegnarlo all'ingresso associato i_refXmlItems sul blocco funzione. All'inizio di ogni operazione di lettura, il contenuto di questo array viene cancellato.

Quando si esegue il blocco funzione, l'ingresso i_refXmlItems viene memorizzato internamente per un ulteriore uso. Se viene rilevato un evento di modifica online durante l'esecuzione del blocco funzione (q_xBusy = TRUE), le variabili utilizzate internamente vengono aggiornate con il valore corrente dell'ingresso.

NOTA: Non riassegnare i_refXmlItems a un'altra variabile durante l'esecuzione del blocco funzione.

Il numero di elementi (somma di elementi e attributi) memorizzabili nell'array viene specificato dal parametro Gc_udiXmlMaxNumOfItems nel GPL.

L'array contiene i campi di tipo STRING per memorizzare i nomi e i valori degli elementi e attributi. È possibile specificare la lunghezza di questi STRINGs con il parametro globale Gc_uiXmlLengthOfString. Se il valore da leggere nel file supera la lunghezza specificata, il valore originale viene troncato. Se è stato troncato almeno un valore, ciò viene indicato dall'uscita q_xWarnValueTruncated.

NOTA: L'uscita q_xWarnValueTruncated è valida solo se l'uscita q_xDone è TRUE.

La struttura gerarchica degli elementi dal file XML è indicata dal parametro uiParentIndex per ciascun elemento nell'array di tipo XmlItems. Per ulteriori informazioni, consultare uiParentIndex Esempio per relazioni gerarchiche indicate da uiParentIndex.

Interfaccia

Ingresso	Tipo di dati	Descrizione
i_xExecute	BOOL	Il blocco funzione esegue l'operazione di lettura con il file specificato XML su un fronte di salita di questo ingresso. Consultare inoltre il capitolo Comportamento dei blocchi funzione con l'ingresso i_xExecute.
i_sFilePath	STRING[255]	Percorso del file XML da leggere. Se si specifica un nome di file senza estensione, il blocco funzione aggiunge l'estensione .xml.
i_sXPathItemToRead	STRING[255]	Espressione XPath per indirizzare gli elementi da leggere dal file XML. Valore predefinito: '//*'
i_xReadElementsOnly	BOOL	Se questo ingresso è TRUE, i nomi degli elementi e i rispettivi valori vengono letti e memorizzati nel buffer dell'applicazione. Se questo ingresso è FALSE, anche gli attributi insieme con i rispettivi valori vengono letti e memorizzati nel buffer dell'applicazione.
i_refXmlItems	REFERENCE TO XmlItems	Buffer fornito dall'applicazione per memorizzare gli elementi letti dal file XML specificato. Il buffer viene cancellato con l'esecuzione del blocco funzione.

Uscita	Tipo di dati	Descrizione
q_xDone	BOOL	Se questa uscita è impostata a TRUE, l'esecuzione è stata completata correttamente.
q_xBusy	BOOL	Se questa uscita è impostata a TRUE, l'esecuzione del blocco funzione è in corso.
q_xError	BOOL	Se questa uscita è impostata su TRUE, è stato rilevato un errore. Per informazioni, consultare q_etResult e q_etResultMsg.
q_etResult	ET_Result	Fornisce informazioni su stato e diagnostica come valore numerico. Se q_xBusy = TRUE, il valore indica lo stato. Se q_xDone o q_xError = TRUE, il valore indica il risultato.
q_sResultMsg	STRING[80]	Fornisce ulteriori informazioni su stato e diagnostica come messaggio di testo.
q_udiNumOfItemsRead	UDINT	Indica il numero totale di elementi e attributi letti dal file XML.
q_xWarnValueTruncated	BOOL	Se si imposta questa uscita a TRUE, è stato troncato almeno un valore. NOTA: L'uscita viene aggiornata insieme con q_xDone.

Per ulteriori informazioni sul comportamento del segnale degli ingressi e delle uscite di base, consultare il capitolo Comportamento dei blocchi funzione con l'ingresso i_xExecute.

Uso delle variabili del tipo POINTER TO … o REFERENCE TO …

Il blocco funzione fornisce ingressi e/o ingressi/uscite di tipo POINTER TO… o REFENCE TO…. Utilizzando questo tipo di puntatore o riferimento, il blocco funzione accede all'area di memoria indirizzata. In caso di evento di modifica online, può accadere che le aree di memoria vengano spostate in nuovi indirizzi e che di conseguenza un puntatore o un riferimento non siano più validi. Per evitare errori associati a puntatori non validi, occorre aggiornare ciclicamente le variabili di tipo POINTER TO… o REFERENCE TO… , o almeno all'inizio del ciclo nel quale vengono usate.

Espressioni XPath che definiscono il contenuto da leggere

Per poter leggere un singolo elemento o gruppo di elementi dal file XML, utilizzare la sintassi del linguaggio XPath (XML Path). Il contenuto da leggere è specificato dall'ingresso i_XpathItemToRead

NOTA: Il blocco funzione FB_XmlRead supporta un sotto insieme delle funzionalità fornite con le espressioni XPath.

La tabella elenca le espressioni XPath supportate:

Espressione XPath	Descrizione
//*	Seleziona tutti gli elementi nel documento.
/	Indica un percorso assoluto all'elemento.
/…/child::*	Seleziona tutti gli elementi secondari del nodo.
/…/descendant::*	Seleziona tutti gli elementi discendenti del nodo.
/…/<nome elemento>	Seleziona tutti gli elementi con il nome specificato del nodo.
/…/<nome elemento>[<n>]	Seleziona l'n^o elemento con il nome del nodo specificato.
/…/<nome elemento>[@<attributo>]	Seleziona tutti gli elementi con il nome specificato e l'attributo del nodo specificato.
/…/<nome elemento>[@<attributo>=<valore>]	Seleziona tutti gli elementi con il nome specificato e l'attributo e il valore del nodo specificati.

NOTA: I predicati, ossia le espressioni tra parentesi quadre [], possono essere seguiti da una barra / insieme con un nome di elemento per indirizzare il successivo elemento secondario.

Esempio: /…/<nome elemento>[<n>]/<nome elemento>