Document revision date: 30 March 2001

## OpenVMS Debugger Manual

Previous | Contents | Index

## SHOW TRACE

> Displays information about tracepoints.

### Format

> SHOW TRACE

### Qualifiers

> #### /PREDEFINED

> Displays information about predefined tracepoints.

> #### /USER

> Displays information about user-defined tracepoints.

### Description

> The SHOW TRACE command displays information about tracepoints that are currently set, including any options such as WHEN or DO clauses, /AFTER counts, and so on, and whether the tracepoints are deactivated.

> By default, SHOW TRACE displays information about both user-defined and predefined tracepoints (if any). This is equivalent to entering the SHOW TRACE/USER/PREDEFINED command. User-defined tracepoints are set with the SET TRACE command. Predefined tracepoints are set automatically when you start the debugger, and they depend on the type of program you are debugging.

> If you established a tracepoint using SET TRACE/AFTER:n, the SHOW TRACE command displays the current value of the decimal integer n, that is, the originally specified integer value minus 1 for each time the tracepoint location was reached. (The debugger decrements n each time the tracepoint location is reached until the value of n is 0, at which time the debugger takes trace action.)

> On Alpha systems, the SHOW TRACE command does not display individual instructions when the trace is on a particular class of instruction (as with SET TRACE/CALL or SET TRACE/RETURN).

> Related commands:

> > (ACTIVATE, DEACTIVATE, SET, CANCEL) TRACE

### Examples

#1
    DBG> SHOW TRACE
    tracepoint at routine CALC\MULT
    tracepoint on calls:
            RET     RSB     BSBB    JSB     BSBW    CALLG   CALLS
    DBG>

> 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
    all> SHOW TRACE/PREDEFINED
    predefined tracepoint on program activation
     DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_ AT H1 SOURCE
            (EXAM/SOURCE .%SOURCE_SCOPE\%PC);
        SET DISP/DYN/REM/SIZE:64/PROC INST_ AT H1 INST
            (EXAM/INSTRUCTION .0\%PC))
    predefined tracepoint on program termination
    all>

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

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

#2
    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 Compaq DECwindows Motif for OpenVMS user 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 Compaq DECwindows Motif for OpenVMS user 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 Compaq DECwindows Motif for OpenVMS user 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

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

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

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

> 1. Executes a line of source code (the default is STEP/LINE).
> 2. Reports that execution has completed by issuing a "stepped to ..." message (the default is STEP/NOSILENT).
> 3. Displays the line of source code at which execution is suspended (the default is STEP/SOURCE).
> 4. 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 debugging a multiprocess program, the STEP command is executed in the context of the current process set. In addition, when debugging a multiprocess program, the way in which execution continues in your process depends on whether you entered a SET MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By default (SET MODE NOINTERRUPT), when one process stops, the debugger takes no action with regard to the other processes. Also by default (SET MODE WAIT), the debugger waits until all process in the current process set have stopped before prompting for a new command. See Chapter 15 for more information.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 4538PRO_061.HTML