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.

Related commands:

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

Examples

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.

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.

DBG> SET SCOPE 1
DBG> EXAMINE %R5
      

In this example, the SET SCOPE command directs the debugger to look for symbols without pathname 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.

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.

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.

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>
      

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.

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

A complete ODS-2 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 DECnet Phase IV that 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 HP 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

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]
      

In this example, the SET SOURCE command specifies that the debugger should search directories [PROJA], [PROJB], and [PETER.PROJC], in that order, for the latest version of source files.

DBG> SET SOURCE/MODULE=CTEST/EXACT [],SYSTEM::DEVICE:[PROJD]
DBG> SHOW SOURCE
   source directory search list for CTEST, 
    match the exact source file version: 
        [] 
        SYSTEM::DEVICE:[PROJD] 
    source directory list for all other modules, 
    match the latest source file version: 
        [PROJA] 
        [PROJB] 
        [PETER.PROJC]
      

In this continuation of the previous example, the SET SOURCE/MODULE=CTEST command specifies that the debugger should search the current default directory ([]) and SYSTEM::DEVICE:[PROJD], in that order, for source files to use with the module CTEST. The /EXACT qualifier specifies that the search will try to locate the exact version of the CTEST source files found in the debug symbol table.

DBG> SET SOURCE /EXACT
DBG> SHOW SOURCE
    no directory search list in effect, 
     match the exact source file
DBG> SET SOURCE [JONES]
DBG> SHOW SOURCE
    source directory list for all modules, 
     match the exact source file version: 
         [JONES]
DBG> CANCEL SOURCE /EXACT
DBG> SHOW SOURCE 
     source directory list for all modules, 
     match the latest source file version: 
         [JONES]
      

In this example, the SET SOURCE/EXACT command establishes a search method (exact version) that remains in effect for the SET SOURCE [JONES] command. The CANCEL SOURCE/EXACT command not only cancels SET SOURCE/EXACT command, but also affects the SET SOURCE [JONES] command.

Establishes default qualifiers (/LINE, /INTO, and so on) for the STEP command.

Format

SET STEP step-default[,...]

Parameters

step-default

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

BRANCH	Subsequent STEP commands are treated as STEP/BRANCH (step to the next branch instruction).
CALL	Subsequent STEP commands are treated as STEP/CALL (step to the next call instruction).
EXCEPTION	Subsequent STEP commands are treated as STEP/EXCEPTION (step to the next exception).
INSTRUCTION	Subsequent STEP commands are treated as STEP/INSTRUCTION (step to the next instruction). On VAX processors, you can also specify one or more instructions ( opcode[,...]). The debugger then steps to the next instruction in the specified list. On VAX processors, if you specify a vector instruction, do not include an instruction qualifier (/UNALIGNED_DATA, /MODIFY, /0, or /1) with the instruction mnemonic.
INTO	Subsequent STEP commands are treated as STEP/INTO (step into called routines) rather than STEP/OVER (step over called routines). When INTO is in effect, you can qualify the types of routines to step into by using the [NO]JSB, [NO]SHARE, and [NO]SYSTEM parameters, or by using the STEP/[NO]JSB, STEP/[NO]SHARE, and STEP/[NO]SYSTEM command/qualifier combinations (the latter three take effect only for the immediate STEP command).
JSB	(VAX only) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/JSB (step into routines called by a JSB instruction as well as those called by a CALL instruction). This is the default for all languages except DIBOL.
NOJSB	(VAX only) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/NOJSB (step over routines called by a JSB instruction, but step into routines called by a CALL instruction). This is the default for DIBOL.
LINE	(Default) Subsequent STEP commands are treated as STEP/LINE (step to the next line).
OVER	(Default) Subsequent STEP commands are treated as STEP/OVER (step over all called routines) rather than STEP/INTO (step into called routines).
RETURN	Subsequent STEP commands are treated as STEP/RETURN (step to the return instruction of the routine that is currently executing---that is, up to the point just prior to transferring control back to the calling routine).
SEMANTIC_EVENT	(Alpha only) Subsequent STEP commands are treated as STEP/SEMANTIC_EVENT (step to the next semantic event). This simplifies debugging optimized programs (see Chapter 14 for more information).
SHARE	(Default) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/SHARE (step into called routines in shareable images as well as into other called routines).
NOSHARE	If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/NOSHARE (step over called routines in shareable images, but step into other routines).
SILENT	Subsequent STEP commands are treated as STEP/SILENT (after a step, do not display the "stepped to..." message or the source line for the current location).
NOSILENT	(Default) Subsequent STEP commands are treated as STEP/NOSILENT (after a step, display the "stepped to..." message).
SOURCE	(Default) Subsequent STEP commands are treated as STEP/SOURCE (after a step, display the source line for the current location). Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands are treated as SET BREAK/SOURCE, SET TRACE/SOURCE, and SET WATCH/SOURCE, respectively (at a breakpoint, tracepoint, or watchpoint, display the source line for the current location).
NOSOURCE	Subsequent STEP commands are treated as STEP/NOSOURCE (after a step, do not display the source line for the current location). Also, subsequent SET BREAK, SET TRACE, and SET WATCH commands are treated as SET BREAK/NOSOURCE, SET TRACE/NOSOURCE, and SET WATCH/NOSOURCE, respectively (at a breakpoint, tracepoint, or watchpoint, do not display the source line for the current location).
SYSTEM	(Default) If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/SYSTEM (step into called routines in system space (P1 space) as well as into other called routines).
NOSYSTEM	If INTO is in effect, subsequent STEP commands are treated as STEP/INTO/NOSYSTEM (step over called routines in system space, but step into other routines).

Description

The SET STEP command establishes default qualifiers for subsequent STEP commands. The parameters that you specify in the SET STEP command have the same names as the qualifiers for the STEP command. The following parameters affect where the STEP command suspends execution after a step:

BRANCH
CALL
EXCEPTION
INSTRUCTION
INSTRUCTION=(opcode[,...]) (VAX only)
LINE
RETURN
SEMANTIC_EVENT (Alpha only)

The following parameters affect what output is seen when a STEP command is executed:

[NO]SILENT
[NO]SOURCE

The following parameters affect what happens at a routine call:

INTO
[NO]JSB (VAX only)
OVER
[NO]SHARE
[NO]SYSTEM

You can override the current STEP defaults for the duration of a single STEP command by specifying other qualifiers. Use the SHOW STEP command to identify the current STEP defaults.

Enabling screen mode by pressing PF1-PF3 enters the SET STEP NOSOURCE command as well as the SET MODE SCREEN command. Therefore, any display of source code in output and DO displays that would result from a STEP command or from a breakpoint, tracepoint, or watchpoint being triggered is suppressed, to eliminate redundancy with the source display.

On VAX systems, the STEP/OVER command may sometimes result in stepping into, not over, Fortran Run-Time Library routines. For more information, see Chapter 14.

Related commands:

SHOW STEP
STEP

Examples

DBG> SET STEP INSTRUCTION,NOSOURCE
      

This command causes the debugger to execute the program to the next instruction when a STEP command is entered, and not to display lines of source code with each STEP command.

DBG> SET STEP LINE,INTO,NOSYSTEM,NOSHARE
      

This command causes the debugger to execute the program to the next line when a STEP command is entered, and to step into called routines in user space only. The debugger steps over routines in system space and in shareable images.