The VisualPQL Debugger

Errors may also occur during program execution that prevent successful running of the program. Typically these errors might 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.

Error Messages

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

Debug Mode

Compile Errors

Run Time Errors

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 VisualPQL GUI Debugger

The VisualPQL debugger is itself a VisualPQL program that uses particular debug functions to interact with the executing system. If you wanted to, you could use these functions to develop a different interface to the debugger but you do not need to use these functions simply to debug your own programs. To avoid confusion, these functions are not documented here, please contact SIR support for details, if you need them.

Using the debugger requires additional memory beyond that needed by the program. As a VisualPQL program is compiled, source commands are converted into operating codes that 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 that is used for internal reference and is used on several commands that display the contents of the stack. These numbers are not editor line numbers or the line numbers in a source code listing.

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

To start the debugger, first compile a program with the DEBUG keyword then select Debug... from the Program menu. Select the compiled object (SYSTEM.DEBUG:O is the default) from the member list.

The VisualPQL Debugger

Source

The Set BreakPoint button sets or clear a breakpoint on the selected line. A breakpoint is a command where execution stops before that command is executed.

The Step Into Subroutines box if checked and subroutines are compiled with debug, means that the source of the subroutines are displayed when they are executed.

Press Next to execute next command and moves the selected line to the next executable line.

Press Continue to run until a breakpoint or watchpoint is hit or the program ends.

Run-to-here executes all lines until the selected line is reached.

Run-to-end executes the program ignoring all breakpoints and watchpoints.

Exit stops debugging, stops the program execution and closes the debugger.

The Files, Members and Buffers buttons let you open, edit files members and buffers.

The Globals and Attributes buttons let you view and modify global variables and file attributes.

Clear Output clears the main window output area.

The Program source code lines are displayed in the large listing area. Note that the line that is about to be executed is marked with a » character and the selected line is highlighted.

Data

Press View to select variables of interest or to change the order that they are displayed. The most recently selected are displayed first.

Press Modify to change the value of a variable.

Press Set Watchpoint to set a watchpoint on or off on the selected variable. A watchpoint means that execution stops on the command after the command that changes the value in that variable. An active watchpoint is indicated with a ¤

Press Clear All to remove all watchpoints.

Double click on a variable to modify its value.

When a variable is selected from the list, its value is displayed at the bottom of the screen. If it is a string variable then blanks are shown with a dot (·).

Stack

Press Up to move to the source that called the currently displayed source.

Press Down to return one level to the source of the called subroutine (after pressing up).

Press ->|<- to return to the subroutine source and line about to be executed.

You can double click on a routine to view its source.

How to debug a program

In a larger program, you probably need to set breakpoints or watchpoints to stop execution and return to the debugger when a particular line is about to be executed or when the value of a given variable is changed. After setting a breakpoint on a source line or a watchpoint on a variable, press continue to execute the program. The following example is a small program that is easily debugged but is worked through in detail to show a debugging process.

This example program is meant to extract first name, last name and middle initial from a string containing a full name. The problem is that last name is not being calculated properly.

SUBROUTINE FMLNAME (NAME) RETURNING (FNAME,MINIT,LNAME) REPLACE  NODATABASE DEBUG DYNAMIC
. STRING*50 NAME
. STRING FNAME MINIT LNAME
. INTEGER FSPACE LSPACE
. SET FNAME MINIT LNAME ("")
. COMPUTE FSPACE = ABS(SRST(NAME," "))
. COMPUTE LSPACE = LEN(NAME) + 1 - ABS(SRST(REVERSE(NAME)," "))
. COMPUTE FNAME = SBST(NAME,1,FSPACE-1)
. COMPUTE LNAME = SBST(NAME,LSPACE+1,LEN(NAME)-LSPACE)
. IF (LSPACE NE FSPACE) COMPUTE MINIT = SBST(NAME,FSPACE+1,1)
END SUBROUTINE

RETRIEVAL DEBUG
. STRING FNAME MINIT LNAME
. PROCESS CASES
.   PROCESS RECORD 1
.     EXECUTE SUBROUTINE FMLNAME (NAME) RETURNING (FNAME,MINIT,LNAME)
.     WRITE NAME
.     WRITE FNAME " / " MINIT " / " LNAME
.   END RECORD
. END CASE
END RETRIEVAL

Start retrieval execution
John D Jones
John  / D  / *
James A Arblaster
James  / A  / *
Mary Black
Mary  / B  / *
...

Setting a BreakPoint

Check the step into subroutine box so that you are able to debug the called subroutine and press next. You should now be looking at the subroutine source.

We know the computation of last name (and middle initial) is not working so put a break on

. COMPUTE LNAME = SBST(NAME,LSPACE+1,LEN(NAME)-LSPACE)

At this point we could work out the problem but for sake of the example, put a watchpoint on LSPACE so we can find the next time it is modified and clear the breakpoint on LNAME (select it and press set breakpoint).

Setting a WatchPoint

Press continue and execution stops at the breakpoint at the start of the record 1 block in the main routine.

Press continue again and execution stops after the line that has set the value of LSPACE:

. COMPUTE LSPACE = LEN(NAME) + 1 - ABS(SRST(REVERSE(NAME)," "))

Repeat the process but press next rather than continue when executing the subroutine. Use the modify button in the data section to remove trailing blanks from the name and step through the computes to see that the program is working correctly.

So the fix is to remove the trailing blanks from NAME when calculating the positions of the blanks.

...
. COMPUTE NAME = TRIM(NAME)
. COMPUTE FSPACE = ABS(SRST(NAME," "))
. COMPUTE LSPACE = LEN(NAME) + 1 - ABS(SRST(REVERSE(NAME)," "))
...