Programming Language Support

The debugger recognizes the syntax, data types, operators, expressions,scoping rules, and other constructs of a supported language. You can change the debugging context from one language to another (with the SET LANGUAGE command) during a debugging session.

Symbolic Debugging

The debugger is a symbolic debugger. You can refer to program locations by the symbols used in your program — the names of variables, routines, labels, and so on. You can also specify explicit memory addresses or machine registers if you choose.

Support for All Data Types

The debugger recognizes the data types generated by the compilers of all supported languages, such as integer, floating-point, enumeration, record,array, and so on, and displays the values of each program variable according to its declared type.

Flexible Data Format

With the debugger, you can enter and display a variety of data forms and data types. The source language of the program determines the default format for the entry and display of data. However, you can select other formats as needed.

Starting or Resuming Program Execution

Once the program is under control of the debugger, you can start or resume program execution with the GO or STEP command. The GO command causes the program to execute until specified events occur (the PC points to a designated line of code, a variable is modified, an exception is signaled, or the program terminates). You can use the STEP command to execute a specified number instructions or lines of source code, or until the program reaches the next instruction of a specified class.

Breakpoints

You can set a breakpoint with the SET BREAK command, to suspend program execution at a specified location in order to check the current status of the program. You can also direct the debugger to suspend execution when the program is about to execute an instruction of a specific class. You can also suspend execution when certain events occur, such as exceptions and tasking (multithread) events.

Tracepoints

You can set a tracepoint with the SET TRACE command, to cause the debugger to report each time that program execution reaches a specified location (that is, each time the program counter (PC) references that location). As with the SET BREAK command, you can also trace the occurrence of classes of instructions and monitor the occurrence of certain events, such as exceptions and tasking (multithread) events.

Watchpoints

You can set a watchpoint with the SET WATCH command to cause the debugger to suspend program execution whenever a particular variable (or other specified memory location) has been modified, at which point the debugger reports the old and new values of the variable.

Manipulation of Variables and Program Locations

You can use the EXAMINE command to determine the value of a variable or memory location. You can use the DEPOSIT command to change that value. You can then continue execution of the program to determine the effect of the change without having to recompile, relink, and rerun the program.

Evaluation of Expressions

You can use the EVALUATE command to compute the value of a source-language expression or an address expression in the syntax of the language to which the debugger is currently set.

Control Structures

You can use logical control structures (FOR, IF, REPEAT, WHILE) in commands to control the execution of other commands.

Shareable Image Debugging

You can debug shareable images (images that are not directly executable). The SET IMAGE command enables you to access the symbols declared in as shareable image (that was compiled and linked with the /DEBUG qualifiers).

Multiprocess Debugging

You can debug multiprocess programs (programs that run in more than one process). The SHOW PROCESS and SET PROCESS commands enable you to display process information and to control the execution of images in individual processes.

Task Debugging

You can debug tasking programs (also known as multithread programs). These programs use POSIX Threads Library or POSIX 1003.1b services, or use language-specific tasking services (for example, Ada tasking programs). The SHOW TASK and SET TASK commands enable you to display task information and to control the execution of individual tasks.

Terminal and Workstation Support

The debugger supports all VT-series terminals and VAX workstations.

Online Help

Online help is always available during a debugging session. Online help contains information about all debugger commands and additional selected topics.

Source Code Display

During a debugging session, you can display the source code for program modules written in any of the languages supported by the OpenVMS Debugger.

Screen Mode

In screen mode, you can capture and display various kinds of information in scrollable display units. You can move these display units around the screen and resize them as needed. Automatically updated source, instruction, and register displays units are available. You can selectively direct debugger input, output, and diagnostic messages to specific display units. You can also create display units to capture the output of specific command sequences.

Kept Debugger

The kept debugger enables you to run different program images or rerun the same image from the current debugging session without having to first exit and restart the debugger. When you rerun a program, you can choose to retain or cancel any previously set breakpoints, as well as most trace points and watch points.

DECwindows Motif User Interface

The OpenVMS Debugger has an optional HP DECwindows Motif graphical user interface (GUI) that provides access to common debugger commands by means of push buttons, pull down menus, and pop up menus. The GUI is an optional enhancement to the debugger command line interface that is available on workstations running DECwindows Motif. When using the GUI, you have full command-line access to all debugger commands that are relevant within a DECwindows Motif environment.

Microsoft Windows Interface

The OpenVMS Debugger has an optional client/server configuration that allows you to access the debugger and its functions from a PC running on your supplied Microsoft operating system. This debugger implementation has a debug server that runs on OpenVMS on an Alpha or Integrity server CPU, and a debug client interface that runs on Microsoft operating systems on an Intel or Alpha CPU.

Client/Server Configuration

The client/server configuration allows you to debug programs that run on an OpenVMS node remotely from another OpenVMS node using the DECwindows Motif user interface, or from a PC using the Microsoft Windows interface. Up to 31 debug clients can simultaneously access the same debug server,which allows many debugging options.

Keypad Mode

When you start the debugger, several predefined debugger command sequences are assigned to the keys of the numeric keypad of the VT52, VT100, and LK201 keyboards. You can also create your own key definitions.

Source Editing

As you find errors during a debugging session, you can use the EDIT command to use any editor available on your system. You can specify the editor with the SET EDITOR command. If you use the Language-Sensitive Editor (LSE), the editing cursor is automatically positioned within the source file corresponding to the source code that appears in the screen-mode source display.

Command Procedures

You can direct the debugger to execute a command procedure (a file of debugger commands) to re-create a debugging session, to continue a previous session, or to avoid typing the same debugger commands many times during a debugging session. In addition, you can pass parameters to command procedures.

Initialization Files

You can create an initialization file that contains debugger commands to set default debugging modes, screen display definitions, keypad key definitions, symbol definitions, and so on. Upon start up, the OpenVMS Debugger automatically executes the initialization file to create the predefined debugging environment.

Log Files

You can create a log file to contain a record of command input and debugger output. You can then use the log file to analyze the debugging session, or edit the file for use as a command procedure in subsequent debugging sessions.

Symbol Definitions

You can define your own symbols to represent lengthy commands, address expressions, or values in abbreviated form.

$ CC/DEBUG/NOOPTIMIZE INVENTORY,FORMS

Note that the /DEBUG and /NOOPTIMIZE qualifiers are compiler command defaults for some languages. These qualifiers are used in the example for emphasis. (For information about compiling programs in a specific language, see the documentation for that language.)

The /DEBUG qualifier in the compiler command in Example 1.1, “Compiling a Program with the /DEBUG Qualifier” directs the compiler to include the symbol information associated with FORMS.C and INVENTORY.C in object modules FORMS.OBJ and INVENTORY.OBJ, respectively. This enables you to refer to the symbolic names of variables, routines,and other declared symbols while debugging the program. Only object files created with the /DEBUG qualifier contain symbol information. You can control whether to include all symbol information or only that required to trace program flow (see Section 5.1.1, “Compiling”).

Some compilers optimize the object code to reduce the size of the program or to make it run faster. In such cases the object code does not always match the source code, which can make debugging more difficult. To avoid this, compile the program with the /NOOPTIMIZE command qualifier (or equivalent). After the non-optimized program has been debugged, you can recompile and test it again without the /NOOPTIMIZE qualifier to take advantage of optimization. Section 14.1, “Debugging Optimized Code” describes some of the effects of optimization.

$ LINK/DEBUG FORMS,INVENTORY 

In Example 1.2, the /DEBUG qualifier in the LINK command directs the linker to include in the executable image all symbol information that is contained in the object modules being linked. Most languages require that you specify all included object modules in the LINK command. See Section 5.1.3, “Linking” for more details on how to control symbol information with the LINK command.

$ CC/DEBUG/NOOPTIMIZE TESTPROGRAM
$ LINK/DSF=TESTDISK:[TESTDIR]TESTPROGRAM.DSF TESTPROGRAM
$ DEFINE DBG$IMAGE_DSF_PATH TESTDISK:[TESTDIR]
$ DEBUG/KEEP TESTPROGRAM

