OpenVMS Debugger Manual

Updated: 11 December 1998

OpenVMS Debugger Manual

Contents

Index

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. type Help Built_in_Symbols.
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.
In most cases, this default scope search list enables you to resolve ambiguities in a predictable, natural way that is consistent with language rules. But if you cannot access a symbol that is defined multiple times, use either of the following techniques:
Specify the symbol with a path-name prefix. The path-name prefix consists of any nesting program units (for example, module\routine\block) that are necessary to specify the symbol uniquely. For example:
DBG> EXAMINE MOD4\ROUT3\X DBG> TYPE MOD4\27
Establish a new default scope (or a scope search list) for symbol lookup by using the SET SCOPE command. You can then specify the symbol without using a path-name prefix. For example:
DBG> SET SCOPE MOD4\ROUT3 DBG> EXAMINE X DBG> TYPE 27
The SET SCOPE command is useful in those cases where otherwise you would need to use a path name repeatedly to specify symbols.
To restore the default scope search list, use the CANCEL SCOPE command.
When the default scope search list is in effect, you can use the SET SCOPE/CURRENT command to specify that symbol searches start at a numeric scope other than scope 0, relative to the call stack (for example, scope 2).
When you use the SET SCOPE command, the debugger searches only the program locations you specify explicitly, unless you specify /CURRENT. Also, the scope or scope search list established with a SET SCOPE command remains in effect until you restore the default scope search list or enter another SET SCOPE command. However, if you specify /CURRENT, the default scope search list is restored whenever program execution is resumed.
The SET SCOPE command updates a screen-mode source or instruction display only if you specify /CURRENT.
If a name you specify in a SET SCOPE command is the name of both a module and a routine, the debugger sets the scope to the routine. In such cases, use the SET SCOPE/MODULE command if you want to set the scope to the module.
If you specify a module name in a SET SCOPE command, the debugger sets that module if it is not already set. However, if you want only to set a module, use the SET MODULE command rather than the SET SCOPE command, to avoid the possibility of disturbing the current scope search list.
For information specific to Ada programs, type Help Language_Support Ada.
Related commands:

CANCEL ALL
SEARCH
SET MODULE
(SHOW,CANCEL) SCOPE
SHOW SYMBOL
SYMBOLIZE
TYPE

Examples

#1
DBG> EXAMINE Y %DEBUG-W-NOUNIQUE, symbol 'Y' is not unique DBG> SHOW SYMBOL Y data CHECK_IN\Y data INVENTORY\COUNT\Y DBG> SET SCOPE INVENTORY\COUNT DBG> EXAMINE Y INVENTORY\COUNT\Y: 347.15 DBG>

In this example, the first EXAMINE Y command indicates that symbol Y is defined multiple times and cannot be resolved from the current scope search list. The SHOW SYMBOL command displays the different declarations of symbol Y. The SET SCOPE command directs the debugger to look for symbols without path-name prefixes in routine COUNT of module INVENTORY. The subsequent EXAMINE command can now interpret Y unambiguously.

#2
DBG> CANCEL SCOPE DBG> SET SCOPE/CURRENT 1

In this example, the CANCEL SCOPE command restores the default scope search list (0,1,2,...,n). The SET SCOPE/CURRENT command then changes the scope search list to 1,2,...,n, so that symbol searches start with scope 1 (that is, with the caller of the routine in which execution is currently suspended). The predefined source and instruction displays SRC and INST, respectively, are updated and now show the source and instructions for the caller of the routine in which execution is suspended.

#3
DBG> SET SCOPE 1 DBG> EXAMINE %R5

In this example, the SET SCOPE command directs the debugger to look for symbols without path-name prefixes in scope 1 (that is, in the caller of the routine in which execution is suspended). The EXAMINE command then displays the value of register R5 in the caller routine. The SET SCOPE command without /CURRENT does not update any source or instruction display.

#4
DBG> SET SCOPE 0, STACKS\R2, SCREEN

This command directs the debugger to look for symbols without path-name prefixes according to the following scope search list. First the debugger looks in the PC scope (denoted by 0). If the debugger cannot find a specified symbol in the PC scope, it then looks in routine R2 of module STACKS. If necessary, it then looks in module SCREEN. If the debugger still cannot find a specified symbol, it looks no further.

#5
DBG> SHOW SYMBOL X data ALPHA\X ! global X data ALPHA\BETA\X ! local X data X (global) ! same as ALPHA\X DBG> SHOW SCOPE scope: 0 [ = ALPHA\BETA ] DBG> SYMBOLIZE X address ALPHA\BETA\%R0: ALPHA\BETA\X DBG> SET SCOPE \ DBG> SYMBOLIZE X address 00000200: ALPHA\X address 00000200: (global) X DBG>

