JES: Just Educational Services

Jonathan E. Sisk's
Pick/BASIC: A Programmer's Guide

Appendix E - The Pick/BASIC Interactive Debugger

Click to enlarge

The Pick/BASIC Debugger is used for tracing execution and variables during the runtime of Pick/BASIC programs.

Symbol Definitions

Each variable referred to in a program produces a symbol, which is used to refer to that particular variable throughout the rest of the program and through functions within the debugger. The symbol definitions are automatically defined during the compile process and are with the executable object code in the dictionary level of the program file.

Activating the Pick/BASIC Debugger

The Pick/BASIC debugger is basically activated one of two ways, either voluntarily or involuntarily.

Voluntary Debugger Entry.

In the voluntary form, the debugger is entered upon pressing the break key while running a Pick/BASIC program. It may also be entered prior to execution of a program with the "D" option:

>RUN BP HELLO (D)<cr> *E1

If the program has been cataloged, then this form changes to:

>HELLO (D) <cr> 
E1
*

If the program has been cataloged , then this changes to:

>HELLO (D)<cr>
*E1
*

Fatal Error Conditions.

In the involuntary form, a Pick/BASIC program enters the debugger whenever a "fatal" error condition is encountered, like when an attempt is made to read from a file that has not previously been opened. When a fatal condition is encountered, the program "breaks" and displays something to this effect:

Innn

[Bnnn] text.of.fatal.error.message

*

The "I" in Innn indicates that an "interrupt" has occurred in the program at line nnn, the corresponding source program line. The "Bnnn" is the BASIC error message item-id, as retrieved from the ERRMSG file. The text next to the message attempts to explain the reason why the program crashed and burned.

Nonfatal Error Conditions.

A "non-fatal" error condition is one in which a program error of some sort has been detected, but is not considered serious enough to warrant terminating the program. The classic case of such a condition is the infamous message:

[B***] VARIABLE HAS NOT BEEN ASSIGNED A VALUE!  ZERO USED.

Although the error does not stop the program, it still should be corrected. Sometimes it is difficult to "catch" the message being displayed, like when it flashes past just before a screen clearing operation.

Another option is provided to force all error conditions, whether normally considered fatal or not, to enter the debugger. This is the "E" option, and here is how it is used:

>RUN MY.PROGRAMS TEST.PROG (E)<cr>

(program starts running.... )
(Bang! It breaks!)
[B***] VARIABLE HAS NOT BEEN ASSIGNED A VALUE! ZERO USED.
*

USING THE DEBUG STATEMENT

In the tedious debugging phase of writing programs, it might be necessary to insert one or more DEBUG statements within the program at potential trouble spots. When the DEBUG statement is executed, the program immediately enters the debugger, where variables may be interrogated and logic can be traced. Naturally, once the problems have been detected and corrected, then the DEBUG statements should be removed from the version that will go into production.

Prompt Character

The prompt character, an asterisk (*), appears in the leftmost column of the terminal display screen, indicating that the debugger is ready to accept any legal command.

Term Conventions

The following two abbreviations are used in command templates for the Pick/BASIC debugger:

op Abbreviation for operator. Used in setting "breakpoints" with the "B" command. (See the following section on operators.)

var Abbreviation for variable name. The actual name of the variable, as defined in the program source code.

Operators

The operators listed below perform logical comparison functions.

= Equal to
> Greater than
< Less than
>= Greater than or equal to
<= Less than or equal to
# Not equal to

Referencing, Displaying and Changing Variables

While in the debugger, any individual variable may be displayed. For example, let's suppose that there was a variable called AMOUNT.DUE, and you wanted to display its current value. You would enter:

*/AMOUNT.DUE<cr> 

This would locate and display its current value, and allow you the option of changing it:

*/AMOUNT.DUE 12500=_

Note that when the cursor remains to the right of the ..... symbol, anything you enter will replace the current value of the variable. Issuing a carriage return while on the right side of the equal sign leaves the current value intact.

Referencing Dimensioned Arrays

If a dimensioned array variable is requested without also providing a subscript, then all elements in the array are individually displayed and the current value of any element may be changed. Pressing Return will "step" down to the next element until the last element is reached or the break key is pressed. For example, suppose there were a dimensioned array named CUSTOMER.ITEM:

*/CUSTOMER.ITEM<cr>
*CUSTOMER.ITEM(l) PROPELLER HEAD ENTERPRISES=<cr>
*CUSTOMER.ITEM(2) 1400 W. 147TH ST=<cr>
*CUSTOMER.ITEM(3) CHICAGO=<cr>
*CUSTOMER.ITEM(4) IL=<cr>
*CUSTOMER.ITEM(5) 60609=<break>
*

Individual subscripts in dimensioned arrays may also be examined and optionally changed. For example, the instruction:

*/CUSTOMER.ITEM(1)<cr>

might display:

*/CUSTOMER.ITEM(I) PROPELLER HEAD ENTERPRISES=<cr>

Once again, the current value may be replaced.