See Section 5.1.5, “Creating Separate Symbol Files (Alpha Only)” for more information about debugging programs that have separate symbol files. See the VSI OpenVMS Linker Utility Manual for more information about using the /DSF qualifier.

In addition to passing symbol information to the executable image, the LINK /DEBUG command causes the image activator to start the debugger if you execute the resulting image with the DCL command RUN. (See Section 1.6, “Starting the Debugger by Running a Program”.)

$ RUN/NODEBUG FORMS

This is convenient for checking your program once you think it is error free. Note that the data required by the debugger occupies space within the executable image. When your program is correct, you can link your program again without the /DEBUG qualifier. This creates an image with only trace back data in the debug symbol table, which creates a smaller executable file.

This section explains how to start the kept debugger from DCL level ($) and bring your program under debugger control. Section 1.6, “Starting the Debugger by Running a Program” and Section 1.7, “Starting the Debugger After Interrupting a Running Program” describe other ways to invoke the debugger.

The message displayed indicates that this debugging session is initialized fora C program and that the name of the main program unit (the module containing the image transfer address) is FORMS. The initialization sets up language-dependent debugger parameters. These parameters control the way the debugger parses names and expressions, formats debugger output, and so on. See Section 4.1.9, “Language Dependencies and the Current Language” for more information about language-dependent parameters.

%DEBUG-I-NOTATMAIN, Type GO to reach main program

With some of these programs (for example, Ada programs), the temporary breakpoint enables you to debug the initialization code using full symbolic information. See Section 14.3, “Debugging Multilanguage Programs” for more information.

At this point, you can debug your program as explained in Chapter 2, Getting Started with the Debugger .

RUN and RERUN Command Options for Programs That Require Arguments

Some programs require arguments. This section explains how to use the RUN and RERUN commands with the /ARGUMENTS and /COMMAND qualifiers when debugging a program with the kept debugger.

After starting the kept debugger, you can specify the image to be debugged by entering the RUN command with an image name, or the RUN /COMMAND command with a DCL foreign command. Note that you can specify a DCL foreign command only with the /COMMAND qualifier to the RUN command.

You can specify a list of arguments with the /ARGUMENTS qualifier to the RUN and RERUN commands.

#include <stdio.h>

main(int argc, char *argv[])
{
  int i;

  for (i = 0; i < argc; i++)
    printf("%s\n", argv[i]);
}

$ cc/debug/noopt echoargs.c
$ link/debug echoargs

$ ECHO == "$ sys$disk:[]echoargs.exe"

RUN with /COMMAND and /ARGUMENTS

$ DEBUG/KEEP
     Debugger Banner and Version Number
DBG> RUN/COMMAND="echo"/ARGUMENTS="fa sol la mi"
%DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS
%DEBUG-I-NOTATMAIN,Type GO to reach main program
DBG> GO
break at routine ECHOARGS\main
   1602: for (i = 0; i < argc; i++)
DBG> GO
_dsa1:[jones.test]echoargs.exe;2
fa
sol
la
mi
%DEBUG-I-EXITSTATUS,is '%SYSTEM-S-NORMAL, Normal successful completion'

This section of the debugger session shows the use of the RERUN command with the /ARGUMENTS qualifier to run the same image again, with new arguments fee fii foo fum. (If you omit the /ARGUMENTS qualifier, the debugger reruns the program with the arguments used previously.)

DBG> RERUN/ARGUMENTS="fee fii foo fum"
%DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS
%DEBUG-I-NOTATMAIN,Type GO to reach main program
DBG> GO
break at routine ECHOARGS\main
   1602: for (i = 0; i < argc; i++)
DBG> GO
_dsa1:[jones.test]echoargs.exe;2
fee
fii
foo
fum
%DEBUG-I-EXITSTATUS,is '%SYSTEM-S-NORMAL, Normal successful completion'

This section of the debugging session uses the RUN command to invoke a fresh image of echoargs, with the /ARGUMENTS qualifier to specify a new set of arguments a b c.

DBG> RUN/ARGUMENTS="a b c" echoargs
%DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS
%DEBUG-I-NOTATMAIN,Type GO to reach main program
DBG> GO
break at routine ECHOARGS\main
   1602: for (i = 0; i < argc; i++)
DBG> GO
_dsa1:[jones.test]echoargs.exe;2
a
b
c
%DEBUG-I-EXITSTATUS,is '%SYSTEM-S-NORMAL, Normal successful completion'
DBG> quit

RUN Command Restrictions

DBG> RERUN
%DEBUG-I-NOTATMAIN, Language: C, Module: ECHOARGS
%DEBUG-I-NOTATMAIN, Type GO to reach main program

DBG> 

The RERUN command terminates the image you were debugging and brings a fresh copy of that image under debugger control, pausing at the start of the main source module as if you had used the RUN command (see Section 1.3.1, “Starting the Kept Debugger”).

When you use the RERUN command you can save the current state (activated or deactivated) of any breakpoints, trace points, and static watch points. Note that the state of a particular nonstatic watchpoint might not be saved, depending on the scope of the variable being watched relative to the main program unit (where execution restarts). RERUN /SAVE is the default. To clear all breakpoints tracepoints, and watchpoints, enter RERUN /NOSAVE.

The RERUN command invokes the same version of the image that is currently under debugger control. To debug a different version of that program (or a different program) from the same debugging session, use the RUN command. To rerun a program with new arguments, use the /ARGUMENTS qualifier (see the section called “RUN and RERUN Command Options for Programs That Require Arguments”).

DBG> RUN TOTALS
%DEBUG-I-NOTATMAIN, Language: FORTRAN, Module: TOTALS
DBG>

The debugger loads the program and pauses execution at the start of the main source module.

For more information about startup conditions and restrictions, see Section 1.3.1, “Starting the Kept Debugger”.

For information about all RUN command options, see the debugger RUN command description.

Noscreen mode is the default, line-oriented mode of displaying input and output. The interactive examples throughout this chapter, excluding Section 2.2.2, “Screen Mode”, show noscreen mode.

DBG> TYPE 7
module SWAP_ROUTINES
     7:        TEMP := A;
DBG>

DBG> TYPE TEST\16:21

Path names are discussed in more detail in Section 2.3.2, “Executing the Program by Step Unit”, with the STEP command.

You can also use the EXAMINE /SOURCE command to display the source line for a routine or any other program location that is associated with an instruction.

The debugger also displays source lines automatically when it suspends execution at a breakpoint or watch point, after a STEP command, or when a trace point is triggered (see Section 2.3, “Controlling and Monitoring Program Execution”).

After displaying source lines at various locations in your program, you can redisplay the location at which execution is currently paused by pressing KP5.

To switch to noscreen mode from screen mode, press PF1 PF3 (or type SET MODE NOSCREEN). You can use the TYPE and EXAMINE /SOURCE commands in screen mode as well as noscreen mode.

Screen mode provides the easiest way to view your source code. To switch to screen mode, press PF3 (or type SET MODE SCREEN). In screen mode, by default the debugger splits the screen into three displays named SRC, OUT, and PROMPT, as shown in Figure 2.2, “Default Screen Mode Display Configuration”.

The SRC display shows the source code of the module in which execution is currently paused. An arrow in the left column points to the source line corresponding to the current value of the program counter (PC). The PC is a register that contains the memory address of the instruction to be executed next. The line numbers, which are assigned by the compiler, match those in a listing file. As you execute the program, the arrow moves down and the source code is scrolled vertically to center the arrow in the display.

The OUT display captures the debugger's output in response to the commands that you enter. The PROMPT display shows the debugger prompt, your input (the commands that you enter), debugger diagnostic messages, and program output.

You can scroll both SRC and OUT to see whatever information might scroll beyond the display window's edge. Press KP3 repeatedly as needed to select the display to be scrolled (by default, SRC is scrolled). Press KP8 to scroll up and KP2 to scroll down. Scrolling a display does not affect program execution.

