# 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.