Document revision date: 19 July 1999

When you enter the LINK/DEBUG command to link object modules and produce an executable image, the linker performs several functions that affect debugging:

• It builds a debug symbol table (DST) from the DST records contained in the object modules being linked. The DST is the primary source of symbol information during a debugging session.
• It resolves references to global symbols and builds a global symbol table (GST). The GST duplicates some of the global symbol information already contained in the DST, but the GST is used by the debugger for symbol lookup under certain circumstances.
• It puts the DST and GST in the executable image.
• It sets flags in the executable image that cause the image activator to pass control to the debugger when you enter the DCL command RUN (see Section 1.2).

Section 5.4 explains how to link shareable images for debugging, including how to define universal symbols (global symbols that are defined within a shareable image and referenced from another image).

Table 5-2 summarizes the level of DST and GST information passed to the debugger depending on the compiler or LINK command option. The compiler command qualifier controls the level of DST information passed to the linker. The LINK command qualifier controls not only how much DST and GST information is passed to the debugger but also whether the program can be brought under debugger control (see Section 1.2).

Table 5-2 Effect of Compiler and Linker on DST and GST Symbol Information

Compiler Command Qualifier1	DST Data in Object Module	LINK Command Qualifier2	DST Data Passed to Debugger	GST Data Passed to Debugger3
/DEBUG	Full	/DEBUG	Full	Full
/DEBUG=TRACE	Traceback only	/DEBUG	Traceback only	Full
/NODEBUG	None	/DEBUG	None	Full
/DEBUG	Full	/DSF 6	Full	Full 7
/DEBUG=TRACE	Traceback only	/DSF 6	Traceback only	Full 7
/NODEBUG	None	/DSF 6	None	Full 7
/DEBUG	Full	/TRACE 4	Traceback only	Full
/DEBUG=TRACE	Traceback only	/TRACE	Traceback only	Full
/NODEBUG	None	/TRACE	None	Full
/DEBUG	Full	/NOTRACE 5

If you specify /NODEBUG with the compiler command and subsequently link and execute the image, the debugger issues the following message when the program is brought under debugger control:

%DEBUG-I-NOLOCALS, image does not contain local symbols

The previous message, which occurs whether you linked with the /TRACEBACK or /DEBUG qualifier, indicates that no DST has been created for that image. Therefore, you have access only to global symbols contained in the GST.

If you do not specify /DEBUG with the LINK command, the debugger issues the following message when the program is brought under debugger control:

%DEBUG-I-NOGLOBALS, some or all global symbols not accessible

The previous message indicates that the only global symbol information available during the debugging session is stored in the DST.

These concepts are discussed in later sections. In particular, see Section 5.4 for additional information related to debugging shareable images.

5.1.4 Controlling Symbol Information in Debugged Images

Symbol records occupy space within the executable image. After you debug your program, you might want to link it again without using the /DEBUG qualifier to make the executable image smaller. This creates an image with only traceback data in the DST and with a GST.