%DEBUG-I-SOURCESCOPE, Source lines not available for .0
\%PC.Displaying source in a caller of the current routine.
DBG>

In such cases, the arrow in the SRC display identifies the line that contains code following the call statement in the calling routine.

Use the GO command to start or resume program execution.

With most programming languages, when you bring a program under debugger control, execution is initially paused directly at the beginning of the main program. Entering a GO command at this point quickly enables you to test for an infinite loop or an exception.

If an infinite loop occurs during execution, the program does not terminate, so the debugger prompt does not reappear. To obtain the prompt, interrupt execution by pressing Ctrl/C (see Section 1.4, “Interrupting Program Execution and Aborting Debugger Commands”). If you are using screen mode, the pointer in the source display indicates where execution stopped. You can also use the SHOW CALLS command to identify the currently active routine calls on the call stack (see Section 2.3.3, “Determining Where Execution Is Paused”).

If an exception that is not handled by your program is signaled, the debugger interrupts execution at that point so that you can enter commands. You can then look at the source display and a SHOW CALLS display to find where execution is paused.

The most common use of the GO command is in conjunction with breakpoints, tracepoints, and watchpoints, as described in Section 2.3.4, “Suspending Program Execution with Breakpoints”, Section 2.3.5, “Tracing Program Execution with Tracepoints”, and Section 2.3.6, “Monitoring Changes in Variables with Watchpoints”, respectively. If you set a breakpoint in the path of execution and then enter the GO command, execution is paused at that breakpoint. Similarly, if you set a tracepoint, execution is monitored through that tracepoint. If you set a watchpoint, execution is paused when the value of the watched variable changes.

Use the STEP command to execute the program one or more step units at a time.

DBG> STEP
stepped to TEST\COUNT\%LINE 27
     27:   X := X + 1;
DBG>

Execution is now paused at the first machine-code instruction for line 27 within routine COUNT of module TEST.

When displaying a program symbol (for example, a line number, routine name, or variable name), the debugger always uses a path name. A path name consists of the symbol plus a prefix that identifies the symbol's location. In the previous example, the path name is TEST \COUNT \%LINE27. The leftmost element of a path name is the module name. Moving toward the right, the path name lists any successively nested routines and blocks that enclose the symbol. A backslash character (\) is used to separate elements (except when the language is Ada, where a period is used to parallel Ada syntax).

A path name uniquely identifies a symbol of your program to the debugger. In general, you need to use path names in commands only if the debugger cannot resolve a symbol ambiguity in your program (see Section 2.5, “Controlling Access to Symbols in Your Program”). Usually the debugger can determine the symbol you mean from its context.

When using the STEP command, note that only those source lines for which code instructions were generated by the compiler are recognized as executable lines by the debugger. The debugger skips over any other lines - for example, comment lines.

You can specify different stepping modes, such as stepping by instruction rather than by line (SET STEP INSTRUCTION). Also, by default, the debugger steps over called routines-execution is not paused within a called routine, although the routine is executed. By entering the SET STEP INTO command, you direct the debugger to suspend execution within called routines as well as within the routine in which execution is currently paused (SET STEP OVER is the default mode).

Use the SHOW CALLS command when you are unsure where execution is paused during a debugging session (for example, after a Ctrl/C interruption).

DBG> SHOW CALLS
module name   routine name   line   rel PC     abs PC
*TEST         PRODUCT        18     00000009   0000063C
*TEST         COUNT          47     00000009   00000647
*MY_PROG      MY_PROG        21     0000000D   00000653
DBG>

This example indicates that execution is paused at line 18 of routine PRODUCT (in module TEST), which was called from line 47 of routine COUNT (in module TEST), which was called from line 21 of routine MY_PROG (in module MY_PROG).

The SET BREAK command enables you to select locations at which to suspend program execution (breakpoints).You can then enter commands to check the call stack, examine the current values of variables, and so on. You resume execution from a breakpoint with the GO or STEP commands.

DBG> SET BREAK COUNT
DBG> GO
   .
   .
   .
break at routine PROG2\COUNT
     54:  procedure COUNT(X, Y:INTEGER);
DBG>

At this breakpoint, you can use the STEP command to step through routine COUNT and then use the EXAMINE command (discussed in Section 2.4.1, “Displaying the Value of a Variable”) to check on the values of X and Y.

When using the SET BREAK command, you can specify program locations using various kinds of address expressions (for example, line numbers, routine names, memory addresses, byte offsets). With high-level languages, you typically use routine names, labels, or line numbers, possibly with path names to ensure uniqueness.

DBG> SET BREAK %LINE 41

DBG> SET BREAK SCREEN_IO\%LINE 58

DBG> SET BREAK/LINE
DBG> SET BREAK/CALL

You can set breakpoints on events, such as exceptions, or state transitions in tasking programs.

You can conditionalize a breakpoint (with a WHEN clause)or specify that a list of commands be executed at the breakpoint (with a DO clause).

To display the current breakpoints, enter the SHOW BREAK command.

To deactivate a breakpoint, enter the DEACTIVATE BREAK command, and specify the program location exactly as you did when setting the breakpoint. This causes the debugger to ignore the breakpoint during program execution. However, you can activate it at a later time, for example, when you rerun the program (see Section 1.3.3, “Rerunning the Same Program from the Kept Debugger”). A deactivated breakpoint is listed as such in a SHOW BREAK display.

To activate a breakpoint, use the ACTIVATE BREAK command. Activating a breakpoint causes it to take effect during program execution.

The commands DEACTIVATE BREAK/ALL and ACTIVATE BREAK/ALL operate on all breakpoints and are particularly useful when rerunning a program.

To cancel a breakpoint, use the CANCEL BREAK command. A canceled breakpoint is no longer listed in a SHOW BREAK display.

The SET TRACE command enables you to select locations for tracing the execution of your program (tracepoints), without stopping its execution. After setting a tracepoint, you can start execution with the GO command and then monitor the path of execution, checking for unexpected behavior. By setting a tracepoint on a routine, you can also monitor the number of time sit is called.

DBG> SET TRACE COUNT
DBG> GO
trace at routine PROG2\COUNT
     54:  procedure COUNT(X, Y:INTEGER);
   .
   .
   .

This is the only difference between a breakpoint and a tracepoint. When using the SET TRACE command, you specify address expressions, qualifiers, and optional clauses exactly as with the SET BREAK command. The commands SHOW TRACE, ACTIVATE TRACE, DEACTIVATE TRACE, and CANCEL TRACE operate on tracepoints in a manner similar to the corresponding commands for breakpoints (see Section 2.3.4, “Suspending Program Execution with Breakpoints”).

The SET WATCH command enables you to specify program variables that the debugger monitors as your program executes. This process is called setting watchpoints. If the program modifies the value of a watched variable, the debugger suspends execution and displays information. The debugger monitors watchpoints continuously during program execution. (Note that you can also use the SET WATCH command to monitor arbitrary program locations, not just variables.)

DBG> SET WATCH TOTAL

DBG> SET WATCH TOTAL
DBG> GO
   .
   .
   .
watch of SCREEN_IO\TOTAL at SCREEN_IO\%LINE 13
     13:   TOTAL = TOTAL + 1;
    old value: 16
    new value: 17
break at SCREEN_IO\%LINE 14
     14:   POP(TOTAL);
DBG>

In this example, a watchpoint is set on the variable TOTAL and execution is started. When the value of TOTAL changes, execution is paused. The debugger announces the event ("watch of …"), identifying where TOTAL changed (the beginning of line 13) and the associated source line. The debugger then displays the old and new values and announces that execution has been paused at the beginning of the next line (14). Finally, the debugger prompts for another command. When a change in a variable occurs at a point other than the beginning of a source line, the debugger gives the line number plus the byte offset from the beginning of the line.

On Alpha systems, you can set a watchpoint on a nonstatic variable by setting a tracepoint on the defining routine and specifying a DO clause to set the watchpoint whenever execution reaches the tracepoint. Since a nonstatic variable is allocated on the stack or in a register and exists only when its defining routine is active (on the call stack), the variable name is not always meaningful in the way that a static variable name is.

