HP OpenVMS Systems Documentation
OpenVMS Debugger Manual
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 126.96.36.199 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 188.8.131.52 for information about setting watchpoints in
installed writable shareable images.
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:
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.
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:
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:
The SHOW IMAGE command shows that image SHR1 needs to be set:
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:
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
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:
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:
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
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.
You should now have access to all debugging options for the executable and resident images.
%DEBUG-W-UNAOPNSRC, unable to open source file DISK:[JONES.WORK]PRG.FOR;2
In such cases, use the SET SOURCE command to direct the debugger to the new directory. The command can be applied to all source files for your program or to only the source files for specific modules.
For example, after you enter the following command line, the debugger looks for all source files in WORK$:[JONES.PROG3]:
DBG> SET SOURCE WORK$:[JONES.PROG3]
You can specify a directory search list with the SET SOURCE command. For example, after the following command line is entered, the debugger looks for source files first in the current default directory () and then in WORK$:[JONES.PROG3]:
DBG> SET SOURCE , WORK$:[JONES.PROG3]
If you want to apply the SET SOURCE command only to the source files for a given module, use the /MODULE=module-name qualifier and specify that module. For example, the following command line specifies that the source files for module SCREEN_IO are in the directory DISK2:[SMITH.SHARE] (the search of source files for other modules is not affected by this command):
DBG> SET SOURCE/MODULE=SCREEN_IO DISK2:[SMITH.SHARE]
To summarize, the SET SOURCE/MODULE command specifies the location of source files for a particular module, but the SET SOURCE command specifies the location of source files for modules that were not mentioned explicitly in SET SOURCE/MODULE commands.
When you enter a SET SOURCE command, be aware that one of the two qualifiers, /LATEST or /EXACT, will always be active. The /LATEST qualifier directs the debugger to search for the latest version of your source files (the highest-numbered version in your directory). The /EXACT qualifier, the default, 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.
Use the SHOW SOURCE command to display all source directory search lists currently in effect. The command displays the search lists for specific modules (as previously established by one or more SET SOURCE/MODULE commands) and the search list for all other modules (as previously established by a SET SOURCE command). For example:
DBG> SET SOURCE [PROJA],[PROJB],USER$:[PETER.PROJC] DBG> SET SOURCE/MODULE=COBOLTEST , DISK$2:[PROJD] DBG> SHOW SOURCE source directory search list for COBOLTEST:  DISK$2:[PROJD] source directory search list for all other modules: [PROJA] [PROJB] USER$:[PETER.PROJC] DBG>
If no SET SOURCE or SET SOURCE/MODULE command has been entered, the SHOW SOURCE command indicates that no search list is currently in effect.
Use the CANCEL SOURCE command to cancel the effect of a previous SET SOURCE command. Use the CANCEL SOURCE/MODULE command to cancel the effect of a previous SET SOURCE/MODULE command (specifying the same module name).
When a source directory search list has been canceled, the debugger again expects the source files corresponding to the designated modules to be in the same directories they were in at compile time.
For more information about how the debugger locates source files that
have been moved to another directory after compile time, see the
SET SOURCE command.
6.3 Displaying Source Code by Specifying Line Numbers
The TYPE command enables you to display source lines by specifying compiler-assigned line numbers, where each line number designates a line of source code.
For example, the following command displays line 160 and lines 22 to 24 of the module being debugged:
DBG> TYPE 160, 22:24 module COBOLTEST 160: START-IT-PARA. module COBOLTEST 22: 02 SC2V2 PIC S99V99 COMP VALUE 22.33. 23: 02 SC2V2N PIC S99V99 COMP VALUE -22.33. 24: 02 CPP2 PIC PP99 COMP VALUE 0.0012. DBG>
You can display all the source lines of a module by specifying a range of line numbers starting from 1 and ending at a number equal to or greater than the largest line number in the module.
After displaying a source line, you can display the next line in that module by entering a TYPE command without a line number---that is, by entering a TYPE command and then pressing the Return key. For example:
DBG> TYPE 160 module COBOLTEST 160: START-IT-PARA. DBG> TYPE module COBOLTEST 161: MOVE SC1 TO ES0. DBG>
You can then display the next line and successive lines by entering the TYPE command repeatedly, which lets you read through your code one line at a time.
To display source lines in an arbitrary module of your program, specify the module name with the line numbers. Use standard pathname notation---that is, first specify the module name, then a backslash (\), and finally the line numbers (or the range of line numbers) without intervening spaces. For example, the following command displays line 16 of module TEST:
DBG> TYPE TEST\16
If you specify a module name with the TYPE command, the module must be set. Use the SHOW MODULE command to determine whether a particular module is set. Then use the SET MODULE command, if necessary (see Section 5.2).
If you do not specify a module name with the TYPE command, the debugger displays source lines for the module in which execution is currently paused by default---that is, the module associated with the PC scope. If you have specified another scope with the SET SCOPE command, the debugger displays source lines in the module associated with the specified scope.
In screen mode, the output of a TYPE command updates the current source display (see Section 7.2.6).
After displaying source lines at various locations in your program, you
can redisplay the line at which execution is currently paused by
6.4 Displaying Source Code by Specifying Code Address Expressions
The EXAMINE/SOURCE command enables you to display the source line corresponding to a code address expression. A code address expression denotes the address of a machine-code instruction and, therefore, must be one of the following:
You cannot specify a variable name with the EXAMINE/SOURCE command, because a variable name is associated with data, not with instructions.
When you use the EXAMINE/SOURCE command, the debugger evaluates the address expression to obtain a memory address, determines which compiler-assigned line number corresponds to that address, and then displays the source line designated by the line number.
For example, the following command line displays the source line associated with the address (declaration) of routine SWAP:
DBG> EXAMINE/SOURCE SWAP module MAIN 47: procedure SWAP(X,Y: in out INTEGER) is DBG>
If you specify a line number that is not associated with an instruction, the debugger issues a diagnostic message. For example:
DBG> EXAMINE/SOURCE %LINE 6 %DEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8 %DEBUG-E-NOSYMBOL, symbol '%LINE 6' is not in the symbol table DBG>
When using the EXAMINE/SOURCE command with a symbolic address expression (a line number, label, or routine), you might need to set the module in which the entity is defined, unless that module is already set. Use the SHOW MODULE command to determine whether a particular module is set. Then, if necessary, use the SET MODULE command (see Section 5.2).
DBG> EXAMINE/SOURCE .%PC module COBOLTEST 162: DISPLAY ES0. DBG>
Note the use of the contents-of operator (.), which specifies the contents of the entity that follows the period. If you do not use the contents-of operator, the debugger tries to find a source line for the PC rather than for the address currently stored in the PC:
DBG> EXAMINE/SOURCE %PC %DEBUG-W-NOSRCLIN, no source line for address 7FFF005C DBG>
The following example shows the use of a numeric path name (1\) to display the source line at the PC value one level down the call stack (at the call to the routine in which execution is paused):
DBG> EXAMINE/SOURCE .1\%PC
In screen mode, the output of an EXAMINE/SOURCE command updates the current source display (see Section 7.2.6).
The debugger uses the EXAMINE/SOURCE command in the following contexts to display source code at the current PC value.
Keypad key 5 (KP5) is bound to the following debugger command sequence:
EXAMINE/SOURCE .%SOURCE_SCOPE\%PC; EXAMINE/INST .%INST_SCOPE\%PC
This command sequence displays the source line and the instruction at which execution is currently paused in the current scope. Pressing KP5 enables you to quickly determine your debugging context.
The predefined source display SRC is an automatically updated display that executes the following built-in command every time the debugger interrupts execution and prompts for commands (see Section 7.4.1):