Verificare le uscite ed eseguire un Job Octave controllato

Il pulsante Run Job di GX-TXT Octave Script Workspace avvia un’esecuzione supervisionata: non è equivalente a Validate review, che controlla la configurazione senza calcolare. In questa guida prepariamo uno script con cinque misure sintetiche di tensione, dichiariamo un Dataset di uscita, eseguiamo una sola volta il codice e verifichiamo il risultato nel supervisore Script Jobs e nel Dataset canonico.

La procedura riguarda GX-TXT DEV112-P005 e il modulo Octave Script Workspace 1.8.3. Utilizza soltanto dati artificiali, uno script di durata limitata e le API pubbliche GX-TXT. Non sono necessari strumenti di laboratorio.

1. Salvare un piccolo script con le API pubbliche

Nel Source creare un nuovo script GNU Octave e salvarlo con File → Save, assegnando un’identità nella Session. Il seguente esempio definisce gain, calcola cinque punti e pubblica una tabella attraverso Dataset Publication API v2.

% Synthetic five-point voltage series; no external instrument is used.
gxtxt_parameter_declare('gain', 'double', 'default', 2.0, ...
                        'min', 0.0, 'max', 4.0, ...
                        'description', 'Synthetic voltage multiplier');

ctx = gxtxt_context();
time_s = [0; 1; 2; 3; 4];
voltage_V = ctx.parameters.gain .* [0.1; 0.2; 0.3; 0.4; 0.5];

if (!gxtxt_api_has_operation('DATASET_PUBLICATION_API_v2', 'publish_series'))
  error('Required Dataset Publication API operation unavailable');
endif

request = struct('dataset_id', 'o18_voltage_output', ...
                 'contract', 'table.generic', 'storage', 'csv', ...
                 'x_values', time_s, 'y_values', voltage_V, ...
                 'x_variable', struct('variable_id', 'time_s', ...
                                      'name', 'Elapsed time', 'unit', 's', ...
                                      'semantic_role', 'time'), ...
                 'y_variable', struct('variable_id', 'voltage_V', ...
                                      'name', 'Synthetic voltage', 'unit', 'V', ...
                                      'semantic_role', 'voltage'), ...
                 'notes', 'Synthetic five-point output of controlled Octave Job');

receipt = gxtxt_api_call('DATASET_PUBLICATION_API_v2', ...
                         'publish_series', {request});
disp('O18 controlled Octave publication completed');
disp(receipt);
Source editor Octave con lo script che dichiara gain e chiama publish_series della Dataset Publication API v2.
Figura 1 — Il sorgente scientifico Octave definisce gain e utilizza l’operazione pubblica publish_series per il Dataset di uscita.

Qui gxtxt_parameter_declare registra staticamente un parametro double compreso tra 0 e 4. Durante l’esecuzione, gxtxt_context() fornisce il valore efficace di gain selezionato nel Runner. gxtxt_api_has_operation controlla la presenza dell’operazione pubblica; gxtxt_api_call la richiede al provider GX-TXT.

Il risultato sarà un Dataset con due variabili distinte, time_s in secondi e voltage_V in volt. Il contratto table.generic descrive la tabella canonica; il Dataset ID o18_voltage_output è l’identità scelta dallo script per questa pubblicazione.

2. Aprire la sezione Output request

Con lo script salvato, scegliere Run → Open Script Runner…. Nella finestra individuare Inputs and output, poi Output request (optional). Sono presenti i campi Dataset ID, Display label e la casella Replace owned output.

Script Runner con i parametri e la sezione Output request con Dataset ID, Display label e Replace owned output.
Figura 2 — Script Runner presenta parametri e controlli per la richiesta di un Dataset di uscita.

È necessario distinguere la richiesta di uscita dal commit di pubblicazione: indicare un ID nel Runner non crea automaticamente il Dataset. La pubblicazione avviene soltanto quando il codice scientifico richiede e completa l’API di pubblicazione. Analogamente, l’etichetta nella richiesta documenta l’intenzione della chiamata, mentre i nomi delle variabili pubblicate provengono dalla definizione scientifica.

3. Controllare l’identificativo di uscita

Il Dataset ID deve rispettare la grammatica delle identità GX-TXT. Per esempio, un nome contenente spazi non è valido: Validate review lo rifiuta con un messaggio Invalid dataset ID.

Validate review che rifiuta un Dataset ID di uscita con spazi con il messaggio Invalid dataset ID.
Figura 3 — Validate review rifiuta un Dataset ID non valido senza creare alcun Job.

Questa è una verifica della richiesta, non una prova dell’esecuzione del codice. Correggere il campo prima di proseguire.

4. Convalidare la richiesta senza esecuzione

Usare Dataset ID = o18_voltage_output, Display label = Synthetic voltage series, five points e lasciare inizialmente deselezionata Replace owned output. Verificare che gain = 2.0, quindi premere Validate review.

Script Runner con Dataset ID o18_voltage_output e il messaggio Review valid. No Job submitted.
Figura 4 — La richiesta create-only è valida; non è stato ancora inviato alcun Job.

Il messaggio Review valid. No Job submitted conferma la coerenza dei parametri e della richiesta. Il nome dell’uscita deve corrispondere a quello che lo script intende pubblicare: nell’esempio la definizione request.dataset_id contiene esattamente lo stesso ID.

