Break (command): Difference between revisions

From BR Wiki
Jump to navigation Jump to search
(edit)
(added function names to list of break targets)
 
(17 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The '''Break''' command causes the program to go into [[Step mode]] when a [[Variable|variable]] value changes, or the specified [[line number]] is encountered.  Both "BREAK variable-name" and "[[Display|Display]] variable-name" may be active on the same variable concurrently.
For disambiguation purposes, see also [[Break (Config)]].
 
The '''Break''' [[command]] causes the program to go into [[Step mode]] when a [[Variable|variable]] value changes, or a specified [[line number]] or [[user defined function]] is encountered.  "BREAK variable-name" also implies "[[Display|DISPLAY]] variable-name," so the new value of the variable will be displayed  when a BREAK variable-name occurs.
 
Any line numbers specified must refer to an executable line. A line with an active operation such as a flow control, value assignment or input-output operation will break. Comments, data statements and DIM statements will not break.


==Examples==
==Examples==
The following example will force the currently loaded program to go into [[step]] mode when the execution reaches line 1025:
The following example will force the currently loaded program to go into [[step]] mode when the execution reaches line 1025:


  BREAK 1025
  BREAK 1025
It can also enter step mode when a variable is changed:
BREAK totalfiles
BREAK also works with specific array elements (as of 4.16):
BREAK CUSTOMER$(6)
Will cause a program break whenever CUSTOMER$(6) is changed.


==Syntax==
==Syntax==
BREAK {[ [-p program name substring] {[<[[Line Label|label]]>:[<clause>]]|[<[[line number]]>[:<clause>]]|[<[[variable name]]>]|[<[[function]] name>]|[BEGIN]} [OFF] ]|[ALL OFF]}


[[File:Break.png]]
[[File:Break.png]]
;Examples:


  BREAK <nowiki>[ -p program-name-substring ]  BEGIN [ OFF ]  (break upon entry)</nowiki>
  BREAK <nowiki>[ -p program-name-substring ]  BEGIN [ OFF ]  (break upon entry)</nowiki>
Line 20: Line 36:
This command causes a break to occur upon encountering the indicated conditions. When this happens the program enters step mode.  
This command causes a break to occur upon encountering the indicated conditions. When this happens the program enters step mode.  


The -p parameter specifies which [[program]] or programs the statement pertains to. If not specified, then the full BR path to the current program is stored as the program name search string. However the substring value could be used as a [[mask]] to apply to multiple program [[libraries]].
===Parameters===
 
The -p parameter specifies which [[program]] or programs the statement pertains to. When -p is specified BR will first check the mask against the current program path. If it matches (or if -p is not specified) then the full BR path to the current program is stored as the program name search string. However a -p substring value that does not match the currently loaded program can be used as a [[mask]] to apply to multiple program [[libraries]].
 
The parameters "label:" and "line number" will cause the program to enter [[STEP mode]] when the specified element is reached.
 
The parameters "variable name", "function name", "array name" and "array element" will cause the program to enter [[STEP mode]] when the specified variable or array is changed. BREAK var-name also displays the variable assignment like [[Display (Command)|DISPLAY]] does, except only the first element that changed in an array will be displayed.
 
BEGIN will cause the program to enter step mode upon entry at the first line.
 
Adding the OFF parameter will clear (remove) the specified BREAK setting. ALL OFF will clear all currently active BREAK settings.
 
===Conditional Breakpoints===
Conditional breakpoints are not set with the BREAK command. They must be stored as a program statement in order to tell BR ''when'' to perform the condition test. The preferred command for a current break is "go step". An [[Execcute]] statement is used to execute the command:
 
02000 ...
02010 ! A will never exceed B if the preceding statements are correct
02020 If A > B Then Execute "go step"
02030 A = B
02040 ...
 
This will cause the program to stop before executing line 2020 so the programmer can identify which values and statements caused A to exceed B.
----
Another convenient programming technique is to use LINPUT to momentarily pause after displaying variable contents:
 
02050 If {condition} then Print Partnum$ : Linput Z$
 
If {condition} is true this will display the contents of Partnum$ and then pause for input into an unused variable. The programmer can then continue execution by pressing <enter> on the keyboard, enabling a scrolling effect as the program loops.  


<noinclude>
<noinclude>
[[Category:Commands]]
[[Category:Commands]]
[[Category:Editing Commands]]
[[Category:Statements]]
[[Category:Debugging Statements]]
[[Category:Debug]]
[[Category:Debug]]
</noinclude>
</noinclude>

Latest revision as of 02:09, 18 May 2019

For disambiguation purposes, see also Break (Config).

The Break command causes the program to go into Step mode when a variable value changes, or a specified line number or user defined function is encountered. "BREAK variable-name" also implies "DISPLAY variable-name," so the new value of the variable will be displayed when a BREAK variable-name occurs.

Any line numbers specified must refer to an executable line. A line with an active operation such as a flow control, value assignment or input-output operation will break. Comments, data statements and DIM statements will not break.

Examples

The following example will force the currently loaded program to go into step mode when the execution reaches line 1025:

BREAK 1025

It can also enter step mode when a variable is changed:

BREAK totalfiles

BREAK also works with specific array elements (as of 4.16):

BREAK CUSTOMER$(6) 

Will cause a program break whenever CUSTOMER$(6) is changed.

Syntax

BREAK {[ [-p program name substring] {[<label>:[<clause>]]|[<line number>[:<clause>]]|[<variable name>]|[<function name>]|[BEGIN]} [OFF] ]|[ALL OFF]}

Examples
BREAK [ -p program-name-substring ]  BEGIN [ OFF ]  (break upon entry)
BREAK [ -p program-name-substring ]  variable-name  [ OFF ]
BREAK [ -p program-name-substring ]  line[:clause]  [ OFF ]
BREAK [ -p program-name-substring ]  label:[clause]  [ OFF ]
BREAK [ -p program-name-substring ]  FNname  [ OFF ]
BREAK ALL OFF

This command causes a break to occur upon encountering the indicated conditions. When this happens the program enters step mode.

Parameters

The -p parameter specifies which program or programs the statement pertains to. When -p is specified BR will first check the mask against the current program path. If it matches (or if -p is not specified) then the full BR path to the current program is stored as the program name search string. However a -p substring value that does not match the currently loaded program can be used as a mask to apply to multiple program libraries.

The parameters "label:" and "line number" will cause the program to enter STEP mode when the specified element is reached.

The parameters "variable name", "function name", "array name" and "array element" will cause the program to enter STEP mode when the specified variable or array is changed. BREAK var-name also displays the variable assignment like DISPLAY does, except only the first element that changed in an array will be displayed.

BEGIN will cause the program to enter step mode upon entry at the first line.

Adding the OFF parameter will clear (remove) the specified BREAK setting. ALL OFF will clear all currently active BREAK settings.

Conditional Breakpoints

Conditional breakpoints are not set with the BREAK command. They must be stored as a program statement in order to tell BR when to perform the condition test. The preferred command for a current break is "go step". An Execcute statement is used to execute the command:

02000 ...
02010 ! A will never exceed B if the preceding statements are correct
02020 If A > B Then Execute "go step"
02030 A = B
02040 ...

This will cause the program to stop before executing line 2020 so the programmer can identify which values and statements caused A to exceed B.


Another convenient programming technique is to use LINPUT to momentarily pause after displaying variable contents:

02050 If {condition} then Print Partnum$ : Linput Z$

If {condition} is true this will display the contents of Partnum$ and then pause for input into an unused variable. The programmer can then continue execution by pressing <enter> on the keyboard, enabling a scrolling effect as the program loops.