Debugging Scripts in Altium Designer

The Altium Designer Scripting system offers a full-featured debugging environment. The Scripting Debugger helps you to identify and resolve errors in scripts by providing a range of automated tools and information panels.

Script Errors

Common errors include invalid methods, misplaced grouping operators, mismatched types, logic errors, and typographical errors. When the scripting system encounters an error, the debugger will pause the script and display an error dialog indicating the problem.

The below example shows a script with a missing terminating character and the matching error dialog message.

The debugger will pause a script in response to compile or run time errors.

Once the error dialog is dismissed, the code can then be corrected and the script re-run. If the script needs to be stopped – such as when stepping it through – use the Stop command (Run » Stop, Ctrl+F3) or button ( on the Script Debug toolbar).

Script Debugging

There is a range of tools in the scripting system to help in debugging scripts. These include applying multiple breakpoints in a script, using the Watch List panel to monitor the value of variables, using the bookmarks to jump around more efficiently, and using step into and over facilities to trace through scripts.

For example, the following features can be used when checking the values of variables and expressions in a script:

• Breakpoints
• Expression Evaluation tooltips
• Insight tool tips
• Evaluate dialog
• Watch Expressions

► See Script Editor Tools for information on using the editor tools when debugging scripts.

Tracing

To help find and resolve an unknown error in a script, a series of breakpoints can be inserted into a script to pause the code at multiple points while the values of variables and expressions are checked.

At any point when the script is paused, however, the script can also be advanced one functional line at a time using the Debugger's tracing/step features. In this way, a breakpoint can be used to initially pause the script in the area of interest then advanced one line at a time using the tracing feature. The process of executing a script one line at a time is referred to as tracing or script stepping.

The Script debugger provides commands related to tracing – stepping into (Run » Step Into) and stepping over (Run » Step Over). This allows you to trace the script process and analyze its behavior when debugging the script code.

The Debugging commands available in the Run menu.

Step Into Command

The Step Into process executes script one statement at a time. The command is available from the Run menu, its associated Script Debug toolbar button (), or the F7 shortcut key.

If the statement being executed calls another procedure, stepping into that statement transfers control to the first line in the called procedure. The pea-green colored highlighting in the editor indicates the code line that the script is up to. The script stepping process is canceled with the Run » Stop command, the Ctrl+F3 shortcut, or the toolbar button ().

Step Over Command

The Step Over process is similar to Step Into, except that if the current statement is a call to another procedure, the entire called procedure is executed without stopping rather than tracing through the called procedure. The command is available from the Run menu, its associated button (), or the F8 shortcut key.

This command is useful when it has been determined that a called procedure is not the cause of the problem in the current procedure, and avoids having to needlessly trace through the called procedure line by line – that procedure is 'stepped over'.

Call Stack Panel

The Call Stack panel is used to view the chain of procedures and functions that have led to the current point of execution in the script being debugged.

The Call Stack panel

As you step-debug your script, the panel will show the name of any function or procedure that you enter.

When a call to another function or procedure is encountered, the panel will show the name of this additional function/procedure as it is entered. As the function/procedure is called from within a function/procedure, the original function/procedure is still displayed in the panel.

A 'call stack' is effectively set up, showing the relationship between descendant function/procedure calls. The original function/procedure appears at the bottom of the stack, with each subsequently called function/procedure above it, right up to the currently entered function/procedure on the top of the stack.

As script execution drops out of a sub-function/procedure and passes back into the calling function/procedure, the former will be removed from the stack and the calling function/procedure will become the top of the stack.

Double-clicking on an entry in the panel will jump to the corresponding line of script in which the call to the selected function or procedure is made. The line will be highlighted in the color associated with scripting errors and will have the scripting error marker displayed in the right-hand margin. This is purely used for highlighting purposes. It will disappear when you click on the document and does not inhibit the debug session in any way.

Exceptions and Messages

As tends to be the case with all programming projects, developing and debugging the script code does not necessarily stop with a 'working' script. It is likely that in practical use a script will encounter unforeseen errors, or may not deliver the expected results.

Fortunately, there are a number of ways the scripting system can be used to handle execution exceptions and provide user feedback about the script operation.

Exception Handlers

In DelphiScript, the try keyword introduces a try-except statement or a try-finally statement. These two statements are related but serve different purposes.

Try Finally

In a Try-Finally handler, the statements in the finally block are always executed – regardless of whether an exception error occurred in the try block. Use try-finally block to free temporary objects or other resources, and to perform clean up activities.

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

Try Except

Use the Try-Except statement to catch raised exceptions and execute related error handling code. For example, a specific exception can be caught and a log updated or a descriptive error dialog box opened. A code exception in the try block causes the except block to be executed.

In the below example, the ApplyOffset procedure is called, with suitable parameters, from the DefineOffset procedure. The procedure makes a simple division calculation (on the Ydim and Zdim variables) and reports the result (Offset) in a standard dialog box.

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;

For the ApplyOffset parameters shown above (32,4), the executed script will show the calculated result using the ShowMessage procedure, as shown below.

Alternatively, changing the passed parameters to 32,0 (ApplyOffset(32, 0);) induces a divide-by-zero exception in the Offset calculation, triggering the Except handler block. This uses the ShowWarning procedure to display a relevant Warning dialog box.

Raise

The assumption in the above simple error handling procedure is that the exception is raised in response to a divide by zero error, but this means that other types of exceptions will not be accurately reported by the warning dialog text. In this example however, it is the most likely exception error that will be encountered.

Some form of specific error detection is nevertheless desirable from a user perspective. In DelphiScript the Delphi On keyword (to catch a specified exception type) is not supported, but the Raise statement can used inside an Except block to raise the most recent exception (whatever type it may have been).

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

In this way, when the bulk of a procedure's code exists inside the try block of a try-except statement, all exceptions can be reported by the Raise statement. Note that exception dialog will only report generic error messages, rather than information specific to the script.

Raise can also be used to induce an exception in response to specific tests, for example by applying simple if-then or case statements.

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;

Here, if the above example's Zdim parameter is larger than the Ydim parameter an exception (with message) is raised.

Errors in VB Scripts

The VBScript implementation in the Altium Designer scripting engine has built in functions that can be used in VBScript script projects, such as the MsgBox function.

The On Error statement can be used when trapping errors in VB Scripts. Consult the Microsoft VBScript documentation for more information on trapping errors.

Messages

In general, messages are the primary way to enhance script operation from a user perspective.

Messages can provide alerts for exceptions or indicate running information and warnings, and can be inserted in script routines that deal with input data, calculations, file operations or any procedure where a procedural insight would be beneficial.

Message Dialogs

Along with the basic message dialog available in the scripting system (ShowMessage), a range of specific dialogs are available to provide tailored user feedback.

These include message procedures such as:

• ShowError
• ShowException
• ShowInfo
• ShowWarning
• and more..

Messages Panel

Altium Designer's Messages panel can be a useful debugging tool for scripting, but can also be applied to provide a running stream of useful message information for the user.

The Messages panel is a Workspace Manager object that accessed from the Message Manager interface. The Messages panel can be used in a script to show the states of variables and properties (or indeed any other data) for both debugging and user feedback, as outlined in the example below.

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;