OpenVMS Debugger Manual

Document revision date: 30 March 2001

OpenVMS Debugger Manual

Contents

Index

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

STOP

Interrupts all specified processes that are running.

Format

STOP [process-spec[,...]

Parameters

process-spec
This parameter specifies the process set to be stopped. The default is the current process set. Use any of the following forms:

[%PROCESS_NAME] process-name The process name, if that name does not contain spaces or lowercase characters. The process name can include the asterisk (*) wildcard character.

[%PROCESS_NAME] " process-name" The process name, if that name contains spaces or lowercase characters. You can also use apostrophes (') instead of quotation marks (").

%PROCESS_PID process_id The process identifier (PID, a hexadecimal number).

[%PROCESS_NUMBER] process-number
(or %PROC process-number) The number assigned to a process when it comes under debugger control. A new number is assigned sequentially, starting with 1, to each process. If a process is terminated with the EXIT or QUIT command, the number can be assigned again during the debugging session. Process numbers appear in a SHOW PROCESS display. Processes are ordered in a circular list so they can be indexed with the built-in symbols %PREVIOUS_PROCESS and %NEXT_PROCESS.

process-set-name A symbol defined with the DEFINE/PROCESS_SET command to represent a group of processes.

%NEXT_PROCESS The next process after the visible process in the debugger's circular process list.

%PREVIOUS_PROCESS The process previous to the visible process in the debugger's circular process list.

%VISIBLE_PROCESS The process whose stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.

You can also use the asterisk (*) wildcard character to specify all processes.

Description

The STOP command interrupts the specified processes. You can use the STOP command in nowait mode to stop processes that are still running.

Examples

#1
all> SHOW PROCESS Number Name State Current PC 1 DBGK$$2727282C break SERVER\main\%LINE 18834 2 USER1_2 running not available * 3 USER1_3 running not available all> CLIENTS> STOP all> show process Number Name State Current PC 1 DBGK$$2727282C break SERVER\main\%LINE 18834 2 USER1_2 interrupted 0FFFFFFFF800F7A20 * 3 USER1_3 interrupted 0FFFFFFFF800F7A20 all>

all> SHOW PROCESS
 Number  Name          State            Current PC 
     1 DBGK$$2727282C  break    SERVER\main\%LINE 18834 
     2 USER1_2         running          not available 
*    3 USER1_3         running          not available 
all> CLIENTS> STOP
all> show process 
 Number  Name          State            Current PC 
     1 DBGK$$2727282C  break    SERVER\main\%LINE 18834 
     2 USER1_2         interrupted   0FFFFFFFF800F7A20 
*    3 USER1_3         interrupted   0FFFFFFFF800F7A20 
all>

This command sequence first shows all processes, then stops the processes in process set clients. The last SHOW PROCESS command shows the new process states.

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

WAIT

Causes the debugger to wait until the target processes have stopped before prompting for the next command.

Format

WAIT

Description

When debugging multiprocess programs, the WAIT command causes the debugger to complete executing all process specified by the previous command before displaying a prompt to accept and execute another command.
Related commands:
STOP
SET MODE [NO]INTERRUPT
SET MODE [NO]WAIT

Example


all> 2,3> GO;WAIT processes 2,3 break at CLIENT\main\%LINE 18814 18814: status = sys$qiow (EFN$C_ENF, mbxchan, IO$_READVBLKIO$M_WRITERCHECK, myiosb) process 1 break at SERVER\main\%LINE 18834 18834: if ((myiosb.iosb$w_status == SS$_NOREADER) && (pos_status != -1)) all>

all> 2,3> GO;WAIT
processes 2,3 
  break at CLIENT\main\%LINE 18814 
      18814:      status = sys$qiow (EFN$C_ENF,  mbxchan, 
                        IO$_READVBLKIO$M_WRITERCHECK, myiosb) 
process 1 
  break at SERVER\main\%LINE 18834 
      18834:             if ((myiosb.iosb$w_status ==  
                        SS$_NOREADER) && (pos_status != -1)) 
all>

This command sequence executes the target processes (in this case, 2 and 3), and the debugger waits until both processes reach breakpoints before prompting for the next command.

WHILE

Executes a sequence of commands while the language expression (Boolean expression) you have specified evaluates as true.

Format

WHILE Boolean-expression DO (command[;...])

Parameters

Boolean-expression
Specifies a language expression that evaluates as a Boolean value (true or false) in the currently set language.
command
Specifies a debugger command. If you specify more than one command, separate the commands with semicolons (;). At each execution, the debugger checks the syntax of any expressions in the commands and then evaluates them.

Description

The WHILE command evaluates a Boolean expression in the current language. If the value is true, the command list in the DO clause is executed. The command then repeats the sequence, reevaluating the Boolean expression and executing the command list until the expression is evaluated as false.
If the Boolean expression is false, the WHILE command terminates.
Related commands:
EXITLOOP
FOR
REPEAT

Example


DBG> WHILE (X .EQ. 0) DO (STEP/SILENT)

This command directs the debugger to keep stepping through the program until X no longer equals 0 (Fortran example).

Contents

Index

privacy and legal statement

4538PRO_062.HTML

[%PROCESS_NAME] process-name	The process name, if that name does not contain spaces or lowercase characters. The process name can include the asterisk (*) wildcard character.
[%PROCESS_NAME] " process-name"	The process name, if that name contains spaces or lowercase characters. You can also use apostrophes (') instead of quotation marks (").
%PROCESS_PID process_id	The process identifier (PID, a hexadecimal number).
[%PROCESS_NUMBER] process-number (or %PROC process-number)	The number assigned to a process when it comes under debugger control. A new number is assigned sequentially, starting with 1, to each process. If a process is terminated with the EXIT or QUIT command, the number can be assigned again during the debugging session. Process numbers appear in a SHOW PROCESS display. Processes are ordered in a circular list so they can be indexed with the built-in symbols %PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name	A symbol defined with the DEFINE/PROCESS_SET command to represent a group of processes.
%NEXT_PROCESS	The next process after the visible process in the debugger's circular process list.
%PREVIOUS_PROCESS	The process previous to the visible process in the debugger's circular process list.
%VISIBLE_PROCESS	The process whose stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.