DBG> SHOW SYMBOL X
data ALPHA\X                ! global X 
data ALPHA\BETA\X           ! local X 
data X (global)             ! same as ALPHA\X
DBG> SHOW SCOPE
scope: 0 [ = ALPHA\BETA ]
DBG> SYMBOLIZE X
address ALPHA\BETA\%R0: 
    ALPHA\BETA\X
DBG> SET SCOPE \
DBG> SYMBOLIZE X
address 00000200: 
    ALPHA\X 
address 00000200: (global) 
    X
DBG>

In this example, the SHOW SYMBOL command indicates that there are two declarations of the symbol X---a global ALPHA\X (shown twice) and a local ALPHA\BETA\X. Within the current scope, the local declaration of X (ALPHA\BETA\X) is visible. After the scope is set to the global scope (SET SCOPE \), the global declaration of X is made visible.

SET SEARCH

Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) for the SEARCH command.

Format

SET SEARCH search-default[,...]

Parameters

search-default
Specifies a default to be established for the SEARCH command. Valid keywords (which correspond to SEARCH command qualifiers) are as follows:

ALL Subsequent SEARCH commands are treated as SEARCH/ALL, rather than SEARCH/NEXT.

IDENTIFIER Subsequent SEARCH commands are treated as SEARCH/IDENTIFIER, rather than SEARCH/STRING.

NEXT (Default) Subsequent SEARCH commands are treated as SEARCH/NEXT, rather than SEARCH/ALL.

STRING (Default) Subsequent SEARCH commands are treated as SEARCH/STRING, rather than SEARCH/IDENTIFIER.

Description

The SET SEARCH command establishes default qualifiers for subsequent SEARCH commands. The parameters that you specify with SET SEARCH have the same names as the qualifiers for the SEARCH command. The qualifiers determine whether the SEARCH command: (1) searches for all occurrences of a string (ALL) or only the next occurrence (NEXT); and (2) displays any occurrence of the string (STRING) or only those occurrences in which the string is not bounded on either side by a character that can be part of an identifier in the current language (IDENTIFIER).
You can override the current SEARCH default for the duration of a single SEARCH command by specifying other qualifiers. Use the SHOW SEARCH command to identify the current SEARCH defaults.
Related commands:

SEARCH
(SET,SHOW) LANGUAGE
SHOW SEARCH

Example


DBG> SHOW SEARCH search settings: search for next occurrence, as a string DBG> SET SEARCH IDENTIFIER DBG> SHOW SEARCH search settings: search for next occurrence, as an identifier DBG> SET SEARCH ALL DBG> SHOW SEARCH search settings: search for all occurrences, as an identifier DBG>

DBG> SHOW SEARCH
search settings: search for next occurrence, as a string
 
DBG> SET SEARCH IDENTIFIER
DBG> SHOW SEARCH
search settings: search for next occurrence, as an identifier
 
DBG> SET SEARCH ALL
DBG> SHOW SEARCH
search settings: search for all occurrences, as an identifier
DBG>

In this example, the SET SEARCH IDENTIFIER command directs the debugger to search for an occurrence of the string in the specified range but display the string only if it is not bounded on either side by a character that can be part of an identifier in the current language.
The SET SEARCH ALL command directs the debugger to search for (and display) all occurrences of the string in the specified range.

SET SOURCE

Specifies a directory search list, a directory search method, or both a list and a method for source files.

Format

SET SOURCE directory-spec[,...]

Parameters

directory-spec
Specifies any part of an OpenVMS file specification (typically a device/directory) that the debugger is to use by default when searching for a source file. For any part of a full file specification that you do not supply, the debugger uses the file specification stored in the module's symbol record (that is, the file specification that the source file had at compile time).
If you specify more than one directory in a single SET SOURCE command, you create a source directory search list (you can also specify a search list logical name that is defined at your process level). In this case, the debugger locates the source file by searching the first directory specified, then the second, and so on, until it either locates the source file or exhausts the list of directories.

Qualifiers

/DISPLAY
Specifies the directory search list used when the debugger displays source code. The default display search directory is the compilation directory.
/EDIT
Specifies the directory search list used during execution of the debugger's EDIT command. The default edit search directory is the compilation directory.
/EXACT (default)
Specifies the directory search method used. In this case, the debugger searches for the exact version of the source file, as indicated in the debugger symbol table.
/LATEST
Specifies the directory search method used. In this case, the debugger searches for the latest version of the source file, that is, the highest-numbered version in your directory.
/MODULE=module-name
Specifies the directory search list used only for the designated module. You can append one or more of the qualifiers listed above to the SET SOURCE/MODULE command.
/ORIGINAL
(Applies to STDL programs only. Requires installation of the Correlation Facility (a separate layered product) and invocation of the kept debugger.) Specifies that the debugger display the original STDL source file, rather than the intermediate files produced during STDL compilation.

Description

By default, the debugger expects a source file to be in the same directory it was in at compile time. If a source file has been moved to a different directory since compile time, use the SET SOURCE command to specify a directory search list and search method to locate the file.
Specifying the Directory Search List

