Output dei Job Octave: stdout, stderr e diagnostica

Uno script GNU Octave può produrre risultati numerici, avvisi e messaggi diagnostici. Script Jobs Manager e la finestra Execution details permettono di distinguerli e di consultarli anche dopo la conclusione dell’esecuzione. Questa guida illustra le quattro sorgenti selezionabili, la lettura a pagine, la copia e il salvataggio dell’output e la differenza tra messaggi del programma e messaggi del debugger.

Le schermate sono tratte dall’interfaccia di GX-TXT DEV112-P005, con Octave Script Workspace 1.8.3. Il sorgente usa il tema High Contrast Dark; i controlli Tk/ttk conservano il loro aspetto nativo. I nomi dei comandi sono quelli visibili nella GUI inglese.

1. Scrivere uno script che produca output e avvisi distinti

Aprire Octave Script Workspace in una Session attiva, scegliere File → New Script e registrare con File → Save il seguente script. L’esempio usa soltanto dati sintetici; non richiede strumenti, file esterni o Dataset.

% Synthetic numeric report; stdout and stderr are independent channels.
% There are no input files, devices, Datasets or external dependencies.
values = [1, 3, 5, 7, 9];
mean_value = mean(values);
fprintf(1, 'O25_STDOUT_BEGIN_MEAN=%.2f\n', mean_value);
fprintf(2, 'O25_STDERR_NOTE: simulated acquisition warning\n');
warning('O25_WARNING: synthetic threshold requires review');
padding = repmat('x', 1, 50);
for k = 1:1600
  reading = sin(k / 23);
  fprintf(1, 'O25_ROW=%04d reading=%+.5f note=%s\n', k, reading, padding);
endfor
fprintf(1, 'O25_STDOUT_END rows=%d mean=%.2f\n', 1600, mean_value);
assert(abs(mean_value - 5) < 1e-10);

mean(values) calcola la media aritmetica dei cinque valori, in questo caso 5. fprintf(1, …) scrive sullo standard output (stdout), mentre fprintf(2, …) scrive sullo standard error (stderr). Anche warning(…) genera un messaggio di avvertimento GNU Octave. repmat costruisce una stringa ripetuta, utile per ottenere un log lungo senza grandi strutture dati; sin genera letture numeriche sintetiche. Il ciclo crea 1.600 righe, mentre assert controlla il risultato scientifico.

Source Octave salvato con scritture fprintf su stdout e stderr, warning e un ciclo che genera 1.600 righe di dati sintetici.
Figura 1 — Sorgente Octave salvato, con scrittura esplicita di stdout e stderr e generazione di dati numerici.

2. Aprire l’output di un Job COMPLETED

Dal menu Run → Open Script Runner… controllare la revisione salvata del sorgente, scegliere Validate review e quindi Run Job. Il Job viene eseguito dal supervisore; quando raggiunge COMPLETED, aprire Run → Script Jobs Manager…, selezionare la relativa riga e scegliere Jobs → Open execution details.

Nella finestra dei dettagli è disponibile un elenco di sorgenti di output. Selezionando Program output si leggono le righe prodotte su stdout. Nell’esempio iniziano con:

O25_STDOUT_BEGIN_MEAN=5.00
O25_ROW=0001 reading=+0.04346 note=...
Finestra Execution details con Program output selezionato, la prima pagina delle letture sintetiche e i controlli di navigazione.
Figura 2 — Execution details con Program output: prima pagina delle letture sintetiche e controlli di navigazione.

Lo stato del Job e la revisione dello script sono informazioni diverse dal contenuto del flusso. Anche un Job COMPLETED può avere prodotto avvisi su stderr; per leggerli occorre scegliere l’apposita sorgente.

3. Leggere log lunghi con pagine da 64 KiB

La finestra dei dettagli offre First page, Previous page, Next page e Latest page. Ogni pagina contiene fino a 64 KiB del flusso selezionato. Quando l’output è più lungo, leggere la prima pagina non significa avere letto l’intero documento.

Nell’esempio stdout supera 137 KB: la prima pagina contiene i byte da 0 a 65.536, la seconda da 65.536 a 131.072 e l’ultima contiene il resto. La riga finale è:

O25_STDOUT_END rows=1600 mean=5.00
Ultima pagina di un Program output lungo con la riga O25_STDOUT_END e l’intervallo di byte mostrato nella riga di stato.
Figura 3 — Ultima pagina di un Program output lungo, con la conclusione dello script e la posizione nel flusso.

La riga di stato indica gli intervalli di byte effettivamente mostrati. Latest page porta verso la parte finale del contenuto disponibile, mentre Previous page consente di tornare indietro. Una pagina può iniziare o finire a metà di una riga: le dimensioni sono espresse in byte, non in numero di righe scientifiche.

4. Separare Program stderr dai risultati numerici

Aprire l’elenco dei flussi e scegliere Program stderr. Qui si leggono il messaggio scritto con fprintf(2, …) e l’avviso generato da warning(…), compresa la traccia delle chiamate restituita da GNU Octave quando disponibile.

