
VISUALPQL		The VisualPQL Debuggers

The VisualPQL Debuggers

Errors may be encountered in developing VisualPQL programs. Syntax may be incorrectly specified. Syntax errors are detected by the VisualPQL compiler and reported with Error and Warning Messages during compilation.

Errors may also occur during program execution which prevent successful running of the program. Typical of these types of errors would be files not being found, when no provision has been made to handle the error or subscript references outside the bounds of the allowable range.

The program may compile and run but not perform as expected. Errors in programming logic are typically referred to as program bugs. The VisualPQL debuggers assist in locating program bugs.

Error Messages

Error messages can be issued at compile time or at run time. Error messages have a number and explanatory text. These are printed at the point where the error has occurred and as a summary at the end of the run. The level of detail is controlled through the setting of the message level.

Errors can be related back to the original source line through line numbers. As the source lines are read, these are assigned an input number. This is a two part number such as 2.3 or 3.7. The first part refers to the level of the source input. If source is read directly, it is level 1, if it is included through a CALL, it is level 2 and so on. Various text inclusion commands increase this level, some of which are internal. For example, any text RUN through the menu system starts at level 2.

Each line is then assigned a sequential input line number within that level. The lines that cause any text inclusion are also assigned numbers. Some text inclusion commands are generated internally. Lines generated through a DO REPEAT do not have numbers since they are not part of the input text.

The VisualPQL program lines are also assigned an internal address referred to as the Stack Location. This is where that command is located during the execution of the program and is referred to by any run time error message. This number ascends but has gaps because most commands take multiple stack locations.

For a full listing of the input use PRINT BACK ON. This gives a listing such as:

1.1            CALL TEST.ERROR:T
2.1      00001 program
2.2      00001 compute a = 1
2.3            call inctext
3.1      00003 a = 1
3.2      00005 a = 1
3.3      00007 a = 1
2.4            do repeat x = 1 2 3
2.5            compute a = x
2.6            end repeat
(REPEAT) 00009 compute a = 1
(REPEAT) 00011 compute a = 2
(REPEAT) 00013 compute a = 3
2.7      00015 end program

The routine is "MAIN" if the main program is being executed or is the name of a sub-routine that is being executed.

If the routine has been compiled in debug mode, then an internal line number is assigned to executable parts of the code and this line number is displayed during a debug run. It is not the input sequence number. If the routine has been compiled in debug mode, the source text of the line causing the problem is also displayed.

The stack location is always displayed and is the stack location listed on the PRINT BACK. Use this to locate the line causing the problem.

Overview to the Debuggers

A debugger provides a means of following the execution path through the program statements. Execution can be suspended at any point to examine the values of program variables. In this way the developer can determine where an incorrect branch is taken or if a variable has the expected value.

There are three different environments for using the VisualPQL debugger:

batch mode for non-interactive code tracing

MONITOR mode for command driven interactive debugging, and,

FULLMONITOR mode for interactive debugging in a multi-window menu environment.

Using the debugger requires additional memory beyond what is needed by the program. All modes require the DEBUG keyword on the PROGRAM, RETRIEVAL or SUBROUTINE command.

As a VisualPQL program is compiled, source commands are converted into operating codes which are the executable program and these are held in the command stack. When the DEBUG option is specified on the RETRIEVAL, PROGRAM or SUBROUTINE commands, the compiler keeps the text of each command along with the corresponding operating code in the stack (which is why the debugger requires much more memory). Each command in the stack is assigned a command number which is used for internal reference and which is used on several commands that display the contents of the stack. These numbers have no special relation to editor line numbers or the line numbers in a source code listing.

The following discusses the VisualPQL debugger and the options that are available.

Trace The debuggers follow the execution of the program and can trace the steps that are being executed by displaying the VisualPQL command that is being executed. When commands are traced, they are displayed just before they are executed. There are three general types of traces that can be requested which are described below. In addition the program can be traced for a certain number of steps (commands).

Line trace The debuggers can display lines of source code as they are executed. Various options limit which lines are displayed during execution. Note that in a loop the same line of code may be displayed many times.