DBG> SET TRACE/NOSOURCE ROUT3 DO (SET WATCH Y)
DBG> GO
   .
   .
   .
trace at routine MOD4\ROUT3
%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every
                   instruction
   .
   .
   .
watch of MOD4\ROUT3\Y at MOD4\ROUT3\%LINE 16
   16:      Y := 4
   old value:    3
   new value:    4
break at MOD4\ROUT3\%LINE 17
   17:     SWAP(X, Y);
DBG>

When execution returns to the calling routine, the nonstatic variable is no longer active, so the debugger automatically cancels the watchpoint and issues a message to that effect.

On Alpha and Integrity servers, the debugger treats all watchpoints as nonstatic watchpoints.

The commands SHOW WATCH, ACTIVATE WATCH, DEACTIVATE WATCH, and CANCEL WATCH operate on watchpoints in a manner similar to the corresponding commands for breakpoints (see Section 2.3.4, “Suspending Program Execution with Breakpoints”). However, a nonstatic watchpoint exists only as long as execution remains within the scope of the variable being watched.

EXAMINE address-expression

The debugger recognizes the compiler-generated data type of the variable you specify and retrieves and formats the data accordingly. The following examples show some uses of the EXAMINE command.

DBG> EXAMINE EMPLOYEE_NAME
PAYROLL\EMPLOYEE_NAME:
    "Peter C. Lombardi"
DBG>

DBG> EXAMINE WIDTH, LENGTH, AREA
SIZE\WIDTH:   4
SIZE\LENGTH:  7
SIZE\AREA:    28
DBG>

DBG> EXAMINE REAL_ARRAY
PROG2\REAL_ARRAY
   (1, 1):       27.01000
   (1, 2):       31.00000
   (1, 3):       12.48000
   (2, 1):       15.08000
   (2, 2):       22.30000
   (2, 3):       18.73000
DBG>

DBG> EXAMINE CHAR_ARRAY(4)
PROG2\CHAR_ARRAY(4): 'm'
DBG>

DBG> EXAMINE PART
INVENTORY\PART:
    ITEM:      "WF-1247"
    PRICE:     49.95
    IN_STOCK:  24
DBG>

DBG> EXAMINE IN_STOCK OF PART
INVENTORY\IN-STOCK of PART:
    IN_STOCK:  24
DBG>

You can use the EXAMINE command with any kind of address expression (not just a variable name) to display the contents of a program location. The debugger associates certain default data types with untyped locations. If you want the data interpreted and displayed in some other data format you can override the defaults for typed and untyped locations.

DEPOSIT address-expression = language-expression

The DEPOSIT command is like an assignment statement in most programming languages.

In the following examples, the DEPOSIT command assigns new values to different variables. The debugger checks that the value assigned, which can be a language expression, is consistent with the data type and dimensional constraints of the variable.

DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84"

DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 10

DBG> DEPOSIT C_ARRAY(12) := 'K'

DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172

DBG> DEPOSIT X = -14
%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds
        at or near DEPOSIT

As with the EXAMINE command, you can specify any kind of address expression (not just a variable name) with the DEPOSIT command. You can override the defaults for typed and untyped locations if you want the data interpreted in some other data format.

To facilitate symbol searches, the debugger loads symbol information from the executable image into a run-time symbol table (RST), where that information can be accessed efficiently. Unless symbol information is in the RST, the debugger does not recognize or properly interpret the associated symbols.

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 atone time.

Initially, only the module containing the image transfer address is set. Subsequently, whenever execution of the program is interrupted, the debugger sets the module that contains the routine in which execution is paused. This enables you to reference the symbols that should be visible at that location.

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

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 are set.

Dynamic module setting can slow the debugger down 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 entering the SET MODE NODYNAMIC command (SET MODE DYNAMIC enables dynamic module setting).

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. First, it uses the scope and visibility rules of the currently set language. In addition, because the debugger permits you to specify symbols in arbitrary modules (to set breakpoints and so on), the debugger uses the ordering of routine calls on the call stack to resolve symbol ambiguities.

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

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

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.

DBG> STEP/INTO
stepped to routine TEST\PRODUCT
     6:    function PRODUCT (X, Y : INTEGER) return INTEGER is
DBG>

After the STEP /INTO command executes, subsequent STEP commands revert to the default behavior.

In contrast, the SET STEP command enables you to establish new defaults for the STEP command. These defaults remain in effect until another SET STEP command is entered. For example, the SET STEP INTO command causes subsequent STEP commands to behave like STEP /INTO (SET STEP LINE causes subsequent STEP commands to behave like STEP /LINE).

There is a SET STEP command parameter for each STEP command qualifier.

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

By default, when the PC is at a call statement and you enter the STEP command, the debugger steps over the called routine. Although the routine is executed, execution is not paused within the routine but, rather, on the beginning of the line that follows the call statement. When stepping by instruction, execution is paused on the instruction that follows a called routine's return instruction.

DBG> STEP
stepped to TEST\COUNT\%LINE 18
    18:       AREA := PRODUCT (LENGTH, WIDTH);
DBG> STEP/INTO
stepped to routine TEST\PRODUCT
     6:    function PRODUCT (X, Y : INTEGER) return INTEGER is
DBG>

DBG> STEP/RETURN
stepped on return from TEST\PRODUCT\%LINE 11 to TEST\PRODUCT\%LINE 15+4
    15:    end PRODUCT;
DBG> STEP
stepped to TEST\COUNT\%LINE 19
    19:       LENGTH := LENGTH + 1;
DBG>

DBG> SET STEP INTO

As a result of this command, when the PC is at a call statement, a STEP command suspends execution within the called routine. If you later want to step over routine calls, enter the SET STEP OVER command.

DBG> SET STEP INTO, NOSYSTEM, NOSHARE

To set a breakpoint or a tracepoint on a particular program location, specify an address expression with the SET BREAK or SET TRACE command.

Fundamentally, an address expression specifies a memory address or a register. Because the debugger understands the symbols associated with your program, the address expressions you typically use with the SET BREAK or SET TRACE command are routine names, labels, or source line numbers rather than memory addresses - the debugger converts these symbols to addresses.

DBG> SET BREAK SWAP
DBG> SET TRACE LOOP1

DBG> SET BREAK/RETURN SWAP

DBG> SET TRACE %LABEL 20

DBG> SET BREAK %LINE 14

DBG> SET BREAK %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>

%LINE line-number.statement-number

DBG> SET TRACE %LINE 38.2

DBG> SET TRACE MOD4\%LINE 27

DBG> SET BREAK %LINE 23+5

DBG> SET BREAK 2753

DBG> SET BREAK %HEX 2753

DBG> EVALUATE/ADDRESS SWAP
1536
DBG> EVALUATE/ADDRESS %LINE 26
1629
DBG>

DBG> EVALUATE/ADDRESS/HEX %LINE 26
0000065D
DBG>

When using these qualifiers, do not specify an address expression.

DBG> SET BREAK/LINE

DBG> SET TRACE/BRANCH

Note that opcode tracing slows program execution.

DBG> SET BREAK/LINE/NOSHARE/NOSYSTEM

On Alpha systems, to cause the debugger to suspend program execution when an instruction is emulated, use the command SET BREAK /SYSEMULATE. The syntax of the SET BREAK command when using the /SYSEMULATE qualifier is:

The optional argument mask is a quad word with bits set to specify which instruction groups shall trigger breakpoints. The only emulated instruction group currently defined consists of the BYTE and WORD instructions. Specify this instruction group by setting bit 0 of mask to 1.

If you do not specify mask, or if mask=FFFFFFFFFFFFFFFF, the debugger stops program execution whenever the operating system emulates any instruction.

The SET BREAK and SET TRACE commands provide several options for controlling the behavior of the debugger at breakpoints and tracepoints - the /AFTER, /[NO]SILENT, /[NO]SOURCE, and /TEMPORARY command qualifiers, and the optional WHEN and DO clauses. The following examples show several of these options.

