DataBasic Debugger

This section of the Online Documentation contains the information required to use the DataBasic debugger.

The Overview provides brief descriptions of how to enter the debugger, how to use the Symbol Table and how to enable and disable it.

The Summary of Debugger Commands and subsequent topics contain detailed descriptions of the commands available for using the debugger.

Overview

Entering the debugger

You can only enter the DataBasic debugger if your user-id is assigned a security profile that permits it, as described in Enabling and Disabling the Debugger.

If permitted, you can enter the debugger in the following ways:

• Run your program using the TCL command DEBUG. The debugger is entered before executing the first line of the program.

• Press CTRL+BREAK while the program is executing.

  Note

  This will not work if the break function has been disabled by execution of a BREAK-KEY-OFF or BKOFF command at TCL or by a BREAK {KEY} OFF statement within a program.

• Execute a DEBUG statement from within a DataBasic program. You must have done one of the following:

  • Run your program using the TCL command DEBUG.

  • Set the DB.DEBUG environment option. Use this method when you need to debug a DataBasic program that is run directly or indirectly from TCL.

  • Set the EB.DEBUG environment option. Use this method when you need to debug an Embedded Basic program; for example, a file trigger.

  • Started the program with the F option or set the FATAL.WARNINGS environment option. Use this method when you need find the cause of a warning message.

Once you enter the debugger, the system displays the entry reason, the program's item-id and the line number about to be executed, and prompts you with an asterisk (*). The * distinguishes the DataBasic debugger from the system debugger and TCL. For example, the following display appears when you press CTRL+BREAK while the TEST program is executing:

:RUN PROGRAM TEST

Input Break: TEST 15
*

This display indicates that the program TEST was interrupted and line 15 was about to be executed when you pressed CTRL+BREAK. The debugger prompts you to input a debugger command.

DataBasic debugger entry reasons

The following table shows the entry reasons and their meanings:

Entry Reason	Meaning
Code Abort	The debugger is entered after a run time error.
Break Point	The debugger is entered after a debugger break point is hit.
Called Module	The debugger is entered after an external subroutine or function is called.
DEBUG Cmd/Stmt	The debugger is entered after either a TCL DEBUG command or a run time DEBUG statement.
Execution Count	The debugger is entered after the step execution count expires.
Input Break	The debugger is entered after a user break.
Entered Module	The debugger is entered after a code module is entered by a ENTER or CHAIN statement.
Return To Module	The debugger is entered after the return from an external subroutine or function.

Nested programs

If your program has been called from a PERFORM statement, the debugger prompt shows the level of nesting. This can help you keep track of which of a number of different programs or routines you are currently debugging. It is particularly useful when debugging Embedded Basic subroutines.

For example, if a Proc run from TCL runs a DataBasic program that performs the program you are debugging, the nesting level will be 1 and the debugger prompt will appear as follows:

{1}*

Embedded Basic subroutines are always at nesting level 1 or above. For example, if a program called from TCL causes an Embedded Basic subroutine to run, the subroutine will be at nesting level 1. If that subroutine then carries out an action that causes a second Embedded Basic subroutine to run, the second subroutine will be at nesting level 2.

Symbol table

A symbol table is created by the BASIC command when the program is compiled. The table is appended to the object code item. The symbols can be referenced in the debugger.

Variables

The debugger displays the value of undefined variables as <undefined>, and displays null variables as <null>.

The debugger displays a runtime error message if a variable is referenced before it has been assigned a value. The form of the message depends on whether the variable is a simple variable, a vector entry or an array entry, as follows:

[B10] Program 90740 Line line-no: Unassigned variable variable-name; zero used.

[B10] Program 90740 Line line-no: Unassigned variable vector-name(x,1); zero used.

[B10] Program 90740 Line line-no: Unassigned variable array-name(x,y); zero used.

However, if the symbol table is suppressed, then the message is less explicit:

[B10] Program 90740 Line line-no: Unassigned variable; zero used.

Enabling and disabling the debugger

You can deactivate (or activate) the DataBasic debugger on a port-by-port basis using the SSM command at TCL.

You must be logged on the SYSMAN account to use the SSM command. Briefly, the procedure is as follows:

1. Enter SSM at TCL. The SECURITY SYSTEM MAINTENANCE menu is displayed.

2. Enter 3 to display the SECURITY FILE MAINTENANCE menu.

3. Enter the name of the appropriate security profile (entering * selects the current profile). See Profiles Screens for details.

4. Select Option 16, Basic Debugger. You are then prompted to enable or disable the debugger. N  disables the Basic debugger and is the default. Y  enables the Basic debugger to allow access to the debugger according to your privilege level and any other restrictions that might apply.

5. Save your changes.