OpenVMS Debugger Manual

Document revision date: 19 July 1999

OpenVMS Debugger Manual

Contents

Index

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

#1
DBG> SET MODULE SUB1

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

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 DECwindows Motif interface to the debugger.

(Default) Specifies that debugger output be displayed at the terminal.

NOTERMINAL

Note
This parameter is not available in the DECwindows Motif 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, changes characteristics of one or more processes, or enables/disables dynamic process setting.
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS).

Format

SET PROCESS [process-spec[,...]]

Parameters

process-spec
Specifies a process currently under debugger control. 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.

You can also use the asterisk (*) wildcard character or the /ALL qualifier to specify all processes. Do not specify a process with /ALL or /[NO]DYNAMIC. If you do not specify a process or /ALL with /[NO]HOLD, the visible process is selected.

Qualifiers

/ALL
Applies the SET PROCESS command to all processes.
/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 becomes the visible process automatically. When dynamic process setting is disabled (/NODYNAMIC), the visible process remains unchanged until you specify another process with the SET PROCESS/VISIBLE command.
/HOLD

/NOHOLD (default)
/HOLD puts a specified process on hold. This prevents images in that process from executing when you enter a GO, STEP, or CALL command, unless the process is the visible process. A hold condition in the visible process is ignored.
The /NOHOLD qualifier releases a specified process from a hold condition. This permits images in that process to execute when you enter a GO, STEP, or CALL command, regardless of which process is the visible process.
The behavior described also applies when you use the DO command to broadcast a GO, STEP, or CALL command to specific processes.
For information on the effects of these commands on processes that have or have not been put on hold, see the GO, STEP, CALL, EXIT, and QUIT commands.
/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 or changes characteristics of one or more processes.
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.
The DO command enables you to execute commands in the context of specific processes or of all processes. The DO command is equivalent to entering a SET PROCESS/VISIBLE command for each process specified (or all processes, if no process is specified with the DO command), followed by the specified commands.
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
DO
EXIT
GO
QUIT
SHOW PROCESS
STEP

Examples

#1
DBG_1> SET PROCESS/HOLD/ALL DBG_1> SHOW PROCESS/ALL Number Name Hold State Current PC * 1 TEST_X YES step PROG\%LINE 50 2 TEST_Y YES break PROG\%LINE 71 DBG_1>

The SET PROCESS/HOLD/ALL command puts all processes on hold. This is confirmed in the SHOW PROCESS/ALL display.

#2
DBG_1> SET PROCESS/NOHOLD %VISIBLE_PROCESS DBG_1> SHOW PROCESS/ALL Number Name Hold State Current PC * 1 TEST_X step PROG\%LINE 50 2 TEST_Y YES break PROG\%LINE 71 DBG_1>

The SET PROCESS/NOHOLD %VISIBLE_PROCESS command releases the visible process from the hold condition. This is confirmed in the SHOW PROCESS/ALL display.

#3
DBG_1> SET PROCESS TEST_Y DBG_2> SHOW PROCESS Number Name Hold State Current PC * 2 TEST_Y YES break PROG\%LINE 71 DBG_2>

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.

#4
DBG_1> SET PROCESS/HOLD/ALL DBG_1> DO (EXAMINE X; STEP) For %PROCESS_NUMBER 1 MAIN_PROG\X: 78 For %PROCESS_NUMBER 2 TEST\X: 29 stepped to MAIN_PROG\%LINE 26 in %PROCESS_NUMBER 1 26: K = K + 1 DBG_1>

In this example, SET PROCESS/HOLD/ALL puts all processes on hold. The DO command broadcasts the EXAMINE X and STEP commands to all processes (processes 1 and 2, in this example). The STEP command is executed in the context of process 1, because a hold condition in the visible process is ignored. Because process 2 is on hold, execution is inhibited in that process.

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> for a nonmultiprocess debugging configuration (when the logical name DBG$PROCESS is undefined or has the value DEFAULT).
By default, for a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS), the prompt string consists of a process-independent prefix (specified by prompt-parameter) and a process-specific suffix (specified by /[NO]SUFFIX). The suffix changes automatically as the visible process changes.