DBG> SET BREAK/AFTER:5 %LINE 14

DBG> SET TRACE/LINE DO (EXAMINE X)

DBG> SET BREAK %LINE 27 WHEN (SUM > 100) DO (EXAMINE TEST_RESULT)

See Section 4.1.6, “Evaluating Language Expressions” and Section 14.3.2.2, “Evaluating Language Expressions” for information about evaluating language expressions like SUM > 100.

DBG> SET TRACE/SILENT %LINE 83 DO (EXAMINE STATUS)
DBG> GO
   .
   .
   .
SCREEN_IO\CLEAR\STATUS:   OFF
   .
   .
   .

DBG> DEFINE/VALUE COUNT=0
DBG> SET TRACE/SILENT %LINE 12 DO (DEF/VAL COUNT=COUNT+1;EVAL COUNT)

Source lines are displayed by default at breakpoints, tracepoints, and watchpoints if they are available for the module being debugged. You can also control their display with the SET STEP [NO]SOURCE command and the /[NO]SOURCE qualifier of the SET BREAK, SET TRACE, and SET WATCH commands. See Chapter 6, Controlling the Display of Source Code for information about how to control the display of source code in general and in particular at breakpoints, tracepoints, and watchpoints.

The SET BREAK /EXCEPTION and SET TRACE /EXCEPTION commands direct the debugger to treat any exception generated by your program as a breakpoint or tracepoint, respectively. The breakpoint or tracepoint occurs before any application-declared exception handler is invoked. See Section 14.5, “Debugging Exceptions and Condition Handlers” for debugging techniques associated with exceptions and condition handlers.

The appropriate facility and event-name keywords are defined when the program is brought under debugger control. Use the SHOW EVENT_FACILITY command to identify the current event facility and the associated event-name keywords. The SET EVENT_FACILITY command enables you to change the event facility and change your debugging context. This is useful if you have a multilanguage program and want to debug a routine that is associated with an event facility but that facility is not currently set.

DBG> SET BREAK/EVENT=TOKEN

When a breakpoint or tracepoint is triggered, the debugger identifies the event that caused it to be triggered and gives additional information.

After a breakpoint or tracepoint is set, you can deactivate it, activate it, or cancel it.

To deactivate a breakpoint or tracepoint, enter the DEACTIVATE BREAK or DEACTIVATE TRACE command. This causes the debugger to ignore the breakpoint or tracepoint during program execution. However, you can activate it at a later time, for example, when you rerun the program (see Section 1.3.3, “Rerunning the Same Program from the Kept Debugger”). A deactivated breakpoint or tracepoint is listed as such in a SHOW BREAK display.

To activate a breakpoint or tracepoint, use the ACTIVATE BREAK or ACTIVATE TRACE command. Activating a breakpoint or tracepoint causes it to take effect during program execution.

The commands DEACTIVATE BREAK/ALL and ACTIVATE BREAK/ALL (or DEACTIVATE TRACE/ALL and ACTIVATE TRACE/ALL) operate on all breakpoints or tracepoints and are particularly useful when rerunning a program with the RERUN command.

To cancel a breakpoint or tracepoint, use the CANCEL BREAK or CANCEL TRACE command. A canceled breakpoint or tracepoint is no longer listed in a SHOW BREAK or SHOW TRACE display.

DBG> DEACTIVATE TRACE/LINE
DBG> CANCEL BREAK SWAP, MOD2\LOOP4, 2753

After a watchpoint is set, you can deactivate it, activate it, or cancel it.

To deactivate a watchpoint, use the DEACTIVATE WATCH command. This causes the debugger to ignore the watchpoint during program execution. However, you can activate it at a later time, for example, when you rerun the program (see Section 1.3.3, “Rerunning the Same Program from the Kept Debugger”). A deactivated watchpoint is listed as such in a SHOW WATCH display.

To activate a watchpoint, use the ACTIVATE WATCH command. Activating a watchpoint causes it to take effect during program execution. You can always activate a static watchpoint, but the debugger cancels a nonstatic watchpoint if execution moves out of the scope in which the variable is defined (see Section 3.4.3, “Watching Nonstatic Variables”).

The commands DEACTIVATE WATCH/ALL and ACTIVATE WATCH/ALLoperate on all watchpoint sand are particularly useful when rerunning a program with the RERUN command.

To cancel a watchpoint, use the CANCEL WATCH command. A canceled watchpoint is no longer listed in a SHOW WATCH display.

The SET WATCH command provides the same options for controlling the behavior of the debugger at watchpoints that the SET BREAK and SET TRACE commands provide for breakpoints and tracepoints - namely the /AFTER, /[NO]SILENT, /[NO]SOURCE, and /TEMPORARY qualifiers, and the optional WHEN and DO clauses. See Section 3.3.4, “Controlling Debugger Action at Breakpoints or Tracepoints” for examples.

Storage for a variable in your program is allocated either statically or nonstatically. A static variable is associated with the same memory address throughout execution of the program. A nonstatic variable is allocated on the call stack or in a register and has a value only when its defining routine is active on the call stack. As explained in this section, the technique for setting a watchpoint, the watchpoint's behavior, and the speed of program execution are different for the two kinds of variables.

   .
   .
   .
VAR
     X: [STATIC] INTEGER;
     Y: INTEGER;
   .
   .
   .
DBG> EVALUATE/ADDRESS X
512
DBG> EVALUATE/ADDRESS Y
%R0
DBG>

DBG> SET WATCH Y
%DEBUG-W-SYMNOTACT, nonstatic variable 'MOD4\ROUT3\Y'
    is not active
DBG>

Section 3.4.3.2, “Setting a Watchpoint on a Nonstatic Variable” describes how to set a watchpoint on a nonstatic variable.

DBG> SET WATCH Y
%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction
DBG>

DBG> SET TRACE/NOSOURCE ROUT3 DO (SET WATCH Y)
DBG> GO
   .
   .
   .
trace at routine MOD4\ROUT3
%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction
   .
   .
   .
watch of MOD4\ROUT3\Y at MOD4\ROUT3\%LINE 16
   16:     Y := 4
   old value:    3
   new value:    4
break at MOD4\ROUT3\%LINE 17
   17:     SWAP (X, Y);
DBG>

%DEBUG-I-WATCHVAR, watched variable MOD4\ROUT3\Y has gone out of scope
%DEBUG-I-WATCHCAN, watchpoint now canceled

Before you try to examine or deposit into a nonstatic (stack-local or register) variable, its defining routine must be active on the call stack. That is, program execution must be paused somewhere within the defining routine. See Section 3.4.3, “Watching Nonstatic Variables” for more information about nonstatic variables.

You can examine a static variable at any time during program execution, and you can examine a nonstatic variable as soon as execution reaches its defining routine. However, before you examine any variable, you should execute the program beyond the point where the variable is declared and initialized. The value contained in any uninitialized variable should be considered invalid.

Many compilers optimize code to make the program run faster. If the code that you are debugging has been optimized, some program locations might not match what you would expect from looking at the source code. In particular, some optimization techniques eliminate certain variables so that you no longer have access to them while debugging.

Section 14.1, “Debugging Optimized Code” explains the effect of several optimization techniques on the executable code. When first debugging a program, it is best to disable optimization, if possible, with the /NOOPTIMIZE (or equivalent) compiler command qualifier.

In some cases, when using the EXAMINE or DEPOSIT command with a variable name (or any other symbolic address expression) you might need to set a module or specify a scope or a path name. Those concepts are described in Chapter 5, Controlling Access to Symbols in Your Program. The examples in this chapter assume that all modules are set and that all variable names are uniquely defined.

EXAMINE address-expression[,...]

DBG>EXAMINE X
MOD3\X:   17
DBG>

When displaying the value, the debugger prefixes the variable name with its path name - in this case, the name of the module where variable X is declared (see Section 5.3.2, “Using SHOW SYMBOL and Path Names to Specify Symbols Uniquely”).

