OpenVMS Debugger Manual

In this VAX example, the SHOW TRACE command identifies all tracepoints that are currently set. This example indicates user-defined tracepoints that are triggered whenever execution reaches routine MULT in module CALC or one of the instructions RET, RSB, BSBB, JSB, BSBW, CALLG, or CALLS. #2

DBG_2> SHOW TRACE/PREDEFINED
predefined tracepoint on program activation 
 DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_/SUF=PROCESS_NU AT H1 SOURCE 
        (EXAM/SOURCE .%SOURCE_SCOPE\%PC); 
    SET DISP/DYN/REM/SIZE:64/PROC INST_/SUF=PROCESS_NU AT H1 INST 
        (EXAM/INSTRUCTION .0\%PC)) 
predefined tracepoint on program termination
DBG_2>

This command identifies the predefined tracepoints that are currently set. The example shows the predefined tracepoints that are set automatically by the debugger for a multiprocess program (when DBG$PROCESS has the value MULTIPROCESS). The tracepoint on program activation triggers whenever a new process comes under debugger control. The DO clause creates a process-specific source display named SRC_n and a process-specific instruction display named INST_n whenever a process activation tracepoint is triggered. The tracepoint on program termination triggers whenever a process does an image exit.

SHOW TYPE

Identifies the current type for program locations that do not have a compiler-generated type or, if you specify /OVERRIDE, the current override type.

Format

SHOW TYPE

QUALIFIERS

/OVERRIDE
Identifies the current override type.

DESCRIPTION

The current type for program locations that do not have a compiler-generated type is the type last established by the SET TYPE command. If you did not enter a SET TYPE command, the type for those locations is longword integer.
The current override type for all program locations is the override type last established by the SET TYPE/OVERRIDE command. If you did not enter a SET TYPE/OVERRIDE command, the override type is "none".
Related commands:

CANCEL TYPE/OVERRIDE
DEPOSIT
EXAMINE
(SET,SHOW,CANCEL) MODE
(SET,SHOW,CANCEL) RADIX
SET TYPE

Examples

DBG> SET TYPE QUADWORD
DBG> SHOW TYPE
type: quadword integer
DBG>

In this example, you set the type to quadword for locations that do not have a compiler-generated type. The SHOW TYPE command displays the current default type for those locations as quadword integer. This means that the debugger interprets and displays entities at those locations as quadword integers unless you specify otherwise (for example with a type qualifier on the EXAMINE command).

DBG> SHOW TYPE/OVERRIDE
type/override: none
DBG>

This command indicates that no override type has been defined.

SHOW VECTOR_MODE (VAX only)

Identifies the current vector mode (synchronized or nonsynchronized).
Applies to VAX vectorized programs.

Format

SHOW VECTOR_MODE

DESCRIPTION

The current vector mode is the mode established with the SET VECTOR_MODE command. If you did not enter a SET VECTOR_MODE command, the default vector mode is NONSYNCHRONIZED.
Related commands:

SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only)
SYNCHRONIZE VECTOR_MODE (VAX only)

Example

DBG> SHOW VECTOR_MODE
Vector mode is nonsynchronized
DBG> SET VECTOR_MODE SYNCHRONIZED
DBG> SHOW VECTOR_MODE
Vector mode is synchronized
DBG>

The SHOW VECTOR_MODE command indicates the effect of the SET VECTOR_MODE command.

SHOW WATCH

Displays information about watchpoints.

Format

SHOW WATCH

DESCRIPTION

The SHOW WATCH command displays information about watchpoints that are currently set, including any options such as WHEN or DO clauses, /AFTER counts, and so on, and whether the watchpoints are deactivated.
If you established a watchpoint using SET WATCH/AFTER:n, the SHOW WATCH command displays the current value of the decimal integer n, that is, the originally specified integer value minus 1 for each time the watchpoint location was reached. (The debugger decrements n each time the watchpoint location is reached until the value of n is 0, at which time the debugger takes watch action.)
Related commands:

(ACTIVATE,CANCEL,DEACTIVATE,SET) WATCH

Example

DBG> SHOW WATCH
watchpoint of MAIN\X 
watchpoint of SUB2\TABLE+20
DBG>

This command displays two watchpoints: one at the variable X (defined in module MAIN), and the other at the location SUB2\TABLE+20 (20 bytes beyond the address denoted by the address expression TABLE).

SHOW WINDOW

Identifies the name and screen position of predefined and user-defined screen-mode windows.

Note
This command is not available in the DECwindows Motif interface to the debugger.

Format

SHOW WINDOW [window-name[,...]]

PARAMETERS