Sorgente Program stderr con la nota scritta su stderr e il warning GNU Octave con la traccia delle chiamate.
Figura 4 — Program stderr mostra il messaggio applicativo e il warning GNU Octave separati dallo stdout numerico.

Un messaggio su stderr non implica automaticamente un Job FAILED. Nel primo esperimento lo script genera un warning ma termina correttamente: l’ultima istruzione assert non rileva errori e l’esecuzione risulta COMPLETED. Per decidere se il calcolo è riuscito, consultare lo stato del Job, non soltanto la presenza di testo su stderr.

5. Interpretare il Diagnostic log del supervisore

Selezionare Diagnostic log. Questo flusso riguarda gli eventi gestiti dall’infrastruttura del Job: per esempio launch e terminal, con identificativi e stato dell’esecuzione. Non va confuso con ciò che lo script stampa come dato scientifico.

Sorgente Diagnostic log con gli eventi strutturati launch e terminal della stessa esecuzione.
Figura 5 — Diagnostic log con gli eventi strutturati di avvio e terminazione della stessa esecuzione.

I messaggi diagnostici provengono dal supervisore; possono essere utili per distinguere problemi del runtime, stato terminale e risultati dell’utente. Program stderr resta invece il luogo naturale per messaggi di errore e warning prodotti dall’interprete e dal codice Octave.

6. Utilizzare il Legacy combined stream

Il selettore comprende anche Legacy combined stream. Questa vista legge il flusso combinato disponibile per il Job, nel quale possono comparire insieme la stampa numerica e i messaggi di avvertimento.

Sorgente Legacy combined stream con stampa numerica e avvisi mostrati nella stessa vista.
Figura 6 — Legacy combined stream presenta contenuti del programma e avvisi nella stessa vista.

È utile quando serve una panoramica rapida o quando si consulta un’esecuzione più vecchia. Per attribuire correttamente l’origine dei messaggi, però, è preferibile utilizzare Program output, Program stderr e Diagnostic log separatamente, quando disponibili. La vista combinata non sostituisce una classificazione scientifica dei messaggi.

7. Copiare la pagina visibile oppure l’intero flusso

Nella finestra dei dettagli, Select visible page seleziona il testo della pagina mostrata e Copy selection lo copia negli appunti. Con la prima pagina dell’esempio si copiano quindi 65.536 caratteri, non tutto l’output.

Execution details con Select visible page e Copy selection applicati alla pagina mostrata.
Figura 7 — Selezione e copia del testo limitato alla pagina visibile.

Per copiare l’intero contenuto selezionare invece Copy entire source. Qui la parola source indica il flusso scelto nel selettore, non il file di codice sorgente .m. Per il nostro stdout la copia completa comprende tutti i 137.662 byte, inclusa la riga conclusiva, anziché fermarsi dopo la prima pagina.

Execution details con Copy entire source che copia tutto il flusso selezionato.
Figura 8 — Copia completa del flusso selezionato, senza limitarla alla pagina visualizzata.

Per un testo lungo, scegliere il comando in base allo scopo: Copy selection per una porzione identificata, Copy entire source quando occorre recuperare l’intero log conservato.

8. Salvare l’output completo tramite la finestra di sistema

Save source to file… apre il selettore file nativo. Dopo avere indicato la destinazione e scelto Save, GX-TXT trasferisce tutto il flusso selezionato, non soltanto la pagina corrente.

Selettore file nativo aperto da Save source to file per esportare il Program output completo.
Figura 9 — Selettore di salvataggio nativo per esportare l’intero Program output.

È opportuno dare al file un nome che identifichi Job, tipo di flusso e data dell’esecuzione. L’operazione esporta una copia dell’output: non modifica il Job originale né la sua revisione. La destinazione deve trovarsi al di fuori della Session scientifica d’origine, per mantenere separati i file generati dall’utente dagli snapshot gestiti.

9. Confrontare stdout, stderr e diagnostica quando il Job fallisce

Un altro esempio mostra un errore Octave intenzionale:

% Distinguish intentional native program failure from ordinary warning.
% Deliberately synthetic: no user data or external dependencies.
samples = [2, 4, 6];
fprintf(1, 'O25_ERROR_STDOUT_BEFORE_FAILURE=%d\n', sum(samples));
fprintf(2, 'O25_ERROR_STDERR_NOTE: this run intentionally fails\n');
error('O25_SYNTHETIC_FAILURE: demonstration of GNU Octave stderr');

Questo programma scrive prima un valore numerico su stdout, poi una nota su stderr e infine genera un errore con error(…). Nel Job Manager lo stato diventa FAILED. Selezionando Program stderr, si legge l’errore GNU Octave e la posizione nel sorgente:

Source Octave di una seconda esecuzione che scrive su stdout e stderr e poi genera un errore con error.
Figura 10 — Codice Octave di una seconda esecuzione che genera un errore controllato.
Program stderr del Job FAILED con il messaggio O25_SYNTHETIC_FAILURE e la posizione nel sorgente.
Figura 11 — Program stderr del Job FAILED con il messaggio di errore intenzionale e la relativa traccia.

