OpenVMS Debugger Manual

Updated: 11 December 1998

OpenVMS Debugger Manual

Contents

Index

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 14.
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 14.
Related commands:

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

Examples

#1
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.

#2
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.

#3
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>

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).

#4
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.
If the debugger cannot symbolize the address, a message is displayed.
Related commands:

EVALUATE/ADDRESS
SET MODE [NO]LINE
SET MODE [NO]SYMBOLIC
(SET,SHOW,CANCEL) MODULE
SHOW SYMBOL

Examples

#1
DBG> SYMBOLIZE %R5 address PROG\%R5: PROG\X DBG>

This example shows that the local variable X in routine PROG is located in register R5.

#2
DBG> SYMBOLIZE %HEX 27C9E3 address 0027C9E3: MOD5\X DBG>

This command directs the debugger to treat the integer literal 27C9E3 as a hexadecimal value and convert that address to a symbolic representation, if possible. The address converts to the symbol X in module MOD5.

SYNCHRONIZE VECTOR_MODE (VAX Only)

Forces immediate synchronization between the scalar and vector processors.
Applies to VAX vectorized programs.

Format

SYNCHRONIZE VECTOR_MODE

Description

The SYNCHRONIZE VECTOR_MODE command forces immediate synchronization between the scalar and vector processors by issuing SYNC and MSYNC instructions. The effect is as follows:

Any exception that was caused by a vector instruction and was still pending delivery is immediately delivered. Forcing the delivery of a pending exception triggers an exception breakpoint or tracepoint (if one was set) or invokes an exception handler (if one is available at that location in the program).
Any read or write operation between vector registers and either the general registers or memory is completed immediately. That is, any vector memory instruction that was still being executed completes execution.

Entering the SYNCHRONIZE VECTOR_MODE command is equivalent to issuing SYNC and MSYNC instructions at the location in the program at which execution is suspended.
By default, the debugger does not force synchronization between the scalar and vector processors during program execution (SET VECTOR_MODE NOSYNCHRONIZED). To force such synchronization, use the SET VECTOR_MODE SYNCHRONIZED command.
Related commands:

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

Examples

#1
DBG> SYNCHRONIZE VECTOR_MODE %DEBUG-I-SYNCREPCOM, Synchronize reporting complete

This command forces immediate synchronization between the scalar and vector processors. In this example, the diagnostic message indicates that the synchronization operation has completed and that all pending vector exceptions have been delivered and reported.

#2
DBG> STEP (1) stepped to .MAIN.\SUB\%LINE 99 99: VVDIVD V1,V0,V2 DBG> STEP (2) stepped to .MAIN.\SUB\%LINE 100 100: CLRL R0 DBG> EXAMINE/FLOAT %V2 (3) 0\%V2 [0]: 13.53400 [1]: Reserved operand, encoded as floating divide by zero [2]: 247.2450 ... DBG> SYNCHRONIZE VECTOR_MODE (4) %SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, mask=00000004, PC=000002E1, PSL=03C00010 break on unhandled exception preceding .MAIN.\SUB\%LINE 100 100: CLRL R0) DBG>

DBG> STEP   (1)
stepped to .MAIN.\SUB\%LINE 99 
    99:         VVDIVD  V1,V0,V2
DBG> STEP   (2)
stepped to .MAIN.\SUB\%LINE 100 
   100:         CLRL    R0
DBG> EXAMINE/FLOAT %V2   (3)
0\%V2 
    [0]:  13.53400 
    [1]:  Reserved operand, encoded as floating divide by zero 
    [2]:  247.2450
    ...
DBG> SYNCHRONIZE VECTOR_MODE   (4)
%SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
                  mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\%LINE 100
   100:         CLRL    R0) 
DBG>

The comments that follow refer to the callouts in the previous example:

This STEP command suspends program execution on line 99, just before a VVDIVD instruction is executed. Assume that, in this example, the instruction will trigger a floating-point divide-by-zero exception.
This STEP command executes the VVDIVD instruction. Note, however, that the exception is not delivered at this point in the execution of the program.
The EXAMINE/FLOAT command displays a decoded exception message in element 1 of the destination register, V2. This confirms that a floating-point divide-by-zero exception was triggered and is pending delivery.
The SYNCHRONIZE VECTOR_MODE command forces the immediate delivery of the pending vector exception.

