[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Debugger Manual

Previous Contents Index

This command searches for the next occurrence (by default) of the letter D, starting with line 43.

SELECT

Selects a screen display as the current error, input, instruction, output, program, prompt, scrolling, or source display.

Note
This command is not available in the DECwindows Motif interface to the debugger.

Format

SELECT [display-name]

Parameters

display-name

Specifies the display to be selected. You can specify any one of the following, with the restrictions noted in the qualifier descriptions:

If you omit this parameter and do not specify a qualifier, you "unselect" the current scrolling display (no display then has the scrolling attribute). If you omit this parameter but specify a qualifier (/INPUT, /SOURCE, and so on), you unselect the current display with that attribute (see the qualifier descriptions).

Qualifiers

/ERROR

Selects the specified display as the current error display. This causes all debugger diagnostic messages to go to that display. The display specified must be either an output display or the PROMPT display. If you do not specify a display, selects the PROMPT display current error display. By default, the PROMPT display has the error attribute.

/INPUT

Selects the specified display as the current input display. This causes that display to echo debugger input (which appears in the PROMPT display). The display specified must be an output display.

If you do not specify a display, the current input display is unselected and debugger input is not echoed to any display (debugger input appears only in the PROMPT display). By default, no display has the input attribute.

/INSTRUCTION

Selects the specified display as the current instruction display. This causes the output of all EXAMINE/INSTRUCTION commands to go to that display. The display specified must be an instruction display.

If you do not specify a display, the current instruction display is unselected and no display has the instruction attribute.

By default, for all languages except MACRO--32, no display has the instruction attribute. If the language is set to MACRO--32, the INST display has the instruction attribute by default.

/OUTPUT

Selects the specified display as the current output display). This causes debugger output that is not already directed to another display to go to that display. The display specified must be either an output display or the PROMPT display.

If you do not specify a display, the PROMPT display is selected as the current output display. By default, the OUT display has the output attribute.

/PROGRAM

Selects the specified display as the current program display. This causes the debugger to try to force program input and output to that display. Currently, only the PROMPT display can be specified.

If you do not specify a display, the current program display is unselected and program input and output are no longer forced to the specified display.

By default, the PROMPT display has the program attribute, except on workstations, where the program attribute is unselected.

/PROMPT

Selects the specified display as the current prompt display. This is where the debugger prompts for input. Currently, only the PROMPT display can be specified. Moreover, you cannot unselect the PROMPT display (the PROMPT display always has the prompt attribute).

/SCROLL

(Default) Selects the specified display as the current scrolling display. This is the default display for the SCROLL, MOVE, and EXPAND commands. Although any display can have the scroll attribute, you can use only the MOVE and EXPAND commands (not the SCROLL command) with the PROMPT display.

If you do not specify a display, the current scrolling display is unselected and no display has the scroll attribute.

By default, for all languages except MACRO-32, the SRC display has the scroll attribute. If the language is set to MACRO-32, the INST display has the scroll attribute by default.

/SOURCE

Selects the specified display as the current source display. This causes the output of all TYPE and EXAMINE/SOURCE commands to go to that display. The display specified must be a source display.

If you do not specify a display, the current source display is unselected and no display has the source attribute.

By default, for all languages except MACRO--32, the SRC display has the source attribute. If the language is set to MACRO--32, no display has the source attribute by default.

/SUFFIX[=process-identifier-type]

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Appends a process-identifying suffix to a display name. Use this qualifier only directly after a display name. The suffix denotes the visible process at the time the command was issued.

The /SUFFIX qualifier is used primarily in command procedures when you specify display definitions or key definitions that are bound to display definitions.

Use any of the following process-identifier-type keywords:
PROCESS_NAME The display-name suffix is the process name.
PROCESS_NUMBER The display-name suffix is the process number (as shown in a SHOW PROCESS display).
PROCESS_PID The display-name suffix is the process identifier (PID).

If you specify /SUFFIX without a process-identifier-type keyword, the process identifier type used for the display-name suffix is, by default, the same as that used for the prompt suffix (see the SET PROMPT/SUFFIX command).

Description

Attributes are used to select the current scrolling display and to direct various types of debugger output to particular displays. This gives you the option of mixing or isolating different types of information, such as debugger input, output, diagnostic messages, and so on in scrollable displays.

Use the SELECT command with one or more qualifiers (/ERROR, /SOURCE, and so on) to assign one or more corresponding attributes to a display. By default, if you do not specify a qualifier, /SCROLL is assumed.

If you use the SELECT command without specifying a display name, in general the attribute assignment indicated by the qualifier is canceled (unselected). To reassign display attributes, you must use another SELECT command. For more information, see the individual qualifier.

For a list of the key definitions associated with the SELECT command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions.

Related commands:

Examples

#1 

DBG> SELECT/SOURCE/SCROLL SRC2

This command selects display SRC2 as the current source and scrolling display.

#2 

DBG> SELECT/INPUT/ERROR OUT

This command selects display OUT as the current input and error display. This causes debugger input, debugger output (assuming OUT is the current output display), and debugger diagnostic messages to be logged in the OUT display in the correct sequence.

#3 

DBG> SELECT/SOURCE

This command unselects (deletes the source attribute from) the currently selected source display. The output of a TYPE or EXAMINE/SOURCE command then goes to the currently selected output display.

SET ABORT_KEY

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 DECwindows Motif 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:

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:

SET ATSIGN

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:

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].

SET BREAK

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:

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.

On VAX systems, CALLS and CALLG routines start with an entry mask.

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

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). 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 DECthreads 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:

On Alpha processors, 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-defined handlers.

On Alpha systems, many RTLs establish a jacket RTL handler on a frame where the user program has defined its own handler. This RTL jacket does some setup and argument manipulation before actually calling the handler defined by the user. When processing the exception, the debugger sets the breakpoint on the jacket RTL jacket handler, because that is the address on the call stack. If the debugger suspends program execution at a jacket RTL handler, you can usually reach the user-defined handler by entering a STEP/CALL command followed by a STEP/INTO command. Some cases might require that you enter additional sequences of STEP/CALL and STEP/INTO commands. 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. In this case, activate the RTL as a private image by defining the RTL as a logical name. For example: 


  $DEFINE LIBOTS SYS$SHARE:LIBOTS.EXE;

Note that the trailing semicolon (;) is required.

/INSTRUCTION

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

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

On VAX processors only, you can optionally specify one or more opcodes. This causes the debugger to break on every instruction with an opcode that is on the list.

If you specify a vector instruction (VAX only), do not include an instruction qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION, /MODIFY, /0, or /1) with the instruction mnemonic.

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):

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.

/JSB

/NOJSB

(VAX only) Qualifies /INTO. Use with /INTO and one of the following qualifiers:

The /JSB qualifier is the default for all languages except DIBOL. It lets the debugger break within routines that are called by the JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default) specifies that breakpoints not be set within routines called by JSB instructions. In DIBOL, application-declared routines are called by the CALL instruction and DIBOL Run-Time Library routines are called by the JSB instruction.

/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):

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.

On VAX processors, this qualifier can only be applied to routines called with a CALLS or CALLG instruction; it cannot be used with JSB routines. On Alpha processors, this qualifier can be applied to any routine.

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:

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:

Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4538PRO_051.HTML