windowname
Specifies the name of a screen window definition. If you do not specify a name, or if you specify the asterisk (*) wildcard character by itself, all window definitions are listed. You can use the wildcard within a window name. Do not specify a window definition name with the /ALL qualifier.

QUALIFIERS

/ALL
Lists all window definitions.

DESCRIPTION

Related commands:

(SHOW,CANCEL) DISPLAY
(SET,SHOW) TERMINAL
(SET,CANCEL) WINDOW
SHOW SELECT

Example

DBG> SHOW WINDOW LH*,RH*
window LH1 at (1,11,1,40) 
window LH12 at (1,23,1,40) 
window LH2 at (13,11,1,40) 
window RH1 at (1,11,42,39) 
window RH12 at (1,23,42,39) 
window RH2 at (13,11,42,39)
DBG>

This command displays the name and screen position of all screen window definitions whose names start with LH or RH.

SPAWN

Creates a subprocess, enabling you to execute DCL commands without terminating a debugging session or losing your debugging context.

Note
This command is not available in the DECwindows Motif interface to the debugger.

Format

SPAWN [DCL-command]

PARAMETERS

DCL-command
Specifies a DCL command which is then executed in a subprocess. Control is returned to the debugging session when the DCL command terminates.
If you do not specify a DCL command, a subprocess is created and you can then enter DCL commands. Either logging out of the spawned process or attaching to the parent process (with the DCL command ATTACH) returns you to your debugging session.
If the DCL command contains a semicolon, you must enclose the command in quotation marks ("). Otherwise the semicolon is interpreted as a debugger command separator. To include a quotation mark in the string, enter two consecutive quotation marks ("").

QUALIFIERS

/INPUT=file-spec
Specifies an input DCL command procedure containing one or more DCL commands to be executed by the spawned subprocess. The default file type is .COM. If you specify a DCL command string with the SPAWN command and an input file with /INPUT, the command string is processed before the input file. After processing of the input file is complete, the subprocess is terminated. Do not use the asterisk (*) wildcard character in the file specification.
/OUTPUT=file-spec
Writes the output from the SPAWN operation to the specified file. The default file type is .LOG. Do not use the asterisk (*) wildcard character in the file specification.
/WAIT (default)

/NOWAIT
Controls whether the debugging session (the parent process) is suspended while the subprocess is running. The /WAIT qualifier (default) suspends the debugging session until the subprocess is terminated. You cannot enter debugger commands until control returns to the parent process.
The /NOWAIT qualifier executes the subprocess in parallel with the debugging session. You can enter debugger commands while the subprocess is running. If you use /NOWAIT, you should specify a DCL command with the SPAWN command; the DCL command is then executed in the subprocess. A message indicates when the spawned subprocess completes.
The kept debugger (that is, the debugger invoked with the DCL command DEBUG/KEEP) shares I/O channels with the parent process when it is run by a SPAWN/NOWAIT command. Therefore, in the DECwindows Motif interface, you must press the Return key twice on the DECterm from which the debugger was run after the debugger version number has appeared in the command view.
Optionally, you can execute the kept debugger in the following manner:
 $ DEFINE DBG$INPUT NL: 
 $ SPAWN/NOWAIT RUN DEBUG/KEEP 

DESCRIPTION

The SPAWN command acts exactly like the DCL command SPAWN. You can edit files, compile programs, read mail, and so on without ending your debugging session or losing your current debugging context.
In addition, you can spawn a DCL command SPAWN. DCL processes the second SPAWN command, including any qualifier specified with that command.
Related command:

ATTACH

Examples

DBG> SPAWN
$

This example shows that the SPAWN command, without a parameter, creates a subprocess at DCL level. You can now enter DCL commands. Log out to return to the debugger prompt.

DBG> SPAWN/NOWAIT/INPUT=READ_NOTES/OUTPUT=0428NOTES

This command creates a subprocess that is executed in parallel with the debugging session. This subprocess executes the DCL command procedure READ_NOTES.COM. The output from the spawned operation is written to the file 0428NOTES.LOG.

DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG @MYCOM

This command creates a subprocess that is executed in parallel with the debugging session. This subprocess creates another subprocess to execute the DCL command procedure MYCOM.COM. The output from that operation is written to the file MYCOM.LOG.

STEP

Executes the program up to the next line, instruction, or other specified location.

Format

STEP [integer]

PARAMETERS

integer
A decimal integer that specifies the number of step units (lines, instructions, and so on) to be executed. If you omit the parameter, the debugger executes one step unit.

QUALIFIERS

/BRANCH
Executes the program to the next branch instruction. STEP/BRANCH has the same effect as SET BREAK/TEMPORARY/BRANCH;GO.
/CALL
Executes the program to the next call or return instruction. STEP/CALL has the same effect as SET BREAK/TEMPORARY/CALL;GO.
/EXCEPTION
Executes the program to the next exception, if any. STEP/EXCEPTION has the same effect as SET BREAK/TEMPORARY/EXCEPTION;GO. If no exception occurs, STEP/EXCEPTION has the same effect as GO.
/INSTRUCTION

/INSTRUCTION=(opcode[,...])
When you do not specify an opcode, executes the program to the next instruction. STEP/INSTRUCTION has the same effect as SET BREAK/TEMPORARY/INSTRUCTION;GO.
On VAX processors, you can specify one or more opcodes; the debugger executes the program to the next instruction whose opcode is in the list. The following commands are equivalent:
DBG> STEP/INSTRUCTION=(opcode[,...]) 
DBG> SET BREAK/TEMPORARY/INSTRUCTION=(opcode[,...]);GO 
On VAX processors, you can specify vector instructions; do not include an instruction qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION, /MODIFY, /0, or /1) with the instruction mnemonic.
/INTO
If execution is currently suspended at a routine call, STEP/INTO executes the program up to the beginning of that routine (steps into that routine). Otherwise, STEP/INTO has the same effect as STEP without a qualifier. The /INTO qualifier is the opposite of /OVER (the default behavior).

