OpenVMS Debugger Manual

Document revision date: 19 July 1999

OpenVMS Debugger Manual

Contents

Index

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.

#6

DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS)

#6
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.

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

#8
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.

#9
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

#1
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>

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.

#2
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

#1
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>

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.

#2
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>

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.

#3
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>

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).
The SET EDITOR command provides options for starting different editors, either in a subprocess or through a callable interface.
Related commands:

(SET,SHOW) EDITOR
(SET,SHOW,CANCEL) SOURCE

Examples

#1
DBG> EDIT

This command spawns the DEC Language-Sensitive Editor (LSEDIT) in a subprocess to edit the source file whose code appears in the current source display. The editing cursor is positioned at the beginning of the line that was centered in the source display.

#2
DBG> EDIT SWAP\12

This command spawns the DEC Language-Sensitive Editor (LSEDIT) in a subprocess to edit the source file containing the module SWAP. The editing cursor is positioned at the beginning of source line 12.

#3
DBG> SET EDITOR/CALLABLE_EDT DBG> EDIT

In this example, the SET EDITOR/CALLABLE_EDT command establishes that EDT is the default editor and is started through its callable interface (rather than spawned in a subprocess). The EDIT command starts EDT to edit the source file whose code appears in the current source display. The editing cursor is positioned at the beginning of source line 1, because the default qualifier /NOSTART_POSITION applies to EDT.

ENABLE AST

Enables the delivery of asynchronous system traps (ASTs) in your program.

Format

ENABLE AST

Description

The ENABLE AST command enables the delivery of ASTs while your program is running, including any pending ASTs (ASTs waiting to be delivered). If ASTs are delivered while the debugger is running (processing commands, and so on), they are queued and are delivered when control is returned to the program. Delivery of ASTs in your program is initially enabled by default.

Note
Any call by your program to the $SETAST system service that disables ASTs overrides a previous ENABLE AST command.

Related commands:

(DISABLE,SHOW) AST

Example


DBG> ENABLE AST DBG> SHOW AST ASTs are enabled DBG>

The ENABLE AST command enables the delivery of ASTs in your program, as confirmed with the SHOW AST command.

EVALUATE

Displays the value of a language expression in the current language (by default, the language of the module containing the main program).

Format

EVALUATE language-expression[,...]

Parameters

language-expression
Specifies any valid expression in the current language.

Qualifiers

/BINARY
Specifies that the result be displayed in binary radix.
/CONDITION_VALUE
Specifies that the expression be interpreted as a condition value (the kind of condition value you would specify using the condition-handling mechanism). The message text corresponding to that condition value is then displayed. The specified value must be an integer value.
/DECIMAL
Specifies that the result be displayed in decimal radix.
/HEXADECIMAL
Specifies that the result be displayed in hexadecimal radix.
/OCTAL
Specifies that the result be displayed in octal radix.

Description

The debugger interprets the expression specified in an EVALUATE command as a language expression, evaluates it in the syntax of the current language and in the current radix, and displays its value as a literal (for example, an integer value) in the current language.
The current language is the language last established with the SET LANGUAGE command. If you did not enter a SET LANGUAGE command, the current language is, by default, the language of the module containing the main program.
If an expression contains symbols with different compiler-generated types, the debugger uses the type-conversion rules of the current language to evaluate the expression.
The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The current radix is the radix last established with the SET RADIX command.
If you did not enter a SET RADIX command, the default radix for both data entry and 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.
You can use a radix qualifier (/BINARY, /OCTAL, and so on) to display integer data in another radix. These qualifiers do not affect how the debugger interprets the data you specify; they override the current output radix, but not the input radix.
The EVALUATE command sets the current value of built-in symbols %CURVAL and backslash (\) to the value denoted by the specified expression.
You cannot evaluate a language expression that includes a function call. For example, if PRODUCT is a function that multiplies two integers, you cannot use the command EVALUATE PRODUCT(3,5). If your program assigns the returned value of a function to a variable, you can examine the resulting value of that variable. On Alpha processors, the command EVALUATE procedure-name displays the procedure descriptor address (not the code address) of a specified routine, entry point, or Ada package.
For more information about debugger support for language-specific operators and constructs, type HELP Language.
Related commands:

EVALUATE/ADDRESS
MONITOR
(SET,SHOW) LANGUAGE
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE

Examples

#1
DBG> EVALUATE 100.34 * (14.2 + 7.9) 2217.514 DBG>

This command uses the debugger as a calculator by multiplying 100.34 by (14.2 + 7.9).

#2
DBG> EVALUATE/OCTAL X 00000001512 DBG>

This command evaluates the symbol X and displays the result in octal radix.

#3
DBG> EVALUATE TOTAL + CURR_AMOUNT 8247.20 DBG>

This command evaluates the sum of the values of two real variables, TOTAL and CURR_AMOUNT.

#4
DBG> DEPOSIT WILLING = TRUE DBG> DEPOSIT ABLE = FALSE DBG> EVALUATE WILLING AND ABLE False DBG>

In this example, the EVALUATE command evaluates the logical AND of the current values of two Boolean variables, WILLING and ABLE.

#5
DBG> EVALUATE COLOR'FIRST RED DBG>

In this Ada example, this command evaluates the first element of the enumeration type COLOR.

EVALUATE/ADDRESS

Evaluates an address expression and displays the result as a memory address or a register name.

Format

EVALUATE/ADDRESS address-expression[,...]

Parameters

address-expression
Specifies an address expression of any valid form (for example, a routine name, variable name, label, line number, and so on).

Qualifiers

/BINARY
Displays the memory address in binary radix.
/DECIMAL
Displays the memory address in decimal radix.
/HEXADECIMAL
Displays the memory address in hexadecimal radix.
/OCTAL
Displays the memory address in octal radix.

Description

The EVALUATE/ADDRESS command enables you to determine the memory address or register associated with an address expression.
The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal. The default radix for both data entry and 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.
You can use a radix qualifier (/BINARY, /OCTAL, and so on) to display address values in another radix. These qualifiers do not affect how the debugger interprets the data you specify; that is, they override the current output radix, but not the input radix.
If the value of a variable is currently stored in a register instead of memory, the EVALUATE/ADDRESS command identifies the register. The radix qualifiers have no effect in that case.
The EVALUATE/ADDRESS 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.
On Alpha processors, the command EVALUATE/ADDRESS procedure-name displays the procedure descriptor address (not the code address) of a specified routine, entry point, or Ada package.
Related commands:

EVALUATE
(SET,SHOW,CANCEL) RADIX
SHOW SYMBOL/ADDRESS
SYMBOLIZE

Examples

#1
DBG> EVALUATE/ADDRESS MODNAME\%LINE 110 3942 DBG>

This command displays the memory address denoted by the address expression MODNAME\%LINE 110.

#2
DBG> EVALUATE/ADDRESS/HEX A,B,C 000004A4 000004AC 000004A0 DBG>

This command displays the memory addresses denoted by the address expressions A, B, and C in hexadecimal radix.

#3
DBG> EVALUATE/ADDRESS X MOD3\%R1 DBG>

This command indicates that variable X is associated with register R1. X is a nonstatic (register) variable.

Contents

Index

privacy and legal statement

4538PRO_046.HTML

[%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.