Next: , Previous: Leaving Debug Mode, Up: Debugging

13.3 Breakpoints

Breakpoints can be set in any Octave function, using the dbstop function.

— Loadable Function: rline = dbstop ("func")
— Loadable Function: rline = dbstop ("func", line, ...)

Set a breakpoint in function func.

Arguments are

func
Function name as a string variable. When already in debug mode this should be left out and only the line should be given.
line
Line number where the breakpoint should be set. Multiple lines may be given as separate arguments or as a vector.

When called with a single argument func, the breakpoint is set at the first executable line in the named function.

The optional output rline is the real line number where the breakpoint was set. This can differ from specified line if the line is not executable. For example, if a breakpoint attempted on a blank line then Octave will set the real breakpoint at the next executable line.

See also: dbclear, dbstatus, dbstep, debug_on_error, debug_on_warning, debug_on_interrupt.

Note that breakpoints cannot be set in built-in functions (e.g., sin, etc.) or dynamically loaded function (i.e., oct-files). To set a breakpoint immediately on entering a function, the breakpoint should be set to line 1. The leading comment block will be ignored and the breakpoint will be set to the first executable statement in the function. For example: 

     dbstop ("asind", 1)
     ⇒ 28

Note that the return value of 27 means that the breakpoint was effectively set to line 27. The status of breakpoints in a function can be queried with the dbstatus function.

— Loadable Function: dbstatus ()
— Loadable Function: brk_list = dbstatus ()
— Loadable Function: brk_list = dbstatus ("func")

Report the location of active breakpoints.

When called with no input or output arguments, print the list of all functions with breakpoints and the line numbers where those breakpoints are set. If a function name func is specified then only report breakpoints for the named function.

The optional return argument brk_list is a struct array with the following fields.

name
The name of the function with a breakpoint.
file
The name of the m-file where the function code is located.
line
A line number, or vector of line numbers, with a breakpoint.

See also: dbclear, dbwhere.

Taking the above as an example, dbstatus ("asind") should return 28. The breakpoints can then be cleared with the dbclear function

— Loadable Function: dbclear ("func")
— Loadable Function: dbclear ("func", line, ...)

Delete a breakpoint in the function func.

Arguments are

func
Function name as a string variable. When already in debug mode this should be left out and only the line should be given.
line
Line number from which to remove a breakpoint. Multiple lines may be given as separate arguments or as a vector.

When called without a line number specification all breakpoints in the named function are cleared.

If the requested line is not a breakpoint no action is performed.

See also: dbstop, dbstatus, dbwhere.

These functions can be used to clear all the breakpoints in a function. For example: 

     dbclear ("asind", dbstatus ("asind"));

A breakpoint can be set in a subfunction. For example if a file contains the functions 

     function y = func1 (x)
       y = func2 (x);
     endfunction
     function y = func2 (x)
       y = x + 1;
     endfunction

then a breakpoint can be set at the start of the subfunction directly with 

     dbstop (["func1", filemarker(), "func2"])
     ⇒ 5

Note that filemarker returns a character that marks the subfunctions from the file containing them.

Another simple way of setting a breakpoint in an Octave script is the use of the keyboard function.

— Built-in Function: keyboard ()
— Built-in Function: keyboard (prompt)

This function is normally used for simple debugging. When the keyboard function is executed, Octave prints a prompt and waits for user input. The input strings are then evaluated and the results are printed. This makes it possible to examine the values of variables within a function, and to assign new values if necessary. To leave the prompt and return to normal execution type ‘return’ or ‘dbcont’. The keyboard function does not return an exit status.

If keyboard is invoked without arguments, a default prompt of ‘debug> ’ is used.

See also: dbcont, dbquit.

The keyboard function is typically placed in a script at the point where the user desires that the execution is stopped. It automatically sets the running script into the debug mode.