HP OpenVMS Systems Documentation

Assigns the debugger's abort function to another Ctrl-key sequence. By default, Ctrl/C does the abort function.

Note This command is not available in the HP DECwindows Motif for OpenVMS user interface to the debugger.

Format

SET ABORT_KEY = CTRL_character

Parameters

character

Specifies the key you press while holding down the Ctrl key. You can specify any alphabetic character.

Description

By default, the Ctrl/C sequence, when entered within a debugging session, aborts the execution of a debugger command and interrupts program execution. The SET ABORT_KEY command enables you to assign the abort function to another Ctrl-key sequence. This might be necessary if your program has a Ctrl/C AST service routine enabled.

Many Ctrl-key sequences have predefined functions, and the SET ABORT_KEY command enables you to override such definitions (see the OpenVMS User's Manual). Some of the Ctrl-key characters not used by the operating system are G, K, N, and P.

The SHOW ABORT_KEY command identifies the Ctrl-key sequence currently in effect for the abort function.

Do not use Ctrl/Y from within a debugging session. Instead, use either Ctrl/C or an equivalent Ctrl-key sequence established with the SET ABORT_KEY command.

Related commands:

Ctrl/C
Ctrl/Y
SHOW ABORT_KEY

Example

DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_C
DBG> GO
    ...
    [Ctrl/C]
DBG> EXAMINE/BYTE 1000:101000  !should have typed 1000:1010 
1000: 0 
1004: 0 
1008: 0 
1012: 0 
1016: 0
    [Ctrl/C]
%DEBUG-W-ABORTED, command aborted by user request
DBG> SET ABORT_KEY = CTRL_P
DBG> GO
    ...
    [Ctrl/P]
DBG> EXAMINE/BYTE 1000:101000  !should have typed 1000:1010 
1000: 0 
1004: 0 
1008: 0 
1012: 0 
1016: 0
    [Ctrl/P]
%DEBUG-W-ABORTED, command aborted by user request
DBG>
      

This example shows the following:

• Use of Ctrl/C for the abort function (default).
• Use of the SET ABORT_KEY command to reassign the abort function to Ctrl/P.

Establishes the default file specification that the debugger uses when searching for command procedures.

Format

SET ATSIGN file-spec

Parameters

file-spec

Specifies any part of a file specification (for example, a directory name or a file type) that the debugger is to use by default when searching for a command procedure. If you do not supply a full file specification, the debugger assumes SYS$DISK:[]DEBUG.COM as the default file specification for any missing field.

You can specify a logical name that translates to a search list. In this case, the debugger processes the file specifications in the order they appear in the search list until the command procedure is found.

Description

When you invoke a debugger command procedure with the execute procedure (@) command, the debugger assumes, by default, that the command procedure file specification is SYS$DISK:[]DEBUG.COM. The SET ATSIGN command enables you to override this default.

Related commands:

@ (Execute Procedure)
SHOW ATSIGN

Example

DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> @TEST
      

In this example, when you use the @TEST command, the debugger looks for the file TEST.DBG in USER:[JONES.DEBUG].

Establishes a breakpoint at the location denoted by an address expression, at instructions of a particular class, or at the occurrence of specified events.

Format

SET BREAK [address-expression[,...]]
[WHEN(conditional-expression)]
[DO(command[;...])]

Parameters

address-expression

Specifies an address expression (a program location) at which a breakpoint is to be set. With high-level languages, this is typically a line number, a routine name, or a label, and can include a path name to specify the entity uniquely. More generally, an address expression can also be a memory address or a register and can be composed of numbers (offsets) and symbols, as well as one or more operators, operands, or delimiters. For information about the operators that you can use in address expressions, see the Address_Expressions help topic.

Do not specify the asterisk (*) wildcard character. Do not specify an address expression with any of the following qualifiers:

/ACTIVATING
/BRANCH
/CALL
/EXCEPTION
/HANDLER
/INSTRUCTION
/INTO
/LINE
/OVER
/[NO]SHARE
/[NO]SYSTEM
/SYSEMULATE (Alpha only)
/TERMINATING
/UNALIGNED_DATA (Integrity servers and Alpha only)

The /MODIFY and /RETURN qualifiers are used with specific kinds of address expressions.

If you specify a memory address or an address expression whose value is not a symbolic location, check (with the EXAMINE command) that an instruction actually begins at the byte of memory so indicated. If an instruction does not begin at this byte, a run-time error can occur when an instruction including that byte is executed. When you set a breakpoint by specifying an address expression whose value is not a symbolic location, the debugger does not verify that the location specified marks the beginning of an instruction.

conditional-expression

Specifies a conditional expression in the currently set language that is to be evaluated whenever execution reaches the breakpoint. (The debugger checks the syntax of the expressions in the WHEN clause when execution reaches the breakpoint, not when the breakpoint is set.) If the expression is true, the debugger reports that a breakpoint has been triggered. If an action (DO clause) is associated with the breakpoint, it will occur at this time. If the expression is false, a report is not issued, the commands specified by the DO clause (if one was specified) are not executed, and program execution is continued.

command

Specifies a debugger command to be executed as part of the DO clause when break action is taken. The debugger checks the syntax of the commands in a DO clause when it executes the DO clause, not when the breakpoint is set.

Qualifiers

/ACTIVATING

Causes the debugger to break when a new process comes under debugger control. The debugger prompt is displayed when the first process comes under debugger control. This enables you to enter debugger commands before the program has started execution. See also the /TERMINATING qualifier.

/AFTER:n

Specifies that break action not be taken until the nth time the designated breakpoint is encountered (n is a decimal integer). Thereafter, the breakpoint occurs every time it is encountered provided that conditions in the WHEN clause (if specified) are true. The SET BREAK/AFTER:1 command has the same effect as SET BREAK.

/BRANCH

Causes the debugger to break on every branch instruction encountered during program execution. See also the /INTO and /OVER qualifiers.

/CALL

Causes the debugger to break on every call instruction encountered during program execution, including the RET instruction. See also the /INTO and /OVER qualifiers.

/EVENT=event-name

Causes the debugger to break on the specified event (if that event is defined and detected by the current event facility). If you specify an address expression with /EVENT, causes the debugger to break whenever the specified event occurs for that address expression. You cannot specify an address expression with certain event names.

Event facilities are available for programs that call Ada or SCAN routines or that use POSIX Threads services. Use the SHOW EVENT_FACILITY command to identify the current event facility and the associated event names.

/EXCEPTION

Causes the debugger to break whenever an exception is signaled. The break action occurs before any application-declared exception handlers are invoked.

As a result of a SET BREAK/EXCEPTION command, whenever your program generates an exception, the debugger suspends program execution, reports the exception, and displays its prompt. When you resume execution from an exception breakpoint, the behavior is as follows:

• If you enter a GO command without an address-expression parameter, the exception is resignaled, thus allowing any application-declared exception handler to execute.
• If you enter a GO command with an address-expression parameter, program execution continues at the specified location, thus inhibiting the execution of any application-declared exception handler.
  On Alpha, you must explicitly set a breakpoint in the exception handler before entering a STEP or a GO command to get the debugger to suspend execution within the handler.
• If you enter a CALL command, the routine specified is executed.

On Alpha, an exception might not be delivered (to the program or debugger) immediately after the execution of the instruction that caused the exception. Therefore, the debugger might suspend execution on an instruction beyond the one that actually caused the exception.

/HANDLER

Causes the debugger to scan the call stack and attempt to set a breakpoint on every established frame-based handler whenever the program being debugged has an exception. The debugger does not discriminate between standard RTL handlers and user-established handlers.

On Integrity servers and Alpha systems, most RTLs establish a jacket RTL handler on a frame where the user program has defined a handler. The RTL jacket performs setup, argument manipulation, and dispatch to the user written handlers. When processing the exception, the debugger can only set the breakpoint on the RTL jacket handler, because that is the address on the call stack. If the debugger suspends program execution in a jacket RTL handler, you can usually reach the user-defined handler by finding the dispatch point(s) via some number of STEP/CALLs followed by a STEP/INTO.

See the OpenVMS Calling Standard for more information on frame-based handlers.

If the jacket RTL handler is part of an installed shared image such as ALPHA LIBOTS, the debugger cannot set a breakpoint on it (no private user mode write access). In this case, activate ALL RTLs as private images via logical names. For example:

$DEFINE LIBOTS SYS$SHARE:LIBOTS.EXE;

Note that the trailing semicolon (;) is required. Note also that all (or none) of your shared installed RTLs should be activated privately. Use SHOW IMAGE/FULL data to realize the list of images with system space code sections and then define logicals for all of them and rerun your debug session.

/INSTRUCTION

/INSTRUCTION[=(opcode[,...])]

When you do not specify an opcode, causes the debugger to break on every instruction encountered during program execution.

See also the /INTO and /OVER qualifiers.

/INTO

(Default) Applies only to breakpoints set with the following qualifiers (that is, when an address expression is not explicitly specified):

/BRANCH
/CALL
/INSTRUCTION
/LINE

When used with those qualifiers, /INTO causes the debugger to break at the specified points within called routines (as well as within the routine in which execution is currently suspended). The /INTO qualifier is the default and is the opposite of /OVER.

When using /INTO, you can further qualify the break action with /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM.

/LINE

Causes the debugger to break on the beginning of each source line encountered during program execution. See also the /INTO and /OVER qualifiers.

/MODIFY

Causes the debugger to break on every instruction that writes to and modifies the value of the location indicated by the address expression. The address expression is typically a variable name.

The SET BREAK/MODIFY command acts exactly like a SET WATCH command and operates under the same restrictions.

If you specify an absolute address for the address expression, the debugger might not be able to associate the address with a particular data object. In this case, the debugger uses a default length of 4 bytes. You can change this length, however, by setting the type to either WORD (SET TYPE WORD, which changes the default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the default length to 1 byte). SET TYPE LONGWORD restores the default length of 4 bytes.

/OVER

Applies only to breakpoints set with the following qualifiers (that is, when an address expression is not explicitly specified):

/BRANCH
/CALL
/INSTRUCTION
/LINE

When used with those qualifiers, /OVER causes the debugger to break at the specified points only within the routine in which execution is currently suspended (not within called routines). The /OVER qualifier is the opposite of /INTO (which is the default).

/RETURN

Causes the debugger to break on the return instruction of the routine associated with the specified address expression (which can be a routine name, line number, and so on). Breaking on the return instruction enables you to inspect the local environment (for example, obtain the values of local variables) while the routine is still active. Note that the view of a local environment may differ depending on your architecture.

The address-expression parameter is an instruction address within a routine. It can simply be a routine name, in which case it specifies the routine start address. However, you can also specify another location in a routine, so you can see only those returns that are taken after a certain code path is followed.

A SET BREAK/RETURN command cancels a previous SET BREAK if you specify the same address expression.

/SHARE (default)

/NOSHARE

Qualifies /INTO. Use with /INTO and one of the following qualifiers:

/BRANCH
/CALL
/INSTRUCTION
/LINE

The /SHARE qualifier permits the debugger to break within shareable image routines as well as other routines. The /NOSHARE qualifier specifies that breakpoints not be set within shareable images.

/SILENT

/NOSILENT (default)

Controls whether the "break..." message and the source line for the current location are displayed at the breakpoint. The /NOSILENT qualifier specifies that the message is displayed. The /SILENT qualifier specifies that the message and the source line are not displayed. The /SILENT qualifier overrides /SOURCE. See also the SET STEP [NO]SOURCE command.

/SOURCE (default)

/NOSOURCE

Controls whether the source line for the current location is displayed at the breakpoint. The /SOURCE qualifier specifies that the source line is displayed. The /NOSOURCE qualifier specifies that no source line is displayed. The /SILENT qualifier overrides /SOURCE. See also the SET STEP [NO]SOURCE command.

/SYSEMULATE[=mask]

(Alpha only) Stops program execution and returns control to the debugger after the operating system emulates an instruction. The optional argument mask is an unsigned quadword with bits set to specify which emulated instruction groups shall cause breakpoints. The only emulated instruction group currently defined consists of the BYTE and WORD instructions. Select this instruction group by setting bit 0 of mask to 1.

If mask is not specified or if mask = FFFFFFFFFFFFFFFF, the debugger stops program execution when the operating system emulates any instruction.

/SYSTEM (default)

/NOSYSTEM

Qualifies /INTO. Use with /INTO and one of the following qualifiers:

/BRANCH
/CALL
/INSTRUCTION
/LINE

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

Causes the breakpoint to disappear after it is triggered (the breakpoint does not remain permanently set).

/TERMINATING

Causes the debugger to break when a process does an image exit. The debugger gains control and displays its prompt when the last image of a one-process or multiprocess program exits. A process is terminated when the image has executed the $EXIT system service and all of its exit handlers have executed. See also the /ACTIVATING qualifier.

/UNALIGNED_DATA

(Integrity servers and Alpha only) Causes the debugger to break directly after any instruction that accesses unaligned data (for example, after a load word instruction that accesses data that is not on a word boundary).

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
/RETURN

The following qualifiers affect what happens at a routine call:

/INTO
/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 Integrity server and 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/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.

all> SET BREAK/ACTIVATING
      

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