Note
On Alpha processors, when execution is stopped at an exception break, STEP/INTO does not transfer control to a user exception handler. Stop execution within the handler by setting a breakpoint in the handler.

The STEP/INTO behavior can be changed by also using the /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers.
/JSB

/NOJSB
(VAX only) Qualifies a previous SET STEP INTO command or a current STEP/INTO command.
If execution is currently suspended at a routine call and the routine is called by a JSB instruction, STEP/INTO/NOJSB has the same effect as STEP/OVER. Otherwise, STEP/INTO/NOJSB has the same effect as STEP/INTO.
Use STEP/INTO/JSB to override a previous SET STEP NOJSB command. STEP/INTO/JSB enables STEP/INTO to step into routines called by a JSB instruction, as well as into routines called by a CALL instruction.
The /JSB qualifier is the default for all languages except DIBOL. The /NOJSB qualifier is the default for DIBOL. In DIBOL, application-declared routines are called by the CALL instruction and DIBOL Run-Time Library routines are called by the JSB instruction.
/LINE
Executes the program to the next line of source code. However, the debugger skips over any source lines that do not result in executable code when compiled (for example, comment lines). STEP/LINE has the same effect as SET BREAK/TEMPORARY/LINE;GO. This is the default behavior for all languages.
/OVER
If execution is currently suspended at a routine call, STEP/OVER executes the routine up to and including the routine's return instruction (steps over that routine). The /OVER qualifier is the default behavior and is the opposite of /INTO.

Note
On Alpha processors, when execution is suspended at a source line that contains a loop with a routine call, STEP/OVER steps into the called routine. To step to the next program statement, set a temporary breakpoint at the statement and enter GO.

/RETURN
Executes the routine in which execution is currently suspended up to its return instruction (that is, up to the point just prior to transferring control back to the calling routine). This enables you to inspect the local environment (for example, obtain the values of local variables) before the return instruction deletes the routine's call frame from the call stack. STEP/RETURN has the same effect as SET BREAK/TEMPORARY/RETURN;GO.
STEP/RETURN n executes the program up n levels of the call stack.
/SEMANTIC_EVENT
(Alpha only) Executes the program to the next semantic event.
STEP/SEMANTIC_EVENT simplifies debugging optimized code. (See the Description section.)
/SHARE (default)

/NOSHARE
Qualifies a previous SET STEP INTO command or a current STEP/INTO command.
If execution is currently suspended at a call to a shareable image routine, STEP/INTO/NOSHARE has the same effect as STEP/OVER. Otherwise, STEP/INTO/NOSHARE has the same effect as STEP/INTO.
Use STEP/INTO/SHARE to override a previous SET STEP NOSHARE command. STEP/INTO/SHARE enables STEP/INTO to step into shareable image routines, as well as into other kinds of routines.
/SILENT

/NOSILENT (default)
Controls whether the "stepped to..." message and the source line for the current location are displayed after the STEP has completed. The /NOSILENT qualifier specifies that the message is displayed. The /SILENT qualifier specifies that the message and source line are not displayed. The /SILENT qualifier overrides /SOURCE.
/SOURCE (default)

