BREAK
Set a program breakpoint in the debugger
WTSupported in traditional Synergy on Windows
|
|
USupported on UNIX
|
VSupported on OpenVMS
|
BREAK routine BREAK line BREAK routine:line BREAK label [/LABEL] BREAK . BREAK method BREAK method:line BREAK method#id BREAK method#id:line BREAK method#ALL BREAK method(signature) BREAK image/routine
Arguments
routine
Sets a breakpoint on entry to the specified routine.
line
Sets a breakpoint at the specified source line in the current routine.
routine:line
Sets a breakpoint at the specified source line in the specified routine.
label [/LABEL]
Sets a breakpoint at the specified label in the current routine.
.
(period) Sets a breakpoint at the current line in the current routine.
method
Sets a breakpoint on entry to the specified method.
method:line
Sets a breakpoint at the specified source line in the specified method.
method#id
Sets a breakpoint on entry to the specified implementation of the specified method.
method#id:line
Sets a breakpoint at the specified source line in the specified implementation of the specified method.
method#ALL
Sets a breakpoint on entry to all implementations of the specified method.
method(signature)
Sets a breakpoint on entry to an explicit method.
image/routine
Sets a breakpoint on entry to the specified routine that is inside the specified shared image. (OpenVMS only)
Discussion
The BREAK command sets a program breakpoint, which is a point at which your program stops and goes into the debugger.
You can specify two kinds of breakpoints: entry breakpoints and specific breakpoints. An entry breakpoint causes the program to break upon entering a routine. You can set a break at the entry to a routine using the BREAK routine syntax, and to a method using the BREAK method syntax. A specific breakpoint causes the program to break at a specific line in a routine or method. You can set a specific breakpoint using the BREAK line, BREAK routine:line, BREAK label, BREAK ., BREAK method:line, or BREAK method#id:line syntax.
When a breakpoint occurs, the break line has not yet been executed.
When specifying a line number with the BREAK routine or BREAK method syntax, the colon can be replaced with a space.
You can specify more than one breakpoint, separated by commas. If routine is not specified, the break specification is assumed to be for the current routine.
You can set breakpoints in routines that are .INCLUDEd into another routine. To do so, specify each one in the form
source_file#.line#
You can determine the source file number by viewing a listing file.
The maximum number of breakpoints is 32.
If you try to set a breakpoint in a method whose name is overloaded within the class or whose specified name matches methods in more than one class, the debugger presents a numbered selection list that includes the method name and its parameter types to allow you to select which method should have the breakpoint.
For example,
DBG> break testdrive Found multiple matches: 1: BREAKMETH.CAR.TESTDRIVE() 2: BREAKMETH.CAR.TESTDRIVE(A) 3: BREAKMETH.CAR.TESTDRIVE(A,A,I) *** Choose which breakpoint to set DBG> break testdrive #2 DBG> show break BREAKMETH.CAR.TESTDRIVE(A) on entry
You can either set the breakpoint using one of the unique identifiers, as shown above in the line
DBG> break testdrive #2
or you can set the breakpoint for all of them, like this:
DBG> break testdrive #all
You can use the method#id syntax at any time to set a breakpoint to a particular method, even without a set break attempt generating the list of overloaded methods.
You can alternatively specify an overloaded method by specifying the signature, or parameter list, enclosed in parentheses. (A method does not have to be overloaded to use this syntax, although the signature is not required for a nonoverloaded method.) For example,
BREAK mymethod(i, i)
or
BREAK myclass.mymethod(a, @Class1)
The parameter list is a comma-delimited list of one or more of the following parameter specifications:
Parameter specification |
Description |
---|---|
A |
Parameter is of type alpha |
D |
Parameter is of type decimal |
I |
Parameter is of type integer |
$struct |
Parameter is a structure |
@class |
Parameter is a class handle |
^VAL |
Parameter is passed by value |
^REF |
Parameter is passed by reference |
@$struct |
Parameter is a boxed structure |
@A |
Parameter is a boxed alpha |
@D |
Parameter is a boxed decimal |
@ID |
Parameter is a boxed implied-decimal |
@P |
Parameter is a boxed packed |
@IP |
Parameter is a boxed implied-packed |
@I |
Parameter is a boxed integer |
Except for ^VAL and ^REF, each parameter specification can optionally be preceded by a dimension specification.
A method signature that has a real array parameter must specify it by a left square bracket ([) followed by the number of dimensions. A method signature that has a dynamic array parameter must specify it by a left curly brace ({) followed by the number of dimensions. In either case, if the number of dimensions is one, the number of dimensions may be omitted.
For example,
method mthd arg1, [*]a arg2, [*,*]d arg3, [#]@cls arg4, [#,#][#]@cls proc mreturn end BREAK ns.cls.mthd([A,[2D,{1@cls,{2{@cls)
If the signature doesn’t match a single method implementation exactly, the debugger displays a list of one or more choices, all having the same number of arguments as the signature you specified.
On OpenVMS, you can also set breakpoints in routines inside a shared image using the BREAK image/routine syntax. To do so, you must have done the following when linking the shared image file:
- Included $ELB_DBGn=DATA within the “SYMBOL_VECTOR=” line of the options file used
- Included DBLDIR:elbn.obj
By linking different shared images against different object files, you can specify up to five debuggable shared images in the same application. Linking with an elb.obj file (elb.obj, elb1.obj, elb2.obj, elb3.obj, or elb4.obj) and adding the corresponding vector ($ELB_DBG=DATA, $ELB_DBG1=DATA, $ELB_DBG2=DATA, $ELB_DBG3=DATA, $ELB_DBG4=DATA, respectively) enables the OpenVMS runtime to find the list of routines in the shared image so the debugger can find the routines in the shared image. The logical used to reference the shared image must be used as the image part of the image/routine break specification.
Due to a change in the Itanium kernel in OpenVMS version 8.3 and higher, shared images must not be installed as /RESIDENT, or the programs that use those images will crash. (Installing as /HEADER_RESIDENT is allowed.) |
Examples
The following example sets a breakpoint at lines 7 and 10 in the current routine and also at line 5 in routine ABC.
BREAK 7, abc 5, 10
The following OpenVMS example sets a breakpoint at the entry of the post_data routine in the shared image referenced by the MCBA_LIB logical.
BREAK MCBA_LIB/post_data
The example below shows a breakpoint being set in a .INCLUDEd routine.
Break at 4 in MYFILE (myfile.dbl) on entry 4> xcall flags(1001010, 1) DBG> set break 2.2 DBG> go Break at 2.2 in MYFILE (MYFILEA.DBL) 2.2> nop DBG> step Step to 2.3 in MYFILE (MYFILEA.DBL) 2.3> writes(1, "Exiting include file")
The example below breaks at line 14 within the method mynamespace.myclass.mymethod.
BREAK mynamespace.myclass.mymethod:14
The following example breaks in the third method of myclass at line 53.
BREAK myclass#3:1.53