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[, . . . ]
1 – 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 Specifies the scope denoted by the path-name
prefix 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.
\ Specifies the global scope-that is, the set of
(backslash) 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.
2 – Qualifiers
2.1 /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:
o 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.
o The command parameter specified must be one (and only one)
decimal integer from 0 to n.
o 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.
o The default scope search list is restored when program
execution is resumed.
2.2 /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.
3 – 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:
o 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
o 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
4 – Description, Continued...
The SET SCOPE command is useful in those cases where otherwise
you would need to use a path name repeatedly to specify symbols.
SET SCOPE changes the debugger's language setting to the language
of the specified scope.
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
5 – 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.