TYPE

Displays lines of source code.

Format

TYPE [[module-name\]line-number[:line-number]
[,[module-name\]line-number[:line-number][,...]]]

Parameters

module-name
Specifies the module that contains the source lines to be displayed. If you specify a module name along with the line numbers, use standard path-name notation: insert a backslash (\) between the module name and the line numbers.
If you do not specify a module name, the debugger uses the current scope (as established by a previous SET SCOPE command, or the PC scope if you did not enter a SET SCOPE command) to find source lines for display. If you specify a scope search list with the SET SCOPE command, the debugger searches for source lines only in the module associated with the first named scope.
line-number
Specifies a compiler-generated line number (a number used to label a source language statement or statements).
If you specify a single line number, the debugger displays the source code corresponding to that line number.
If you specify a list of line numbers, separating each with a comma, the debugger displays the source code corresponding to each of the line numbers.
If you specify a range of line numbers, separating the beginning and ending line numbers in the range with a colon (:), the debugger displays the source code corresponding to that range of line numbers.
You can display all the source lines of a module by specifying a range of line numbers starting from 1 and ending at a number equal to or greater than the largest line number in the module.
After displaying a single line of source code, you can display the next line of that module by entering a TYPE command without a line number (that is, by entering TYPE and then pressing the Return key). You can then display the next line and successive lines by repeating this sequence, in effect, reading through your source program one line at a time.

Description

The TYPE command displays the lines of source code that correspond to the specified line numbers. The line numbers used by the debugger to identify lines of source code are generated by the compiler. They appear in a compiler-generated listing and in a screen-mode source display.
If you specify a module name with the TYPE command, the module must be set. Use the SHOW MODULE command to determine whether a particular module is set. Then use the SET MODULE command, if necessary.
In screen mode, the output of a TYPE command is directed at the current source display, not at an output or DO display. The source display shows the lines specified and any surrounding lines that fit in the display window.
Related commands:

EXAMINE/SOURCE
SET (BREAK,TRACE,WATCH)/[NO]SOURCE
SET MODE [NO]SCREEN
(SET,SHOW,CANCEL) SCOPE
SET STEP [NO]SOURCE
STEP/[NO]SOURCE

Examples

#1
DBG> TYPE 160 module COBOLTEST 160: START-IT-PARA. DBG> TYPE module COBOLTEST 161: MOVE SC1 TO ES0. DBG>

In this example, the first TYPE command displays line 160, using the current scope to locate the module containing that line number. The second TYPE command, entered without specifying a line number, displays the next line in that module.

#2
DBG> TYPE 160:163 module COBOLTEST 160: START-IT-PARA. 161: MOVE SC1 TO ES0. 162: DISPLAY ES0. 163: MOVE SC1 TO ES1. DBG>

This command displays lines 160 to 163, using the current scope to locate the module.

#3
DBG> TYPE SCREEN_IO\7,22:24

This command displays line 7 and lines 22 to 24 in module SCREEN_IO.

Contents

Index

Legal

 
4538PRO_063.HTML

OpenVMS Debugger Manual

STEP

Format

STEP [integer]

Parameters

integer

Qualifiers

/BRANCH

/CALL

/EXCEPTION

/INSTRUCTION

/INSTRUCTION=(opcode[,...])

/INTO

/JSB

/NOJSB

/LINE

/OVER

/RETURN

/SEMANTIC_EVENT

/SHARE (default)

/NOSHARE

/SILENT

/NOSILENT (default)

/SOURCE (default)

/NOSOURCE

/SYSTEM (default)

/NOSYSTEM

/VECTOR_INSTRUCTION

Description

Examples

SYMBOLIZE

Format

SYMBOLIZE address-expression[,...]

Parameters

address-expression

Description

Examples

SYNCHRONIZE VECTOR_MODE (VAX Only)

Format

SYNCHRONIZE VECTOR_MODE

Description

Examples

TYPE

Format

TYPE [[module-name\]line-number[:line-number] [,[module-name\]line-number[:line-number][,...]]]

Parameters

module-name

line-number

Description

Examples

TYPE [[module-name\]line-number[:line-number]
[,[module-name\]line-number[:line-number][,...]]]