Testing and debugging scripts

The Analytics Script Editor includes several features that help you test or debug Analytics 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 Analytics 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 Analytics 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 Analytics 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 Analytics 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 Analytics 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 Analytics.

Steps

Set one or more break points

  1. Open the Analytics script in which you want to set one or more break points .
  2. Click the break point column immediately to the left of the target line in the Analytics script.

    The break point column is located between the line numbering column and the left margin of the script.

    You can also set a break point by positioning the cursor in the target line in the script and pressing F9 or clicking Toggle breakpoint  in the Script Editor toolbar.

  3. To remove a break point, click the break point, or position the cursor in the target line and press F9 or click Toggle breakpoint .

Run a script with a break point

  1. Click Run  or press F5 to run the script to the break point.

    The script starts running and executes to the break point. While the script is running in break point mode it is read-only, and most other Analytics functionality is disabled, including the command line.

  2. To move beyond the break point, click Run  or press F5.

    The script runs to the next break point, or if there are no other break points, completes execution of the script.

  3. If the step arrow turns red and stops at a line, indicating an error, the script becomes editable and you can fix the error, and then do either of the following:
    • Continue running the script from the point of the error, or from any other line, by placing the cursor in the appropriate line, and right-clicking and selecting Run From Cursor.
    • Restart the script from the beginning by clicking Run  or pressing F5.

    If a table is open when the error occurs, the Analytics display area automatically switches from the Script Editor to displaying the open table in the View tab. Switch back to the Script Editor to fix the error.

  4. If you want to exit the script before it completes, press Esc and click Yes in the confirmation prompt.

    You can also exit the script by closing Analytics.

  5. After a break point, or after fixing an error, if you want to step through the remainder of the script, do one of the following:
    • After a break point, click Step  or press F10.
    • After fixing an error, place the cursor in the appropriate line, and right-click and select Step From Cursor.

Stepping through scripts

You can step through an Analytics 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

  1. Open the Analytics script that you want to step through.
  2. Click Step or press F10 repeatedly.

    The script starts when you click Step or press F10. A single line is executed, in sequence, each additional time you click Step or press F10.

    While the script is running in step mode it is read-only, and most other Analytics functionality is disabled, including the command line.

  3. If the step arrow turns red , indicating an error, the script becomes editable and you can fix the error, and then do either of the following:
    • Continue stepping through the script from the point of the error, or from any other line, by placing the cursor in the appropriate line, and right-clicking and selecting Step From Cursor.
    • Restart the script and begin stepping through from the beginning by clicking Step  or pressing F10.

    If a table is open when the error occurs, the Analytics display area automatically switches from the Script Editor to displaying the open table in the View tab. Switch back to the Script Editor to fix the error.

  4. If you want to exit the script before it completes, press Esc and click Yes in the confirmation prompt.

    You can also exit the script by closing Analytics.

  5. At any point, if you want to run the remainder of the script without stepping through, click Run or press F5.

Isolating script errors

Whenever you run a script in Analytics 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. Analytics 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 Analytics 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 run 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 immediately following 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 immediately following the multiline command.

Tip

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 script that includes a PASSWORD analytic tag

If you test an analytic script by running it in Analytics and the script has a PASSWORD tag in the analytic header, Analytics automatically generates a PASSWORD command and prompts you to enter the appropriate password. This auto-generated command saves you the labor of inserting a PASSWORD command in the script portion of the analytic script for the purposes of testing, and then removing it again before uploading the analytic script to Robots or AX Server. The auto-generated PASSWORD command is saved in the log, without the password value.

The password value is not saved when you run the analytic script in Analytics, so you must specify the password each time you run the analytic script, including running or stepping through the script from the cursor position.

Analytic scripts are regular scripts with analytic headers that allow them to run in the Robots app on the HighBond platform, or in Analytics Exchange. You can also run analytic scripts in the Analysis App window, a freestanding component of Analytics.