Document revision date: 19 July 1999

When a routine is called recursively, you might need to distinguish among several calls to the same routine, all of which generate new symbols with identical names.

You can include an invocation number in a path name to indicate a particular call to a routine. The number must be a nonnegative integer and must follow the name of the rightmost routine in the path name. A 0 denotes the most recent invocation; 1 denotes the previous invocation, and so on. For example, if PROG calls COMPUTE and COMPUTE calls itself recursively, and each call creates a new variable SUM, the following command displays the value of SUM for the most recent call to COMPUTE:

DBG> EXAMINE PROG\COMPUTE 0\SUM

To refer to the variable SUM that was generated in the previous call to COMPUTE, express the path name with a 1 in place of the 0.

When you do not include an invocation number, the debugger assumes that the reference is to the most recent call to the routine (the default invocation number is 0).

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.3 Using SET SCOPE to Specify a Symbol Search Scope

By default, the debugger looks up symbols that you specify without a pathname prefix by using the scope search list described in Section 5.3.1.

The SET SCOPE command enables you to establish a new scope for symbol lookup so that you do not have to use a path name when referencing symbols in that scope.

In the following example, the SET SCOPE command establishes the path name MOD4\ROUT2 as the new scope for symbol lookup. Then, references to Y without a pathname prefix specify the declaration of Y that is visible in the new scope.

DBG> EXAMINE Y %DEBUG-E-NOUNIQUE, symbol 'Y' is not unique DBG> SHOW SYMBOL Y data MOD7\ROUT3\BLOCK1\Y data MOD4\ROUT2\Y DBG> SET SCOPE MOD4\ROUT2 DBG> EXAMINE Y MOD4\ROUT2\Y: 12 DBG>

After you enter a SET SCOPE command, the debugger applies the path name you specified in the command to all references that are not individually qualified with path names.

You can specify numeric path names with SET SCOPE. For example, the following command sets the current scope to be three calls down from the PC scope:

DBG> SET SCOPE 3

You can also define a scope search list to specify the order in which the debugger should search for symbols. For example, the following command causes the debugger to look for symbols first in the PC scope (scope 0) and then in the scope denoted by routine ROUT2 of module MOD4:

DBG> SET SCOPE 0, MOD4\ROUT2

The debugger's default scope search list is equivalent to entering the following command (if it existed):

DBG> SET SCOPE 0,1,2,3,...,n

Here the debugger searches successively down the call stack to find a symbol.

You can use the SET SCOPE/CURRENT command to reset the reference for the default scope search list to another routine down the call stack. For example, the following command sets the scope search list to be 2,3,4,...,n:

DBG> SET SCOPE/CURRENT 2

To display the current scope search list for symbol lookup, use the SHOW SCOPE command. To restore the default scope search list (see Section 5.3.1), use the CANCEL SCOPE command.

5.4 Debugging Shareable Images

By default, your program might be linked with several Digital-supplied shareable images (for example, the run-time library image LIBRTL.EXE). This section explains how to extend the concepts described in the previous sections when debugging user-defined shareable images.

A shareable image is not intended to be directly executed. A shareable image must first be included as input in the linking of an executable image, and then the shareable image is loaded at run time when the executable image is run. You do not have to install a shareable image to debug it. Instead, you can debug your own private copy by assigning a logical name to it.

See the OpenVMS Linker Utility Manual for detailed information about linking shareable images.

5.4.1 Compiling and Linking Shareable Images for Debugging

The basic steps in compiling and linking a shareable image for debugging are as follows:

1. Compile the source files for the main image and for the shareable image, by using the /DEBUG qualifier.
2. Link the shareable image with the /SHAREABLE and /DEBUG command qualifiers and declare any universal symbols for that image. (A universal symbol is a global symbol that is defined in a shareable image and referenced in another image.)
3. Link the shareable image against the main image by specifying the shareable image with the /SHAREABLE file qualifier as a linker option. Also specify the /DEBUG command qualifier.
4. Define a logical name to point to the local copy of the shareable image. You must specify the device and directory as well as the image name. Otherwise the image activator looks for an image of that name in the system default shareable image library directory, SYS$SHARE.
5. Bring the main image under debugger control. The shareable image is loaded at run time.

These steps are shown next with a simple example. In the example, MAIN.FOR and SUB1.FOR are the source files for the main (executable) image; SHR1.FOR and SHR2.FOR are the source files for the shareable image to be debugged.

You compile the source files for each image as described in Section 5.1.

$ FORTRAN/NOOPT/DEBUG MAIN,SUB1 $ FORTRAN/NOOPT/DEBUG SHR1,SHR2

On VAX processors, use the LINK command with the UNIVERSAL linker option to create the shareable image and specify any universal symbols. For example:

$ LINK/SHAREABLE/DEBUG SHR1,SHR2,SYS$INPUT:/OPTIONS UNIVERSAL=SHR_ROUT [Ctrl/Z]

