Updated: 11 December 1998

OpenVMS Debugger Manual

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

DBG> SET MODULE SUB1
      

This command sets module SUB1 (loads the symbol records of module SUB1 into the RST).

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.

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.

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)

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

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.

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.

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.

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.

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

/POP

/NOPOP (default)

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

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

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.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4538PRO_054.HTML