Debugging Scripts

Il sistema di scripting di Altium Designer offre un ambiente di debug completo. Il Debugger di scripting aiuta a identificare e risolvere gli errori negli script fornendo una gamma di strumenti automatizzati e pannelli informativi.

Errori di script

Gli errori comuni includono metodi non validi, operatori di raggruppamento posizionati in modo errato, tipi non corrispondenti, errori logici ed errori tipografici. Quando il sistema di scripting rileva un errore, il debugger mette in pausa lo script e visualizza una finestra di dialogo di errore che indica il problema.

L'esempio seguente mostra uno script con un carattere di terminazione mancante e il relativo messaggio nella finestra di dialogo di errore.

Il debugger metterà in pausa uno script in risposta a errori di compilazione o di esecuzione.

Una volta chiusa la finestra di dialogo di errore, il codice può essere corretto e lo script rieseguito. Se lo script deve essere arrestato, ad esempio durante l'esecuzione passo passo, utilizzare il comando Stop (Run » Stop, Ctrl+F3) o il pulsante ( sulla barra degli strumenti Script Debug).

Debug degli script

Nel sistema di scripting è disponibile una gamma di strumenti per aiutare nel debug degli script. Questi includono l'applicazione di breakpoint multipli in uno script, l'uso del pannello Watch List per monitorare il valore delle variabili, l'uso dei segnalibri per spostarsi in modo più efficiente e l'uso delle funzioni step into e step over per seguire l'esecuzione degli script.

Ad esempio, durante il controllo dei valori di variabili ed espressioni in uno script, è possibile utilizzare le seguenti funzionalità:

• Breakpoint
• Tooltip di valutazione delle espressioni
• Tooltip Insight
• Finestra di dialogo Evaluate
• Espressioni osservate

► Vedere Strumenti dell'editor di script per informazioni sull'uso degli strumenti dell'editor durante il debug degli script.

Tracciamento

Per aiutare a individuare e risolvere un errore sconosciuto in uno script, è possibile inserire una serie di breakpoint in uno script per mettere in pausa il codice in più punti mentre si controllano i valori di variabili ed espressioni.

Tuttavia, in qualsiasi momento in cui lo script è in pausa, può anche essere fatto avanzare una riga funzionale alla volta utilizzando le funzioni di tracciamento/step del Debugger. In questo modo, un breakpoint può essere usato per mettere inizialmente in pausa lo script nell'area di interesse e poi farlo avanzare una riga alla volta usando la funzione di tracciamento. Il processo di esecuzione di uno script una riga alla volta è chiamato tracciamento o esecuzione passo passo dello script.

Il debugger di script fornisce comandi relativi al tracciamento: step into (Run » Step Into) e step over (Run » Step Over). Questo consente di seguire il processo dello script e analizzarne il comportamento durante il debug del codice dello script.

I comandi di debug disponibili nel menu Run .

Comando Step Into

Il processo Step Into esegue lo script un'istruzione alla volta. Il comando è disponibile dal menu Run , dal relativo pulsante sulla barra degli strumenti Script Debug () oppure tramite il tasto di scelta rapida F7 .

Se l'istruzione in esecuzione richiama un'altra procedura, l'esecuzione step into di tale istruzione trasferisce il controllo alla prima riga della procedura chiamata. L'evidenziazione color verde pisello nell'editor indica la riga di codice a cui è arrivato lo script. Il processo di esecuzione passo passo dello script viene annullato con il comando Run » Stop, la scorciatoia Ctrl+F3 o il pulsante della barra degli strumenti ().

Comando Step Over

Il processo Step Over è simile a Step Into, con la differenza che se l'istruzione corrente è una chiamata a un'altra procedura, l'intera procedura chiamata viene eseguita senza fermarsi, invece di seguirla passo passo. Il comando è disponibile dal menu Run , dal relativo pulsante () oppure tramite il tasto di scelta rapida F8 .

Questo comando è utile quando è stato determinato che una procedura called non è la causa del problema nella procedura corrente, ed evita di dover seguire inutilmente la procedura chiamata riga per riga: tale procedura viene quindi "saltata".

Pannello Call Stack

Il pannello Call Stack viene utilizzato per visualizzare la catena di procedure e funzioni che hanno portato al punto corrente di esecuzione nello script sottoposto a debug.

Il pannello Call Stack 

Durante il debug passo passo dello script, il pannello mostrerà il nome di qualsiasi funzione o procedura in cui si entra.

Quando viene rilevata una chiamata a un'altra funzione o procedura, il pannello mostrerà il nome di questa funzione/procedura aggiuntiva nel momento in cui vi si entra. Poiché la funzione/procedura viene chiamata dall'interno di una funzione/procedura, la funzione/procedura originale continua a essere visualizzata nel pannello.

Viene così effettivamente impostato uno "stack di chiamate", che mostra la relazione tra le chiamate discendenti di funzioni/procedure. La funzione/procedura originale appare in fondo allo stack, con ogni funzione/procedura chiamata successivamente sopra di essa, fino alla funzione/procedura corrente in cima allo stack.

