 |
OpenVMS Debugger Manual
This command puts the debugger in screen mode.
SET MODULE
Loads the symbol records of a module in the current image into the
run-time symbol table (RST) of that image.
Note
The current image is either the main image (by default) or the image
established as the current image by a previous SET IMAGE command.
|
Format
SET MODULE [module-name[,...]]
Parameters
module-name
Specifies a module of the current image whose symbol records are loaded
into the RST. Do not use the asterisk (*) wildcard character. Instead,
use the /ALL qualifier. Do not specify a module name with /ALL or
/CALLS.
Qualifiers
/ALL
Specifies that the symbol records of all modules in the current image
be loaded into the RST.
/CALLS
Sets all the modules that currently have routines on the call stack. If
a module is already set, /CALLS has no effect on that module.
/RELATED (default)
/NORELATED
(Applies to Ada programs.) Controls whether the debugger loads into the
RST the symbol records of a module that is related to a specified
module through a with-clause or subunit relationship. Once loaded, you
can reference names declared in related modules within debugger
commands exactly as you reference them within the Ada source code.
Description
Symbol records must be present in the RST if the debugger is to
recognize and properly interpret the symbols declared in your program.
The process by which the symbol records of a module are loaded into the
RST is called setting a module.
At debugger startup, the debugger sets the module containing the
transfer address (the main program). By default, dynamic mode is
enabled (SET MODE DYNAMIC). Therefore, the debugger sets modules (and
images) automatically as the program executes so that you can reference
symbols as you need them. Specifically, whenever execution is
suspended, the debugger sets the module and image containing the
routine in which execution is suspended. In the case of Ada programs,
as a module is set dynamically, its related modules are also set
automatically, by default, to make the appropriate symbols accessible
(visible).
Dynamic mode makes accessible most of the symbols you might need to
reference. If you need to reference a symbol in a module that is not
already set, proceed as follows:
- If the module is in the current image, use the SET MODULE command
to set the module where the symbol is defined.
- If the module is in another image, use the SET IMAGE command to
make that image the current image, then use the SET MODULE command to
set the module where the symbol is defined.
If dynamic mode is disabled (SET MODE NODYNAMIC), only the module
containing the transfer address is set automatically. You must set any
other modules explicitly.
If you use the SET IMAGE command to establish a new current image, all
modules previously set remain set. However, only the symbols in the set
modules of the current image are accessible. Symbols in the set modules
of other images are temporarily inaccessible.
When dynamic mode is enabled, memory is allocated automatically to
accommodate the increasing size of the RST. If dynamic mode is
disabled, the debugger automatically allocates more memory as needed
when you set a module or an image. Whether dynamic mode is enabled or
disabled, if performance becomes a problem as more modules are set, use
the CANCEL MODULE command to reduce the number of set modules.
If a parameter in a SET SCOPE command designates a program location in
a module that is not already set, the SET SCOPE command sets that
module.
For information specific to Ada programs, type Help Language_Support
Ada.
Related commands:
(SET,SHOW,CANCEL) IMAGE
SET MODE [NO]DYNAMIC
(SHOW,CANCEL) MODULE
Examples
This command sets module SUB1 (loads the symbol records of module SUB1
into the RST).
| #2 |
DBG> SET IMAGE SHARE3
DBG> SET MODULE MATH
DBG> SET BREAK %LINE 31
|
In this example, the SET IMAGE command makes shareable image SHARE3 the
current image. The SET MODULE command sets module MATH in image SHARE3.
The SET BREAK command sets a breakpoint on line 31 of module MATH.
| #3 |
DBG> SHOW MODULE/SHARE
module name symbols language size
FOO yes MACRO 432
MAIN no FORTRAN 280
...
SHARE$DEBUG no Image 0
SHARE$LIBRTL no Image 0
SHARE$MTHRTL no Image 0
SHARE$SHARE1 no Image 0
SHARE$SHARE2 no Image 0
total modules: 17. bytes allocated: 162280.
DBG> SET MODULE SHARE$SHARE2
DBG> SHOW SYMBOL * IN SHARE$SHARE2
|
In this example, the SHOW MODULE/SHARE command identifies all modules
in the current image and all shareable images (the names of the
shareable images are prefixed with SHARE$). The SET MODULE SHARE$SHARE2
command sets the shareable image module SHARE$SHARE2. The SHOW SYMBOL
command identifies any universal symbols defined in the shareable image
SHARE2. For more information, see the SHOW MODULE/SHARE command.
SET OUTPUT
Enables or disables a debugger output option.
Format
SET OUTPUT output-option[,...]
Parameters
output-option
Specifies an output option to be enabled or disabled. Valid keywords
are as follows:
|
LOG
|
Specifies that debugger input and output be recorded in a log file. If
you specify the log file by the SET LOG command, the debugger writes to
that file; otherwise, by default the debugger writes to
SYS$DISK[]:DEBUG.LOG.
|
|
NOLOG
|
(Default) Specifies that debugger input and output not be recorded in a
log file.
|
|
SCREEN_LOG
|
Specifies that, while in screen mode, the screen contents be recorded
in a log file as the screen is updated. To log the screen contents, you
must also specify SET OUTPUT LOG. See the description of the LOG option
regarding specifying the log file.
|
|
NOSCREEN_LOG
|
(Default) Specifies that the screen contents, while in screen mode, not
be recorded in a log file.
|
|
TERMINAL
|
Note
This parameter is not available in the
Compaq DECwindows Motif for OpenVMS user interface to the debugger.
|
(Default) Specifies that debugger output be displayed at the
terminal.
|
|
NOTERMINAL
|
Note
This parameter is not available in the
Compaq DECwindows Motif for OpenVMS user interface to the debugger.
|
Specifies that debugger output, except diagnostic messages, not be
displayed at the terminal.
|
|
VERIFY
|
Specifies that the debugger echo, on the current output device, each
input command string that it is executing from a command procedure or
DO clause. The current output device is by default SYS$OUTPUT (your
terminal) but can be redefined with the logical name DBG$OUTPUT.
|
|
NOVERIFY
|
(Default) Specifies that the debugger not display each input command
string that it is executing from a command procedure or DO clause.
|
Description
Debugger output options control the way in which debugger responses to
commands are displayed and recorded. For details about the SET OUTPUT
command, see the parameter descriptions.
Related commands:
@ (Execute Procedure)
(SET,SHOW) ATSIGN
(SET,SHOW) LOG
SET MODE SCREEN
SHOW OUTPUT
Example
|
DBG> SET OUTPUT VERIFY,LOG,NOTERMINAL
|
This command specifies that the debugger take the following actions:
- Output each command string that it is executing from a command
procedure or DO clause (VERIFY)
- Record debugger output and user input in a log file (LOG)
- Not display output at the terminal, except diagnostic messages
(NOTERMINAL)
SET PROCESS
Establishes the visible process or enables/disables dynamic process
setting.
Used only when debugging multiprocess programs (kept debugger only).
Format
SET PROCESS [process-spec[,...]]
Parameters
process-spec
Specifies a process currently under debugger control. Use any of the
following forms:
|
[%PROCESS_NAME]
process-name
|
The process name, if that name does not contain spaces or lowercase
characters. The process name can include the asterisk (*) wildcard
character.
|
|
[%PROCESS_NAME] "
process-name"
|
The process name, if that name contains spaces or lowercase characters.
You can also use apostrophes (') instead of quotation marks (").
|
|
%PROCESS_PID
process_id
|
The process identifier (PID, a hexadecimal number).
|
[%PROCESS_NUMBER]
process-number
(or %PROC
process-number)
|
The number assigned to a process when it comes under debugger control.
A new number is assigned sequentially, starting with 1, to each
process. If a process is terminated with the EXIT or QUIT command, the
number can be assigned again during the debugging session. Process
numbers appear in a SHOW PROCESS display. Processes are ordered in a
circular list so they can be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
|
|
process-set-name
|
A symbol defined with the DEFINE/PROCESS_SET command to represent a
group of processes.
|
|
%NEXT_PROCESS
|
The next 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 stack, register set, and images are the current
context for looking up symbols, register values, routine calls,
breakpoints, and so on.
|
You can also use the asterisk (*) wildcard character to specify process
set all.
Do not specify a process with the /[NO]DYNAMIC qualifier.
Qualifiers
/DYNAMIC (default)
/NODYNAMIC
Controls whether dynamic process setting is enabled or disabled. When
dynamic process setting is enabled (/DYNAMIC), whenever the debugger
suspends execution and displays its prompt, the process in which
execution is suspended automatically becomes the visible process. When
dynamic process setting is disabled (/NODYNAMIC), the visible process
remains unchanged until you specify another process with the SET
PROCESS/VISIBLE command.
/VISIBLE
Makes the specified process the visible process. This switches your
debugging context to the specified process, so that symbol lookups and
the setting of breakpoints, and so on, are done in the context of that
process. When using /VISIBLE, you must specify one process.
Description
The SET PROCESS command establishes the visible process, defines the
current process set, or defines the visible process.
By default, commands are executed in the context of the visible process
(the process that is your current debugging context). Symbol lookups,
the setting of breakpoints, and so on, are done in the context of the
visible process.
Dynamic process setting is enabled by default and is controlled with
/[NO]DYNAMIC. When dynamic process setting is enabled, whenever the
debugger suspends program execution and displays its prompt, the
process in which execution is suspended becomes the visible process
automatically.
Related commands:
CALL
EXIT
GO
QUIT
SHOW PROCESS
STEP
Example
|
all> SET PROCESS TEST_Y
all> SHOW PROCESS
Number Name State Current PC
* 2 TEST_Y break PROG\%LINE 71
all>
|
The SET PROCESS TEST_Y command makes process TEST_Y the visible
process. The SHOW PROCESS command displays information about the
visible process by default.
SET PROMPT
Changes the debugger prompt string to your personal preference.
Format
SET PROMPT [prompt-parameter]
Parameters
prompt-parameter
Specifies the new prompt string. If the string contains spaces,
semicolons (;), or lowercase characters, you must enclose it in
quotation marks (") or apostrophes ('). If you do not specify a
string, the current prompt string remains unchanged.
By default, the prompt string is DBG> when debugging a single
process program.
By default, when debuggging a multiprocess program, the prompt string
is the name of the current process set followed by a right angle
bracket (>). You should not use the SET PROMPT command when
debugging multiprocess programs.
Qualifiers
/POP
/NOPOP (default)
(Applies only to workstations running VWS.) The /POP qualifier causes
the debugger window to pop over other windows and become attached to
the keyboard when the debugger prompts for input. The /NOPOP qualifier
disables this behavior (the debugger window is not popped over other
windows and is not attached to the keyboard automatically when the
debugger prompts for input).
Description
The SET PROMPT command enables you to tailor the debugger prompt string
to your individual preference.
If you are debugging a multiprocess program, you should not use the SET
PROMPT command.
If you are using the debugger at a workstation, /[NO]POP enables you to
control whether the debugger window is popped over other windows
whenever the debugger prompts for input.
Related commands:
(SET,SHOW) PROCESS
Examples
| #1 |
DBG> SET PROMPT "$ "
$ SET PROMPT "d b g : "
d b g : SET PROMPT "DBG> "
DBG>
|
In this example, the successive SET PROMPT commands change the debugger
prompt from "DBG>" to "$", to "d b g
:", then back to "DBG>".
SET RADIX
Establishes the radix for the entry and display of integer data. When
used with /OVERRIDE, it causes all data to be displayed as integer data
of the specified radix.
Format
SET RADIX radix
Parameters
radix
Specifies the radix to be established. Valid keywords are as follows:
|
BINARY
|
Sets the radix to binary.
|
|
DECIMAL
|
Sets the radix to decimal. This is the default for all languages except
BLISS, MACRO--32, and MACRO--64 (Alpha only).
|
|
DEFAULT
|
Sets the radix to the language default.
|
|
OCTAL
|
Sets the radix to octal.
|
|
HEXADECIMAL
|
Sets the default radix to hexadecimal. This is the default for BLISS,
MACRO--32, and MACRO--64 (Alpha only).
|
Qualifiers
/INPUT
Sets only the input radix (the radix for entering integer data) to the
specified radix.
/OUTPUT
Sets only the output radix (the radix for displaying integer data) to
the specified radix.
/OVERRIDE
Causes all data to be displayed as integer data of the specified radix.
Description
The current radix setting influences how the debugger interprets and
displays integer data in the following contexts:
- Integer data that you specify in address expressions or language
expressions.
- Integer data that is displayed by the EXAMINE and EVALUATE commands.
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.
The SET RADIX command enables you to specify a new radix for data entry
or display (the input radix and output radix, respectively).
If you do not specify a qualifier, the SET RADIX command changes both
the input and output radix. If you specify /INPUT or /OUTPUT, the
command changes the input or output radix, respectively.
Using SET RADIX/OVERRIDE changes only the output radix but causes
all data (not just data that has an integer type) to be
displayed as integer data of the specified radix.
Except when used with /OVERRIDE, the SET RADIX command does not affect
the interpretation or display of noninteger values (such as real or
enumeration type values).
The EVALUATE, EXAMINE, and DEPOSIT commands have radix qualifiers
(/BINARY, /HEXADECIMAL, and so on) which enable you to override, for
the duration of that command, any radix previously established with SET
RADIX or SET RADIX/OVERRIDE.
You can also use the built-in symbols %BIN, %DEC, %HEX, and %OCT in
address expressions and language expressions to specify that an integer
literal should be interpreted in binary, decimal, hexadecimal, or octal
radix.
Related commands:
DEPOSIT
EVALUATE
EXAMINE
(SET,SHOW,CANCEL) MODE
(SHOW,CANCEL) RADIX
Examples
This command sets the radix to hexadecimal. This means that, by
default, integer data is interpreted and displayed in hexadecimal radix.
| #2 |
DBG> SET RADIX/INPUT OCT
|
This command sets the radix for input to octal. This means that, by
default, integer data that is entered is interpreted in octal radix.
| #3 |
DBG> SET RADIX/OUTPUT BIN
|
This command sets the radix for output to binary. This means that, by
default, integer data is displayed in binary radix.
| #4 |
DBG> SET RADIX/OVERRIDE DECIMAL
|
This command sets the override radix to decimal. This means that, by
default, all data (not just data that has an integer type) is displayed
as decimal integer data.
SET SCOPE
Establishes how the debugger looks up symbols (variable names, routine
names, line numbers, and so on) when a path-name prefix is not
specified.
Format
SET SCOPE location[,...]
Parameters
location
Denotes a program region (scope) to be used for the interpretation of
symbols that you specify without a path-name prefix. A location can be
any of the following, unless you specify /CURRENT or /MODULE.
|
path-name prefix
|
Specifies the scope denoted by the path-name prefix. A path-name prefix
consists of the names of one or more nesting program elements (module,
routine, block, and so on), with each name separated by a backslash
character (\). When a path-name prefix consists of more than one name,
list a nesting element to the left of the backslash and a nested
element to the right of the backslash. A common path-name prefix format
is
module\routine\block\.
If you specify only a module name and that name is the same as the
name of a routine, use /MODULE; otherwise, the debugger assumes that
you are specifying the routine.
|
|
n
|
Specifies the scope denoted by the routine which is
n levels down the call stack (
n is a decimal integer). A scope specified by an integer
changes dynamically as the program executes. The value 0 denotes the
routine that is currently executing, the value 1 denotes the caller of
that routine, and so on down the call stack. The default scope search
list is 0,1,2,...,
n, where
n is the number of calls in the call stack.
|
|
\ (backslash)
|
Specifies the global scope---that is, the set of all program locations
in which a global symbol is known. The definition of a global symbol
and the way it is declared depends on the language.
|
When you specify more than one location parameter, you establish a
scope search list. If the debugger cannot interpret the symbol using
the first parameter, it uses the next parameter, and continues using
parameters in order of their specification until it successfully
interprets the symbol or until it exhausts the parameters specified.
Qualifiers
/CURRENT
Establishes a scope search list that is like the default search list
(0,1,2,...,n), numeric scope specified as the command
parameter. Scope 0 is the PC scope, and n is the number of
calls in the call stack.
When using SET SCOPE/CURRENT, note the following conventions and
behavior:
- The default scope search list must be in effect when the command is
entered. To restore the default scope search list, enter the CANCEL
SCOPE command.
- The command parameter specified must be one (and only one) decimal
integer from 0 to n.
- In screen mode, the command updates the predefined source,
instruction, and register displays SRC, INST, and REG, respectively, to
show the routine on the call stack in which symbol searches are to
start.
- The default scope search list is restored when program execution is
resumed.
/MODULE
Indicates that the name specified as the command parameter is a module
name and not a routine name. You need to use /MODULE only if you
specify a module name as the command parameter and that module name is
the same as the name of a routine.
Description
By default, the debugger looks up a symbol specified without a
path-name prefix according to the scope search list
0,1,2,...,n, where n is the number of calls in the
call stack. This scope search list is based on the current PC value and
changes dynamically as the program executes. The default scope search
list specifies that a symbol lookup such as EXAMINE X first looks for X
in the routine that is currently executing (scope 0, also known as the
PC scope); if no X is visible there, the debugger looks in the caller
of that routine (scope 1), and so on down the call stack; if X is not
found in scope n, the debugger searches the rest of the
run-time symbol table (RST)---that is, all set modules and the global
symbol table (GST), if necessary.
|
