Updated: 11 December 1998

OpenVMS Debugger Manual

The /SYSTEM qualifier permits the debugger to break within system routines (P1 space) as well as other routines. The /NOSYSTEM qualifier specifies that breakpoints not be set within system routines.

/TEMPORARY

/TERMINATING

/UNALIGNED_DATA

/VECTOR_INSTRUCTION

Description

When a breakpoint is triggered, the debugger takes the following actions:

1. Suspends program execution at the breakpoint location.
2. If you specified /AFTER when you set the breakpoint, checks the AFTER count. If the specified number of counts has not been reached, execution resumes and the debugger does not do the remaining steps.
3. Evaluates the expression in a WHEN clause, if you specified one when you set the breakpoint. If the value of the expression is false, execution resumes and the debugger does not do the remaining steps.
4. Reports that execution has reached the breakpoint location by issuing a "break..." message, unless you specified /SILENT.
5. Displays the line of source code at which execution is suspended, unless you specified /NOSOURCE or /SILENT when you set the breakpoint or unless you previously entered SET STEP NOSOURCE.
6. Executes the commands in a DO clause, if you specified one when you set the breakpoint. If the DO clause contains a GO command, execution continues and the debugger does not perform the next step.
7. Issues the prompt.

You set a breakpoint at a particular location in your program by specifying an address expression with the SET BREAK command. You set a breakpoint on consecutive source lines, classes of instructions, or events by specifying a qualifier with the SET BREAK command. Generally, you must specify either an address expression or a qualifier, but not both. Exceptions are /EVENT and /RETURN.

The /LINE qualifier sets a breakpoint on each line of source code.

The following qualifiers set breakpoints on classes of instructions. Using these qualifiers with /LINE causes the debugger to trace every instruction of your program as it executes and thus significantly slows down execution:

• /BRANCH
• /CALL
• /INSTRUCTION
• /INSTRUCTION=(opcode[,...]) (VAX only)
• /RETURN
• /VECTOR_INSTRUCTION (VAX only)

The following qualifiers set breakpoints on classes of events:

• /ACTIVATING
• /EVENT=event-name
• /EXCEPTION
• /SYSEMULATE (Alpha only)
• /TERMINATING
• /UNALIGNED_DATA (Alpha only)

The following qualifiers affect what happens at a routine call:

• /INTO
• /[NO]JSB (VAX only)
• /OVER
• /[NO]SHARE
• /[NO]SYSTEM

The following qualifiers affect what output is displayed when a breakpoint is reached:

• /[NO]SILENT
• /[NO]SOURCE

The following qualifiers affect the timing and duration of breakpoints:

• /AFTER:n
• /TEMPORARY

Use the /MODIFY qualifier to monitor changes at program locations (typically changes in the values of variables).

If you set a breakpoint at a location currently used as a tracepoint, the tracepoint is canceled in favor of the breakpoint, and vice versa.

On OpenVMS Alpha systems, the SET BREAK/UNALIGNED_DATA command calls the $START_ALIGN_FAULT_REPORT system service routine. Do not issue this command if the program you are debugging includes a call to the same $START_ALIGN_FAULT_REPORT routine. If you issue the command before the program call, the program call fails. If the program call occurs before you issue the command, unaligned breaks are not set.

Breakpoints can be user defined or predefined. User-defined breakpoints are set explicitly with the SET BREAK command. Predefined breakpoints, which depend on the type of program you are debugging (for example, Ada or multiprocess), are established automatically when you start the debugger. Use the SHOW BREAK command to identify all breakpoints that are currently set. Any predefined breakpoints are identified as such.

User-defined and predefined breakpoints are set and canceled independently. For example, a location or event can have both a user-defined and a predefined breakpoint. Canceling the user-defined breakpoint does not affect the predefined breakpoint, and conversely.

Related commands:

• (ACTIVATE,DEACTIVATE,SHOW,CANCEL) BREAK
• CANCEL ALL
• GO
• (SET,SHOW) EVENT_FACILITY
• SET STEP [NO]SOURCE
• SET TRACE
• SET WATCH
• STEP

Examples

DBG> SET BREAK SWAP\%LINE 12
      