On Alpha processors, use the LINK command with the SYMBOL_VECTOR option to create the shareable image and specify any universal symbols. For example:

$ LINK/SHAREABLE/DEBUG SHR1,SHR2,SYS$INPUT:/OPTIONS SYMBOL_VECTOR=(SHR_ROUT=PROCEDURE) [Ctrl/Z]

In the previous examples:

• The /SHAREABLE command qualifier creates the shareable image SHR1.EXE from the object files SHR1.OBJ and SHR2.OBJ.
• The /OPTIONS qualifier appended to SYS$INPUT: enables you to specify the universal symbol SHR_ROUT.
• The /DEBUG qualifier builds a debug symbol table (DST) and a global symbol table (GST) for SHR1.EXE and puts them in that image. The GST contains the universal symbol SHR_ROUT.

You have now built the shareable image SHR1.EXE in your current default directory. Because SHR1.EXE is a shareable image, you do not execute it explicitly. Instead you link SHR1.EXE against the main (executable) image:

$ LINK/DEBUG MAIN,SUB1,SYS$INPUT:/OPTIONS SHR1.EXE/SHAREABLE [Ctrl/Z] $

In the previous example:

• The LINK command creates the executable image MAIN.EXE from MAIN.OBJ and SUB1.OBJ.
• The /DEBUG qualifier builds a DST and a GST for MAIN.EXE and puts them in that image.
• The /SHAREABLE qualifier appended to SHR1.EXE specifies that SHR1.EXE is to be linked against MAIN.EXE as a shareable image.

When you execute the resulting main image, MAIN.EXE, any shareable images linked against it are loaded at run time. However, by default, the image activator looks for shareable images in the system default shareable image library directory, SYS$SHARE. Therefore, you must define the logical name SHR1 to point to SHR1.EXE in your current default directory. Be sure to specify the device and directory:

$ DEFINE SHR1 SYS$DISK:[]SHR1.EXE

You can now bring both MAIN and SHR1 under debugger control by specifying MAIN with the debugger RUN command (after starting the debugger):

$ DEBUG/KEEP Debugger Banner and Version Number DBG> RUN MAIN

5.4.2 Accessing Symbols in Shareable Images

All the concepts covered in Section 5.1, Section 5.2, and Section 5.3 apply to the modules of a single image, namely the main (executable) image. This section provides additional information that is specific to debugging shareable images.

When you link shareable images for debugging as explained in Section 5.4.1, the linker builds a DST and a GST for each image. The GST for a shareable image contains only universal symbols. To conserve memory, the debugger builds an RST for an image only when that image is set, either dynamically by the debugger or when you use a SET IMAGE command.

The SHOW IMAGE command identifies all shareable images that are linked with your program, shows which images are set, and identifies the current image (see Section 5.4.2.2 for a definition of the current image). Only the main image is set initially when you bring the program under debugger control.

The following sections explain how the debugger sets images dynamically during program execution and how you can access symbols in arbitrary images independently of execution.

See Section 3.4.3.4 for information about setting watchpoints in installed writable shareable images.

5.4.2.1 Accessing Symbols in the PC Scope (Dynamic Mode)

By default, dynamic mode is enabled. Therefore, whenever the debugger interrupts execution, the debugger sets the image and module where execution is paused, if they are not already set.

Dynamic mode gives you the following access to symbols automatically:

• You can reference symbols defined in all set modules in the image where execution is paused.
• You can reference any universal symbols in the GST for that image.

By setting other modules in that image with the SET MODULE command, you can reference any symbol defined in the image.

After an image is set, it remains set until you cancel it with the CANCEL IMAGE command. If the debugger slows down as more images and modules are set, use the CANCEL IMAGE command. You can also enter the SET MODE NODYNAMIC command to disable dynamic mode.

5.4.2.2 Accessing Symbols in Arbitrary Images

The last image that you or the debugger sets is the current image. The current image is the debugging context for symbol lookup. Therefore, when using the following commands, you can reference only the symbols that are defined in the current image:

• DEFINE/ADDRESS
• DEFINE/VALUE
• DEPOSIT
• EVALUATE
• EXAMINE
• TYPE
• (SET,CANCEL) BREAK
• (SET,SHOW,CANCEL) MODULE
• (SET,CANCEL) TRACE
• (SET,CANCEL) WATCH
• SHOW SYMBOL

Note that the SHOW BREAK, SHOW TRACE, and SHOW WATCH commands identify any breakpoints, tracepoints, or watchpoints that have been set in all images.

To reference a symbol in another image, use the SET IMAGE command to make the specified image the current image, then use the SET MODULE command to set the module where that symbol is defined (the SET IMAGE command does not set any modules). The following sample program shows these concepts.

The sample program consists of a main image PROG1 and a shareable image SHR1. Assume that you have just brought the program under debugger control and that execution is paused within the main program unit in image PROG1. Assume that you want to set a breakpoint on routine ROUT2, which is defined in some module in image SHR1.

