Testing and debugging scripts

The ACL Script Editor includes several features that help you test or debug ACL scripts:

  • Run scripts from the cursor position in a script
  • Set break points to pause the execution of a script at a specific line
  • Step through scripts by executing one line at a time
  • Isolate script errors
  • In the associated Variables tab, track the creation of variables and the assignment of values to variables in real time

These features are available whenever a script is open in the Script Editor. If the open script calls one or more subscripts, the subscripts are automatically opened when they are called.

While a script is running in step mode, or break point mode, it is read-only, and most other ACL functionality is disabled, including the command line. If a script error occurs, the script becomes editable, allowing you to fix the error.

When you run a script, regardless of how you run it, all open scripts are automatically saved.

Note

If a table remains open at the completion of running or stepping through a script, the ACL display area automatically switches from the Script Editor to displaying the open table in the View tab. If you want to keep the Script Editor continuously displayed while you are testing or debugging scripts, you can temporarily include the CLOSE command at the end of the script.

Running scripts from the cursor

If you do not want to run or step through a script from the beginning of the script you can position the cursor in the line where you want to start script execution and right-click and select Run From Cursor, or Step From Cursor. Running or stepping through scripts from the cursor allows you to test specific portions of a script and avoid the wasted time and effort of running entire scripts needlessly.

You cannot use Run From Cursor or Step From Cursor once a script is running. You can only use these options to start execution of a script, or restart a script after you encounter or fix a script error.

Note

If you use script execution from the cursor to bypass a section of a script that contains prerequisite operations required by a subsequent section of the script, the subsequent section is unlikely to run correctly.

Setting break points

You can set one or more break points in an ACL script to pause the execution of a script at a specific line. Break points allow you to test a portion of a script without having to run the entire script. They also allow you to examine the state of an ACL project at a specific point in a script. Break points can be a useful tool as you develop and test more complex or critical portions of scripts.

Restarting a script from a break point

When you restart a script from a break point, you have the following options:

  • step through the script from the break point
  • run the script to the next break point, if you have inserted one
  • run the script to the end
  • exit the script

Blank lines and comments

If you position a break point at a blank line, or at a comment line, the script pauses at the first line of the script after the blank line or lines, or after the comment.

Persistence of break points

  • Break points persist in a script even if you close the script.
  • At any time, you can remove all break points from all scripts in an ACL project by right-clicking in the Script Editor and selecting Clear All Breakpoints.
  • All break points are automatically removed from all scripts in a project when you close ACL.

Steps

Stepping through scripts

You can step through an ACL script by executing one line at a time. Stepping through a script allows you to test the execution in a controlled manner, and discover any errors at the exact line where they occur.

The step arrow

Green arrow As you step through a script, the green step arrow indicates the line in the script that is about to be executed. When the arrow progresses one step beyond the line, the line has been executed.

Red arrow If the line contains invalid command syntax, or some other type of error, the script stops and the step arrow turns red and does not progress, highlighting the location of the error. The script is read-only while you are stepping through, but if an error occurs the script becomes editable, allowing you to fix the error.

Steps

Isolating script errors

Whenever you run a script in ACL that encounters an error that causes the script to fail, the line where the error occurs is automatically highlighted in the Script Editor. If the Script Editor is not open, it opens automatically. This identification of script errors occurs regardless of whether you run a script directly in the Script Editor, from the Tools menu, from the command line, or by right-clicking a script in the Navigator.

This automated error identification is a powerful troubleshooting capability, especially for errors that occur deep in nested subscripts. ACL users with scripting ability can fix errors as they encounter them. Users unfamiliar with scripting can record the name of the script and the line number where the error occurred, which makes it easier to get help with script problems.

Using the Variables tab

The Variables tab, in the Navigator, allows you to track the creation of variables and the assignment of values to variables in real time. The tab displays the names, values, and data categories of all variables in the ACL project. Names are listed alphabetically.

If you step through a script, any user-defined or system-generated variables in the script, at the moment of their creation, appear in the Variables tab, or have their value updated if they already existed. Being able to watch exactly what changes are happening with script variables, as they happen, is an important diagnostic tool that can allow you to pinpoint script errors that might be hard to locate by examining script syntax alone.

If you run a script, all changes associated with variables are displayed when a break point is reached, or when a script completes.

Multiline commands

You cannot step through the content of multiline commands such as GROUP, LOOP, or DEFINE FIELD . . . COMPUTED. If you are running a script in step mode and you encounter a multiline command, the entire content of the command is executed and the step arrow is positioned at the line in the script immediately following the end of the multiline command.

Break points are not recognized inside multiline commands. If you set a break point inside a multiline command, the script is paused at the line in the script immediately following the end of the multiline command.

You may be able to test portions of the content of a multiline command by copying the content, without the surrounding command syntax, into a separate script.

Testing an analytic that includes a PASSWORD tag

If you test an analytic by running it in ACL and the analytic has one or more PASSWORD tags, ACL automatically generates a PASSWORD command and prompts you to enter the appropriate password. This auto-generated command saves you the labor of inserting PASSWORD commands in the script portion of an analytic for the purposes of testing, and then removing them again before delivering the analytic to users. The auto-generated PASSWORD command is saved in the log, without the password value.

Password values are not saved when you run an analytic in ACL, so you must specify the password or passwords each time you run the analytic, including running or stepping through the analytic from the cursor position.

ACL analytics are regular ACL scripts with additional annotations that allow them to run in the Analysis App window, which is a freestanding component of ACL, and in ACL GRC Analytics Exchange.

[ Back to top ]

(C) ACL Services Ltd. All Rights Reserved. Thursday, October 4, 2018