Qualifiers

/SUFFIX[=process-identifier-type] (default)

/NOSUFFIX
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS).
The /SUFFIX qualifier enables "dynamic prompt setting". As a result, the prompt string includes a process-specific suffix that automatically identifies the visible process. This is the default.
The /NOSUFFIX qualifier disables dynamic prompt setting. As a result, the prompt string does not include a process-specific suffix and does not change when another process becomes the visible process.
By default, when you start the debugger to debug a multiprocess program, the prompt string is DBG_1>. This indicates that dynamic prompt setting is enabled and that the visible process is process 1 (the first process connected to the debugger). You can control the process-specific prompt-string suffix by specifying one of the following process-identifier-type keywords with the /SUFFIX qualifier:

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

The following table illustrates the possible kinds of prompt strings for a multiprocess debugging configuration. The entire prompt string depends on the prompt-parameter command parameter (which controls the process-independent prefix), and on the values of /[NO]SUFFIX and the process-identifier-type keyword (which control the process-specific suffix).

Prompt Parameter (prefix) Qualifier and Keyword (suffix) Resulting Prompt String

none none unchanged

none /NOSUFFIX DBG>

none /SUFFIX DBG_ proc-number> ¹

none /SUFFIX=PROCESS_NAME proc-name>

none /SUFFIX=PROCESS_NUMBER proc-number>

none /SUFFIX=PROCESS_PID pid>

XYZ_ /NOSUFFIX XYZ_>

XYZ_ /SUFFIX XYZ_ proc-number>

XYZ_ /SUFFIX=PROCESS_NAME XYZ_ proc-name>

XYZ_ /SUFFIX=PROCESS_NUMBER XYZ_ proc-number>

XYZ_ /SUFFIX=PROCESS_PID XYZ_ pid>

Prompt Parameter (prefix)	Qualifier and Keyword (suffix)	Resulting Prompt String
none	none	unchanged
none	/NOSUFFIX	DBG>
none	/SUFFIX	DBG_ proc-number> ¹
none	/SUFFIX=PROCESS_NAME	proc-name>
none	/SUFFIX=PROCESS_NUMBER	proc-number>
none	/SUFFIX=PROCESS_PID	pid>
XYZ_	/NOSUFFIX	XYZ_>
XYZ_	/SUFFIX	XYZ_ proc-number>
XYZ_	/SUFFIX=PROCESS_NAME	XYZ_ proc-name>
XYZ_	/SUFFIX=PROCESS_NUMBER	XYZ_ proc-number>
XYZ_	/SUFFIX=PROCESS_PID	XYZ_ pid>

¹The default prompt for a multiprocess debugging configuration is DBG_process-number>, which is equivalent to entering the following command: DBG> SET PROMPT/SUFFIX=PROCESS_NUMBER "DBG_"

/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 using a multiprocess debugging configuration (when the logical name DBG$PROCESS has the value MULTIPROCESS), /[NO]SUFFIX enables you to specify a process-specific prompt-string suffix.
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>".

#2
DBG_1> SET PROMPT/NOSUFFIX "dbg> " dbg> SET PROMPT/SUFFIX DBG_1> SET PROMPT/SUFFIX=PROCESS_NUMBER "xyz_" xyz_1> SET PROMPT/SUFFIX=PROCESS_NAME SMITH> SET PROMPT/SUFFIX=PROCESS_NAME "John " John SMITH> SET PROMPT/SUFFIX=PROCESS_PID 20800E4D>

DBG_1> SET PROMPT/NOSUFFIX "dbg> "
dbg> SET PROMPT/SUFFIX
DBG_1> SET PROMPT/SUFFIX=PROCESS_NUMBER "xyz_"
xyz_1> SET PROMPT/SUFFIX=PROCESS_NAME
SMITH> SET PROMPT/SUFFIX=PROCESS_NAME "John "
John SMITH> SET PROMPT/SUFFIX=PROCESS_PID
20800E4D>

In this example, the successive SET PROMPT commands show the effects of /[NO]SUFFIX and the prompt-parameter for multiprocess programs.

Contents

Index

privacy and legal statement

4538PRO_054.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.

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