The EXAMINE command usually displays the current value of the entity, denoted by an address expression, in the type associated with that location (for example, integer, real, array, record, and so on).

See Section 4.1.5, “Address Expressions and Their Associated Types” for more information about the types associated with symbolic and nonsymbolic address expressions.

By default, when displaying the value, the debugger identifies the address expression and its path name symbolically if symbol information is available. See Section 4.1.11, “Obtaining and Symbolizing Memory Addresses” for more information about symbolizing addresses.

DBG> EXAMINE wide_buffer
TST\main\wide_buffer[0:31]: 'test data line 1................'

In this condition, you must examine the CFM register and manually adjust the EXAMINE command to account for the non-zero CFM.rrb and CFM.sor fields.

DUMP address-expression1[:address-expression2]

DBG>DUMP/QUADWORD R16:R25
 0000000000000078 0000000000030038 8.......x....... %R16
 000000202020786B 0000000000030041 A.......kx   ... %R18
 0000000000030140 0000000000007800 .x......@....... %R20
 0000000000010038 0000000000000007 ........8....... %R22
 0000000000000006 0000000000000000 ................ %R24
DBG> 

By default, the debugger displays examined entities that do not have a compiler-generated type as longwords.

DEPOSIT address-expression = language-expression

DBG>EXAMINE X
MOD3\X:   17
DBG>DEPOSIT X = 23
DBG>EXAMINE X
MOD3\X:   23
DBG>

The DEPOSIT command usually evaluates a language expression and deposits the resulting value into a program location denoted by an address expression.

DBG>DEPOSIT X = 2.0
DBG>EXAMINE X
MOD3\X:   2
DBG>

In general, the debugger tries to follow the assignment rules for the current language.

The symbols that are declared in your program (variable names, routine names, and so on) are symbolic address expressions. They denote memory addresses or registers. Symbolic address expressions (also called symbolic names in this chapter) have compiler-generated types, and the debugger knows the type and location that are associated with symbolic names. Section 4.1.11, “Obtaining and Symbolizing Memory Addresses” explains how to obtain memory addresses and register names from symbolic names and how to symbolize program locations.

DBG>EXAMINE 926
926:  749404624
DBG>

DBG>DEPOSIT 926 = 84
DBG>EXAMINE 926
926:  84
DBG>

Techniques for examining and depositing into locations that do not have a symbolic name are described in Section 4.5, “Specifying a Type When Examining and Depositing”.

The EXAMINE and DEPOSIT commands accept type qualifiers (/ASCII: n, /BYTE, and so on) that enable you to override the type associated with a program location. This is useful either if you want the contents of the location to be interpreted and displayed in another type, or if you want to deposit some value of a particular type into a location that is associated with another type. Techniques for overriding a type are described in Section 4.5, “Specifying a Type When Examining and Depositing”.

This discussion applies to all commands and constructs that evaluate language expressions, but it focuses on using the EVALUATE command.

EVALUATE language-expression […]

DBG>EVALUATE (8+12)*6/4
30
DBG>

The debugger uses the rules of operator precedence of the current language when evaluating language expressions.

DBG>DEPOSIT X = 23
DBG>EVALUATE (X - 3) * 4
80
DBG>

However, you cannot evaluate a language expression that includes a function call. For example, if PRODUCT is a function that multiplies two integers, you cannot enter the EVALUATE PRODUCT(3, 5) command. If your program assigns the returned value of a function to a variable, you can examine the resulting value of that variable.

If an expression contains symbols with different compiler generated types, the debugger uses the type-conversion rules of the current language to evaluate the expression. If the types are incompatible, a diagnostic message is issued. Debugger support for operators and other constructs in language expressions is listed in the debugger's online help for each language (type HELP Language).

DBG>EXAMINE X
MOD3\X:  23
DBG>EVALUATE %CURVAL
23
DBG>DEPOSIT Y = 47
DBG>EVALUATE \
47
DBG>

DBG>DEPOSIT X = 12    ! Assign the value 12 to X.
DBG>EXAMINE X         ! Display the value of X.
MOD4\X:  12
DBG>EVALUATE X        ! Evaluate and display the value of X.
12
DBG>EVALUATE X + 4    ! Add the value of X to 4.
16
DBG>DEPOSIT X = X/2   ! Divide the value of X by 2 and assign
                      ! the resulting value to X.
DBG>EXAMINE X         ! Display the new value of X.
MOD4\X:   6
DBG>

DBG> EVALUATE ARR
%DEBUG-W-NOVALUE, reference does not have a value
DBG>

DBG>EVALUATE ARR(2)          ! Evaluate element 2 of array ARR.
37
DBG>DEPOSIT K = 5 + ARR(2)   ! Deposit the sum of two integer
DBG>                         ! values into an integer variable.

DBG>EXAMINE Y         ! Display the value of Y.
MOD4\Y:  3
DBG>EVALUATE Y        ! Display the address of Y.
02475B
DBG>EVALUATE .Y       ! Display the value of Y.
3
DBG>EVALUATE Y + 4    ! Add 4 to the address of Y and
02475F                ! display the resulting value.
DBG>EVALUATE .Y + 4   ! Add 4 to the value of Y and display
7                     ! the resulting value.
DBG>

DBG>EVALUATE 1.5 + 1
2.5
DBG>

Do not confuse address expressions with language expressions. An address expression specifies a program location; a language expression specifies a value. In particular, the EXAMINE command expects an address expression as its parameter, and the EVALUATE command expects a language expression as its parameter. These points are shown in the next examples.

DBG>DEPOSIT X = 12
DBG>EXAMINE X
MOD3\X: 12
DBG>EVALUATE X + 6
18
DBG>

DBG>EXAMINE X + 6
MOD3\X+6: 274903
DBG>

In this case the location is not associated with a compiler-generated type. Therefore, the debugger interprets and displays the value stored at that location in the type longword integer (see Section 4.1.5, “Address Expressions and Their Associated Types”).

DBG>EXAMINE X
MOD3\X: 12
DBG>DEPOSIT X + 6 = X + 6
DBG>EXAMINE X
MOD3\X: 12
DBG>EXAMINE X + 6
MOD3\X+6: 18
DBG>

When using the EXAMINE and DEPOSIT commands, you can use three special built-in symbols (address expressions) to refer quickly to the current, previous, and next data locations (logical entities). These are the period (.), the circumflex (^), and the Return key.

DBG>EXAMINE X
SIZE\X: 7
DBG>DEPOSIT . = 12
DBG>EXAMINE .
SIZE\X: 12
DBG>

DBG>EXAMINE ARR(5)    ! Examine element 5 of array ARR.MAIN
\ARR(5): 448670
DBG>EXAMINE ^         ! Examine the previous element (4).MAIN
\ARR(4): 792802
DBG>EXAMINE           ! Examine the next element (5).MAIN
\ARR(5): 448670
DBG>EXAMINE           ! Examine the next element (6).MAIN
\ARR(6): 891236
DBG>

The debugger uses the type associated with the current entity to determine logical successors and predecessors.

You can also use the built-in symbols %CURLOC, %PREVLOC, and %NEXTLOC to achieve the same purpose as the period, circumflex, and Return key, respectively. These symbols are useful in command procedures and also if your program uses the circumflex for other purposes. Moreover, using the Return key to signify the logical successor does not apply to all contexts. For example, you cannot press the Return key after entering the DEPOSIT command to indicate the next location, but you can always use the symbol %NEXTLOC for that purpose.

Note that, like EXAMINE and DEPOSIT, the EVALUATE /ADDRESS command also resets the values of the current, previous, and next logical-entity built-in symbols (see Section 4.1.11, “Obtaining and Symbolizing Memory Addresses”). However, you cannot press the Return key after entering the EVALUATE /ADDRESS command to indicate the next location. For more information about debugger built-in symbols, see Appendix B, Built-In Symbols and Logical Names.

