OpenVMS Debugger Manual

If you start the debugger with the RUN/DEBUG command, and you are not running another process in a multiprocess configuration, and you issue the DISCONNECT command as follows, you will terminate the debugger main process:

$    RUN/DEBUG image_name
... 
DBG> DISCONNECT image_name_process

To retain the debugger main process, start the debugger and issue the DISCONNECT command as show below:

$    DEBUG/KEEP
... 
DBG> DISCONNECT image_name

Caution
The debugger kernel runs in the same process as the image being debugged. If you issue the DISCONNECT command for this process, you release your process, but the kernel remains activated.
This activation continues until the program image finishes running.
If you install a new version of the debugger while one or more disconnected but activated kernels inhabit user program space, you can experience problems with debugger installation and behavior.

Related commands:

EXIT
QUIT
CONNECT

Example

DBG> DISCONNECT JONES

This command releases process JONES from debugger control without terminating the process.

DISPLAY

Creates a new screen display or modifies an existing display.

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

Format

DISPLAY display-name [AT window-spec] [display-kind] [,...]

PARAMETERS

display-name
Specifies the display to be created or modified.
If you are creating a new display, specify a name that is not already used as a display name.
If you are modifying an existing display, you can specify any of the following entities:

A predefined display:

SRC
OUT
PROMPT
INST
REG
FREG (Alpha only)
IREG

A display previously created with the DISPLAY command
A display built-in symbol:

%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE

You must specify a display unless you use /GENERATE (parameter optional), or /REFRESH (parameter not allowed).
You can specify more than one display, each with an optional window specification and display kind.
window-spec
Specifies the screen window at which the display is to be positioned. You can specify any of the following entities:

A predefined window. For example, RH1 (right top half).
A window definition previously established with the SET WINDOW command.
A window specification of the form (start-line, line-count[, start-column, column-count]). The specification can include expressions which can be based on the built-in symbols %PAGE and %WIDTH (for example, %WIDTH/4).

If you omit the window specification, the screen position depends on whether you are specifying an existing display or a new display:

If you are specifying an existing display, the position of the display is not changed.
If you are specifying a new display, it is positioned at window H1 or H2, alternating between H1 and H2 each time you create another display.

display-kind
Specifies the display kind. Valid keywords are as follows:

DO ( command[;...]) Specifies an automatically updated output display. The commands are executed in the order listed each time the debugger gains control. Their output forms the contents of the display. If you specify more than one command, the commands must be separated by semicolons.

INSTRUCTION Specifies an instruction display. If selected as the current instruction display with the SELECT/INSTRUCTION command, it displays the output from subsequent EXAMINE/INSTRUCTION commands.

INSTRUCTION ( command) Specifies an automatically updated instruction display. The command specified must be an EXAMINE/INSTRUCTION command. The instruction display is updated each time the debugger gains control.

OUTPUT Specifies an output display. If selected as the current output display with the SELECT/OUTPUT command, it displays any debugger output that is not directed to another display. If selected as the current input display with the SELECT/INPUT command, it echoes debugger input. If selected as the current error display with the SELECT/ERROR command, it displays debugger diagnostic messages.

REGISTER (VAX only) Specifies an automatically updated register display. The display is updated each time the debugger gains control.

SOURCE Specifies a source display. If selected as the current source display with the SELECT/SOURCE command, it displays the output from subsequent TYPE or EXAMINE/SOURCE commands.

SOURCE ( command) Specifies an automatically updated source display. The command specified must be a TYPE or EXAMINE/SOURCE command. The source display is updated each time the debugger gains control.

You cannot change the display kind of the PROMPT display.
If you omit the display-kind parameter, the display kind depends on whether you are specifying an existing display or a new display:

If you specify an existing display, the display kind is not changed.
If you specify a new display, an OUTPUT display is created.

QUALIFIERS

/CLEAR
Erases the entire contents of a specified display. Do not use this qualifier with /GENERATE or when creating a new display.
/DYNAMIC (default)

/NODYNAMIC
Controls whether a display automatically adjusts its window dimensions proportionally when the screen height or width is changed by a SET TERMINAL command. By default (/DYNAMIC), all user-defined and predefined displays adjust their dimensions automatically.
/GENERATE
Regenerates the contents of a specified display. Only automatically generated displays are regenerated. These include DO displays, register displays, source (cmd-list) displays, and instruction (cmd-list) displays. The debugger automatically regenerates all these kinds of displays before each prompt. If you do not specify a display, it regenerates the contents of all automatically generated displays. Do not use this qualifier with /CLEAR or when creating a new display.
/HIDE
Places a specified display at the bottom of the display pasteboard (same as /PUSH). This hides the specified display behind any other displays that share the same region of the screen. You cannot hide the PROMPT display.
/MARK_CHANGE