/NOSOURCE
Controls whether the source line for the current location is displayed after the STEP has completed. The /SOURCE qualifier specifies that the source line is displayed. The /NOSOURCE qualifier specifies that the source line is not displayed. The /SILENT qualifier overrides /SOURCE. See also the SET STEP [NO]SOURCE command.
/SYSTEM (default)

/NOSYSTEM
Qualifies a previous SET STEP INTO command or a current STEP/INTO command.
If execution is currently suspended at a call to a system routine (in P1 space), STEP/INTO/NOSYSTEM has the same effect as STEP/OVER. Otherwise, STEP/INTO/NOSYSTEM has the same effect as STEP/INTO.
Use STEP/INTO/SYSTEM to override a previous SET STEP NOSYSTEM command. STEP/INTO/SYSTEM enables STEP/INTO to step into system routines, as well as into other kinds of routines.
/VECTOR_INSTRUCTION
(VAX only) Executes the program to the next vector instruction. STEP/VECTOR_INSTRUCTION has the same effect as SET BREAK/TEMPORARY/VECTOR_INSTRUCTION;GO.

DESCRIPTION

The STEP command is one of the four debugger commands that can be used to execute your program (the others are CALL, EXIT, and GO).
The behavior of the STEP command depends on the following factors:

The default STEP mode previously established with a SET STEP command, if any
The qualifier specified with the STEP command, if any
The number of step units specified as the parameter to the STEP command, if any

If no SET STEP command was previously entered, the debugger takes the following default actions when you enter a STEP command without specifying a qualifier or parameter:

Executes a line of source code (the default is STEP/LINE).
Reports that execution has completed by issuing a "stepped to ..." message (the default is STEP/NOSILENT).
Displays the line of source code at which execution is suspended (the default is STEP/SOURCE).
Issues the prompt.

The following qualifiers affect the location to which you step:

/BRANCH
/CALL
/EXCEPTION
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/RETURN
/SEMANTIC_EVENT (Alpha only)
/VECTOR_INSTRUCTION (VAX only)

The following qualifiers affect what output is seen upon completion of a step:

/[NO]SILENT
/[NO]SOURCE

The following qualifiers affect what happens at a routine call:

/INTO
/[NO]JSB (VAX only)
/OVER
/[NO]SHARE
/[NO]SYSTEM

If you plan to enter several STEP commands with the same qualifiers, you can first use the SET STEP command to establish new default qualifiers (for example, SET STEP INTO, NOSYSTEM makes the STEP command behave like STEP/INTO/NOSYSTEM). Then you do not have to use those qualifiers with the STEP command. You can override the current default qualifiers for the duration of a single STEP command by specifying other qualifiers. Use the SHOW STEP command to identify the current STEP defaults.
If an exception breakpoint is triggered (resulting from a SET BREAK/EXCEPTION or a STEP/EXCEPTION command), execution is suspended before any application-declared condition handler is started. If you then resume execution with the STEP command, the debugger resignals the exception and the program executes to the beginning of (steps into) the condition handler, if any.
On Alpha systems, if your program has been compiled with the /OPTIMIZE qualifier, semantic stepping mode is available, with the STEP/SEMANTIC_EVENT and SET STEP SEMANTIC_EVENT commands. When you are debugging optimized code, the apparent source program location tends to bounce back and forth, with the same line appearing repeatedly. In semantic stepping mode, the program executes to the next point in the program where a significant effect (semantic event) occurs.
A semantic event is one of the following:

Data event --- An assignment to a user variable
Control event --- A control flow decision, with a conditional or unconditional transfer of control, other than a call
Call event --- A call (to a routine that is not stepped over) or a return from a call

Not every assignment, transfer of control, or call is a semantic event. The major exceptions are as follows:

When two instructions are required to assign to a complex or X_floating value, only the first instruction is treated as a semantic event.
When there are multiple branches that are part of a single higher-level construct, such as a decision tree of branches that implement a case or select construct, then only the first is treated as a semantic event.
When a call is made to a routine that is a compiler-specific helper routine, such as a call to OTS$MOVE, which handles certain kinds of string or storage copy operations, the call is not considered a semantic event. Control will not stop at the call.
To step into such a routine, you must do either of the following:

Set a breakpoint at the routine entry point.
Use a series of STEP/INSTRUCTION commands to reach the call of interest and then use STEP/INSTRUCTION/INTO to enter the called routine.

When there is more than one potential semantic event in a row with the same line number, only the first is treated as a semantic event.

