DEBUG STEP — VMS C_3.0
The STEP command causes the debugger to execute your program by
line, by instruction, or by some other step unit. STEP is one of
the four debugger commands that can cause your program to execute
(the others are CALL, EXIT, and GO).
Format:
STEP [/qualifier] [n]
The behavior of the STEP command depends on the following
factors:
o The default STEP mode previously established with a SET STEP
command, if any.
o The qualifier specified with the STEP command, if any.
o The number of step units specified as parameter to the STEP
command, if any.
If no SET STEP command was previously entered, the debugger takes
the following default action when you enter a STEP command
without specifying a qualifier or parameter:
1. Executes a line of source code (STEP/LINE is the default).
2. Reports that execution has completed by issuing a "stepped to
..." message (STEP/NOSILENT is the default).
3. Displays the line of source code where execution is suspended
(STEP/SOURCE is the default).
4. Issues the prompt.
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.
Additional information available:
ExamplesMultiprocess ProgramsParametersQualifiers
/BRANCH/CALL/EXCEPTION/INSTRUCTION/INSTRUCTION
/INTO/JSB/LINE/NOJSB/NOSHARE/NOSILENT/NOSOURCE
/NOSYSTEM/OVER/RETURN/SHARE/SILENT/SOURCE
/SYSTEM
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>
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, causes the debugger to
execute 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 causes the debugger to execute 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>
In this example, the STEP/INTO command causes the debugger to
execute the program up to the start of the routine that is being
called at the current PC value (SWAP, in this case). The STEP
command executes the next line of source code. The STEP/RETURN
command causes the debugger to finish executing 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 the
default STEP command qualifier to be /INSTRUCTION. This is
verified by the SHOW STEP command. The STEP command causes the
debugger to execute the next instruction. After the STEP command
has completed, execution is suspended at the first instruction
(MOVL) of line 26 in module SUB1.
Multiprocess Programs
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:
1. The STEP command is executed in the context of the visible
process, but images in any other unheld processes (processes
that have not been placed on hold with 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
unheld process, but images in any other unheld processes are
also allowed to execute. In all cases, a hold condition in
the visible process is ignored.
2. Once execution is started, the way in which it continues
depends on whether the command SET MODE [NO]INTERRUPT was
entered. 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.
Parameters
n
A decimal integer that specifies the number of step units (lines,
instructions, and so on) to be executed. If you do not specify
the parameter n, the debugger executes one step unit.
Qualifiers
STEP command qualifiers determine the exact stepping behavior.
The following qualifiers affect the location to which you step:
/BRANCH, /CALL, /EXCEPTION, /INSTRUCTION,
/INSTRUCTION=(opcode-list), /LINE, /RETURN.
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, /OVER, /[NO]SHARE, /[NO]SYSTEM.
/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 RET instruction.
STEP/CALL has the same effect as SET BREAK/TEMPORARY/CALL;GO.
/EXCEPTION
Executes the program to the next exception condition, if any.
STEP/EXCEPTION has the same effect as SET
BREAK/TEMPORARY/EXCEPTION;GO. If no exception condition occurs,
STEP/EXCEPTION has the same effect as GO.
/INSTRUCTION
Executes the program to the next instruction. STEP/INSTRUCTION
has the same effect as SET BREAK/TEMPORARY/INSTRUCTION;GO.
/INSTRUCTION=(opcode-list)
Executes the program to the next instruction whose opcode is
specified in the list. STEP/INSTRUCTION=(opcode[,...]) has the
same effect as SET BREAK/TEMPORARY/INSTRUCTION=(opcode[,...]);GO.
/INTO
If execution is currently suspended at a routine call, STEP/INTO
executes the program up to the start of that routine (steps into
that routine). Otherwise, STEP/INTO has the same effect as STEP
without a qualifier. /INTO is the opposite of /OVER (the default
behavior).
The STEP/INTO behavior may be modified by also using the
/[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers.
/JSB
Use STEP/INTO/JSB to override a previous SET STEP NOJSB command.
STEP/INTO/JSB enables a STEP/INTO command to step into routines
that are called by a JSB instruction, as well as into routines
that are called by a CALL instruction. /JSB is the default for
all languages except DIBOL. (See /NOJSB for more information).
/LINE
Executes the program to the next line of source code. However,
note that 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.
/NOJSB
Use /NOJSB with /INTO. 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.
/NOJSB is the default for DIBOL. In DIBOL, user-written routines
are called by the CALL instruction and DIBOL run-time library
routines are called by the JSB instruction.
/NOSHARE
Use /NOSHARE with /INTO. 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.
/NOSILENT
Specifies that the "stepped to..." message is displayed after the
STEP has completed. This is the default.
/NOSOURCE
Specifies that the source line for the current location is not
displayed after the STEP has completed. See also SET STEP
[NO]SOURCE.
/NOSYSTEM
Use /NOSYSTEM with /INTO. 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.
/OVER
If execution is currently suspended at a routine call, STEP/OVER
executes the routine up to and including the routine's RET
instruction (steps over that routine). /OVER is the default
behavior and is the opposite of /INTO.
/RETURN
Executes the routine in which execution is currently suspended up
to its RET 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 RET 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.
/SHARE
Use STEP/INTO/SHARE to override a previous SET STEP NOSHARE
command. STEP/INTO/SHARE enables a STEP/INTO command to step
into shareable image routines, as well as into other kinds of
routines. /SHARE is the default.
/SILENT
Specifies that the "stepped to..." message and the source line
for the current location are not displayed after the STEP has
completed. /SILENT overrides /SOURCE.
/SOURCE
Specifies that the source line for the current location is
displayed after the STEP has completed. This is the default.
See also SET STEP [NO]SOURCE.
/SYSTEM
Use STEP/INTO/SYSTEM to override a previous SET STEP NOSYSTEM
command. STEP/INTO/SYSTEM enables a STEP/INTO command to step
into system routines (in P1 space), as well as into other kinds
of routines. /SYSTEM is the default.