/NOMARK_CHANGE (default)
Controls whether the lines that change in a DO display each time it is automatically updated are marked. Not applicable to other kinds of displays.
When you use /MARK_CHANGE, any lines in which some contents have changed since the last time the display was updated are highlighted in reverse video. This qualifier is particularly useful when you want any variables in an automatically updated display to be highlighted when they change.
The /NOMARK_CHANGE qualifier (default) specifies that any lines that change in DO displays are not to be marked. This qualifier cancels the effect of a previous /MARK_CHANGE on the specified display.
/POP (default)

/NOPOP
Controls whether a specified display is placed at the top of the display pasteboard, ahead of any other displays but behind the PROMPT display. By default (/POP), the display is placed at the top of the pasteboard and hides any other displays that share the same region of the screen, except the PROMPT display.
The /NOPOP qualifier preserves the order of all displays on the pasteboard (same as /NOPUSH).
/PROCESS[=(process-spec)]

/NOPROCESS (default)
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Controls whether the specified display is process specific (that is, whether the specified display is associated only with a particular process). The contents of a process-specific display are generated and modified in the context of that process. You can make any display process specific, except the PROMPT display.
The /PROCESS=(process-spec) qualifier causes the specified display to be associated with the specified process. You must include the parentheses. Use any of the following process-spec forms:

[%PROCESS_NAME] proc-name The process name, if that name contains no space or lowercase characters. The process name can include the asterisk (*) wildcard character.

[%PROCESS_NAME] " proc-name" The process name, if that name contains space or lowercase characters. You can also use apostrophes (') instead of quotation marks (").

%PROCESS_PID proc-id The process identifier (PID, a hexadecimal number).

%PROCESS_NUMBER proc-number
(or %PROC proc-number) The number assigned to a process when it comes under debugger control. Process numbers appear in a SHOW PROCESS display.

proc-group-name A symbol defined with the DEFINE/PROCESS_GROUP command to represent a group of processes. Do not specify a recursive symbol definition.

%NEXT_PROCESS The process after the visible process in the debugger's circular process list.

%PREVIOUS_PROCESS The process previous to the visible process in the debugger's circular process list.

%VISIBLE_PROCESS The process whose call stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.

The /PROCESS qualifier causes the specified display to be associated with the process that was the visible process when the DISPLAY/PROCESS command was executed.
The /NOPROCESS qualifier (which is the default) causes the specified display to be associated with the visible process, which might change during program execution.
If you do not specify /PROCESS, the current process-specific behavior (if any) of the specified display remains unchanged.
For more information, see the /SUFFIX qualifier.
/PUSH

/NOPUSH
The /PUSH qualifier has the same effect as /HIDE. The /NOPUSH qualifier preserves the order of all displays on the pasteboard (same as /NOPOP).
/REFRESH
Refreshes the terminal screen. Do not specify any command parameters with this qualifier. You can also use Ctrl/W to refresh the screen.
/REMOVE
Marks the display as being removed from the display pasteboard, so it is not shown on the screen unless you explicitly request it with another DISPLAY command. Although a removed display is not visible on the screen, it still exists and its contents are preserved. You cannot remove the PROMPT display.
/SIZE:n
Sets the maximum size of a display to n lines. If more than n lines are written to the display, the oldest lines are lost as the new lines are added. If you omit this qualifier, the maximum size of the display is as follows:

If you specify an existing display, the maximum size is unchanged.
If you are creating a display, the default size is 64 lines.

For an output or DO display, /SIZE:n specifies that the display should hold the n most recent lines of output. For a source or instruction display, n gives the number of source lines or lines of instructions that can be placed in the memory buffer at any one time. However, you can scroll a source display over the entire source code of the module whose code is displayed (source lines are paged into the buffer as needed). Similarly, you can scroll an instruction display over all of the instructions of the routine whose instructions are displayed (instructions are decoded from the image as needed).
/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). See also the /[NO]PROCESS qualifier.

DESCRIPTION