Quando l'esecuzione dello script esce da una sottofunzione/sottoprocedura e ritorna alla funzione/procedura chiamante, la prima verrà rimossa dallo stack e la funzione/procedura chiamante diventerà la cima dello stack.

Facendo doppio clic su una voce nel pannello si passa alla riga di script corrispondente in cui viene effettuata la chiamata alla funzione o procedura selezionata. La riga verrà evidenziata con il colore associato agli errori di scripting e mostrerà il marcatore di errore di scripting nel margine destro. Questo viene usato esclusivamente a scopo di evidenziazione. Scomparirà quando si fa clic sul documento e non ostacola in alcun modo la sessione di debug.

Eccezioni e messaggi

Come spesso accade in tutti i progetti di programmazione, lo sviluppo e il debug del codice dello script non si fermano necessariamente a uno script "funzionante". È probabile che, nell'uso pratico, uno script incontri errori imprevisti o non produca i risultati attesi.

Fortunatamente, esistono diversi modi in cui il sistema di scripting può essere utilizzato per gestire le eccezioni di esecuzione e fornire all'utente un feedback sul funzionamento dello script.

Gestori di eccezioni

In DelphiScript, la parola chiave try introduce un'istruzione try-except oppure un'istruzione try-finally. Queste due istruzioni sono correlate ma hanno scopi diversi.

Try Finally

In un gestore Try-Finally, le istruzioni nel blocco finally vengono sempre eseguite, indipendentemente dal fatto che nel blocco try si sia verificata o meno un'eccezione. Utilizzare il blocco try-finally per liberare oggetti temporanei o altre risorse e per eseguire attività di pulizia.

Reset(F);
Try
  // process file F
Finally
  CloseFile(F);
End;

Try Except

Utilizzare l'istruzione Try-Except per intercettare le eccezioni generate ed eseguire il relativo codice di gestione degli errori. Ad esempio, è possibile intercettare un'eccezione specifica e aggiornare un log oppure aprire una finestra di dialogo di errore descrittiva. Un'eccezione nel codice del blocco try provoca l'esecuzione del blocco except.

Nell'esempio seguente, la procedura ApplyOffset viene chiamata, con parametri appropriati, dalla procedura DefineOffset. La procedura esegue un semplice calcolo di divisione (sulle variabili Ydim e Zdim ) e riporta il risultato (Offset) in una finestra di dialogo standard.

Procedure ApplyOffset(Ydim, Zdim);
Var
   Offset;
Begin;
   Try
      Offset := Ydim div Zdim;
      ShowInfo('Calculated Offset = ' + IntToStr(Offset));
   Except
      ShowWarning('Entered Z dimension must be greater than zero.');
   End;
End;

Procedure DefineOffset;
Begin;
   ApplyOffset(32, 4);
End;

Per i parametri ApplyOffset mostrati sopra (32,4), lo script eseguito mostrerà il risultato calcolato utilizzando la procedura ShowMessage, come mostrato di seguito.

In alternativa, modificando i parametri passati a 32,0 (ApplyOffset(32, 0);) si provoca un'eccezione di divisione per zero nel calcolo Offset, attivando il blocco gestore Except. Questo utilizza la procedura ShowWarning per visualizzare una finestra di dialogo Warning pertinente.

Raise

L'ipotesi nella semplice procedura di gestione degli errori sopra descritta è che l'eccezione venga generata in risposta a un errore di divisione per zero, ma ciò significa che altri tipi di eccezioni non verranno riportati accuratamente dal testo della finestra di avviso. In questo esempio, tuttavia, è l'errore di eccezione più probabile che si verifichi.

Una qualche forma di rilevamento specifico dell'errore è comunque auspicabile dal punto di vista dell'utente. In DelphiScript, la parola chiave Delphi On (per intercettare un tipo di eccezione specificato) non è supportata, ma l'istruzione Raise può essere utilizzata all'interno di un blocco Except per rilanciare l'eccezione più recente, qualunque sia il suo tipo.

Try
   Offset := Ydim div Zdim;
   ShowInfo('Calculated Offset = ' + IntToStr(Offset));
Except
   Raise;
End;

In questo modo, quando la maggior parte del codice di una procedura si trova all'interno del blocco try di un'istruzione try-except, tutte le eccezioni possono essere segnalate dall'istruzione Raise . Si noti che la finestra di dialogo dell'eccezione riporterà solo messaggi di errore generici, anziché informazioni specifiche dello script.

Procedure ApplyOffset(Ydim, Zdim);
Var
   Offset;
Begin;
   if Zdim > Ydim then
      Begin;
         Raise('Z dimension must be smaller than Y dimension.');
      End;
   Offset := Ydim div Zdim;
   ShowInfo('Calculated Offset = ' + IntToStr(Offset));
End;

Procedure CreateMessages;
var
   WS : IWorkSpace;
   MM : IMessagesManager;
Begin
   WS := GetWorkSpace;           // obtain Workspace Manager interface
   MM := WS.DM_MessagesManager;  // obtain Message Manager interface
   
   MM.ClearMessages;             // initialize

   MM.BeginUpdate;
   // add relevant messages here using MM.AddMesssage procedures
   MM.EndUpdate;

   WS.DM_ShowMessageView;         // display messages
End;