BREAK

Set a program breakpoint in the debugger

WSupported 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 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