Debugging Scripts

Das Scripting-System von Altium Designer bietet eine voll ausgestattete Debugging-Umgebung. Der Scripting-Debugger hilft Ihnen dabei, Fehler in Skripten zu identifizieren und zu beheben, indem er eine Reihe automatisierter Werkzeuge und Informationsfenster bereitstellt.

Skriptfehler

Häufige Fehler sind ungültige Methoden, falsch platzierte Gruppierungsoperatoren, nicht übereinstimmende Typen, Logikfehler und Tippfehler. Wenn das Scripting-System auf einen Fehler stößt, hält der Debugger das Skript an und zeigt einen Fehlerdialog an, der auf das Problem hinweist.

Das folgende Beispiel zeigt ein Skript mit einem fehlenden Abschlusszeichen sowie die dazugehörige Meldung im Fehlerdialog.

Der Debugger hält ein Skript als Reaktion auf Kompilierungs- oder Laufzeitfehler an.

Sobald der Fehlerdialog geschlossen wurde, kann der Code korrigiert und das Skript erneut ausgeführt werden. Wenn das Skript angehalten werden muss – etwa beim schrittweisen Durchlaufen – verwenden Sie den Befehl Stop (Run » Stop, Ctrl+F3) oder die Schaltfläche ( in der Symbolleiste Script Debug).

Skript-Debugging

Im Scripting-System steht eine Reihe von Werkzeugen zur Verfügung, die beim Debuggen von Skripten helfen. Dazu gehören das Setzen mehrerer Haltepunkte in einem Skript, die Verwendung des Fensters Watch List zur Überwachung von Variablenwerten, die Nutzung von Lesezeichen für effizienteres Navigieren sowie die Funktionen Step Into und Step Over zum Nachverfolgen von Skripten.

Beispielsweise können beim Prüfen der Werte von Variablen und Ausdrücken in einem Skript die folgenden Funktionen verwendet werden:

• Haltepunkte
• Tooltips zur Ausdrucksauswertung
• Insight-Tooltips
• Dialogfeld „Evaluate“
• Überwachungsausdrücke

► Informationen zur Verwendung der Editor-Werkzeuge beim Debuggen von Skripten finden Sie unter Script Editor Tools.

Nachverfolgung

Um einen unbekannten Fehler in einem Skript zu finden und zu beheben, kann eine Reihe von Haltepunkten in das Skript eingefügt werden, damit der Code an mehreren Stellen angehalten wird, während die Werte von Variablen und Ausdrücken geprüft werden.

Immer wenn das Skript angehalten ist, kann es außerdem mithilfe der Nachverfolgungs-/Schritt-Funktionen des Debuggers jeweils um eine funktionale Zeile weitergeführt werden. Auf diese Weise kann ein Haltepunkt verwendet werden, um das Skript zunächst im interessierenden Bereich anzuhalten und es dann mit der Nachverfolgungsfunktion Zeile für Zeile weiterzuführen. Der Vorgang, ein Skript Zeile für Zeile auszuführen, wird als Nachverfolgung oder schrittweises Durchlaufen des Skripts bezeichnet.

Der Skript-Debugger stellt Befehle für die Nachverfolgung bereit – Step Into (Run » Step Into) und Step Over (Run » Step Over). Dadurch können Sie den Skriptablauf verfolgen und sein Verhalten beim Debuggen des Skriptcodes analysieren.

Die im Menü Run verfügbaren Debugging-Befehle.

Befehl „Step Into“

Der Vorgang Step Into führt das Skript Anweisung für Anweisung aus. Der Befehl ist im Menü Run , über die zugehörige Schaltfläche in der Symbolleiste Script Debug () oder über die Tastenkombination F7 verfügbar.

Wenn die ausgeführte Anweisung eine andere Prozedur aufruft, überträgt das Hineinspringen in diese Anweisung die Steuerung auf die erste Zeile der aufgerufenen Prozedur. Die erbsengrüne Hervorhebung im Editor zeigt die Codezeile an, bei der das Skript aktuell angekommen ist. Der Vorgang des schrittweisen Durchlaufens des Skripts wird mit dem Befehl Run » Stop, der Tastenkombination Ctrl+F3 oder der Symbolleistenschaltfläche () abgebrochen.

Befehl „Step Over“