In the rare event of needing to reference a two-dimensional array, the syntax calls for both coordinates, as in the following example:

*/TAX.TABLE.ITEM(3,2) 

Listing All Program Variables

A complete list of every variable defined in the program can be obtained with the command:

*/*<cr>

Note, however, that when all variables are being displayed, you are not given the chance to change any of them. Again, they must be requested individually to be changed.

Zone Output Specification

The following command sets left and right margins for output zone limits of debugger display:

*[{leftmargin,rightmargin}}]

The [ command followed immediately by a <or> removes zone limits.

Pick/BASIC Debugger Commands

*?
*$

Displays current program name, execution line number, and object code verification status.

*Bvar operator variable 
*Bvar operator "literal"

The B command sets program breakpoints contingent either on a match between the contents of specified variables, or on a specified variable matching a literal. For example:

*BREPORT.DATE=TODAY
*BCHECK.AMOUNT>0
*BEMPLOYEE.DEPARTMENT="ACCOUNTING"

In the first example, the program breaks and enters the debugger when the current value of REPORT.DATE matches the current value of TODAY; in the second, the program breaks when the value of CHECK.AMOUNT becomes greater than 0; and in the third, the break occurs when EMPLOYEE.DEPARTMENT contains the string "ACCOUNTING". Note that strings containing alphabetic or punctuation characters must be enclosed in quotes, but numeric "constants" do not.

*B$operator linenumber

The "$" symbol is a special means of referring to a source line number. This provides the ability to enter the debugger, for example, when a certain program line is executed. For example:

B$=45 

This instructs the debugger to be entered before executing line 45 of the program.

B$>40

This causes the debugger to be activated before executing line 40 and then to reactivate itself before each subsequent program line is executed, until this breakpoint condition is removed.

As breakpoint conditions are entered into the breakpoint table, a plus ( + ) character is displayed for each breakpoint successfully entered, until the table is full. The maximum number of breakpoints is four.

Note that the spaces between the arguments in the above syntax illustrations are simply there for readability--they are not allowed when actually composing breakpoints, as shown in the following examples:

*B$=45                         (OK)
*BCHECK.SUM # CRC.TOTAL (wrong)
*D

Displays the contents of the Break and Trace tables.

*DE 
*DEBUG

Transfers control to the system debugger; see your system manuals for available commands.

*E{numberlines}

Specifies the number of instructions to execute prior to returning to debugger command level. Followed immediately by a <cr>, The E command disables previous iteration counter setting.

*END

Terminates program execution and returns control to TCL.

*G{linenumber}

"Go to" function. Transfers control to a specific program (source) line number. Followed immediately by a carriage return, the G command resumes program execution from the current program line number. Note that if the program was compiled without EOL (End-Of-Line) characters, then the only number allowable for the "Go to" is one (1).

* K {breakpoint-number}

Kills a breakpoint previously set with the B command, and removes the entry from the breakpoint table, Followed immediately by a < cr >, the K command removes all breakpoint entries from the table.

*L {startingline-numberlines}
*L{numberlines}
*L{*}
*L

Displays source cede program lines, beginning from specified starting line number, or from current position if no starting line number is specified. The L command followed by an asterisk displays the entire program. Followed immediately by a <cr>, the L command displays the current program source cede line. (See also the Z command.)

*LP

Toggles the line printer bit, either directing debugger output to the terminal screen or the spooler.

*N{numbertimes}

Instructs the debugger to ignore breakpoints for the next number of times they are encountered. The N command followed immediately by a < cr > resets the bypass, and breakpoints are processed at each occurrence.

*OFF

Terminates program execution, logs process off system, and returns control to the logon message.

*P

Toggles the LISTFLG function, either enabling or disabling output display.

*PC

Closes the currently open spooler file entry, releasing control to spooler.

*R

Removes the top return stack address of local subroutine from stack, causing the program to return from current subroutine as though a RETURN statement had been encountered.

*S

Displays the contents of the subroutine stack.

*T {var}

Sets a trace table entry, instructing the debugger to display the specified data element, along with the contents of the break and trace tables, on each break. A plus (+) character is displayed for each trace table entry successfully entered into the table, up to a maximum of six entries. Entering the T command without parameters toggles the trace function on or off.

*U {trace table entry}

Removes trace table entries previously specified with the T command. A minus (-) character is displayed for each trace table entry successfully removed from the table. Followed immediately by a <cr>, the U command clears all trace table entries previously specified with the T command.

*V

Verifies Pick/BASIC object cede. No longer serves any useful function.

*Z {DICT} filename itemname
*Z<cr>
FILE/PROG NAME?filename itemname

Specifies that the debugger should use the symbol table defined for the program referenced in itemname, in the specified filename. Only required when the source cede for the program is in a different file than the object cede. Entered without parameters, the Z command prompts for the filename and itemname.


Previous chapter Top

 

Creative Commons License
Jonathan E. Sisk's "Pick/BASIC: A Programmer's Guide" by Jonathan E. Sisk is licensed under a Creative Commons Attribution 3.0 Unported License.
Based on a work at jes.com.