This command causes the debugger to break on line 12 of module SWAP.

DBG> SET BREAK/AFTER:3 SUB2
      

This command causes the debugger to break on the third and subsequent times that SUB2 (a routine) is executed.

DBG> SET BREAK/NOSOURCE LOOP1 DO (EXAMINE D; STEP; EXAMINE Y; GO)
 
 
      

This command causes the debugger to break at location LOOP1. At the breakpoint, the following commands are issued, in the order given: (1) EXAMINE D, (2) STEP, (3) EXAMINE Y, and (4) GO. The /NOSOURCE qualifier suppresses the display of source code at the breakpoint.

DBG> SET BREAK ROUT3 WHEN (X > 4) DO (EXAMINE Y)
      

This command causes the debugger to break on routine ROUT3 when X is greater than 4. At the breakpoint, the EXAMINE Y command is issued. The syntax of the conditional expression in the WHEN clause is language-dependent.

DBG> SET BREAK/TEMPORARY 1440
DBG> SHOW BREAK
breakpoint at 1440 [temporary]
DBG>
      

This command sets a temporary breakpoint at memory address 1440. After that breakpoint is triggered, it disappears.

DBG> SET BREAK/LINE
      

This command causes the debugger to break on the beginning of every source line encountered during program execution.

DBG> SET BREAK/LINE WHEN (X .NE. 0)
DBG> SET BREAK/INSTRUCTION WHEN (X .NE. 0)
      

These two commands cause the debugger to break when X is not equal to 0. The first command tests for the condition at the beginning of every source line encountered during execution. The second command tests for the condition at each instruction. The syntax of the conditional expression in the WHEN clause is language-dependent.

DBG> SET BREAK/INSTRUCTION=ADDL3
      

(VAX only) This command causes the debugger to break whenever the instruction ADDL3 is about to be executed.

DBG> SET BREAK/LINE/INTO/NOSHARE/NOSYSTEM
      

This command causes the debugger to break on the beginning of every source line, including lines in called routines (/INTO) but not in shareable image routines (/NOSHARE) or system routines (/NOSYSTEM).

DBG> SET BREAK/RETURN ROUT4
      

This command causes the debugger to break whenever the return instruction of routine ROUT4 is about to be executed.

DBG> SET BREAK/RETURN %LINE 14
      

This command causes the debugger to break whenever the return instruction of the routine that includes line 14 is about to be executed. This form of the command is useful if execution is currently suspended within a routine and you want to set a breakpoint on that routine's return instruction.

DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS)
      

This command causes the debugger to break whenever an exception is signaled. At the breakpoint, the SET MODULE/CALLS and SHOW CALLS commands are issued.

DBG> SET BREAK/EVENT=RUN RESERVE, %TASK 3
      

This command sets two breakpoints, which are associated with task RESERVE and task 3 (task ID = 3), respectively. Each breakpoint is triggered whenever its associated task makes a transition to the RUN state.

DBG_1> SET BREAK/ACTIVATING
      

This command causes the debugger to break whenever a process of a multiprocess program is brought under debugger control.

Establishes a default qualifier (/ADDRESS, /COMMAND, /PROCESS_GROUP, or /VALUE) for the DEFINE command.

Format

SET DEFINE define-default

Parameters

define-default

Specifies the default to be established for the DEFINE command. Valid keywords (which correspond to DEFINE command qualifiers) are as follows:

ADDRESS	Subsequent DEFINE commands are treated as DEFINE/ADDRESS. This is the default.
COMMAND	Subsequent DEFINE commands are treated as DEFINE/COMMAND.
PROCESS_GROUP	Subsequent DEFINE commands are treated as DEFINE/PROCESS_GROUP.
VALUE	Subsequent DEFINE commands are treated as DEFINE/VALUE.

Description

The SET DEFINE command establishes a default qualifier for subsequent DEFINE commands. The parameters that you specify in the SET DEFINE command have the same names as the qualifiers for the DEFINE command. The qualifiers determine whether the DEFINE command binds a symbol to an address, a command string, a list of processes, or a value.

You can override the current DEFINE default for the duration of a single DEFINE command by specifying another qualifier. Use the SHOW DEFINE command to identify the current DEFINE defaults.