You can use the DISPLAY command to create a display or to modify an existing display.
To create a display, specify a name that is not already used as a display name (the SHOW DISPLAY command identifies all existing displays).
By default, the DISPLAY command places a specified display on top of the display pasteboard, ahead of any other displays but behind the PROMPT display, which cannot be hidden. The specified display thus hides the portions of other displays (except the PROMPT display) that share the same region of the screen.
For a list of the key definitions associated with the DISPLAY command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions.
Related commands:

Ctrl/W
EXPAND
MOVE
SET PROMPT
(SET,SHOW) TERMINAL
(SET,SHOW,CANCEL) WINDOW
SELECT
(SHOW,CANCEL) DISPLAY

Examples

DBG> DISPLAY REG

This command shows the predefined register display, REG, at its current window location.

DBG> DISPLAY/PUSH INST

This command pushes display INST to the bottom of the display pasteboard, behind all other displays.

DBG> DISPLAY NEWDISP AT RT2
DBG> SELECT/INPUT NEWDISP

In this example, the DISPLAY command shows the user-defined display NEWDISP at the right middle third of the screen. The SELECT/INPUT command selects NEWDISP as the current input display. NEWDISP now echoes debugger input.

DBG> DISPLAY DISP2 AT RS45
DBG> SELECT/OUTPUT DISP2

In this example, the DISPLAY command creates a display named DISP2 essentially at the right bottom half of the screen, above the PROMPT display, which is located at S6. This is an output display by default. The SELECT/OUTPUT command then selects DISP2 as the current output display.

DBG> SET WINDOW TOP AT (1,8,45,30)
DBG> DISPLAY NEWINST AT TOP INSTRUCTION
DBG> SELECT/INST NEWINST

In this example, the SET WINDOW command creates a window named TOP starting at line 1 and column 45, and extending down for 8 lines and to the right for 30 columns. The DISPLAY command creates an instruction display named NEWINST to be displayed through TOP. The SELECT/INST command selects NEWINST as the current instruction display.

DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS)

This command creates a DO display named CALLS at window Q3. Each time the debugger gains control from the program, the SHOW CALLS command is executed and the output is displayed in display CALLS, replacing any previous contents.

DBG> DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C)

This command creates a DO display named EXAM at window Q2. The display shows the current values of variables A, B, and C whenever the debugger prompts for input. Any changed values are highlighted.

DBG_3> DISPLAY/PROCESS OUT_X AT S4

This command makes display OUT_X specific to the visible process (process 3) and puts the display at window S4.

DBG_2> DISPLAY/PROCESS OUT_/SUFFIX AT S45 OUTPUT

This command creates an output display at window S45. By default, /PROCESS makes the display specific to the visible process (process 2, in this example). The /SUFFIX qualifier appends a process-identifying suffix, that denotes the visible process, to the display name OUT_. By default, the /SUFFIX qualifier appends the same process identifier suffix that appears on the prompt. Therefore, the full display name is OUT_2.

DO

Executes a debugger command in the context of one or more processes.
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS).

Format

DO (command[;...])

PARAMETERS

command
Specifies a debugger command that is to be executed in the context of the processes specified.

QUALIFIERS

/PROCESS=(process-spec[,...])
Specifies one or more processes in whose context the commands are executed. You must include the parentheses even if you specify only one process. If you do not specify /PROCESS, the commands are executed in the context of all processes (this effect is also achieved if you specify the asterisk (*) wildcard character for process-spec).
Use any of the following forms:

[%PROCESS_NAME] proc-name The process name, if that name contains no space or lowercase characters. The process name can include the asterisk (*) wildcard character.