On OpenVMS Version 6.1 and later, a complete OpenVMS file specification has the following format:
node::device:[directory]file-name.file-type;version-number
This format reflects the DECnet node name functionality used in the default version of DECnet shipped with the OpenVMS operating system. For more information, see the DECnet for OpenVMS Networking Manual.
On OpenVMS systems running Version 6.1 or later and DECnet-Plus for OpenVMS, a complete file specification can include expanded node designations, called full names. Full names are hierarchically structured DECnet-Plus for OpenVMS node names that can be stored in a DECdns naming service. Full names can be a maximum of 255 bytes long, in the following format:
namespace:.directory ... .directory.node-name
In this syntax statement, namespace identifies the global naming service, directory ... .directory defines the hierarchical directory path within the naming service, and node-name is the specific object defining the DECnet node.
For information on full names and suggestions for setting up a system of names, see the OpenVMS System Manager's Manual. For information on DECnet-Plus for OpenVMS, see the DECnet-Plus for OpenVMS Introduction and User's Guide.
If the full file specification of a source file exceeds 255 characters, the debugger cannot locate the file. You can work around this problem by first defining a logical name "X" (at DCL level) to expand to your long file specification, and then using the SET SOURCE X command.
A SET SOURCE command with neither the /DISPLAY nor the /EDIT qualifier changes both the display and edit search directories.
When compiling a program with the /DEBUG qualifier, if you use a rooted-directory logical name to specify the location of the source file, make sure that it is a concealed rooted-directory logical name. If it is not concealed and you move the source file to another directory after compilation, you cannot then use the debugger SET SOURCE command to specify the new location of the source file.
To create a concealed rooted-directory logical name, use the DCL command DEFINE with the /TRANSLATION_ATTR=CONCEALED qualifier.
Specifying the Directory Search Method

When you issue a SET SOURCE command, be aware that one of the two qualifiers ---/LATEST or /EXACT---will always be active. These qualifiers affect the debugger search method. The /LATEST qualifier directs the debugger to search for the version last created (the highest-numbered version in your directory). The /EXACT qualifier directs the debugger to search for the version last compiled (the version recorded in the debugger symbol table created at compile time). For example, a SET SOURCE/LATEST command might search for SORT.FOR;3 while a SET SOURCE/EXACT command might search for SORT.FOR;1.
If the debugger locates this version using the directory search list, it checks that the creation or revision date and time, file size, record format, and file organization are the same as the original compile-time source file. If these characteristics match, the debugger concludes that the original source file has been located in its new directory.
If the debugger cannot locate this version using the directory search list, it identifies the file that has the closest revision date and time (if such a file exists in that directory) and issues a NOTORIGSRC message ("original version of source file not found") when first displaying the source code.
Specifying the /EDIT Qualifier

The /EDIT qualifier is needed when the files used for the display of source code are different from the files to be edited by using the EDIT command. This is the case with Ada programs. For Ada programs, the (SET, SHOW, CANCEL) SOURCE commands affect the search of files used for source display (the "copied" source files in Ada program libraries); the (SET,SHOW,CANCEL) SOURCE/EDIT commands affect the search of the source files you edit when using the EDIT command. If you use /MODULE with /EDIT, the effect of /EDIT is further qualified by /MODULE.
For information specific to Ada programs, type HELP Language_Support Ada.
Specifying the /ORIGINAL Qualifier

Before you can use the /ORIGINAL qualifier in a SET SOURCE command, the Correlation Facility (a separate layered product) must be installed on your system. Refer to Correlation Facility documentation for information on creating a correlation library before debugging.
Then, invoke the kept debugger and issue the SET SOURCE/ORIGINAL command as follows:
$ DEBUG/KEEP DBG> SET SOURCE/ORIGINAL DBG> RUN filename.EXE
After issuing these commands, you can debug STDL source code in the same way you debug any other supported language program.
Related commands:

(SHOW,CANCEL) SOURCE

Examples

#1
DBG> SHOW SOURCE no directory search list in effect DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC] DBG> SHOW SOURCE source directory list for all modules, match the latest source file version: [PROJA] [PROJB] [PETER.PROJC]

DBG> SHOW SOURCE
  no directory search list in effect
DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC]
DBG> SHOW SOURCE 
    source directory list for all modules, 
    match the latest source file version: 
        [PROJA] 
        [PROJB] 
        [PETER.PROJC]

Previous Next Contents Index

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

4538PRO_055.HTML

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

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.

ALL	Subsequent SEARCH commands are treated as SEARCH/ALL, rather than SEARCH/NEXT.
IDENTIFIER	Subsequent SEARCH commands are treated as SEARCH/IDENTIFIER, rather than SEARCH/STRING.
NEXT	(Default) Subsequent SEARCH commands are treated as SEARCH/NEXT, rather than SEARCH/ALL.
STRING	(Default) Subsequent SEARCH commands are treated as SEARCH/STRING, rather than SEARCH/IDENTIFIER.