Document revision date: 30 March 2001

## OpenVMS Debugger Manual

Previous | Contents | Index

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

#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

> 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

#1
    DBG> SET RADIX HEX

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

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 4538PRO_053.HTML