Related commands:

• DEFINE
• DEFINE/PROCESS_GROUP
• DELETE
• SHOW DEFINE
• SHOW SYMBOL/DEFINED

Example

DBG> SET DEFINE VALUE
      

The SET DEFINE VALUE command specifies that subsequent DEFINE commands are treated as DEFINE/VALUE.

Establishes the editor that is started by the EDIT command.

Format

SET EDITOR [command-line]

Parameters

command-line

Specifies a command line to start a particular editor on your system when you use the EDIT command.

You need not specify a command line if you use /CALLABLE_EDT, /CALLABLE_LSEDIT, or /CALLABLE_TPU. If you do not use one of these qualifiers, the editor specified in the SET EDITOR command line is spawned to a subprocess when you enter the EDIT command.

You can specify a command line with /CALLABLE_LSEDIT or /CALLABLE_TPU but not with /CALLABLE_EDT.

Qualifiers

/CALLABLE_EDT

Specifies that the callable version of the EDT editor is started when you use the EDIT command. Do not specify a command line with this qualifier (a command line of "EDT" is used).

/CALLABLE_LSEDIT

(VAX only) Specifies that the callable version of the DEC Language-Sensitive Editor (LSEDIT) is started when you use the EDIT command. If you also specify a command line, it is passed to callable LSEDIT. If you do not specify a command line, the default command line is LSEDIT.

/CALLABLE_TPU

Specifies that the callable version of the DEC Text Processing Utility (DECTPU) is started when you use the EDIT command. If you also specify a command line, it is passed to callable DECTPU. If you do not specify a command line, the default command line is TPU.

/START_POSITION

/NOSTART_POSITION (default)

Controls whether the /START_POSITION qualifier is appended to the specified or default command line when you enter the EDIT command. Currently, only DECTPU and the DEC Language-Sensitive Editor (specified as TPU or /CALLABLE_TPU, and LSEDIT or /CALLABLE_LSEDIT, respectively) support this qualifier.

The /START_POSITION qualifier affects the initial position of the editor's cursor. By default (/NOSTART_POSITION), the editor's cursor is placed at the beginning of source line 1, regardless of which line is centered in the debugger's source display or whether you specify a line number in the EDIT command. If you specify /START_POSITION, the cursor is placed either on the line whose number you specify in the EDIT command, or (if you do not specify a line number) on the line that is centered in the current source display.

Description

The SET EDITOR command enables you to specify any editor that is installed on your system. In general, the command line specified as parameter to the SET EDITOR command is spawned and executed in a subprocess.

On VAX processors, if you use EDT, LSEDIT, or DECTPU, you can start these editors in a more efficient way. You can specify /CALLABLE_EDT, /CALLABLE_LSEDIT, or /CALLABLE_TPU, which causes the callable versions of EDT, LSEDIT, and DECTPU, respectively, to be invoked by the EDIT command. In the case of LSEDIT and DECTPU, you can also specify a command line that is executed by the callable editor.

On Alpha processors, you can use /CALLABLE_EDT or /CALLABLE_TPU, but not /CALLABLE_LSEDIT.

Related commands:

• EDIT
• (SET,SHOW,CANCEL) SOURCE
• SHOW DEFINE

Examples

DBG> SET EDITOR '@MAIL$EDIT ""'
      

This command causes the EDIT command to spawn the command line '@MAIL$EDIT ""', which starts the same editor as you use in MAIL.

DBG> SET EDITOR/CALLABLE_TPU
      

This command causes the EDIT command to start callable DECTPU with the default command line of TPU.

DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI.TPU$SECTION
      

This command causes the EDIT command to start callable DECTPU with the command line TPU/SECTION=MYSECINI.TPU$SECTION.

DBG> SET EDITOR/CALLABLE_EDT/START_POSITION
      

This command causes the EDIT command to start callable EDT with the default command line of EDT. Also the /START_POSITION qualifier is appended to the command line, so that the editing session starts on the source line that is centered in the debugger's current source display.

Establishes the current event facility.

Event facilities are available for programs that call Ada or SCAN routines or that use DECthreads services.