The LINK/NOTRACEBACK command enables you to secure the contents of an image from users after it has been debugged. Use this command for images that are to be installed with privileges (see the OpenVMS System Manager's Manual and the OpenVMS System Management Utilities Reference Manual). When you use the /NOTRACEBACK qualifier with the LINK command, no symbolic information (including traceback data) is passed to the image.

5.1.5 Creating Separate Symbol Files (Alpha Only)

On Alpha systems, you can LINK your program with the /DSF qualifier to create a separate file that contains symbol information. By default, the symbol file has the same file name as the executable file created by the LINK utility, and has file type .DSF. For example:

$ CC/DEBUG/NOOPTIMIZE TESTPROGRAM.C $ LINK/DSF TESTPROGRAM $ DEFINE DBG$IMAGE_DSF_PATH SYS$DISK:[] $ DEBUG/KEEP TESTPROGRAM

This example does the following:

1. Compiles TESTPROGRAM.C
2. Creates TESTPROGRAM.EXE and TESTPROGRAM.DSF
3. Defines logical name DBG$IMAGE_DSF_PATH as the current directory
4. Invokes the kept debugger

This procedure allows you to create smaller executable files and still have global symbol information available for debugging. Certain applications, such as installed resident files, require that the executable not contain symbol tables. In addition, .DSF files allow you to deliver executable files without symbol tables to customers, but retain separate .DSF files for future debugging needs.

Debugging an executable file that has a separate symbol (.DSF) file requires the following:

• The name of the .DSF file must match the name of the .EXE file being debugged.
• You must be running in a configuration in which DBG$PROCESS is defined as DEFAULT or MULTIPROCESS.
• You must define DBG$IMAGE_DSF_PATH to point to the directory that contains the .DSF file.

See the OpenVMS Linker Utility Manual for more information about using the /DSF qualifier.

5.2 Setting and Canceling Modules

You need to set a module if the debugger is unable to locate a symbol that you have specified (for example, a variable name X) and issues a message as in the following example:

DBG> EXAMINE X %DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table DBG>

This section explains module setting, and the conditions under which you might need to set or cancel a module, using the SET MODULE and CANCEL MODULE commands.

When you compile and link your program using the /DEBUG command qualifier, as explained in Section 5.1, complete symbol information is passed from the program's source code to its executable image

Symbol information is contained in the debug symbol table (DST) and global symbol table (GST) within the executable image. The DST contains detailed information about local and global symbols. The GST duplicates some of the global symbol information contained in the DST.

To facilitate symbol searches, the debugger loads symbol information from the DST and GST into a run-time symbol table (RST), which is structured for efficient symbol lookup. Unless symbol information is in the RST, the debugger does not recognize or properly interpret the associated symbol.

Because the RST takes up memory, the debugger loads it dynamically, anticipating what symbols you might want to reference in the course of program execution. The loading process is called module setting, because all symbol information for a given module is loaded into the RST at one time.

When your program is brought under debugger control, all GST records are loaded into the RST, because global symbols must be accessible throughout the debugging session. Also, the debugger sets the module that contains the main program (the routine specified by the image transfer address, where execution is paused at the start of a debugging session). You then have access to all global symbols and to any local symbols that should be visible within the main program.

Subsequently, whenever execution of the program is interrupted, the debugger sets the module that contains the routine in which execution is paused. (For Ada programs, the debugger also sets any module that is related by a with-clause or subunit relationship, as explained in the debugger's online help. Type Help Language_Support_Ada.) This enables you to reference the symbols that should be visible at that program location (in addition to the global symbols). This default mode of operation is called dynamic mode. When setting a module dynamically, the debugger issues a message such as the following:

%DEBUG-I-DYNMODSET, setting module MOD4

If you try to reference a symbol that is defined in a module that has not been set, the debugger warns you that the symbol is not in the RST. You must then use the SET MODULE command to set the module containing that symbol explicitly. For example:

DBG> EXAMINE X %DEBUG-E-NOSYMBOL, symbol 'X' is not in the symbol table DBG> SET MODULE MOD3 DBG> EXAMINE X MOD3\ROUT2\X: 26 DBG>

The SHOW MODULE command lists the modules of your program and identifies which modules are set.

When a module is set, the debugger automatically allocates memory as needed by the RST. This can eventually slow down the debugger as more modules are set. If performance becomes a problem, you can use the CANCEL MODULE command to reduce the number of set modules, which automatically releases memory. Or you can disable dynamic mode by entering the SET MODE NODYNAMIC command. When dynamic mode is disabled, the debugger does not set modules automatically. Use the SHOW MODE command to determine whether dynamic mode is enabled or disabled.

For additional information about module setting specific to Ada programs, see the debugger's online help (type Help Language_Support_Ada).

Section 5.4 explains how to set images and modules when debugging shareable images.

5.3 Resolving Symbol Ambiguities

Symbol ambiguities can occur when a symbol (for example, a variable name X) is defined in more than one routine or other program unit.

In most cases, the debugger resolves symbol ambiguities automatically, by using the scope and visibility rules of the currently set language and the ordering of routine calls on the call stack, as explained in Section 5.3.1.

However, in some cases the debugger might respond as follows when you specify a symbol that is defined multiple times:

• It might not be able to determine the particular declaration of the symbol that you intended. For example:

  DBG> EXAMINE X %DEBUG-W-NOUNIQUE, symbol 'X' is not unique DBG>

• It might reference the declaration that is visible in the current scope, which may not be the one you want.

To resolve such problems, you must specify a scope where the debugger should search for a particular declaration of the symbol. In the following example, the pathname COUNTER\X uniquely specifies a particular declaration of X:

DBG> EXAMINE COUNTER\X COUNTER\X: 14 DBG>

The following sections discuss scope concepts and explain how to resolve symbol ambiguities.

5.3.1 Symbol Lookup Conventions

This section explains how the debugger searches for symbols, resolving most potential symbol ambiguities using the scope and visibility rules of the programming language and also its own rules. Section 5.3.2 and Section 5.3.3 describe supplementary techniques that you can use when necessary.

You can specify symbols in debugger commands by using either a path name or the exact symbol.

If you use a path name, the debugger looks for the symbol in the scope denoted by the pathname prefix (see Section 5.3.2).

If you do not specify a pathname prefix, by default, the debugger searches the run-time symbol table (RST) as explained in the following paragraphs (you can modify this default behavior with the SET SCOPE command as explained in Section 5.3.3).

First, the debugger looks for symbols in the PC scope (also known as scope 0), according to the scope and visibility rules of the currently set language. This means that, typically, the debugger first looks within the block or routine surrounding the current PC value (where execution is currently paused). If the symbol is not found, the debugger searches the nesting program unit, then its nesting unit, and so on. The precise manner, which depends on the language, ensures that the correct declaration of a symbol that is defined multiple times is chosen.

However, you can reference symbols throughout your program, not just those that are visible in the PC scope as defined by the language. This is necessary so you can set breakpoints in arbitrary areas, examine arbitrary variables, and so on. Therefore, if the symbol is not visible in the PC scope, the debugger continues searching as follows.

After the PC scope, the debugger searches the scope of the calling routine (if any), then its caller, and so on. Symbolically, the complete scope search list is denoted (0,1,2,...,n), where 0 denotes the PC scope and n is the number of calls on the call stack. Within each scope (call frame), the debugger uses the visibility rules of the language to locate a symbol.

This search list, based on the call stack, enables the debugger to differentiate symbols that are defined multiple times in a convenient, predictable way.

If the symbol is still not found, the debugger searches the rest of the RST---that is, the other set modules and the global symbol table (GST). At this point the debugger does not attempt to resolve any symbol ambiguities. Instead, if more than one occurrence of the symbol is found, the debugger issues a message such as the following:

%DEBUG-W-NOUNIQUE, symbol 'Y' is not unique

If you have used a SET SCOPE command to modify the default symbol search behavior, you can restore the default behavior with the CANCEL SCOPE command.

5.3.2 Using SHOW SYMBOL and Path Names to Specify Symbols Uniquely

If the debugger indicates that a symbol reference is not unique, use the SHOW SYMBOL command to obtain all possible path names for that symbol, then specify a path name to reference the symbol uniquely. For example:

DBG> EXAMINE COUNT %DEBUG-W-NOUNIQUE, symbol 'COUNT' is not unique DBG> SHOW SYMBOL COUNT data MOD7\ROUT3\BLOCK1\COUNT data MOD4\ROUT2\COUNT routine MOD2\ROUT1\ROUT3\COUNT DBG> EXAMINE MOD4\ROUT2\COUNT MOD4\ROUT2\COUNT: 12 DBG>

The command SHOW SYMBOL COUNT lists all declarations of the symbol COUNT that exist in the RST. The first two declarations of COUNT are variables (data). The last declaration listed is a routine. Each declaration is shown with its pathname prefix, which indicates the path (search scope) the debugger must follow to reach that particular declaration. For example, MOD4\ROUT2\COUNT denotes the declaration of the symbol COUNT in routine ROUT2 of module MOD4.

The pathname format is as follows. The leftmost element of a path name identifies the module containing the symbol. Moving toward the right, the path name lists the successively nested routines and blocks that lead to the particular declaration of the symbol (which is the rightmost element).

The debugger always displays symbols with their path names, but you need to use path names in debugger commands only to resolve an ambiguity.

The debugger looks up line numbers like any other symbols you specify (by default, it first looks in the module where execution is paused). A common use of path names is for specifying a line number in an arbitrary module. For example:

DBG> SET BREAK QUEUE_MANAGER\%LINE 26

The SHOW SYMBOL command identifies global symbols twice, because global symbols are included both in the DST and in the GST. For example:

DBG> SHOW SYMBOL X data ALPHA\X ! global X data ALPHA\BETA\X ! local X data X (global) ! same as ALPHA\X DBG>

In the case of a shareable image, its global symbols are universal symbols and the SHOW SYMBOL command identifies universal symbols twice (see Section 5.1.2 and Section 5.4).

5.3.2.1 Simplifying Path Names

Path names are often long. You can simplify the process of specifying path names in three ways:

• Abbreviate a path name
• Define a brief symbol for a path name
• Set a new search scope so you do not have to use a path name

To abbreviate a path name, delete the names of nesting program units starting from the left, but leave enough of the path name to specify it uniquely. For example, ROUT3\COUNT is a valid abbreviated path name for the routine in the first example of Section 5.3.2.

To define a symbol for a path name, use the DEFINE command. For example:

DBG> DEFINE INTX = INT_STACK\CHECK\X DBG> EXAMINE INTX

To set a new search scope, use the SET SCOPE command, which is described in Section 5.3.3.

5.3.2.2 Specifying Symbols in Routines on the Call Stack

You can use a numeric path name to specify the scope associated with a routine on the call stack (as identified in a SHOW CALLS display). The pathname prefix "0\" denotes the PC scope, the pathname prefix "1\" denotes scope 1 (the scope of the caller routine), and so on.

For example, the following commands display the current values of two distinct declarations of Y, which are visible in scope 0 and scope 2, respectively:

DBG> EXAMINE 0\Y DBG> EXAMINE 2\Y

By default, the EXAMINE Y command signifies EXAMINE 0\Y.

See the SET SCOPE/CURRENT command description in Section 5.3.3. That command enables you to reset the reference for the default scope search list relative to the call stack.

5.3.2.3 Specifying Global Symbols

To specify a global symbol uniquely, use a backslash (\) as a prefix to the symbol. For example, the following command displays the value of the global symbol X:

DBG> EXAMINE \X

	privacy and legal statement
4538PRO_011.HTML