docs/docs/Rockwell/Optix/DotNet/tpDiagnosticQueryInterface.md

title
tpDiagnosticQueryInterface

⚙️ tpDiagnosticQueryInterface

La classe tpDiagnosticQueryInterface è una NetLogic che permette di eseguire query su un database SQLite e aggiornare variabili di output con i risultati in tempo reale.

È pensata per interfacciarsi con un database di diagnostica e fornire dinamicamente dati a variabili HMI, abilitando l’aggiornamento automatico dei valori tramite query configurabili.

---

🚦 Panoramica generale

La logica si basa su:

• Una variabile Query che contiene la stringa SQL da eseguire.
• Una variabile Enabled che abilita o disabilita l’esecuzione della query.
• Una lista di variabili OutVariables che ricevono i valori dal primo record risultato della query.
• Un database SQLite a cui si accede tramite percorso predefinito.

---

🛠️ Funzionamento principale

Elemento	Descrizione
Start()	Inizializza riferimenti alle variabili, al database e si iscrive agli eventi di cambio variabile.
UpdateStatus()	Esegue la query SQL se abilitato, aggiorna le variabili di output con i risultati.
Stop()	Pulisce le liste e rimuove gli handler eventi per evitare memory leak.

---

🔄 Flusso di lavoro

1. Alla partenza, recupera le variabili Query e Enabled, e il riferimento al database SQLite.
2. Si iscrive agli eventi di cambio delle variabili Query e Enabled.
3. Quando Query o Enabled cambiano, viene eseguita la query SQL se Enabled è true.
4. Il primo record risultato viene scritto sulle variabili di output, fino a un massimo di variabili disponibili.

---

💡 Dettagli importanti

• Se la query SQL fallisce, viene loggato un messaggio d’errore molto colorito e dettagliato (con frase in dialetto veneziano).
• Le variabili di output sono i primi N figli dell’oggetto NetLogic, dove N è il numero di colonne del risultato SQL.
• L’aggiornamento supporta solo il primo record del risultato (riga zero).

---

🛠️ Come configurare le variabili di output su NetLogic in Factory Talk Optix

La classe si aspetta che sull’oggetto NetLogic siano create variabili aggiuntive per mappare i valori restituiti dalla query SQL.

1. Creazione delle variabili di output

• Nome variabile: Devono avere nomi sequenziali nel formato [0], [1], [2], ecc.
• Come crearle:
  • Apri Factory Talk Optix e seleziona l’oggetto NetLogic in design time.
  • Aggiungi variabili figlie di tipo IUAVariable o equivalente, con i nomi indicati sopra.
• Tipo variabile: Può essere arbitrario (es. String, Int32, Float, ecc.) in base al tipo di dato atteso dalla colonna SQL.

2. Gestione delle variabili in runtime

• Il codice legge dinamicamente queste variabili usando la numerazione [0], [1], ecc., e le usa come destinazione per i valori estratti dal primo record della query.
• Se non esistono variabili per tutte le colonne, il ciclo si interrompe al primo nome mancante.
• È possibile aggiungere tutte le variabili necessarie in modo sequenziale, in base al numero di colonne della query.

3. Tipo arbitrario e flessibilità

• Le variabili possono avere qualsiasi tipo supportato da Factory Talk Optix e compatibile con i tipi di dato SQL.
• Il codice scrive valori tramite RemoteWrite e usa UAValue che gestisce diversi tipi.
• È importante che il tipo della variabile corrisponda al tipo del dato restituito per evitare errori.

---

🔧 Esempio di configurazione variabili

Nome variabile	Tipo suggerito	Descrizione
[0]	String	Prima colonna risultato query
[1]	Int32	Seconda colonna risultato query
[2]	Float	Terza colonna risultato query
...	...	...

---

⚠️ Nota importante

• La classe attualmente supporta solo il primo record della query (riga zero).
• Per gestire più righe servirebbe implementare una logica di iterazione e mapping aggiuntiva.

---

🧰 Metodi principali

Metodo	Descrizione
Start()	Setup iniziale: recupera variabili e database, iscrive eventi, prepara lista variabili output.
UpdateStatus()	Esegue la query e aggiorna le variabili se abilitato.
UpdateStatus(object, VariableChangeEventArgs)	Overload che risponde agli eventi di cambio variabile, invocando il metodo senza parametri.
Stop()	Pulizia delle risorse e rimozione degli eventi.

---

🔍 In Depth: Funzioni di tpDiagnosticQueryInterface

---

Start()

Descrizione:
Metodo di inizializzazione chiamato all’avvio della NetLogic.
Recupera le variabili Query e Enabled e il database SQLite.
Registra gli eventi di cambio variabile per aggiornare lo stato.
Costruisce la lista OutVariables basandosi sui figli dell’oggetto NetLogic.

Eccezioni:
Lancia eccezioni se le variabili o il database non vengono trovati, con messaggi personalizzati in dialetto veneziano.

---

UpdateStatus()

Descrizione:
Controlla se la logica è abilitata leggendo la variabile Enabled.
Se abilitata, esegue la query SQL contenuta in Query.
Scrive il primo record dei risultati sulle variabili OutVariables.

Error Handling:
In caso di errore nella query, logga un messaggio di errore molto colorito contenente dettagli tecnici.

---

UpdateStatus(object sender, VariableChangeEventArgs e)

Descrizione:
Handler evento che richiama semplicemente UpdateStatus() senza parametri per aggiornare lo stato quando Query o Enabled cambiano.

---

Stop()

Descrizione:
Pulizia e rimozione dei riferimenti alle variabili e agli eventi.
Serve a prevenire perdite di memoria quando la NetLogic viene fermata o distrutta.

---