Scripter Automation Debugging Tips and Tricks

Automation is a way of running a program without having to interact with the program’s user interface. This is especially useful if you need to create many maps or graphs that contain the same properties. Most program operations can be controlled through a script. A script is a text file containing a series of instructions carried out when the script is run. A single script can create all of the objects at once, so no time is wasted repeating the same commands in the program over and over again. Many different programs can be used to access automation objects. Such programs include Visual BASIC, Windows Script Host, and many of the Microsoft Office applications, among others.

Golden Software's Scripter is a program for developing and running scripts. Instructions are written in a Visual BASIC-like programming language. Scripter offers many features to help you write, edit, and debug scripts. Its features include language syntax coloring, a list of the procedures defined in the script, an object browser for examining procedures available in external objects, a visual dialog editor, break points, single-step execution (including options to step over and to step out of procedures), a watch window for displaying the values of script variables, and more. Scripter is distributed free with Golden Software programs that support automation.

The Scripter application is included with Golden Software programs that support automation.

Which Programs Support Automation

MapViewer, Grapher, Surfer, and Voxler support automation. To open Scripter, click the Windows Start button, click on the appropriate Golden Software program folder in the full program list, and click the Scripter link.

Where Can I Find Script Examples

Script examples are located in each program’s Samples directory, each program's Knowledge base, and on our file download site at https://s3.amazonaws.com/public.goldensoftware.com/index.html?prefix=scripts/.

Script snippets are located in each program’s help file. Open the help and click on the Automation directory. Each object is listed in the Object Overview or Object Hierarchy. All methods and properties are listed in the Methods and Properties directory. Most objects, methods, and properties have an example script snippet. The snippets can be combined and edited slightly to form complete scripts.

Additionally, Grapher can record a script from within the program. Click the Automation | Scripts | Record button. A previous newsletter article, Creating a Script using Grapher's Script Recorder, stepped through using the Script Recorder in Grapher. In addition, a tutorial lesson is included in Grapher that steps through the process of recording a script.

Parts of the Scripter Window

Scripter has several useful windows and areas that can help you debug your scripts. These are the Immediate Pane, the Watch Pane, the Stack Window, the Loaded Window, the Object list, the Proc list, the Break Bar, and the Status Bar. If you don’t see all of these windows, click the View | Always Split command. The Immediate Pane and Watch Pane are particularly useful, especially when running or debugging scripts.

This image highlights the parts of the Scripter window.

The Immediate Pane is useful for seeing Debug.Print statements while the script is running or after the script is complete. It is also useful for running one line statements of code.

This Immediate Pane shows the Application object reference and a Debug.Print statement, listing the plot name.

The Watch Pane is useful for debugging scripts. You can type lines of code here to evaluate. Use it for identifying objects and references.

This Watch Pane displays the name of the GrapherApp object.

The Stack Window shows which line is currently being executed. The first line is the current statement; the second line (when there is one) called the first line, and so on. Clicking on a line brings that script/module into a window and highlights the line in the edit window.

This Stack Window shows the script that is running and the line that the script is stopped on.

The Loaded Window is useful when you have multiple scripts (scripts within scripts). It shows the name of the script(s) that are running.

This Loaded Window displays all of the scripts that are running. The top script is the current script. The other scripts are called by the current script.

The Object list shows all the objects for the current module. The Proc list shows all the procedures for the current object. For additional information about objects, modules, and procedures, refer to the help file included with Scripter.

The Break Bar highlights points in the script where a stop or pause has been inserted. It also highlights the row that a script stops on, if the script does not complete.

The Status Bar displays the error message if a script does not complete. Before running a script, verify that the View | Status Bar command is enabled, otherwise you will not see the error message.

Finding the Right Command

It can sometimes be difficult to find the right command to perform an action in a script. Here are some general tips to find the right command:

Always walk through the process in the program’s interface. The names of objects are often the same in the program and automation. For example, if you want to create a contour map in the Surfer program, you click the Home | New Map | Contour command in a new plot window. This creates a new object (or shape) in the Contents window. To do this in a script, after creating a plot window, add the contour map through the Shapes collection AddContourMap command.
Search the help. Every method and property has information about how to use it. Every object has information about how to call it. You can often search for the object name (like contourmap) with no space between words and find the appropriate object type.	The Object Hierarchy is pictured here. It helps determine which objects use which other objects and aids you in finding the appropriate command.
Copy/paste from existing scripts or script snippets in the help. You may need to modify the section you are copying, but this is often easier than starting from scratch.
For non-program specific commands (BASIC commands such as declarations, flow control, math operations, etc), use the Help | Basic Language Help command in Scripter. If you aren’t sure if a command is program specific (such as creating a Surfer contour map), first try searching in the help's Automation directory, which lists program specific commands.
Always start with the Object Hierarchy or Object Overview if you don’t know what object you need or how to access the object. Each program has an object hierarchy that steps you through how objects are connected. In the previous example, you see Application | Documents | PlotDocument| Shapes Collection. This means you need to traverse or drill through these other objects to create the contour map.

Tips on Using the Object Hierarchy

To access a particular object you must traverse the object hierarchy using the methods and properties provided by the objects. Methods and properties are used to edit the object’s properties. Refer to the help file for additional information about what methods and properties are and how to use them.

If you want to create an ellipse, for example, in the program, you would need to create a plot window and click on the Draw | Ellipse command. This creates an object in the Object Manager. In the script, you have to go through the Application | Documents | PlotDocument | Shapes Collection before you can get to Ellipse. In a script, each object is separated by decimal point, like this: Application.Documents.PlotDocument.Shapes.Ellipse. Specifically, this would appear as:

SurferApp.Documents(1).Plots.Shapes.AddEllipse(..)

Click on an object in the object hierarchy to see all of the methods and properties for that object. For example, if you want to create an ellipse, you need a command from the Shapes collection to create it. In the program, this was Draw | Ellipse. In the script, you would do a similar command. To determine the exact command, click on the Shapes Collection in the Object Hierarchy. On the Shapes Collection page, scroll down and click on the AddEllipse method. The displayed page shows all of the information needed to create the ellipse and an example demonstrating it. The example (in the Surfer help) shows:

Set Ellipse = Shapes.AddEllipse(Left:=5, Bottom:=7, Right:=6, Top:=10)

The left side of the first = is the name of the new object being created. The right side contains the Shapes collection, the command to add the ellipse, and the options necessary to create the object.

If you want to change the properties of the ellipse, you can click on the Ellipse object in the Object Hierarchy. The only properties listed on the Ellipse Object page are Fill and Line. This is similar to the options available in the program. In the program, in the Property Manager there is a Fill tab and Line tab for the ellipse. If you click on either of the Fill Property or Line Property pages, the property page describing the property is listed.

From the property page, you can click on links to LineFormat Object and FillFormat Object pages, which contain the Line and Fill properties. These properties are shared by all objects that have line or fill attributes. The Common Objects section of the Object Hierarchy page also take you directly to these shared object types, like LineFormat, FillFormat, MarkerFormat, etc.

When you click the link to LineFormat Object or FillFormat Object, that object page is displayed. You’ll notice various properties, like ForeColorRGBA, Style, etc. These are properties of the new object. These same properties are in the Property Manager, when you click on the Line or Fill tab.

	LineFormat.Style = “Solid” LineFormat.ForeColorRGBA.Color = srfColorBlack LineFormat.ForeColorRGBA.Opacity = 100 LineFormat.Width = 0
The Property Manager on the left has the same properties as the script snippet on the right.

To know how to use a property, click on that property name. For instance, when you click on Width, you see:

The syntax object.Width is used when returning the property of the object:

Debug.Print Objectname.width

The syntax object.Width = is used when setting the property of an object:

Objectname.Width = 0.214

The Type is Double – a number format. The Description explains what should be included. In this case, the value, which indicates the width in page units, is required.

Debugging Scripts

