Debugging PerfectScript macros

PerfectScript macros are written with an editor and saved as a source file. The macro compiler creates an object, which it saves in a hidden area of the source (the macro compiler does not create a separate object file). When you save a source file, the object is destroyed. It is recreated each time the source file is compiled. A compiled source file (macro) contains instructions that are executed when you play the macro.

A macro compiler is used to compile or “translate” macros so that WordPerfect Office applications can play them. Macros in PerfectScript are compiled when you record, play, or save them. The tool used for compiling PerfectScript macros is the PerfectScript Debugger.

Compilation errors

Sometimes, when you type or edit a macro, errors are created. For example, if you mistype a word, when you compile the macro, a compile-time syntax error displays a syntax error message. The compiler does not recognize typographical errors and guesses that it is a label’s calling statement. When the compiler reaches the end of the file and does not find a corresponding label, it displays a syntax error message. The message contains information about the error and its location. The compiler makes a best guess and may not always be accurate. The compiler identifies syntax errors and suggests solutions.

Common syntax errors are caused by

•

missing semicolons between parameters

•

missing parentheses

•

missing double quotation marks

•

missing command in a conditional or loop statement

•

undefined calling statements

•

using commas between parameters instead of semicolons

Run-time errors

Run-time is the same as execution time. Run-time errors occur while the macro is playing. Referencing a variable that has not been assigned a value causes a run-time error. Run-time error messages identify errors that occur while the macro plays and show where the errors occur.

For users familiar with other programming languages such as Visual Basic or C++, the PerfectScript Debugger has many of the same features and buttons found in those language compilers.

Debugging breakpoints

Use breakpoints to indicate locations in the macro where execution of the macro should be interrupted and suspended, and where the debugger should become active. While the macro executes statements, the debugger is mostly inactive, and the debugger state message line displays the text “Macro is running.” However, the debugger is not completely disabled. You can interrupt the macro. This causes the debugger to become active, as if there were a breakpoint at the point where the macro is currently executing. Breakpoint commands are also available while the macro is running, so that you can add and remove breakpoints.

You can stop a macro at any line, DLL call, or other place in the macro. A dialog box displays the labels, functions, procedures, and variables being passed, so that you can check them. All breakpoints allow a message to be logged to the debugger event log.

The PerfectScript Debugger automatically creates three breakpoints: Macro Start, Macro End, and Error. It marks the breakpoints it adds with an exclamation mark (!), which can be removed if desired.

Debug options

When the debugger stops at a macro statement, it stops before the indicated statement executes. The PerfectScript Debugger provides the following options to continue macro execution:

To play a PerfectScript macro in debug mode

Click Tools

Macro

Debugger.

Click Tools

Macro

Play.

Enable the PerfectScript macro option.

Type a filename in the Filename box.

Click OK.

In the PerfectScript debug dialog box, click Debug and choose one of the following menu commands:

•

Continue — continues executing the macro until the next breakpoint

•

Step into — executes the next statement

•

Step over — executes the label or routine call without stopping until debugging is complete. This will stop the macro at the next statement in the current label or routine.

•

Step out — executes the macro until the next return is encountered, if you have entered a routine or label

•

Run to cursor — executes to the line below the cursor in the macro source list

•

Skip to cursor — skips a series of statements without executing them; if some statements need to be repeated, sets the next statement to be executed by the Debugger, without executing any statements between the current point and the new line.

•

Animate — repeats the next Continue or Step command until you stop it, or until the macro ends. Between each command, the Debugger displays for the amount of time you specify in the Settings dialog box.

•

Use the Skip to cursor menu command with extreme caution, since skipping to a line that is not within the same label or routine could cause the internal macro execution to become invalid, which will almost certainly result in execution failure.

•

You need a .wcl file in the same folder as the PerfectScript macro file. For information on creating a .wcl file see “To create a WCL file.”

To set a breakpoint in PerfectScript macros

Click Tools

Macro

Debugger.

Click Tools

Macro

Play.

Enable the PerfectScript macro option.

Type a filename in the Filename box.

Click OK.

In the Debugger dialog box, click Debug

Breakpoints

Edit.

In the Edit breakpoints dialog box, click the Location and condition tab.

Choose the type of breakpoint you want from the Type list box.

Click one of the following buttons:

•

Add — creates a new breakpoint

•

Update — updates an existing breakpoint

•

You can add a line number breakpoint by double-clicking the line in the macro source list where you want the macro to stop.

Wordperfect Quattro Pro