Der Vorgang Step Over ist ähnlich wie Step Into, mit dem Unterschied, dass bei einem Aufruf einer anderen Prozedur in der aktuellen Anweisung die gesamte aufgerufene Prozedur ohne Anhalten ausgeführt wird, anstatt sie Schritt für Schritt nachzuverfolgen. Der Befehl ist im Menü Run , über die zugehörige Schaltfläche () oder über die Tastenkombination F8 verfügbar.

Dieser Befehl ist nützlich, wenn festgestellt wurde, dass eine called Prozedur nicht die Ursache des Problems in der aktuellen Prozedur ist, und vermeidet, dass die aufgerufene Prozedur unnötigerweise Zeile für Zeile nachverfolgt werden muss – diese Prozedur wird „übersprungen“.

Fenster „Call Stack“

Das Fenster Call Stack wird verwendet, um die Kette von Prozeduren und Funktionen anzuzeigen, die zum aktuellen Ausführungspunkt im gerade debugten Skript geführt haben.

Das Fenster Call Stack 

Während Sie Ihr Skript schrittweise debuggen, zeigt das Fenster den Namen jeder Funktion oder Prozedur an, die Sie betreten.

Wenn ein Aufruf einer weiteren Funktion oder Prozedur erfolgt, zeigt das Fenster den Namen dieser zusätzlichen Funktion/Prozedur an, sobald sie betreten wird. Da die Funktion/Prozedur innerhalb einer anderen Funktion/Prozedur aufgerufen wird, bleibt die ursprüngliche Funktion/Prozedur weiterhin im Fenster sichtbar.

Dadurch wird effektiv ein „Call Stack“ aufgebaut, der die Beziehung zwischen untergeordneten Funktions-/Prozeduraufrufen zeigt. Die ursprüngliche Funktion/Prozedur erscheint unten im Stack, jede danach aufgerufene Funktion/Prozedur darüber, bis hin zur aktuell betretenen Funktion/Prozedur ganz oben im Stack.

Wenn die Skriptausführung eine Unterfunktion/-prozedur verlässt und in die aufrufende Funktion/Prozedur zurückkehrt, wird die erstere aus dem Stack entfernt und die aufrufende Funktion/Prozedur wird zum obersten Eintrag im Stack.

Ein Doppelklick auf einen Eintrag im Fenster springt zu der entsprechenden Skriptzeile, in der der Aufruf der ausgewählten Funktion oder Prozedur erfolgt. Die Zeile wird in der Farbe hervorgehoben, die Skriptfehlern zugeordnet ist, und im rechten Rand wird die Markierung für Skriptfehler angezeigt. Dies dient ausschließlich der Hervorhebung. Sie verschwindet, wenn Sie auf das Dokument klicken, und beeinträchtigt die Debug-Sitzung in keiner Weise.

Ausnahmen und Meldungen

Wie bei allen Programmierprojekten üblich, endet die Entwicklung und das Debuggen des Skriptcodes nicht unbedingt mit einem „funktionierenden“ Skript. Es ist wahrscheinlich, dass ein Skript im praktischen Einsatz auf unvorhergesehene Fehler stößt oder nicht die erwarteten Ergebnisse liefert.

Glücklicherweise gibt es mehrere Möglichkeiten, wie das Scripting-System verwendet werden kann, um Ausnahmen während der Ausführung zu behandeln und dem Benutzer Rückmeldungen über den Skriptbetrieb zu geben.

Exception-Handler

In DelphiScript leitet das Schlüsselwort try eine try-except-Anweisung oder eine try-finally-Anweisung ein. Diese beiden Anweisungen sind verwandt, dienen jedoch unterschiedlichen Zwecken.

Try Finally

In einem Try-Finally-Handler werden die Anweisungen im Block finally immer ausgeführt – unabhängig davon, ob im Block try ein Ausnahmefehler aufgetreten ist. Verwenden Sie den Block try-finally, um temporäre Objekte oder andere Ressourcen freizugeben und Aufräumarbeiten durchzuführen.

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

Try Except

Verwenden Sie die Try-Except-Anweisung, um ausgelöste Ausnahmen abzufangen und den zugehörigen Fehlerbehandlungscode auszuführen. So kann beispielsweise eine bestimmte Ausnahme abgefangen und ein Protokoll aktualisiert oder ein beschreibendes Fehlerdialogfeld geöffnet werden. Eine Code-Ausnahme im Block try führt dazu, dass der Block except ausgeführt wird.