The STEP/SEMANTIC_EVENT command causes a breakpoint to be set at the next semantic event. Execution proceeds to that next event. Parts of any number of different lines and statements may be executed along the way, without interfering with progress. When the semantic event is reached (that is, when the instruction associated with that event is reached but not yet executed), execution is suspended (similar to reaching the next line when STEP/LINE is used).
For more information on debugging optimized programs, see Chapter 13.
If you are using the multiprocess debugging configuration to debug a multiprocess program (if the logical name DBG$PROCESS has the value MULTIPROCESS), note the following additional points:

The STEP command is executed in the context of the visible process, but images in any other processes that are not on hold (through a SET PROCESS/HOLD command) are also allowed to execute. If you use the DO command to broadcast a STEP command to one or more processes, the STEP command is executed in the context of each specified process that is not on hold, but images in any other processes that are not on hold are also allowed to execute. In all cases, a hold condition in the visible process is ignored.
After execution is started, the way in which it continues depends on whether you entered a SET MODE [NO]INTERRUPT command. By default (SET MODE INTERRUPT), execution continues until it is suspended in any process. At that point, execution is interrupted in any other processes that were executing images, and the debugger prompts for input.

On VAX systems, the STEP/OVER command results in stepping into, not over, Fortran Run-Time Library routines. For more information, see Chapter 13.
Related commands:

CALL
DO
EXIT
GO
SET BREAK/EXCEPTION
SET MODE [NO]INTERRUPT
SET PROCESS
(SET,SHOW) STEP

Examples

DBG> SHOW STEP
step type: source, nosilent, by line, 
           over routine calls
DBG> STEP
stepped to SQUARES$MAIN\%LINE 4 
     4:         OPEN(UNIT=8, FILE='DATAFILE.DAT', STATUS='OLD')
DBG>

In this example, the SHOW STEP command identifies the default qualifiers currently in effect for the STEP command. In this case, the STEP command, without any parameters or qualifiers, executes the next line of source code. After the STEP command has completed, execution is suspended at the beginning of line 4.

DBG> STEP 5
stepped to MAIN\%LINE 47 
    47:         SWAP(X,Y);
DBG>

This command executes the next 5 lines of source code. After the STEP command has completed, execution is suspended at the beginning of line 47.

DBG> STEP/INTO
stepped to routine SWAP 
    23: procedure SWAP (A,B: in out integer) is
DBG> STEP
stepped to MAIN\SWAP\%LINE 24 
    24:    TEMP: integer := 0;
DBG> STEP/RETURN
stepped on return from MAIN\SWAP\%LINE 24 to MAIN\SWAP\%LINE 29 
    29: end SWAP;
DBG>

In this example, execution is paused at a call to routine SWAP, and the STEP/INTO command executes the program up to the beginning of the called routine. The STEP command executes the next line of source code. The STEP/RETURN command executes the rest of routine SWAP up to its RET instruction (that is, up to the point just prior to transferring control back to the calling routine).

DBG> SET STEP INSTRUCTION
DBG> SHOW STEP
step type: source, nosilent, by instruction, 
           over routine calls
DBG> STEP
stepped to SUB1\%LINE 26: MOVL     S^#4,B^-20(FP) 
    26:    Z:integer:=4;
DBG>

In this example, the SET STEP INSTRUCTION command establishes /INSTRUCTION as the default STEP command qualifier. This is verified by the SHOW STEP command. The STEP command executes the next instruction. After the STEP command has completed, execution is suspended at the first instruction (MOVL) of line 26 in module SUB1.

SYMBOLIZE

Converts a memory address to a symbolic representation, if possible.

Format

SYMBOLIZE address-expression[,...]

PARAMETERS

address-expression
Specifies an address expression to be symbolized. Do not use the asterisk (*) wildcard character.

DESCRIPTION

If the address is a static address, it is symbolized as the nearest preceding symbol name, plus an offset. If the address is also a code address and a line number can be found that covers the address, the line number is included in the symbolization.
If the address is a register address, the debugger displays all symbols in all set modules that are bound to that register. The full path name of each such symbol is displayed. The register name itself ("%R5", for example) is also displayed.
If the address is a call stack location in the call frame of a routine in a set module, the debugger searches for all symbols in that routine whose addresses are relative to the frame pointer (FP) or the stack pointer (SP). The closest preceding symbol name plus an offset is displayed as the symbolization of the address. A symbol whose address specification is too complex is ignored.
On Alpha processors, the commands SYMBOLIZE procedure-code-address and SYMBOLIZE procedure-descriptor-address both display the path name of the routine, entry point, or Ada package specified by these addresses.

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4538P049.HTM
  OSSG Documentation
  22-NOV-1996 13:02:48.22
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal