Debugger GX-TXT · Guida 03 — Quando un’API GX-TXT non è disponibile
Questa guida fa parte del progetto GX-TXT Script Debugger. Le schermate provengono da esecuzioni reali in GX-TXT dev112-P011-bis, già realizzate per il corso sul debugger; gli esempi usano dati sintetici. I codici D identificano gli esercizi corrispondenti del corso completo sul debugger.
Scarica gli script delle sei guide pratiche (ZIP). Per ripetere questa guida, estrai i file della cartella lezione_03/scripts.
D38 — Disponibilità di API e operazioni
Un nome API riconosciuto non basta a garantire che una specifica operazione sia disponibile nella versione e nel contesto in uso. Prima di diagnosticare un calcolo, verifichiamo i requisiti dichiarati.
Controllare due operazioni
Importa e registra D38_api_check.m.
Lo script richiede CANONICAL_DATASET_API_v2@2 e
NUMERIC_API_v1@1, poi controlla le operazioni
read_range e statistics con
gxtxt_api_has_operation.
Imposta un breakpoint sulla stampa, dopo i due controlli, e avvia il
debug. Nella copia usata per la prova, has_read e
has_statistics sono entrambi logici con valore 1:
Continua per stampare READ_RANGE 1 e
STATISTICS 1. Se un’operazione fosse assente, lo script la
segnalerebbe con l’asserzione; se mancasse già un requisito API,
gxtxt_api_require potrebbe fermarsi prima dei due
controlli. Verifica sempre il contratto e la versione effettiva: un
esito in questa Session non garantisce lo stesso inventario su tutte le
installazioni.
Il pannello può mostrare anche variabili dell’ambiente di esecuzione o riepiloghi limitati. Per la diagnosi osserva i due valori espliciti preparati dallo script.
Esercizio
Che cosa significa has_read = 1? Significa anche che un
Dataset con qualunque ID esiste?
Soluzione ragionata
Indica che l’operazione richiesta risulta disponibile nel contesto della prova. Non prova che un particolare Dataset o una variabile esistano: occorre controllare anche gli input della chiamata.
Interpretare un requisito non soddisfatto
gxtxt_api_require verifica il requisito dichiarato,
mentre gxtxt_api_has_operation controlla una specifica
operazione di un’API presente. Se il requisito fallisce, controlla
identità dell’API, versione richiesta e provider indicato dal contratto:
un provider non disponibile non si risolve cambiando il Dataset. Se il
requisito passa ma un’operazione manca, confronta il nome con la
documentazione della versione in uso. Evita di sostituire i risultati
assenti con numeri inventati: conserva messaggio, requisito e contesto
della Session.
Due requisiti volutamente impossibili
In una Session di prova importa e registra unavailable_api.m, apri il debugger
e avvia Start Debug. Il file dichiara
EXAMPLE_MISSING_API_v1@1, un nome inventato per
l’esercizio. Nella prova il controllo preliminare ha fermato il Job con
FAILED, segnalando che l’API richiesta non era disponibile;
la stampa successiva non è stata raggiunta.
Ripeti con unavailable_provider.m: l’API
NUMERIC_API_v1 è conosciuta, ma il requisito richiede il
provider inventato example.missing. Nella prova il
controllo preliminare ha segnalato il provider richiesto e quello
trovato, math.numeric, terminando il Job con
FAILED prima della pausa nello script. Apri Program
output / diagnostics e scegli Diagnostic log
per leggere il motivo:
Questi due FAILED sono risultati attesi, perché i
requisiti sono volutamente inesistenti. Nei programmi reali usa identità
e versione documentate per l’installazione; non copiare i nomi fittizi
come dipendenze. La prova seguente è diversa: API e operazione esistono,
ma il Dataset richiesto non esiste nella Session.
D42 — Errori del Bridge e del programma
Una chiamata attraverso Script Bridge può fallire perché la richiesta non corrisponde ai dati disponibili. Il messaggio va interpretato insieme agli argomenti preparati dallo script, senza confonderlo con un errore di indicizzazione locale.
Un Dataset intenzionalmente assente
In una Session di prova che non contenga
debug_missing_dataset_example, importa D42_missing_dataset.m. Lo script
richiede un ID volutamente inesistente tramite
CANONICAL_DATASET_API_v2/read_range. Metti un breakpoint
sulla chiamata e avvia il debug.
Premi Continue. Nella prova il Job termina con
FAILED e segnala
Unknown dataset: debug_missing_dataset_example:
Il messaggio identifica l’operazione e l’ID richiesto. La traccia attraversa anche funzioni del Bridge: per trovare l’errore nel nostro esempio, torna agli argomenti della chiamata nel sorgente. L’indicazione last paused si riferisce all’ultima fotografia osservata, non a variabili vive dopo il fallimento.
Confronta la D35, dove l’errore era un indice Octave fuori intervallo su un vettore già in memoria. Qui la richiesta punta deliberatamente a un Dataset assente: non è un difetto del framework. Per una lettura valida prepara la serie della D41 e usa lo script della D39.
Esercizio
Un messaggio dice che un Dataset è sconosciuto. Che cosa controlli prima di modificare la formula numerica?
Soluzione ragionata
Controlla Session aperta, esistenza del Dataset e corrispondenza esatta dell’ID richiesto. Poi verifica le variabili e i parametri della lettura.
Altre tappe del progetto
- Debugger GNU Octave in GX-TXT: breakpoint, variabili e API pubbliche
- Debugger GX-TXT · Modulo 09 — Casi pratici integrati
- Debugger GX-TXT · Modulo 10 — Autonomia e progetto conclusivo
- Debugger GX-TXT · Modulo 05 — Python: casi fondamentali
- Debugger GX-TXT · Modulo 01 — Fondamenti e primo Debug Job
- Debugger GX-TXT · Modulo 02 — Breakpoint e sorgente