OLAP DML Debugger Commands

Accessing the debugging environment

Access to the debugging environment is through the TRACE command, which controls the list of programs that is traced. To use the TRACE command, you must be connected to an analytic workspace from OLAP Worksheet. You enter OLAP DML commands in the command input window in OLAP Worksheet.

To debug a single program, attach the analytic workspace in which the program resides, and use the TRACE command to add that program to the trace list.

trace quarter.rpt

To trace all programs that are executed in your host session, specify an asterisk (*) instead of a program name.

trace *

To see the current trace list, which contains the names of all the programs that will be traced by the debugger when it is executed, specify a question mark (?) instead of a program name. For each program, the list contains the current TRACE settings.

trace ?

The following output is displayed in the output pane in the command input window.

QUARTER.RPT IN STOP ARGS OUT STOP VALUE
TRACE * IN STOP ARGS OUT NOSTOP VALUE

Using the debugger

When you run a program on the trace list, the debugging environment takes over execution of the program. When this happens, a double-line arrow prompt (=>) is displayed in the output pane of the command input window in OLAP Worksheet.

The debugging environment suspends execution of the program so that you can do the following:

• Step through a program one line at a time

• Display current values of OLAP DML objects

• Display the program's return value

You can use almost any OLAP DML command in the command input window. For example, you might use SHOW to examine the current values of OLAP DML objects.

Using the four debugger commands

You can also use four special debugger commands to help you investigate the current execution environment. These commands are listed in the following table.

Command	Description
GO	Specifies the number of lines that are executed in the debugging environment before execution stops. Each line of code is displayed as it is executed, except for lines that contain only comments. If you do not specify the number of lines, then all the code is executed to the end of the program without displaying the lines.
WATCH	Sets a watch point. When this point is reached in your program, execution is suspended. You can also use WATCH to enable, disable, or clear watch points. Finally, you can use WATCH to display a list of the current watch points.
BACK	Displays a list of currently running programs and indicates which programs call other programs. You have the option of displaying a program's arguments next to its name in the list.
ARGS	Displays a list of arguments for all the currently running programs. You can also display arguments for a single program.

For complete information about the program debugger commands, see the entry for TRACE in OLAP DML Reference.

Stepping through your program using the debugger GO command

When any program on the list is executed, the debugger suspends the program's execution according to the settings you have specified and displays the double-line arrow prompt in the output pane of the command input window.

At this point, you can use the GO debugger command to step through the execution of the program:

• To execute one line at a time, specify 1 as an argument.

  go 1
  

• To execute a group of lines, you can specify a higher number.

  go 3
  

At any point where the debugger prompts for a command, you can use OLAP DML commands to examine the current value of OLAP DML objects, or otherwise look at the execution environment to confirm that the program is executing as expected.

Note: Although the debugger displays labels in your program, it does not include them in the count of lines. Also, the debugger does not count or display lines that contain only comments.

BACK command

In many cases, you will trace a single program; however, you can use the OLAP Worksheet to trace a group of nested programs as well. The debugging environment will keep track of all the nested levels, and you have all the debugging capabilities in each program. To help keep track of the levels, you can use the BACK command to display a list of currently running programs. The list identifies the programs that call other programs and displays each program's arguments next to the program name.

Example: Using the BACK command in a debugging session

The following example presents a debugging session in which three nested programs are traced. PROG1 calls PROG2, and PROG2 calls PROG3. Only PROG2 accepts an argument, and the debugging environment displays its value upon entering PROG2. While in PROG3, the user types the BACK command to display the names of the programs that are currently executing, along with any arguments.

Enter the following commands in the input pane of the command input window in OLAP Worksheet:

trace prog1
trace prog2
trace prog3
prog1

The following is displayed in the output pane of the command input window:

= Entering PROG1

Enter the following command in the input pane:

go

The following is displayed in the output pane:

this is prog1
= Entering PROG2 From PROG1
= Args: 234

Enter the following command in the input pane:

go

The following is displayed in the output pane:

this is prog2
= Entering PROG3 From PROG2

Enter the following command in the input pane:

go

The following is displayed in the output pane:

this is prog3
= Leaving PROG3

Enter the following command in the input pane:

back

The following is displayed in the output pane:

= Command Level    -> PROG1           
= PROG1            -> PROG2           (Args: 234)
= PROG2            -> PROG3           

Enter the following command in the input pane:

go

The following is displayed in the output pane:

= Leaving PROG2

Enter the following command in the input pane:

go

The following is displayed in the output pane:

= Leaving PROG1

To exit the debugger, enter the following command in the input pane:

go

Exiting the debugging environment

From the Debug menu in OLAP Worksheet, choose Interrupt to exit the debugging environment.