Format

SET EVENT_FACILITY facility-name

Parameters

facility-name

Specifies an event facility. Valid facility-name keywords are as follows:

ADA	If the event facility is set to ADA, the (SET,CANCEL) BREAK and (SET,CANCEL) TRACE commands recognize Ada-specific events as well as generic, low-level task events. (Ada events consist of task and exception events.) You can set the event facility to ADA only if the main program is written in Ada or if the program calls an Ada routine.
THREADS	If the event facility is set to THREADS, the (SET,CANCEL) BREAK and (SET,CANCEL) TRACE commands recognize DECthreads-specific as well as generic, low-level task events. All DECthreads events are task (thread) events. You can set the event facility to THREADS only if the shareable image CMA$RTL is currently part of the program's process (if that image is listed in a SHOW IMAGE display).
SCAN	(VAX only) If the event facility is set to SCAN, the (SET,CANCEL) BREAK and (SET,CANCEL) TRACE commands recognize SCAN (pattern-matching) events. You can set the event facility to SCAN only if the main program is written in SCAN or if the program calls a SCAN routine.

Description

The current event facility (ADA, THREADS, or SCAN) defines the eventpoints that you can set with the SET BREAK/EVENT and SET TRACE/EVENT commands.

When started with a program that is linked with an event facility, the debugger automatically sets the facility in a manner appropriate for the type of program. For example, if the main program is written in Ada or SCAN, the event facility is set to ADA or SCAN, respectively.

The SET EVENT_FACILITY command enables you to change the event facility and thereby change your debugging context. This is useful if you have a multilanguage program and want to debug a routine that is associated with an event facility but that facility is not currently set.

On VAX processors, you cannot use both Ada and DECthreads tasking services in the same program. This implies that you can change the event facility only from ADA to SCAN or from DECthreads to SCAN, or conversely.

Use the SHOW EVENT_FACILITY command to identify the event names associated with the current event facility. These are the keywords that you can specify with the (SET,CANCEL) BREAK/EVENT and (SET,CANCEL) TRACE/EVENT commands.

Related commands:

• (SET,CANCEL) BREAK/EVENT
• (SET,CANCEL) TRACE/EVENT
• SHOW BREAK
• SHOW EVENT_FACILITY
• SHOW IMAGE
• SHOW TASK
• SHOW TRACE

Example

DBG> SET EVENT_FACILITY THREADS
      

This command establishes THREADS (DECthreads) as the current event facility.

Loads symbol information for one or more shareable images and establishes the current image.

Format

SET IMAGE [image-name[,...]]

Parameters

image-name

Specifies a shareable image to be set. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an image name with /ALL.

Qualifiers

/ALL

Specifies that all shareable images are set.

Description

The SET IMAGE command builds data structures for one or more specified images but does not set any modules within the images specified.

The current image is the current debugging context: you have access to symbols in the current image. If you specify only one image with the SET IMAGE command, that image becomes the current image. If you specify a list of images, the last one in the list becomes the current image. If you specify /ALL, the current image is unchanged.

Before an image can be set with the SET IMAGE command, it must have been linked with the /DEBUG or /TRACEBACK qualifier on the DCL command LINK. If an image was linked /NOTRACEBACK, no symbol information is available for that image and you cannot specify it with the SET IMAGE command.

Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands are available only when the image in whose context they were created is the current image. When you use the SET IMAGE command to establish a new current image, these definitions are temporarily unavailable. However, definitions created with the DEFINE/COMMAND and DEFINE/KEY commands are available for all images.

Related commands:

• SET MODE [NO]DYNAMIC
• (SET,SHOW,CANCEL) MODULE
• (SHOW,CANCEL) IMAGE

Example

DBG> SET IMAGE SHARE1
DBG> SET MODULE SUBR
DBG> SET BREAK SUBR
      

This sequence of commands shows how to set a breakpoint on routine SUBR in module SUBR of shareable image SHARE1. The SET IMAGE command sets the debugging context to SHARE1. The SET MODULE command loads the symbol records of module SUBR into the run-time symbol table (RST). The SET BREAK command sets a breakpoint on routine SUBR.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4538PRO_052.HTML