Kednos PL/I for OpenVMS Systems
User Manual
Previous Contents Index

3.3.7 Controlling Symbol References

In most cases, the way the debugger handles symbols (variable names and so on) is transparent to you. However, the following two areas may require action on your part:

3.3.7.1 Module Setting

To facilitate symbol searches, the debugger loads symbol records from the executable image into a run-time symbol table (RST), where they can be accessed efficiently. Unless a symbol record is in the RST, the debugger cannot recognize or properly interpret that symbol.

Because the RST uses memory, the debugger loads it dynamically, anticipating what symbols you might want to reference during execution. The loading process is called module setting, because all of the symbol records of a given module are loaded into the RST at one time.

At debugger startup, only the module containing the image transfer address is set. As your program executes, whenever the debugger interrupts execution, it sets the module surrounding the current PC value. This lets you reference the symbols that should be visible at that location.

If you try to reference a symbol in a module that has not been set, the debugger issues a warning. For example: 


DBG> EXAMINE K
%DEBUG-W-NOSYMBOL, symbol 'K' is not in symbol table 
DBG>

You must then use the SET MODULE command to set the module containing that symbol manually: 


DBG> SET MODULE MOD3
DBG> EXAMINE K
MOD3\ROUT2\K: 26 
DBG>

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

Note that dynamic module setting may slow down the debugger as more and more modules are set. If performance becomes a problem, you can use the CANCEL MODULE command to reduce the number of set modules, or you can disable dynamic module setting by issuing the SET MODE NODYNAMIC command. (The SET MODE DYNAMIC command enables dynamic module setting.)

3.3.7.2 Resolving Multiply Defined Symbols

The debugger finds the symbols that you reference in commands according to the scope and visibility rules of the currently set language. In general, the debugger first searches for a symbol within the block or routine surrounding the current PC value. If the symbol is not found in that scope region, the debugger searches the nesting program unit, then its nesting unit, and so on. (The precise order of search depends on the currently set language and guarantees that the proper declaration of a multiply defined symbol is selected.)

The debugger allows you to reference symbols throughout your program, not just those that are visible at the current PC value, so that you can set breakpoints in arbitrary areas, examine arbitrary variables, and so on. Therefore, if the symbol is not visible at the current PC value, the debugger also searches other scope regions. First, it searches within the currently executing routine, then the caller of that routine, then its caller, and so on, until the symbol is found. Symbolically, this search list is denoted 0,1,2,..., n, where n is the number of calls in the call stack. Within each of these scope regions, the debugger uses the visibility rules of the currently set language to locate symbols.

If the debugger cannot resolve a symbol ambiguity, it issues a warning. For example: 


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

You can then use a path-name prefix to uniquely specify a declaration of the given symbol. First, use the SHOW SYMBOL command to identify all path names associated with the given symbol; then use the desired path name when referencing the symbol. For example: 


DBG> SHOW SYMBOL Y
data MOD7\ROUT3\BLOCK1\Y 
data MOD4\ROUT2\Y
DBG> EXAMINE MOD4\ROUT2\Y
MOD4\ROUT2\Y: 12 
DBG>

If you need to refer to a particular declaration of Y repeatedly, use the SET SCOPE command to establish a new default scope for symbol lookup. Then, references to Y without a path-name prefix will specify the declaration of Y that is visible in the new scope region. For example: 


DBG> SET SCOPE MOD4\ROUT2
DBG> EXAMINE Y
MOD4\ROUT2\Y: 12 
DBG>

To display the current scope for symbol lookup, use the SHOW SCOPE command. To restore the default scope, use the CANCEL SCOPE command.

3.4 Sample Debugging Session

This section shows a sample debugging session with a PL/I program, SUM, which contains a logic error. Line numbers have been added to facilitate the discussion. 


    1             SUM: PROCEDURE OPTIONS(MAIN); 
    2    1             DECLARE (I,HIGHEST,TOTAL) FIXED; 
    3    1                TOTAL=0; 
    4    1                HIGHEST=1; 
    5    1                DO WHILE (HIGHEST>0); 
    6    2                    GET LIST (HIGHEST) OPTIONS (PROMPT 
    7    2                     ('Type a number greater than 0, or 0 to quit: ')); 
    8    2                    IF HIGHEST <=0 
    9    2                     THEN 
   10    2                        STOP; 
   11    2                    DO I=1 TO HIGHEST; 
   12    3                        TOTAL=TOTAL+I; 
   13    3                        END; 
   14    2                    PUT SKIP EDIT 
   15    2                     ('The sum of integers from 1 through', 
   16    2                     HIGHEST,' is',TOTAL) 
   17    2                     (A,F(10),A,F(10)); 
   18    2                    PUT SKIP; 
   19    2                    END;  /* DO WHILE */ 
   20    1        END SUM;

This program prompts for a number and prints the sum of the integers from 1 through the number entered. The problem in the program occurs because the variable TOTAL is not reinitialized when a new number is entered; the statement assigning the value 0 to TOTAL occurs before the loop instead of within it.

Initially, you might compile, link, and run the program as follows: 


$ PLI SUM
$ LINK SUM
$ RUN SUM
Type a number greater than 0, or 0 to quit: 5
 
The sum of integers from 1 through         5 is        15
Enter a number: 4
The sum of integers from 1 through         4 is        25
Type a number greater than 0, or 0 to quit: 0
$
The program returns a correct sum for the first number you enter, but the sum for the second number is obviously too high.

To debug the program, you must compile and link with the debugger. (If you want a listing with line numbers to refer to during the debugging session, include the /LIST qualifier with the PLI command, and then print the listing file that results; you need not specify the file type because the PRINT command searches for the LIS file type by default.) For example: 


$ PLI/DEBUG/LIST/NOOPTIMIZE SUM
$ LINK/DEBUG SUM
$ PRINT SUM
You are now ready to begin a debugging session. The terminal session is keyed to the numbered notes that follow. 


$ RUN SUM
 
                    VAX DEBUG Version <VMS_VERSION> 
 
%DEBUG-I-INITIAL, language is PLI, module set to 'SUM'  (1)
DBG> SET BREAK %LINE 7   (2)
DBG> GO   (3)
break at SUM\%LINE 7   (4)
     7:              ('Type a number greater than 0, or 0 to quit: ')); 
DBG> EXAMINE TOTAL
SUM\TOTAL:      0   (5)
DBG> GO
Type a number greater than 0, or 0 to quit: 5
 
The sum of integers from 1 through         5 is        15   (6)
 
break at SUM\%LINE 7
     7:              ('Type a number greater than 0, or 0 to quit: '));   (7)
DBG> EXAMINE TOTAL
SUM\TOTAL:     15   (8)
DBG> DEPOSIT TOTAL=0   (9)
DBG> GO
Type a number greater than 0, or 0 to quit: 4
The sum of integers from 1 through         4 is        10   (10)
 
break at SUM\%LINE 7
     7:              ('Type a number greater than 0, or 0 to quit: ')); 
DBG> GO
Type a number greater than 0, or 0 to quit: 0 (11)
%DEBUG-I-EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion'
DBG> EXIT   (12)
$

  1. When you issue the RUN command, the debugger displays an informational message and the DBG> prompt. You are now in the default noscreen mode. The lines of source code are displayed as they are executed, by default.
  2. You decide that the problem may lie with the initialization of the variable TOTAL. You can test this hypothesis by examining the value of TOTAL each time you enter a new number. To stop the program at the point at which you can do this, you set a breakpoint at line 7.
  3. The GO command starts program execution.
  4. When line 7 is reached, the debugger interrupts program execution and displays the source line at which the breakpoint was set.
  5. You use the EXAMINE command to determine the current value of the variable TOTAL. Its value is 0, as expected at this point.
  6. The GO command resumes program execution. The program now prompts you for a number. You type 5. The program's response is correct.
  7. The debugger again reaches the breakpoint at line 7 and displays the source line.
  8. You examine the variable TOTAL with the EXAMINE command. Its value is 15, not 0 as it should be. This indicates that the assignment statement that initializes TOTAL is misplaced.
  9. The DEPOSIT command replaces the contents of TOTAL with 0, thus allowing the program to return a correct result the next time through the loop.
  10. The GO command resumes program execution. The result is correct.
  11. When you enter a 0 in response to the prompt, the program exits, causing the debugger to display a message that indicates the termination status.
  12. The EXIT command terminates the debugging session.
You can now correct the program so that it reinitializes the variable TOTAL correctly.

3.5 Debugger Command Summary

This section lists all of the debugger commands and any related DCL commands in functional groupings, along with brief descriptions.

During a debugging session, you can get online HELP on any command and its qualifiers by typing the HELP command followed by the name of the command in question. The HELP command has the following form: 

HELP debugger command

3.5.1 Starting and Terminating a Debugging Session

($) RUN 1 Invokes the debugger if LINK/DEBUG was used
($) RUN/[NO]DEBUG 1 Controls whether the debugger is invoked when the program is executed
Ctrl/z or EXIT Ends a debugging session, executing all exit handlers
QUIT Ends a debugging session without executing any exit handlers declared in the program
Ctrl/y Interrupts a debugging session and returns you to the DCL level
Ctrl/c Has the same effect as Ctrl/y, unless the program has a Ctrl/c service routine
($) CONTINUE 1 Resumes a debugging session after a Ctrl/y interruption
($) DEBUG 1 Resumes a debugging session after a Ctrl/y interruption but returns you to the debugger prompt
ATTACH Passes control of your terminal from the current process to another process (similar to the DCL command ATTACH)
SPAWN Creates a subprocess; lets you issue DCL commands without interrupting your debugging context (similar to the DCL command SPAWN)
1This is a DCL command, not a debugger command.