5. Inviare una sola volta Run Job

Premere Run Job. GX-TXT crea la richiesta con una fotografia immutabile del sorgente registrato, della sua revisione e dei parametri ammessi. Durante la preparazione i controlli possono essere temporaneamente disabilitati e compare Submitting immutable Script and input snapshots….

Script Runner durante l’invio con il messaggio Submitting immutable Script and input snapshots.
Figura 5 — La fase di invio è visibile nel Runner; il Job non va considerato concluso solo perché è stato richiesto.

Questa fase non deve essere confusa con la riuscita finale. Il Job passa attraverso gli stati del supervisore; l’apertura o la chiusura della finestra di revisione non sostituisce il controllo dello stato effettivo.

6. Verificare l’esito in Script Jobs

Aprire Script Jobs e individuare il Job dello script Octave. La tabella mostra il riferimento registrato, il linguaggio, la versione, la revisione, lo stato e gli orari.

Tabella Script Jobs con l’esecuzione Octave dello script nello stato COMPLETED.
Figura 6 — Script Jobs mostra la singola esecuzione Octave come COMPLETED.

COMPLETED indica che il supervisore ha concluso correttamente quell’esecuzione. Nell’esempio il Job usa GNU Octave 9.4.0, lo script registrato alla revisione 1 e si conclude senza errori. Eventuali servizi CORE automatici possono avere propri Job distinti: non vanno confusi con l’esecuzione Octave richiesta dall’utente.

7. Aprire i dettagli dell’esecuzione e leggere il risultato

Selezionare il Job e aprire i dettagli dell’esecuzione. Nella sezione Program output, il messaggio stampato dallo script conferma la chiamata di pubblicazione. Il risultato contiene il Dataset ID, il provider CSV e l’impronta SHA-256 del contenuto.

Dettagli del Job con Program output, Dataset ID pubblicato, provider CSV e impronta SHA-256.
Figura 7 — I dettagli del Job riportano il messaggio dello script, il Dataset pubblicato e il risultato della transazione.

Oltre al messaggio del programma, GX-TXT conserva il rapporto dell’esecuzione. Questo distingue l’identità del sorgente registrato dal contenuto finale pubblicato: sono due oggetti diversi, ciascuno verificabile mediante la propria impronta.

8. Controllare i cinque punti del Dataset canonico

Il Dataset o18_voltage_output è stato pubblicato nel namespace privato del produttore analysis.octave_script, con contratto table.generic. La lettura canonica restituisce le due variabili time_s e voltage_V, entrambe con cinque valori.

Tempo (s)Tensione (V)
00.2
10.4
20.6
30.8
41.0

I risultati seguono la relazione V_i = g * (0.1 + 0.1*i) V, con i = 0,1,2,3,4 e g = 2.0. Il piccolo scarto della rappresentazione decimale nel CSV, quando presente, è la normale serializzazione dei numeri in virgola mobile. La corrispondenza scientifica si verifica quindi entro la precisione numerica pertinente.

Il completamento del Job e la presenza del Dataset canonico sono verifiche complementari: un Job completato non implica automaticamente che un Dataset sia stato pubblicato. In questo caso la pubblicazione è confermata anche dal record canonico e dal contenuto delle cinque righe.

9. Evitare la sovrascrittura involontaria

Se nel Runner si conserva lo stesso Output Dataset ID e si seleziona Validate review dopo che l’uscita esiste già, GX-TXT rifiuta la richiesta create-only: Output Dataset already exists; choose a new ID or review owned replacement.

Validate review che rifiuta la richiesta create-only con Output Dataset already exists.
Figura 8 — La revisione create-only rifiuta il Dataset già esistente.

Se l’uscita appartiene allo stesso produttore autorizzato, si può selezionare Replace owned output per riesaminare esplicitamente l’intenzione di sostituzione.

Script Runner con Replace owned output selezionato e la revisione dell’intenzione di sostituzione convalidata.
Figura 9 — Con Replace owned output selezionato, la revisione dell’intenzione di sostituzione viene convalidata.

Attenzione: in questo esempio è stata verificata soltanto la convalida GUI della sostituzione posseduta. Non è stato inviato un secondo Job e non è stata eseguita alcuna sostituzione. Una futura pubblicazione che debba effettivamente sostituire un Dataset richiede anche l’appropriata intenzione replace_owned nella richiesta all’API, con i controlli di proprietà del produttore. La selezione della casella non garantisce da sola che uno script esegua una sostituzione.

10. Chiudere il Runner e conservare il risultato

Dopo aver letto l’esito, tornare al Source e utilizzare Close per chiudere la revisione. La chiusura non è un comando per annullare un Job già ammesso. Lo script originale rimane registrato e il Dataset prodotto continua a essere disponibile nella Session.

Source editor Octave con lo script ancora salvato e invariato dopo il completamento del Job.
Figura 10 — Il sorgente Octave rimane salvato e invariato dopo il completamento del Job.

Percorso da ricordare: salvare il Source, aprire Run → Open Script Runner…, compilare e convalidare l’Output request, premere una sola volta Run Job, controllare Script Jobs, leggere Program output e verificare il Dataset pubblicato. La pubblicazione deve essere esplicita nel codice: Output request, Validate review, Run Job e commit del Dataset sono passaggi differenti, con responsabilità differenti.