If you try to set a breakpoint on ROUT2, the debugger looks for ROUT2 in the current image, PROG1:

DBG> SET BREAK ROUT2 %DEBUG-E-NOSYMBOL, symbol 'ROUT2' is not in symbol table DBG>

The SHOW IMAGE command shows that image SHR1 needs to be set:

DBG> SHOW IMAGE image name set base address end address *PROG1 yes 00000200 000009FF SHR1 no 00001000 00001FFF total images: 2 bytes allocated: 32856 DBG> SET IMAGE SHR1 DBG> SHOW IMAGE image name set base address end address PROG1 yes 00000200 000009FF *SHR1 yes 00001000 00001FFF total images: 2 bytes allocated: 41948 DBG>

SHR1 is now set and is the current image. However, because the SET IMAGE command does not set any modules, you must set the module where ROUT2 is defined before you can set the breakpoint:

DBG> SET BREAK ROUT2 %DEBUG-E-NOSYMBOL, symbol 'ROUT2' is not in symbol table DBG> SET MODULE/ALL DBG> SET BREAK ROUT2 DBG> GO break at routine ROUT2 10: SUBROUTINE ROUT2(A,B) DBG>

Now that you have set image SHR1 and all its modules and have reached the breakpoint at ROUT2, you can debug using the normal method (for example, step through the routine, examine variables, and so on).

After you have set an image and set modules within that image, the image and modules remain set even if you establish a new current image. However, you have access to symbols only in the current image at any one time.

5.4.2.3 Accessing Universal Symbols in Run-Time Libraries and System Images

The following paragraphs describe how to access a universal symbol (such as a routine name) in a run-time library or other shareable image for which no symbol-table information was generated. With this information you can, for example, use the CALL command to execute a run-time library or system service routine as explained in Section 13.7.

Enter the SET MODULE command with the following command syntax:

SET MODULE SHARE$image-name

For example:

DBG> SET MODULE SHARE$LIBRTL

The debugger creates dummy modules for each shareable image in your program. The names of these shareable image modules have the prefix SHARE$. The command SHOW MODULE/SHARE identifies these shareable image modules as well as the modules in the current image.

Once a shareable image module has been set with the SET MODULE command, you can access all of the image's universal symbols. For example, the following command lists all of the universal symbols in LIBRTL:

DBG> SHOW SYMBOL * IN SHARE$LIBRTL . . . routine SHARE$LIBRTL\STR$APPEND routine SHARE$LIBRTL\STR$DIVIDE routine SHARE$LIBRTL\STR$ROUND . . . routine SHARE$LIBRTL\LIB$WAIT routine SHARE$LIBRTL\LIB$GETDVI . . .

You can then specify these universal symbols with, for example, the CALL or SET BREAK command.

Setting a shareable image module with the SET MODULE command loads the universal symbols for that image into the run-time symbol table so that you can reference these symbols from the current image. However, you cannot reference other (local or global) symbols in that image from the current image. That is, your debugging context remains set to the current image.

5.4.3 Debugging Resident Images (Alpha Only)

A resident image is a shareable module that is created and installed in a particular way to enhance its efficiency. The requirements of creating such an image include linking the image without a symbol table, and running the image in system space. These requirements make such an image difficult to debug. The following procedure creates a resident image that can be more easily debugged.

1. Compile the shareable image. For example:

   $ CC/DEBUG/NOOPTIMIZE RESIDENTMODULE.C

2. Link the shareable image using the /DSF qualifier. For example:

   $ LINK/NOTRACEBACK/SHAREABLE/SECTION_BINDING/DSF RESIDENTMODULE

   
   See the OpenVMS Linker Utility Manual for information about linking the image.

3. Create the installed resident image. See OpenVMS System Management Utilities Reference Manual: A--L for information about using the Install utility. See OpenVMS System Manager's Manual: Tuning, Monitoring, and Complex Systems for information about resident images.
4. Compile the program that calls the resident image. For example:

   $ CC/DEBUG/NOOPTIMIZE TESTPROGRAM

5. Create the executable image that calls the resident image. For example:

   $ LINK/DSF TESTPROGRAM

6. Create a private copy of the resident image. For example:

   $ COPY SYS$LIBRARY:RESIDENTMODULE.EXE []RESIDENTMODULE.EXE

7. Define a logical name that points to the private copy of the resident image. For example:

   $ DEFINE RESIDENTMODULE []RESIDENTMODULE

8. Make sure that the .DSF file for the test program and the .DSF file for the resident module both reside in the same directory.
9. Define DBG$IMAGE_DSF_PATH to point to the directory that contains the .DSF files.
10. Invoke the debugger. For example:

    $ DEBUG/KEEP TESTPROGRAM

    
    Note that TESTPROGRAM must be running in a configuration in which DBG$PROCESS is defined as DEFAULT or MULTIPROCESS.

You should now have access to all debugging options for the executable and resident images.

	privacy and legal statement
4538PRO_012.HTML