As the current entity is reset with new examine or deposit operations, the debugger associates each new location with a type in the manner indicated to determine logical successors and predecessors. This is shown in the following examples.

1000: ARY(1)
1002: ARY(2)
1004: ARY(3)
1006: FLT
1010: BTE
1011: undefined
   .
   .
   .

DBG>EXAMINE 1000          ! Examine ARY(1), associated with 1000.
MOD3\ARY(1):  13          ! Current entity is now ARY(1).
DBG>EXAMINE               ! Examine next location, ARY(2),
MOD3\ARY(2):   7          ! using type of ARY(1) as reference.
DBG>EXAMINE               ! Examine next location, ARY(3).
MOD3\ARY(3):  19          ! Current entity is now ARY(3).
DBG>EXAMINE               ! Examine entity at 1006 (FLT).
MOD3\FLT:  1.9117807E+07  ! Current entity is now FLT.
DBG>EXAMINE               ! Examine entity at 1010 (BTE).
MOD3\BTE:   43            ! Current entity is now BTE.
DBG>EXAMINE               ! Examine entity at 1011 (undefined).
1011: 17694732            ! Interpret data as longword integer.
DBG>                      ! Location is not symbolized.

The same principles apply when you use type qualifiers with the EXAMINE and DEPOSIT commands (see Section 4.5.2, “Overriding the Current Type”). The type specified by the qualifier determines the data boundary of an entity and, therefore, any logical successors and predecessors.

The debugger enables you to set your debugging context to any of several supported languages. The setting of the current language determines how the debugger parses and interprets the names, numbers, operators, and expressions you specify in debugger commands, and how it displays data.

$ PASCAL/NOOPTIMIZE/DEBUG TEST1
$ LINK/DEBUG TEST1
$ DEBUG/KEEP
           Debugger Banner and Version Number
DBG>RUN TEST1
Language: PASCAL, Module: TEST1
DBG>

When debugging modules whose code is written in other languages, you can use the SET LANGUAGE command to establish a new language-dependent context. Section 14.3, “Debugging Multilanguage Programs” highlights some important language differences. Debugger support for operators and other constructs in language expressions is listed for each language in the debugger's online help (type HELP Language).

The debugger can interpret and display integer data in any one of four radixes: decimal, hexadecimal, octal, and binary. The default radix is decimal for most languages.

On Alpha systems, the exceptions are BLISS, MACRO-32 and MACRO-64, which have a default radix of hexadecimal.

You cannot control the radix for other kinds of integer data. For example, addresses are always displayed in hexadecimal radix in a SHOW CALLS display. Or, when specifying an integer n with various command qualifiers (/AFTER: n, /UP: n, and so on), you must use decimal radix.

DBG>SET RADIX HEXADECIMAL

After this command is executed, all integer data that you enter in address or language expressions is interpreted as being hexadecimal. Also, all integer data displayed by the EVALUATE and EXAMINE commands is given in hexadecimal radix.

DBG>SHOW RADIX
input radix: hexadecimal
output radix: hexadecimal
DBG>

The SHOW RADIX command identifies both the input radix (for data entry) and the output radix (for data display). The SET RADIX command qualifiers /INPUT and /OUTPUT enable you to specify different radixes for data entry and display. For more information, see the SET RADIX command.

Use the CANCEL RADIX command to restore the default radix.

The examples that follow show several techniques for displaying or entering integer data in another radix without changing the current radix.

DBG>SHOW RADIX
input radix: decimal
output radix: decimal
DBG>EVALUATE 18 + 5
23                         ! 23 is decimal integer.
DBG>EVALUATE/HEX 18 + 5
00000017                   ! 17 is hexadecimal integer.
DBG>

The radix qualifiers do not affect the radix for data entry.

DBG>EXAMINE X
MOD4\X: 4398                ! 4398 is a decimal integer.
DBG>EXAMINE/OCTAL .        ! X is the current entity.
MOD4\X: 00000010456         ! 10456 is an octal integer.
DBG>

DBG>SHOW RADIX
input radix: decimal
output radix: decimal
DBG>EVAL %BIN 10              ! Evaluate the binary integer 10.
2                             ! 2 is a decimal integer.
DBG>EVAL %HEX (10 + 10)       ! Evaluate the hexadecimal integer 20.
32                            ! 32 is a decimal integer.
DBG>EVAL %HEX 20 + 33         ! Treat 20 as hexadecimal, 33 as decimal.
65                            ! 65 is a decimal integer.
DBG>EVAL/HEX %OCT 4672        ! Treat 4672 as octal and display in hex.
000009BA                      ! 9BA is a hexadecimal number.
DBG>EXAMINE X + %DEC 12       ! Examine the location 12 decimal bytes
MOD3\X+12:  493847            ! beyond the address of X.
DBG>DEPOS J = %OCT 7777777    ! Deposit an octal value.
DBG>EXAMINE .                 ! Display that value in decimal radix.
MOD3\J:  2097151
DBG>EXAMINE/OCTAL .           ! Display that value in octal radix.
MOD3\J:  00007777777
DBG>EXAMINE %HEX 0A34D        ! Examine location A34D, hexadecimal.
SHARE$LIBRTL+4941:  344938193 ! 344938193 is a decimal integer.
DBG>

For more examples showing the use of the radix built-in symbols, see Appendix B, Built-In Symbols and Logical Names.

DBG>EVALUATE/ADDRESS X       ! A variable name
2476
DBG>EVALUATE/ADDRESS SWAP    ! A routine name
1536
DBG>EVALUATE/ADDRESS %LINE 26
1629
DBG>

DBG>EVALUATE/ADDRESS/HEX X
000009AC
DBG>

DBG>EVALUATE/ADDRESS K
%R2
DBG>

Like the EXAMINE and DEPOSIT commands, EVALUATE /ADDRESS resets the values of the current, previous, and next logical-entity built-in symbols (see Section 4.1.8, “Specifying the Current, Previous, and Next Entity”).Unlike the EVALUATE command, EVALUATE /ADDRESS does not affect the current-value built-in symbols %CURVAL and backslash (\).

DBG>SYMBOLIZE %R2
address MOD3\%R2:    MOD3\K
DBG>

DBG>EVALUATE/ADDRESS X
2476
DBG>EXAMINE 2476
MOD3\X:  16
DBG>

DBG>EVALUATE/ADDRESS K
%R2
DBG>EXAMINE %R2
MOD3\%R2:  78
DBG>

DBG>EVALUATE/ADDRESS Y
512
DBG>EXAMINE 512
MOD3\Y:  28
DBG>EXAMINE/NOSYMBOLIC 512
512:  28
DBG>

Symbolic mode also affects the display of instructions.

DBG>EXAMINE/INSTRUCTION .%PC
HELLO\main\%LINE 8: add        r34=200028, r1
DBG>EXAMINE/NOSYMBOL/INSTRUCTION .%PC
65969:              add        r34 = 200028, r1
DBG>

The following examples show use of the EXAMINE, DEPOSIT, and EVALUATE commands with some integer, real, and Boolean types.

DBG>EXAMINE WIDTH, LENGTH, AREA
SIZE\WIDTH:   4SIZE
SIZE\LENGTH:  7SIZE
SIZE\AREA:    28
DBG>

DBG>DEPOSIT WIDTH = CURRENT_WIDTH + 10
DBG>

DBG>DEPOSIT X = -14
%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near DEPOSIT
DBG>

DBG>DEPOSIT I = 12345
DBG>EXAMINE I
MOD3\I:  12345
DBG>DEPOSIT I = 123.45
DBG>EXAMINE I
MOD3\I:  123
DBG>

DBG>DEPOSIT Y = 2.356     ! Y is of type G_floating point.
DBG>EXAMINE Y
MOD3\Y: 2.35600000000000
DBG>EVALUATE Y + 3
5.35600000000000
DBG>DEPOSIT R = 5.35E3    ! R is of type F_floating point.
DBG>EXAMINE R
MOD3\R:  5350.000
DBG>EVALUATE R*50
   267500.0