Debugging a script is the process of finding why a script is not working properly and correcting it. Here are some tips to debugging a script:

• Before running a script, verify that the View | Status Bar command is checked, otherwise you will not see the error message when the script fails.
• Press F5 to run a script (Script | Run). The script will go until it reaches an error. This is a good first debugging step, as long as there is not an On Error GotoErrLabel line in the script (see below for this option). The script stops and waits at the first error.
• Probably the simplest debugging technique is to insert instructions into your script to monitor the progress of the script and display the values of variables at various points throughout the script. Use the Debug.Print statement to display information in the Scripter immediate window:
  Debug.Print "The value of variable x is "; x
• Click the Debug | Browse command to browse all objects and see their properties. Sometimes the help example may not be complete or may have an option misspelled. But Browse always contains the correct information. The commands listed in Browse are created directly from the program and the syntax listed here must match your script for the command to work.
• Use F8 (Debug | Step Into) to step through scripts one line at a time. This determines the exact order in which commands are executed, which can help you determine why a script is not working in the expected manner.
• Use F9 (Debug | Toggle Break) to add a break line. The script can then run until it gets to the break line. The break line is displayed as a red dot in the break bar (the area between the sheet tabs and the code window).
• Use SHIFT+F8 (Debug | Step Over) to step over commands without executing them. This is extremely useful for loops. If you know the loop functions properly, you won’t want to step through the loop for each increment, so this lets you bypass the loop entirely.
• Use F7 (Debug | Step to Cursor) to run the script up to the point where your cursor is in the script. This is extremely useful when you know everything works up to a certain point in a script.
• If you want to skip errors, so the script will not stop if or when a command fails, use something like this in your script:
  Sub OpenFile(srf As Object, filename As String)
      On Error Goto ErrLabel
      srf.Documents.Open filename
  Exit Sub
  
  ErrLabel:
     MsgBox "Unable to open file " & filename
      ' Must use RESUME or EXIT at end of
      ' error handling code
      Exit
  End Sub
  The On Error Goto ErrLabel line tells Scripter that when an error is encountered, it should go to the ErrLabel subroutine. This will exit the script gracefully, instead of stopping on the error message line. This is useful when you want the script to complete, regardless of an error condition.
• While a script is paused (either due to a break line or an error in the script), there are several ways to view the value of a variable:
  • In the Immediate Pane, type a question mark, followed by the variable name and press ENTER. The current value of the variable is displayed.?GrapherApp
  • In the code window, place the cursor on the variable name you want to examine (that is, click on the variable name in the code window). Press SHIFT+F9, select the Debug | Quick Watch command, or click this  button on the toolbar. The current value of the variable is displayed in the Immediate Pane.
• To continuously monitor a variable’s value, click on the variable name in the code window, and press CTRL+F9 or select the Debug | Add Watch command. Alternatively, type the variable name in the Watch Pane and press ENTER. The variable name and its value are displayed in the Watch Pane. Every time the script execution pauses, the variable value is automatically updated. To clear a variable from the Watch Pane, highlight the line showing the variable value and press the DELETE or BACKSPACE key.
• If a command that you know should work (like srfColorRed for Surfer) is not working, and you have multiple Golden Software products and/or versions, you could be running a different Scripter than you want (for example, a Grapher Scripter for Surfer, or a Surfer 9 Scripter for a Surfer 11 script). Because four Golden Software programs all use Scripter, it can be difficult to know which Scripter window is open. Click Edit | References and check the box next to the program name you want to run. If it is not checked, the named arguments will not work from the script.

Conclusion

Scripter makes creating graphs and maps more efficient by allowing you to run commands automatically, instead of manually in the user interface. Scripter has an easy-to-use window interface, and some debugging tools that help you determine why your script isn’t running as it should. The help associated with each program includes an Object Hierarchy that makes it easy to locate the appropriate command. Using a combination of the help and the Scripter debugging features, your script will be creating publication-quality maps and graphs in no time.

Updated February 13, 2024