Totalview® for HPC Reference Guide : PART I Using the CLI : Chapter 2 CLI Commands : dstep
dstep
Steps lines, stepping into subfunctions
Format 
dstep [ -back ][ num-steps]
Arguments 
-back
(ReplayEngine only) Steps to the previous source line, moving into subroutines that called the current function. This option can be abbreviated to -b.
num-steps
An integer greater than 0, indicating the number of source lines to execute.
Description 
The dstep command executes source lines; that is, it advances the program by steps (source lines). If a statement in a source line invokes a subfunction, the dstep command steps into the function.
The optional num-steps argument defines the number of dstep operations to perform. If you do not specify num-steps, the default is 1.
NOTE >> You can use the dskipCommand to create and manage single-stepper “skip” rules that modify the way source-level single stepping works. You can add rules that match a function, all functions in a source file, or a specific function in a specific source file.
The dstep command iterates over the arenas in the focus set by doing a thread-level, process-level, or group-level step in each arena, depending on the width of the arena. The default width is process (p).
If the width is process, the dstep command affects the entire process that contains the thread being stepped. Thus, although the CLI is only stepping one thread, all other threads in the same process also resume executing. In contrast, the dfocus t dstep command steps only the thread of interest (TOI).
NOTE >> On systems having identifiable manager threads, thedfocus t dstep command allows the manager threads as well as the TOI to run.
The action taken on each term in the focus list depends on whether its width is thread, process, or group, and on the group specified in the current focus. (If you do not explicitly specify a group, the default is the control group.)
If some thread hits an action point other than the goal breakpoint during a step operation, that ends the step.
Group Width
The behavior depends on the group specified in the arena:
Process group
TotalView examines that group and identifies each process having a thread stopped at the same location as the TOI. TotalView selects one matching thread from each matching process. TotalView then runs all processes in the group and waits until the TOI arrives at its goal location; each selected thread also arrives there.
Thread group
The behavior is similar to process width behavior except that all processes in the program control group run, rather than just the process of interest (POI). Regardless of which threads are in the group of interest, TotalView only waits for threads that are in the same share group as the TOI. This is because it is not useful to run threads executing in different images to the same goal.
Process Width (default)
The behavior depends on the group specified in the arena. Process width is the default.
Process group
TotalView allows the entire process to run, and execution continues until the TOI arrives at its goal location. TotalView plants a temporary breakpoint at the goal location while this command executes. If another thread reaches this goal breakpoint first, your program continues to execute until the TOI reaches the goal.
Thread group
TotalView runs all threads in the process that are in that group to the same goal as the TOI. If a thread arrives at the goal that is not in the group of interest, this thread also stops there. The group of interest specifies the set of threads for which TotalView waits. This means that the command does not complete until all threads in the group of interest are at the goal.
Thread Width
Only the TOI is allowed to run. (This is not supported on all systems.)
Command alias 
Alias
Definition
Description
s
dstep
Runs the TOI one statement, while allowing other threads in the process to run.
S
{dfocus g dstep}
Searches for threads in the share group that are at the same PC as the TOI, and steps one such aligned thread in each member one statement. The rest of the control group runs freely. This is a group stepping command.
sl
{dfocus L dstep}
Steps the process threads in lockstep. This steps the TOI one statement, and runs all threads in the process that are at the same PC as the TOI to the same (goal) statement. Other threads in the process run freely. The group of threads that is at the same PC is called the lockstep group.This alias does not force process width. If the default focus is set to group, this steps the group.
SL
{dfocus gL dstep}
Steps lockstep threads in the group. This steps all threads in the share group that are at the same PC as the TOI one statement. Other threads in the control group run freely.
sw
{dfocus W dstep}
Steps worker threads in the process. This steps the TOI one statement, and runs all worker threads in the process to the same (goal) statement. The nonworker threads in the process run freely. This alias does not force process width. If the default focus is set to group, this steps the group.
SW
{dfocus gW dstep}
Steps worker threads in the group. This steps the TOI one statement, and runs all worker threads in the same share group to the same (goal) statement. All other threads in the control group run freely.
Examples 
dstep
Executes the next source line, stepping into any procedure call it encounters. Although the CLI only steps the current thread, other threads in the process run.
s 15
Executes the next 15 source lines.
f p1.2 dstep
Steps thread 2 in process 1 by one source line. This also resumes execution of all threads in process 1; they halt as soon as thread 2 in process 1 executes its statement.
f t1.2 s
Steps thread 2 in process 1 by one source line. No other threads in process 1 execute.
 
Related Topics
Creating a Process by Single Stepping
Stepping and Setting Breakpoints
Using Stepping Commands
Group > Step Command
Process > Step Command
Thread > Step Command
dstepiCommand
dnextCommand
dfocusCommand
dskipCommand