QMBasic Debugger

Top  Previous  Next

 

The QM interactive debugger enables the developer to step through an application program in a convenient manner, stopping at desired points and examining data items.

 

Programs to be debugged must be compiled with the DEBUGGING option to the BASIC command or by including the $DEBUG compiler directive in the program source. At run time, the debugger will stop at selected places in the execution of these programs but will run normally through programs not compiled in this mode. Catalogued programs and subroutines may be debugged in exactly the same way as other programs.

 

The debugger is activated either by use of the DEBUG command in place of RUN or by a DEBUG statement encountered during execution of a program. The latter method enables debug mode to be entered part way through execution of the program. The debugger can also be entered from the quit confirmation prompt if any program currently being executed has been compiled in debug mode.

 

During application development it is often worth compiling the entire application in debug mode. Execution of the program with the RUN command will not invoke the debugger unless a  DEBUG statement is encountered. There is a small performance impact of running a debug mode program in this way but it is usually not significant.

 

Phantom processes and those acting as the server side of a QMClient connection can be debugged using the PDEBUG command.

 

 

The debugger will identify the program from which it was entered and locate the source program record. If this is not available, a warning is displayed and execution of the program continues in non-debug mode though other programs and subroutines called by it will still be subject to debugging if their source records are available.

 

When used with QMConsole on a Windows system, via the QMTerm terminal emulator or the bundled version of AccuTerm, the debugger operates in full screen mode. The display is divided into two areas. The upper portion of the screen shows the source program with the line about to be executed highlighted. The lower portion of the screen is used to echo commands and to display their responses. The top line of the screen displays the program name and current line and element number. The display may be toggled between the debugger and the application by use of the F4 key. Full screen mode also supports a command stack similar to that found at the command prompt.

 

When used on other terminals, the debugger output is mixed with the application output.

 

The current position in a program is referenced by a line number and an element number. Most QMBasic source lines hold only a single element (element 0) but lines with multiple statements separated by semicolons or clauses of IF/THEN/ELSE constructs, etc, are considered to represent separate execution elements. The debugger can step line by line or element by element through a program.

 

The debugger cannot step through statements inserted into a program from an include record. In such cases, it will step over the included statements as though they were part of the immediately preceding statement.

 

Debugger commands fall into two groups; function keys and word based commands. In many cases both forms are available. Not all terminals support function keys.

 

 

Function Key Commands

 

(Some function keys may not be available on all terminal emulations)

F1Display help screen
F2Abort program
F3Stop program
F4Display user screen (normal program output)
F5Free run

F6

F7Step program element
F8Step line
Ctrl-F7Run to parent program / subroutine (internal or external)
Ctrl-F8Exit program, returning to parent program or external subroutine

 

If an application dynamically rebinds the codes sent by keys used by the debugger, setting the DEBUG.REBIND.KEYS mode of the  OPTION command will cause the debugger to reset these to the bindings specified in the terminfo entry for the current terminal type on each entry to the debug screen. Note that the debugger cannot revert to the user bindings on exit as it has no way to determine what these were. This feature is available only with AccuTerm.

 

 

Word Based Commands

 

Where a short form is available, this is the upper case portion of the command as shown. Commands may be entered in any mix of upper and lower case.

 

ABORTQuit the program, generating an abort.
BRK nSet a breakpoint on line n.
CLRClear all breakpoints.
CLR nClear breakpoint on line n.
DUMP var pathDumps a variable to an operating system level file.
EPExit program, returning to parent program or external subroutine.
EXitExit subroutine, returning to parent program, internal or external subroutine.
Goto nContinue execution at line n.
HELPDisplay help page.
QuitQuit the program, generating an abort.
RunFree run.
Run nRun to line n.
SET var=valueChange content of a program variable
STACKDisplay the call stack. The current program is shown first.
Step nExecute n lines.
Step .nExecute n elements.
STOPQuit the program, generating a stop.
UnWatchCancels an active watch action.
ViewDisplay user screen (normal program output)
Watch varWatches the named variable.

 

 

The following commands apply only to full screen mode debugging:

 

SRCRevert to default program source display
SRC nameShow source of program name.
SRC nDisplay around line n of currently displayed program.
SRC +nMove display forward n lines in program.
SRC -nMove display backward n lines in program.

 

The following commands apply only to non-full screen mode debugging:

 

SRCDisplay current source line
SRC nDisplay source line n. Entering a blank debugger command line after this command will display the next source line.
SRC n,mDisplay m lines starting at source line n. The value of m is limited to three lines less than the screen size. Entering a blank debugger command line after this command will display the next m source lines.

 

 

Displaying Program Variables

 

Entering a variable name preceded or followed by a slash (/) or a question mark (?) displays the type and content of the given variable (var/, /var, var?, ?var). This name may be a variable in a common block defined in the current program. If the common block has not been linked at the time the command is entered, the variable will appear as unassigned. For programs compiled with case insensitive names, the debugger is also case insensitive.

 

Private local variables in a subroutine declared using the LOCAL statement can be referenced using a name formed by concatenating the subroutine name and variable name with a colon between them. If a subroutine is executed recursively, it is only possible to view the current instance of the variables.

 

The debugger will not recognise names defined using EQUATE or $DEFINE.

 

The debugger recognises variable names STATUS(), INMAT(), COL1(), COL2() and OS.ERROR() to display the corresponding system variable. All @-variables may also be displayed except for @VOC (which is a file variable) and those representing constants such as @FM and @TRUE.

 

Display of long strings is broken into short sections to fit the available display space. Entering Q at the continuation prompt will terminate display.

 

When displaying strings with an active remove pointer, the position of this pointer is also shown.

 

If the variable is a matrix, the name may be followed by the index value(s) for the element to be displayed. Entry of the name without an index will display the dimensions of the matrix. Subsequent presses of the return key display successive elements of the matrix until either all elements have been displayed or another command is entered.

 

CLI.REC/

Array: Dim (20)

<return>

CLI.REC(0) = Unassigned

<return>

CLI.REC(1) = String (8 bytes): "J Watson"

<return>

CLI.REC(2) = 13756

CLI.REC(8)/

Integer: 86

 

The variable name may be followed by a field, value or subvalue reference which will be used to restrict the display if the data is a string. Note that this qualifier has no effect on other data types.

 

REC/

String (11 bytes,R=4): "487FM912VM338"

REC<1>/

String (3 bytes): "487"

REC<2,1>/

String (3 bytes): "912"

 

Entering a slash alone will repeat the most recent display command.

 

Analysis of very large character strings is sometime easier from outside the debugger. The DUMP command can be used to dump the contents of a variable to an operating system level file that can then be processed with other tools.

 

 

 

Changing Program Variables

 

The SET command can be used to alter the value of a variable.

 

SET var = valueto set a numeric value
SET var = "string"to set a string value. Double quotes, single quotes or backslashes may be used to enclose the string.
SET var(row,col) = valueto set a matrix element

 

 

 

Watching Variables

 

The WATCH command causes the debugger to monitor the named variable. Whenever a value is assigned to this variable (even if the value is the same as currently stored), the debugger will stop program execution and display the new value. Only one variable can be watched at a time.

 

The UNWATCH command cancels the watch action. The watch action is automatically cancelled when the watched variable ceases to exist. This might be return from the program in which the program exists, redimensioning a common block, etc.