Program output conserva comunque il messaggio scritto prima dell’errore: O25_ERROR_STDOUT_BEFORE_FAILURE=12. Il Diagnostic log, invece, riporta gli eventi del supervisore e lo stato terminale FAILED.

Diagnostic log del Job fallito con gli eventi del supervisore e lo stato terminale FAILED.
Figura 12 — Il Diagnostic log identifica lo stato terminale del Job fallito, distinto dal messaggio dello script.

Questo confronto mostra perché non conviene usare un unico flusso come unica fonte di diagnosi: il risultato parziale, la causa dell’errore e lo stato di esecuzione sono informazioni complementari.

10. Distinguere Debugger output dal Program output

Il pannello Debugger output si trova nel debugger aperto da Run → Debug Session script…. Non coincide con nessuno dei quattro flussi selezionabili in Execution details: contiene messaggi relativi ai comandi e agli stati del debugger.

Per esempio, con uno script numerico che chiama una funzione:

% Synthetic native GNU Octave debugger stdout and Debugger output.
1; % Enable local functions in an executable script.
function result = double_value(number)
  result = number * 2;
endfunction
sample = 7;
value = double_value(sample);
fprintf(1, 'O25_DEBUG_RESULT=%d\n', value);
assert(value == 14);

Impostando un breakpoint sulla chiamata value = double_value(sample) e avviando Start Debug, il pannello segnala PAUSED. Dopo Continue mostra anche la conclusione COMPLETED.

Pannello Debugger output durante una sospensione PAUSED del programma Octave sul breakpoint.
Figura 13 — Debugger output durante una sospensione PAUSED del programma Octave.
Pannello Debugger output dopo Continue con lo stato COMPLETED del Job gestito.
Figura 14 — Debugger output dopo Continue e completamento del Job gestito.

Il valore scientifico O25_DEBUG_RESULT=14 non è un messaggio del debugger: compare in Program output, raggiungibile tramite Program output / diagnostics….

Program output dello stesso Job di debug con il risultato O25_DEBUG_RESULT=14.
Figura 15 — Program output dello stesso Job di debug con il risultato numerico, separato dai messaggi di controllo.

11. Follow latest output durante l’esecuzione

Per un Job ancora attivo, la finestra dei dettagli può abilitare Follow latest output. La funzione è destinata a seguire la parte più recente del flusso mentre lo script produce nuovi dati. Può essere utile per un’elaborazione che registra campioni progressivamente.

L’esempio seguente produce un flusso finito di letture, con pause deliberate. fflush(stdout) richiede la scrittura dei dati in uscita, mentre pause scandisce il tempo fra i campioni:

% Synthetic extended bounded live stream for Follow latest output.
% Only numeric samples; no devices, Datasets, files, or input access.
fprintf(1, 'O25_EXTENDED_LIVE_BEGIN\n');
fflush(stdout);
for n = 1:180
  fprintf(1, 'O25_EXTENDED_SAMPLE=%03d volts=%.3f\n', n, n / 18);
  fflush(stdout);
  pause(0.25);
endfor
fprintf(1, 'O25_EXTENDED_LIVE_END count=180\n');
fflush(stdout);
Execution details di un Job ancora RUNNING con Follow latest output disponibile e campioni progressivi.
Figura 16 — Dettagli di un Job ancora RUNNING, con Follow latest output disponibile e campioni progressivi.

La disponibilità del controllo dipende dallo stato del Job. Dopo COMPLETED l’opzione risulta disabilitata, ma tutte le pagine dell’output già conservato restano consultabili.

Execution details dello stesso Job dopo il completamento con Follow latest output disabilitato.
Figura 17 — Output del medesimo Job dopo il completamento, con Follow latest output disabilitato.

Se si è aperta la finestra quando l’output era ancora vuoto, Reconnect permette di rileggere la pagina aggiornata. Anche Latest page può essere usato per vedere i byte più recenti disponibili. Non interpretare un riquadro temporaneamente vuoto come prova che il Job non abbia prodotto dati: verificare lo stato e aggiornare la vista.

12. Chiudere i dettagli senza perdere lo storico

Per tornare all’editor, chiudere le finestre di dettaglio, quindi lo Script Jobs Manager. Le esecuzioni completate e fallite continuano a essere disponibili nel loro storico; la chiusura delle finestre non cancella automaticamente i Job e non equivale a Cancel Job.

Octave Script Workspace con il sorgente salvato e lo spazio di lavoro concentrato sul codice dopo la chiusura dei dettagli.
Figura 18 — Ritorno all’editor Octave con il sorgente salvato e lo spazio di lavoro nuovamente concentrato sul codice.

In conclusione, i flussi devono essere interpretati secondo la loro funzione: stdout documenta ciò che il programma produce, stderr segnala avvisi ed errori dell’interprete, Diagnostic log descrive eventi del supervisore, Legacy combined stream conserva una vista combinata e Debugger output documenta le azioni del debugger. Per ricostruire un’esecuzione scientifica, usare insieme stato del Job, revisione del sorgente e flussi appropriati.