Im folgenden Beispiel wird die Prozedur ApplyOffset mit geeigneten Parametern aus der Prozedur DefineOffset aufgerufen. Die Prozedur führt eine einfache Divisionsberechnung durch (mit den Variablen Ydim und Zdim ) und meldet das Ergebnis (Offset) in einem Standarddialogfeld.

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;

Für die oben gezeigten Parameter ApplyOffset (32,4) zeigt das ausgeführte Skript das berechnete Ergebnis mithilfe der Prozedur ShowMessage an, wie unten dargestellt.

Alternativ führt das Ändern der übergebenen Parameter auf 32,0 (ApplyOffset(32, 0);) zu einer Division-durch-null-Ausnahme in der Berechnung Offset, wodurch der Handler-Block Except ausgelöst wird. Dieser verwendet die Prozedur ShowWarning, um ein entsprechendes Dialogfeld Warning anzuzeigen.

Raise

Die Annahme im oben gezeigten einfachen Fehlerbehandlungsverfahren ist, dass die Ausnahme als Reaktion auf einen Division-durch-null-Fehler ausgelöst wird. Das bedeutet jedoch, dass andere Arten von Ausnahmen im Text des Warnungsdialogs nicht korrekt gemeldet werden. In diesem Beispiel ist dies jedoch der wahrscheinlichste Ausnahmefehler, der auftreten wird.

Aus Benutzersicht ist dennoch eine Form spezifischer Fehlererkennung wünschenswert. In DelphiScript wird das Delphi-Schlüsselwort On (zum Abfangen eines angegebenen Ausnahmetyps) nicht unterstützt, aber die Anweisung Raise kann innerhalb eines Blocks Except verwendet werden, um die zuletzt aufgetretene Ausnahme erneut auszulösen, unabhängig von ihrem Typ.

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

Auf diese Weise können, wenn sich der Großteil des Codes einer Prozedur innerhalb des Blocks try einer Try-Except-Anweisung befindet, alle Ausnahmen durch die Anweisung Raise gemeldet werden. Beachten Sie, dass der Ausnahmedialog nur allgemeine Fehlermeldungen anzeigt und keine skriptspezifischen Informationen.

Raise Raise kann auch verwendet werden, um als Reaktion auf bestimmte Prüfungen eine Ausnahme auszulösen, beispielsweise durch einfache if-then- oder case-Anweisungen.

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;

Wenn hier der Parameter Zdim des obigen Beispiels größer ist als der Parameter Ydim, wird eine Ausnahme (mit Meldung) ausgelöst.

Fehler in VB-Skripten

Die VBScript-Implementierung in der Scripting-Engine von Altium Designer verfügt über integrierte Funktionen, die in VBScript-Skriptprojekten verwendet werden können, wie etwa die Funktion MsgBox .

Die On Error-Anweisung kann beim Abfangen von Fehlern in VB-Skripten verwendet werden. Weitere Informationen zum Abfangen von Fehlern finden Sie in der Microsoft VBScript-Dokumentation.

Meldungen

Im Allgemeinen sind Meldungen die wichtigste Möglichkeit, den Ablauf eines Skripts aus Benutzersicht zu verbessern.

Meldungen können auf Ausnahmen hinweisen oder Laufzeitinformationen und Warnungen anzeigen und in Skriptroutinen eingefügt werden, die Eingabedaten, Berechnungen, Dateivorgänge oder andere Verfahren verarbeiten, bei denen ein Einblick in den Ablauf hilfreich ist.

Meldungsdialoge

Neben dem grundlegenden Meldungsdialog, der im Skriptsystem verfügbar ist (ShowMessage), steht eine Reihe spezifischer Dialoge zur Verfügung, um dem Benutzer gezieltes Feedback zu geben.

Dazu gehören Meldungsprozeduren wie:

• ShowError
• ShowException
• ShowInfo
• ShowWarning
• und weitere..

Bereich „Messages“

Der Messages Bereich von Altium Designer kann ein nützliches Debugging-Werkzeug für Skripte sein, lässt sich aber auch verwenden, um dem Benutzer einen fortlaufenden Strom nützlicher Meldungsinformationen bereitzustellen.

Der Messages Bereich ist ein Workspace-Manager-Objekt, auf das über die Message-Manager-Schnittstelle zugegriffen wird. Der Messages Bereich kann in einem Skript verwendet werden, um die Zustände von Variablen und Eigenschaften (oder auch beliebigen anderen Daten) sowohl zum Debuggen als auch für Benutzerfeedback anzuzeigen, wie im folgenden Beispiel dargestellt.

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;