[%PROCESS_NAME] " proc-name" The process name, if that name contains space or lowercase characters. You can also use apostrophes (') instead of quotation marks (").

%PROCESS_PID proc-id The process identifier (PID, a hexadecimal number).

%PROCESS_NUMBER proc-number
(or %PROC proc-number) The number assigned to a process when it comes under debugger control. Process numbers appear in a SHOW PROCESS display.

proc-group-name A symbol defined with the DEFINE/PROCESS_GROUP command to represent a group of processes. Do not specify a recursive symbol definition.

%NEXT_PROCESS The process after the visible process in the debugger's circular process list.

%PREVIOUS_PROCESS The process previous to the visible process in the debugger's circular process list.

%VISIBLE_PROCESS The process whose call stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.

DESCRIPTION

By default, commands are executed in the context of the visible process. The DO command enables you to execute commands in the context of one or more processes that are currently under debugger control (this is also referred to as "broadcasting" commands to processes). The DO command is equivalent to entering a SET PROCESS/VISIBLE command for each process specified with the /PROCESS qualifier (or for all processes, if /PROCESS is not specified) and then entering the specified commands.
To change the visible process, use the SET PROCESS command.
When using the DO command, note that a hold condition in the visible process (as established with the SET PROCESS/HOLD command) is ignored.
Related command: SET PROCESS.

Examples

DBG_2> DO (SHOW CALLS)
For %PROCESS_NUMBER 1 
   module name   routine name  line     rel PC    abs PC 
  *MOD4          SUB3            31    0000001E  0000041E 
For %PROCESS_NUMBER 2 
   module name   routine name  line     rel PC    abs PC 
  *MOD3          SUB1             4    0000000B  0000040B
DBG_2>

This command executes a SHOW CALLS command in the context of all processes that are currently under debugger control.

DBG_3> DO/PROCESS=(%PROC 2,%PROC 1) (EVAL/ADDR X;EXAMINE X)
For %PROCESS_NUMBER 2 
  %DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table 
For %Process_number 1 
  512 
  TEST\X: 1
DBG_3>

This command executes the two commands EVAL/ADDR X and EXAMINE X in the context of processes 2 and 1.

DUMP

Displays the contents of memory.

Format

DUMP address-expression1 [:address-expression2]

PARAMETERS

address-expression1
Specifies the first memory location to be displayed.
address-expression2
Specifies the last memory location to be displayed (default is address-expression1).

QUALIFIERS

/BINARY
Displays each examined entity as a binary integer.
/BYTE
Displays each examined entity as a byte integer (length 1 byte).
/DECIMAL
Displays each examined entity as a decimal integer.
/HEXADECIMAL
Displays each examined entity as a hexadecimal integer.
/LONGWORD (default)
Displays each examined entity in the longword integer type (length 4 bytes). This is the default type for program locations that do not have a compiler-generated type.
/OCTAL
Displays each examined entity as an octal integer.
/QUADWORD
Displays each examined entity in the quadword integer type (length 8 bytes).
/WORD
Displays each examined entity in the word integer type (length 2 bytes).

DESCRIPTION

The DUMP command displays the contents of memory, including registers, variables, and arrays. The DUMP command formats its output im a manner similar to the DCL command DUMP. The debugger DUMP command makes no attempt to interpret the structure of aggregates.
In general, when you enter a DUMP command, the debugger evaluates address-expression1 to yield a program location. The debugger then displays the entity stored at that location as follows:

If the entity has a symbolic name, the debugger uses the size of the entity to determine the address range to display.
If the entity does not have a symbolic name (and, therefore, no associated compiler-generated type) the debugger displays address-expression1 through address-expression2 (if specified).

In either case, the DUMP command displays the contents of these locations as longword (by default) integer values in the current radix.
The default radix for display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO--32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO--32, and MACRO--64, which have a default radix of hexadecimal.
Use one of the four radix qualifiers (/BINARY, /DECIMAL, /HEXADECIMAL, /OCTAL) to display data in another radix. You can also use the SET RADIX and SET RADIX/OVERRIDE commands to change the default radix.
Use one of the size qualifiers (/BYTE, /WORD, /LONGWORD, /QUADWORD) to change the format of the display.
The DUMP command sets the current entity built-in symbols %CURLOC and period (.) to the location denoted by the address expression specified. Logical predecessors (%PREVLOC or the circumflex character (^)) and successors (%NEXTLOC) are based on the value of the current entity.
Related commands:

EXAMINE

Examples

DBG> DUMP/QUAD R16:R25
 0000000000000078 0000000000030038 8.......x....... %R16 
 000000202020786B 0000000000030041 A.......kx   ... %R18 
 0000000000030140 0000000000007800 .x......@....... %R20 
 0000000000010038 0000000000000007 ........8....... %R22 
 0000000000000006 0000000000000000 ................ %R24 
 
DBG>

This command displays general registers R16 through R25 in quadword format and hexadecimal radix.

DBG> DUMP APPLES
 00000000 00030048 00000000 00004220  B......H....... 00000000000300B0 
 63724F20 746E6F6D 646F6F57 000041B0 �A..Woodmont Orc 00000000000300C0 
 20202020 20202020 20202073 64726168 hards            00000000000300D0 
 6166202C 73646E61 6C747275 6F432020   Courtlands, fa 00000000000300E0 
                   00002020 2079636E ncy   ..         00000000000300F0 
 
DBG>

This command displays an entity named APPLES in longword format and hexadecimal radix.

DBG> DUMP/BYTE/DECIMAL 30000:30040
    0    0    0    0    0    3    0  -80 �....... 0000000000030000 
    0    0    0    0    0    3    1   64 @....... 0000000000030008 
    0    0    0    0    0    3    0   48 0....... 0000000000030010 
    0    0    0    0    0    3    0   56 8....... 0000000000030018 
    0    0    0    0    0    3    0  -64 �....... 0000000000030020 
    0    0    0    0    0    3    0  -80 �....... 0000000000030028 
    0    0    0    0    0    0    7  -50 �....... 0000000000030030 
  101  101  119   32  116  120  101  110 next wee 0000000000030038 
                                     107 k        0000000000030040 
DBG>

This command displays locations 30000 through 30040 in byte format and decimal radix.

EDIT

Starts the editor established with the SET EDITOR command. If you did not enter a SET EDITOR command, starts the DEC Language-Sensitive Editor (LSEDIT), if that editor is installed on your system.

Format

EDIT [[module-name\] line-number]

PARAMETERS

module-name
Specifies the name of the module whose source file is to be edited. If you specify a module name, you must also specify a line number. If you omit the module name parameter, the source file whose code appears in the current source display is chosen for editing.
line-number
A positive integer that specifies the source line on which the editor's cursor is initially placed. If you omit this parameter, the cursor is initially positioned at the beginning of the source line that is centered in the debugger's current source display, or at the beginning of line 1 if the editor was set to /NOSTART_POSITION (see the SET EDITOR command.)

QUALIFIERS

/EXIT

/NOEXIT (default)
Controls whether you end the debugging session prior to starting the editor. If you specify /EXIT, the debugging session is terminated and the editor is then started. If you specify /NOEXIT, the editing session is started and you return to your debugging session after terminating the editing session.

DESCRIPTION

If you have not specified an editor with the SET EDITOR command, the EDIT command starts the DEC Language-Sensitive Editor (LSEDIT) in a spawned subprocess (if LSEDIT is installed on your system). The typical (default) way to use the EDIT command is not to specify any parameters. In this case, the editing cursor is initially positioned at the beginning of the line that is centered in the currently selected debugger source display (the current source display).

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4538P035.HTM
  OSSG Documentation
  22-NOV-1996 13:02:25.28
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

DO ( command[;...])	Specifies an automatically updated output display. The commands are executed in the order listed each time the debugger gains control. Their output forms the contents of the display. If you specify more than one command, the commands must be separated by semicolons.
INSTRUCTION	Specifies an instruction display. If selected as the current instruction display with the SELECT/INSTRUCTION command, it displays the output from subsequent EXAMINE/INSTRUCTION commands.
INSTRUCTION ( command)	Specifies an automatically updated instruction display. The command specified must be an EXAMINE/INSTRUCTION command. The instruction display is updated each time the debugger gains control.
OUTPUT	Specifies an output display. If selected as the current output display with the SELECT/OUTPUT command, it displays any debugger output that is not directed to another display. If selected as the current input display with the SELECT/INPUT command, it echoes debugger input. If selected as the current error display with the SELECT/ERROR command, it displays debugger diagnostic messages.
REGISTER	(VAX only) Specifies an automatically updated register display. The display is updated each time the debugger gains control.
SOURCE	Specifies a source display. If selected as the current source display with the SELECT/SOURCE command, it displays the output from subsequent TYPE or EXAMINE/SOURCE commands.
SOURCE ( command)	Specifies an automatically updated source display. The command specified must be a TYPE or EXAMINE/SOURCE command. The source display is updated each time the debugger gains control.

[%PROCESS_NAME] proc-name	The process name, if that name contains no space or lowercase characters. The process name can include the asterisk (*) wildcard character.
[%PROCESS_NAME] " proc-name"	The process name, if that name contains space or lowercase characters. You can also use apostrophes (') instead of quotation marks (").
%PROCESS_PID proc-id	The process identifier (PID, a hexadecimal number).
%PROCESS_NUMBER proc-number (or %PROC proc-number)	The number assigned to a process when it comes under debugger control. Process numbers appear in a SHOW PROCESS display.
proc-group-name	A symbol defined with the DEFINE/PROCESS_GROUP command to represent a group of processes. Do not specify a recursive symbol definition.
%NEXT_PROCESS	The process after the visible process in the debugger's circular process list.
%PREVIOUS_PROCESS	The process previous to the visible process in the debugger's circular process list.
%VISIBLE_PROCESS	The process whose call stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.

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