3.5.2 Controlling and Monitoring Program Execution
GO Starts or resumes program execution
STEP Executes the program up to the next line, instruction, or specified instruction
SET
SHOW STEP 		Establishes or displays the default qualifiers for the STEP command
SET
SHOW
CANCEL BREAK 		Sets, displays, or cancels breakpoints
SET
SHOW
CANCEL TRACE 		Sets, displays, or cancels tracepoints
SET
SHOW
CANCEL WATCH 		Sets, displays, or cancels watchpoints
SET
CANCEL
  • EXCEPTION
  • BREAK
Sets or cancels exception breakpoints
SHOW CALLS Identifies the currently active routine calls
SHOW STACK Gives additional information about the currently active routine calls
CALL Calls a routine

3.5.3 Examining and Manipulating Data
EXAMINE Displays the value of a variable or the contents of a program location
DEPOSIT Changes the value of a variable or the contents of a program location
EVALUATE Evaluates a language or address expression

3.5.4 Controlling Type Selection and Symbolization
SET
SHOW
CANCEL RADIX 		Establishes the radix for data entry and display, displays the radix, or restores the radix
SET
SHOW
CANCEL TYPE 		Establishes the type to be associated with untyped program locations, displays the type, or restores the type
SET MODE [NO]G_FLOAT Controls whether double-precision floating-point constants are interpreted as G_FLOAT or D_FLOAT
SET MODE [NO]LINE Controls whether code locations are displayed in terms of line numbers or routine-name + byte offset
SET MODE [NO]SYMBOLIC Controls whether code locations are displayed symbolically or in terms of numeric addresses
SYMBOLIZE Converts a virtual address to a symbolic address

3.5.5 Controlling Symbol Lookup
SHOW SYMBOL Displays symbols in your program
SET
SHOW
CANCEL MODULE 		Sets a module by loading its symbol records into the debugger's symbol table, identifies a set module, or cancels a set module
SET
SHOW
CANCEL IMAGE 		Sets a shareable image by loading data structures into the debugger's symbol table, identifies a set image, or cancels a set image
SET MODE [NO]DYNAMIC Controls whether modules and shareable images are set automatically when the debugger interrupts execution
SET
SHOW
CANCEL SCOPE 		Establishes, displays, or restores the scope for symbol lookup

3.5.6 Displaying Source Code
TYPE Displays lines of source code
EXAMINE/SOURCE Displays the source code at the location specified by the address expression
SET
SHOW
CANCEL SOURCE 		Creates, displays, or cancels a source directory search list
SEARCH Searches the source code for the specified string
SET
SHOW SEARCH 		Establishes or displays the default qualifiers for the SEARCH command
SET
SHOW
  • MAX_SOURCE_
  • FILES
Establishes or displays the maximum number of source files that may be kept open at one time
SET
SHOW MARGINS 		Establishes or displays the left and right margin settings for displaying source code

3.5.7 Using Screen Mode
SET MODE [NO]SCREEN Enables or disables screen mode
SET MODE [NO]SCROLL Controls whether an output display is updated line by line or once per command
DISPLAY Modifies an existing display
SET
SHOW
CANCEL DISPLAY 		Creates, identifies, or deletes a display
  • SET
  • SHOW
  • CANCEL
WINDOW 		Creates, identifies, or deletes a window definition
SELECT Selects a display for a display attribute
SHOW SELECT Identifies the displays selected for each of the display attributes
SCROLL Scrolls a display
SAVE Saves the current contents of a display and writes it to another display
EXTRACT Saves a display or the current screen state and writes it to a file
EXPAND Expands or contracts a display
MOVE Moves a display across the screen
SET
SHOW TERMINAL 		Establishes or displays the height and width of the screen
Ctrl/w or
DISPLAY/REFRESH 		Refreshes the screen

3.5.8 Editing Source Code
EDIT Invokes an editor during a debugging session
SET
SHOW EDITOR 		Establishes or identifies the editor invoked by the EDIT command

3.5.9 Defining Symbols
DEFINE Defines a symbol as an address, command, or value
DELETE or UNDEFINE Deletes symbol definitions
SET
SHOW DEFINE 		Establishes or displays the default qualifier for the DEFINE command
SHOW SYMBOL/DEFINED Identifies symbols that have been defined

3.5.10 Using Keypad Mode
SET MODE [NO]KEYPAD Enables or disables keypad mode
DEFINE/KEY Creates key definitions
DELETE/KEY or
UNDEFINE/KEY 		Deletes key definitions
SET KEY Establishes the key definition state
SHOW KEY Displays key definitions

3.5.11 Using Command Procedures and Log Files
DECLARE Defines parameters to be passed to command procedures
SET
SHOW LOG 		Specifies or identifies the debugger log file
SET OUTPUT [NO]LOG Controls whether a debugging session is logged
SET OUTPUT [NO]SCREEN_LOG Controls whether, in screen mode, the screen contents are logged as the screen is updated
SET OUTPUT [NO]VERIFY Controls whether debugger commands are displayed as a command procedure is executed
SHOW OUTPUT Displays the current output options established by the SET OUTPUT command
SET
SHOW ATSIGN 		Establishes or displays the default file specification that the debugger uses to search for command procedures
@file-spec Executes a command procedure

Previous Next Contents Index