DBG>DEPOSIT I = 22222
DBG>EVALUATE R/I
   0.2407524
DBG>

DBG>DEPOSIT WILLING = TRUE
DBG>DEPOSIT ABLE = FALSE
DBG>EVALUATE WILLING AND ABLE
False
DBG>

DBG>EXAMINE EMPLOYEE_NAME
PAYROLL\EMPLOYEE_NAME:    "Peter C. Lombardi"
DBG>

DBG>DEPOSIT PART_NUMBER = "WG-7619.3-84"
DBG>

%DEBUG-I-ISTRTRU, string truncated at or near DEPOSIT

If the string has fewer characters, the debugger pads the remaining characters to the right of the string by inserting ASCII space characters.

You can examine an entire array aggregate, a single indexed element, or a slice (a range of elements). However, you can deposit into only one element at a time. The following examples show typical operations with arrays.

DBG>EXAMINE ARRX
MOD3\ARRX
    (1):     42
    (2):     17
    (3):    278
    (4):     56
    (5):    113
    (6):    149
DBG>

DBG>EXAMINE ARRX(4)
MOD3\ARRX(4):   56
DBG>

DBG>EXAMINE ARRX(2:5)
MOD3\ARRX
    (2):     17
    (3):    278
    (4):     56
    (5):    113
DBG>

In general, a range of values to be examined is denoted by two values separated by a colon (value1:value2). Depending on the language, two periods (..) can be used instead of a colon.

DBG>DEPOSIT ARRX(2) = 53
DBG>

DBG>EXAMINE REAL_ARRAY
PROG2\REAL_ARRAY
   (1, 1):       27.01000
   (1, 2):       31.00000
   (1, 3):       12.48000
   (2, 1):       15.08000
   (2, 2):       22.30000
   (2, 3):       18.73000
DBG>

DBG>DEPOSIT REAL_ARRAY(1, 4) = 26.13
%DEBUG-I-SUBOUTBND, subscript 2 is out of bounds, value is 4,
bounds are 1..3
DBG>

In the previous example, the deposit operation was executed because the diagnostic message is of I level. This means that the value of some array element adjacent to (1, 3), possibly (2, 1) might have been affected by the out-of-bounds deposit operation.

DBG>FOR I = 1 TO 4 DO (DEPOSIT COLOR_ARRAY(I) = RED)
DBG>

You can also use the built-in symbols (.) and (^)to step through array elements, as explained in Section 4.1.8, “Specifying the Current, Previous, and Next Entity”.

You can examine an entire record aggregate, a single record component, or several components. However, you can deposit into only one component at a time. The following examples show typical operations with records.

DBG>EXAMINE PART
INVENTORY\PART:
    ITEM:     "WF-1247"
    PRICE:     49.95
    IN_STOCK:  24
DBG>

DBG>EXAMINE PART.IN_STOCK
INVENTORY\PART.IN_STOCK: 24
DBG>

DBG>EXAMINE IN_STOCK OF PART
INVENTORY\IN_STOCK of PART:    IN_STOCK:  24
DBG>

DBG>EXAMINE PART.ITEM, PART.IN_STOCK
INVENTORY\PART.ITEM:     "WF-1247"
INVENTORY\PART.IN_STOCK:  24
DBG>

DBG>DEPOSIT PART.IN_STOCK = 17
DBG>

You can examine the entity designated (pointed to) by a pointer variable and deposit a value into that entity. You can also examine a pointer variable.

   .
   .
   .
TYPE
     T = ^REAL;
VAR
     A : T;
   .
   .
   .

DBG>EXAMINE A^
MOD3\A^:  1.7
DBG>

DBG>DEPOSIT A^ = 3.9
DBG>EXAMINE A^
MOD3\A^:  3.9
DBG>

DBG>EXAMINE/HEXADECIMAL A
SAMPLE\A: 0000B2A4
DBG>

If you specify an address expression that is associated with an instruction in an EXAMINE command (for example, a line number), the debugger displays the first instruction at that location. You can then use the period (.), Return key, and circumflex (^) to display the current, next, and previous instruction (logical entity), as described in Section 4.1.8, “Specifying the Current, Previous, and Next Entity”.

DBG>EXAMINE %LINE 12
MOD3\%LINE 12:     BIS     R31, R31, R2
DBG>EXAMINE
MOD3\%LINE 12+4:   BIS     R31, R2, R0  ! Next instruction
DBG>EXAMINE
MOD3\%LINE 12+8:   ADDL    R31, R0, R0  ! Next instruction
DBG>EXAMINE ^
MOD3\%LINE 12+4:   BIS     R31, R2, R0  ! Previous instruction
DBG>

Line numbers, routine names, and labels are symbolic address expressions that are associated with instructions. In addition, instructions might be stored in various other memory addresses and in certain registers during the execution of your program.

As shown in the previous examples, the debugger knows whether an address expression is associated with an instruction. If it is, the EXAMINE command displays that instruction (you do not need to use the /INSTRUCTION qualifier). You use the /INSTRUCTION qualifier to display the contents of an arbitrary program location as an instruction - that is, the command EXAMINE /INSTRUCTION causes the debugger to interpret and format the contents of any program location as an instruction (see Section 4.5.2, “Overriding the Current Type”).

module TEST
     1:         .TITLE  TEST
     2:
     3: TEST$START::
     4:         .WORD   0
     5:
     6:         MOVL    #2, R2
     7:         BRB     LABEL_2
     8:
     9:         .LONG   ^X12345
    10:         .LONG   ^X14465
    11:
    12: LABEL_2:
    13:         MOVL    #5, R5
    14:
    15:         .END    TEST$START

DBG>EXAMINE %LINE 6
TEST\TEST$START\%LINE 6:  MOVL    S^#02, R2
DBG>

DBG>EXAMINE
TEST\TEST$START\%LINE 7:  BRB     TEST\TEST$START\LABEL_2
DBG>

DBG>EXAMINE
TEST\TEST$START\%LINE 7+2:  MULF3   S^#11.00000, S^#0.5625000, S^#0.5000000
DBG>EXAMINE
%DEBUG-W-ADDRESSMODE, instruction uses illegal or undefined addressing modes
TEST\TEST$START\%LINE 7+6:  MULD3   S^#0.5625000[R4], S^#0.5000000, @W^5505(R0)
DBG>EXAMINE
TEST$START+12:   HALT
DBG>

DBG>SHOW TYPE          ! Show type for locations without
type: long integer     ! a compiler-generated type.
DBG>SHOW RADIX         ! Identify current radix.
input radix: decimal
output radix: decimal
DBG>EXAMINE %R11       ! Display value in R11.
MOD3\%R11:  1024
DBG>DEPOSIT %R11 = 444 ! Deposit new value into R11.
DBG>EXAMINE %R11       ! Check new value.
R11:  444
DBG>EXAMINE %PC        ! Display value in program counter.
MOD\%PC: 1553
DBG>EXAMINE %SP        ! Display value in stack pointer.
0\%SP:  2147278720
DBG>

See Section 4.3.1, “Examining Instructions” for specific information about the PC.

Processor Status (Alpha Only)

On Alpha systems, the processor status (PS) is a register whose value represents a number of processor state variables. The first three bits of the PS are reserved for the use of the software. The values of these bits can be controlled by a user program. The remainder of the bits, bits 4 to 64, contain privileged information and cannot be altered by a user-mode program.

DBG>EXAMINE %PS
MOD1\%PS:
      SP_ALIGN IPL VMM   CM   IP SW
         48     0   0   USER   0  3
DBG>

See the Alpha Architecture Reference Manual for complete information about the PS, including the values of the various bits.

DBG>EXAMINE/LONG/HEX %PS
MOD1\%PS:        0000001B
DBG>EXAMINE/LONG/BIN %PS
MOD1\%PS:        00000000 00000000 00000000 00011011
DBG>

The command EXAMINE /PS displays the value at any location in PS format. This is useful for examining the combined current and saved PS values.