Branch trace A branch trace tracks the situations in which execution is redirected to some place other than the next command. Commands such as a JUMP, IFTHEN, NEXT and the END of looping blocks cause this redirection of the flow of execution.

Execute trace The execute trace only traces subroutine call (execute) and return instructions.

Watchpoint The debuggers can keep a watch on specified variables and suspend execution when the value of a variable changes. Values are checked after completion of each statement.

Breakpoint Similar to the watchpoint, the debugger can suspend execution when it reaches a certain point in the program. This point is identified by the line number that the debugger has assigned to a command in the source code. This is frequently used to let the program run to the point in the program where you suspect a problem.

Scope Specifies the area or scope of interest. You may only be interested in one or two subroutines, for example. Any other options apply only to the defined scope.
Variable names and command line numbers refer to the currently executing routine unless SCOPE is used. Use the routine name as a prefix to reference a different routine.

Vardump As the debugger traces the execution of a routine, you may want to see the values of the variables. The vardump displays the values of a set of variables at given points during execution.

Run Time Debugger

The Run Time Debugger is intended for batch (non-interactive) runs and has debugging instructions embedded within the VisualPQL code which specify types of information to print to the output file. The DEBUG keyword must appear on the PROGRAM or RETRIEVAL command to enable the debugger. The command is:

PQLDEBUG [ [NO]ARGDUMP ]
         [ [NO]VARDUMP ]
         [ [NO]LINETRACE ]
         [ [NO]BRANCHTRACE ]
         [ [NO]EXECUTETRACE ]

This enables and disables various debugging options. Any number of PQLDEBUG commands may appear in a program.

ARGDUMP Specifies whether the input and output values of subroutines are printed as the subroutines are executed.

VARDUMP Specifies whether when a subroutine debug trace is printed, the current values of all variables are printed.

LINETRACE Specifies that from the point at which this statement is traversed, that every command executed is listed. Only the first physical line of a command is listed.

BRANCHTRACE Specifies that only branching instructions (JUMP, EXECUTE, RETURN, IF) are traced. Causes much less output than LINETRACE.

EXECUTETRACE Specifies that only subroutine EXECUTE and RETURN instructions are traced. Causes much less output than LINETRACE or BRANCHTRACE.

Interactive Line Mode Monitor

This interactively controls execution and can view the state of the system as execution progresses. The main program and the subroutines to be debugged are compiled with the DEBUG keyword. Only routines of interest need to be compiled with this keyword. Selective debugging of routines can significantly reduce the amount of memory needed.

When the MONITOR keyword is specified on the RETRIEVAL or PROGRAM statement, the user is placed in the MONITOR subsystem just prior to the start of program execution. The following prompt is displayed.

PQL/DBG >
Enter commands at the prompt. The commands and keywords may be abbreviated to the minimum number of characters that makes them unique. The < code>SET and CLEAR commands enable and disable various debugger options. The SHOW command displays the current setting of the specified option.

Run a program that is compiled with the DEBUG and MONITOR keywords, set the desired options at the prompt and start execution of the program (with the GO command). The information requested through the options as well as the normal program output is displayed. Depending on the selected options, execution may halt for you to inspect results, set other options and continue execution.

Interactive Debugger Commands

`ABORT`	Terminates the executing program.
`DEPOSIT [routine.]varname = { 'str' \| number }`	Sets the value of the specified variable to a value.
`EXAMINE [routine.]varname`	Displays the current value of a variable.
`GO`	Continues program execution. Execution continues until the next breakpoint, watchpoint or end of program is reached.
`HELP`	Invokes Help for the debugger.
`LIST [[routine.] commandno [:commandno]]`	Displays the specified command line or range of lines.
`STEP count`	Continues program execution for the specified number of commands. Execution continues until the number of steps have been executed or until a watchpoint or breakpoint is encountered. If a subroutine call is encountered, the subroutine is considered a single step.
`TRACE count`	Has same effect as the step command except that the command lines are displayed as they are executed. If a subroutine is executed, each command of the subroutine is traced.

There are two pieces of information which can be displayed but not set:

SHOW STACK Displays the next command.

SHOW SYSTEM n Displays the value from the SYSTEM function with the specified numeric argument.

SET, CLEAR and SHOW

CLEAR option_name [ parameters ]

SET option_name [parameters ]

SHOW option_name [ qualifier ]

SET sets a debugger option. CLEAR turns the specified option off. If parameters are not specified, all settings of the option are cleared. SHOW displays the current setting of an option. The options are:

ARGDUMP Specifies that the values of the input and output variables are displayed when a subroutine is executed.

BRANCHTRACE Specifies that only branching instructions (JUMP, EXECUTE, RETURN, IF, etc.) are traced. Causes much less output than LINETRACE.

BREAKPOINT [routine.]command_num Sets a point in the program at which execution is suspended and the debugger prompt displayed. This point is identified by the line number that the debugger has assigned to a command in the source code.

EXECUTETRACE Specifies that only EXECUTE SUBROUTINE and RETURN instructions are traced. Causes much less output than LINETRACE or BRANCHTRACE.

LINETRACE Specifies that, from the point at which this statement is traversed, every command executed is listed. Only the first physical line of a command is listed.

SCOPE routine Specifies the routine to display if no routine name prefix is used on commands that specify variable names or line numbers.

VARDUMP Specifies whether when a subroutine debug trace is printed, the current values of all variables are listed.

WATCHPOINT [routine.]varname Sets the name of a variable which, when its value changes, temporarily suspends the execution of the program and displays the old and new values of the variable.

The Full Screen Debug Monitor

To invoke the full screen debugger, use the DEBUG and FULLMONITOR keywords on the PROGRAM, RETRIEVAL or SUBROUTINE command. If there are subroutines to be debugged, use DEBUG on the routine to be debugged and FULLMONITOR on the main routine. When the program is run, a multiple window screen is displayed as show below.

Full Screen Debugger

The VisualPQL statements are displayed in region 1 on the bottom half of the screen. Each statement is preceded by its line number and the first executable statement is highlighted. The '@' symbol to the left of the line number indicates which instruction is executed next.

When you first enter the Full Screen debugger, Region 1 is the active region. This region displays the VisualPQL statements. Using the arrow keys moves the highlight bar through the source statements. Use the 'N' (step) command to execute one line at a time or use 'G' (go) to execute until a break or watch point is encountered.

The Top Bar Menu

At the top of the screen are the names of the six pull-down menus that can be invoked by entering the first letter of the name.

Breakpoint Sets, clears or views breakpoints and watchpoints. Setting a breakpoint defines a line number where execution stops temporarily. A watchpoint names a variable to watch. Anytime the value of the variable changes execution stops and the old and new values are displayed.

Execute Terminates or continues execution.

Option Sets or clears trace and dump options.

Region Controls where the various regions or windows are displayed on the screen. Change the size, position or video attributes of the regions as needed.

View Opens new regions to view data, files, breakpoints, procedures or subroutines.

?help Accesses context sensitive help.

The Bottom Bar Menu

A bar at the bottom lists commands that are available by entering a single character. The list of commands varies, giving commands that are valid in the current context. The following commands are active when the debugger is first entered:

A-at Set a breakpoint at the current line (the program line highlighted in region 1).

D-data View a data value or deposit a new value. Invoking 'D' moves to the region number 7, the data region, or opens a window for the data region.

G-go Continue program execution until a breakpoint, watchpoint or job termination is encountered.

H-here Set a temporary breakpoint here (at the currently highlighted line) and continue execution.

I-nxt Move to the next region. The number of the current region is displayed in the upper right corner of the screen.
L-loc Position the highlight bar to a specified line number. This command doesn't effect execution.

N-step Execute the next instruction in the current routine. Step steps over subroutine or subprocedure code.

P-rgn Move to the region specified.

Q-quit Terminate program execution.

T-trc The trace command executes the next instruction, allowing a trace into subroutine code.

U-usr Toggles to view user output to execution window screen.

X-stk Move to stack region (region 3) which displays the subroutine call stack and any variables specified with ARGDUMP or VARDUMP.

The Data Region Bar Menu

Some additional commands are available in the data region:

F-cpu Moves to the region containing the source code that is executing. (Region 1)

L-look Add a new variable to the list being displayed in the data region.

D-dep Deposit a value into the variable highlighted in the data region.

K-kil Remove highlighted variable from list of variables.

Operating the full screen debugger

The full screen debugger has seven standard regions, identified by a number, which contain information about the executing program. Each region has a window on the screen. These can be re-located and re-sized. Some region windows may overlap others, partially obscuring information. At any given time, one region is the active region. The active region window number is displayed at the upper right corner of the screen and the active region window itself is always fully displayed. Move from one active region to another with the I on the bottom bar menu.

In addition to the seven standard regions, you may create others. The View option creates additional regions to contain the text of files, members (proc), and routine listings for routines other than the current one. You may create as many of these additional regions as necessary. A file display or member display region, allows scrolling through the text. When in a user defined routine region, all of the options available in the Current window (Region 1) are available.

The seven standard regions are:

1: Program Listing
Lists the commands of the currently executing routine.

2: Output File
Lists the program output from WRITE statements, errors and warnings but not from full screen statements (those that contain the AT keyword).

3: Stack
Displays the next command to execute and the VARDUMP and ARGDUMP data for each subroutine in the subroutine call sequence.

4: Breakpoints
Displays the defined breakpoints

5: Watchpoints
Displays watchpoint variables and their current values

6: Log
Displays informative messages issued by the debugger.

7: Data
Displays names and values of specified 'Look' variables. Note that a different bottom bar menu is available when this is the active region.

Setting Breakpoints

There are three ways to set a breakpoint:

Use 'B' to access the breakpoint menu from the top of the screen and select Set breakpoints. This prompts for the routine name and line number.
Move the highlighted bar to the line where a break is desired and use 'A' (at) to set a breakpoint. Execution stops every time the break is encountered.
Use 'H' (here) to set a temporary breakpoint at the highlighted bar. Execution is continued, stopping once at the temporary break and then the break is cancelled.

Viewing and Manipulating Data

Values of watchpoint variables are displayed in the Watchpoint window (Region 5) and in the Log window (Region 6). The Log window displays both old and new values. The Watchpoint window displays only the current value. The values of other variables can be monitored in the Data window (Region 7) by defining Look variables.

Move to the Data Region by using 'D' (data). To add Look variables which are displayed but do not stop execution when changed, use 'L' (look). To alter a data value, highlight the variable desired and use 'D' (deposit). To resume program execution use 'G' (go). To return to the Code window (Region 1) use 'F' (cpu).

The Stack Region

The Stack Region (region 3) displays the subroutine call stack (the path of subroutine calls that got to this point), the command about to be executed and any data specified by the ARGDUMP and VARDUMP settings. If all the local variables or argument values are not visible, move to this region and scroll through the display. To move to the Stack Region use 'X' (stk) or 'P' (rgn) then specify region 3.

`Trace`	The debuggers follow the execution of the program and can trace the steps that are being executed by displaying the VisualPQL command that is being executed. When commands are traced, they are displayed just before they are executed. There are three general types of traces that can be requested which are described below. In addition the program can be traced for a certain number of steps (commands).
`Line trace`	The debuggers can display lines of source code as they are executed. Various options limit which lines are displayed during execution. Note that in a loop the same line of code may be displayed many times.
`Branch trace`	A branch trace tracks the situations in which execution is redirected to some place other than the next command. Commands such as a `JUMP, IFTHEN, NEXT` and the `END` of looping blocks cause this redirection of the flow of execution.
`Execute trace`	The execute trace only traces subroutine call (execute) and return instructions.
`Watchpoint`	The debuggers can keep a watch on specified variables and suspend execution when the value of a variable changes. Values are checked after completion of each statement.
`Breakpoint`	Similar to the watchpoint, the debugger can suspend execution when it reaches a certain point in the program. This point is identified by the line number that the debugger has assigned to a command in the source code. This is frequently used to let the program run to the point in the program where you suspect a problem.
`Scope`	Specifies the area or scope of interest. You may only be interested in one or two subroutines, for example. Any other options apply only to the defined scope. Variable names and command line numbers refer to the currently executing routine unless `SCOPE` is used. Use the routine name as a prefix to reference a different routine.
`Vardump`	As the debugger traces the execution of a routine, you may want to see the values of the variables. The vardump displays the values of a set of variables at given points during execution.

`ARGDUMP`	Specifies whether the input and output values of subroutines are printed as the subroutines are executed.
`VARDUMP`	Specifies whether when a subroutine debug trace is printed, the current values of all variables are printed.
`LINETRACE`	Specifies that from the point at which this statement is traversed, that every command executed is listed. Only the first physical line of a command is listed.
`BRANCHTRACE`	Specifies that only branching instructions (`JUMP, EXECUTE, RETURN, IF`) are traced. Causes much less output than `LINETRACE`.
`EXECUTETRACE`	Specifies that only subroutine `EXECUTE` and `RETURN` instructions are traced. Causes much less output than `LINETRACE` or `BRANCHTRACE`.

`SHOW STACK`	Displays the next command.
`SHOW SYSTEM n`	Displays the value from the `SYSTEM` function with the specified numeric argument.

`ARGDUMP`	Specifies that the values of the input and output variables are displayed when a subroutine is executed.
`BRANCHTRACE`	Specifies that only branching instructions (`JUMP, EXECUTE, RETURN, IF`, etc.) are traced. Causes much less output than `LINETRACE`.
`BREAKPOINT [routine.]command_num`	Sets a point in the program at which execution is suspended and the debugger prompt displayed. This point is identified by the line number that the debugger has assigned to a command in the source code.
`EXECUTETRACE`	Specifies that only `EXECUTE SUBROUTINE` and `RETURN` instructions are traced. Causes much less output than `LINETRACE` or `BRANCHTRACE`.
`LINETRACE`	Specifies that, from the point at which this statement is traversed, every command executed is listed. Only the first physical line of a command is listed.
`SCOPE routine`	Specifies the routine to display if no routine name prefix is used on commands that specify variable names or line numbers.
`VARDUMP`	Specifies whether when a subroutine debug trace is printed, the current values of all variables are listed.
`WATCHPOINT [routine.]varname`	Sets the name of a variable which, when its value changes, temporarily suspends the execution of the program and displays the old and new values of the variable.

`Breakpoint`	Sets, clears or views breakpoints and watchpoints. Setting a breakpoint defines a line number where execution stops temporarily. A watchpoint names a variable to watch. Anytime the value of the variable changes execution stops and the old and new values are displayed.
`Execute`	Terminates or continues execution.
`Option`	Sets or clears trace and dump options.
`Region`	Controls where the various regions or windows are displayed on the screen. Change the size, position or video attributes of the regions as needed.
`View`	Opens new regions to view data, files, breakpoints, procedures or subroutines.
`?help`	Accesses context sensitive help.

`A-at`	Set a breakpoint at the current line (the program line highlighted in region 1).
`D-data`	View a data value or deposit a new value. Invoking 'D' moves to the region number 7, the data region, or opens a window for the data region.
`G-go`	Continue program execution until a breakpoint, watchpoint or job termination is encountered.
`H-here`	Set a temporary breakpoint here (at the currently highlighted line) and continue execution.
`I-nxt`	Move to the next region. The number of the current region is displayed in the upper right corner of the screen.
`L-loc`	Position the highlight bar to a specified line number. This command doesn't effect execution.
`N-step`	Execute the next instruction in the current routine. Step steps over subroutine or subprocedure code.
`P-rgn`	Move to the region specified.
`Q-quit`	Terminate program execution.
`T-trc`	The trace command executes the next instruction, allowing a trace into subroutine code.
`U-usr`	Toggles to view user output to execution window screen.
`X-stk`	Move to stack region (region 3) which displays the subroutine call stack and any variables specified with `ARGDUMP` or `VARDUMP`.

`F-cpu`	Moves to the region containing the source code that is executing. (Region 1)
`L-look`	Add a new variable to the list being displayed in the data region.
`D-dep`	Deposit a value into the variable highlighted in the data region.
`K-kil`	Remove highlighted variable from list of variables.