OpenVMS Debugger Manual


Previous Contents Index

Related commands:

DEPOSIT
EVALUATE
EXAMINE
SET WATCH

Example


DBG> MONITOR COUNT
      

This command displays the name and current value of the variable COUNT in the monitor view of the debugger's HP DECwindows Motif for OpenVMS user interface. The value is updated whenever the debugger regains control from the program.


MOVE

Moves a screen display vertically or horizontally across the screen.

Note

This command is not available in the HP DECwindows Motif for OpenVMS user interface to the debugger.

Format

MOVE [display-name[,...]]


Parameters

display-name

Specifies a display to be moved. You can specify any of the following entities:

If you do not specify a display, the current scrolling display, as established by the SELECT command, is chosen.


Qualifiers

/DOWN[:n]

Moves the display down by n lines (if n is positive) or up by n lines (if n is negative). If you omit n, the display is moved down by 1 line.

/LEFT[:n]

Moves the display to the left by n lines (if n is positive) or right by n lines (if n is negative). If you omit n, the display is moved to the left by 1 line.

/RIGHT[:n]

Moves the display to the right by n lines (if n is positive) or left by n lines (if n is negative). If you omit n, the display is moved to the right by 1 line.

/UP[:n]

Moves the display up by n lines (if n is positive) or down by n lines (if n is negative). If you omit n, the display is moved up by 1 line.

Description

You must specify at least one qualifier.

For each display specified, the MOVE command simply creates a window of the same dimensions elsewhere on the screen and maps the display to it, while maintaining the relative position of the text within the window.

The MOVE command does not change the order of a display on the display pasteboard. Depending on the relative order of displays, the MOVE command can cause the display to hide or uncover another display or be hidden by another display, partially or totally.

A display can be moved only up to the edge of the screen.

For a list of the keypad-key definitions associated with the MOVE command, type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the current key definitions.

Related commands:

DISPLAY
EXPAND
SELECT/SCROLL
(SET,SHOW) TERMINAL

Examples

#1

DBG> MOVE/LEFT
      

This command moves the current scrolling display to the left by 1 column.

#2

DBG> MOVE/UP:3/RIGHT:5 NEW_OUT
      

This command moves display NEW_OUT up by 3 lines and to the right by 5 columns.


PTHREAD

Passes a command to the POSIX Threads debugger for execution.

Note

This command is valid only when the event facility is THREADS and the program is running POSIX Threads 3.13 or later.

Format

PTHREAD command


Parameters

command

A POSIX Threads debugger command.

Description

Passes a command to the POSIX Threads debugger for execution. The results appear in the command view. Once the POSIX Threads debugger command has been completed, control is returned to the OpenVMS debugger. You can get help on POSIX Threads debugger commands by typing PTHREAD HELP .

See the Guide to POSIX Threads Library for more information about using the POSIX Threads debugger.

Related commands:


Example


DBG_1> PTHREAD HELP
    conditions [-afhwqrs] [-N <n>] [id]...: list condition variables 
    exit: exit from DECthreads debugger 
    help [topic]: display help information 
    keys [-v] [-N <n>] [id]...: list keys 
    mutexes [-afhilqrs] [-N <n>] [id]...: list mutexes 
    quit: exit from DECthreads debugger 
    show [-csuv]: show stuff 
    squeue [-c <n>] [-fhq] [-t <t> 
] [a]: format queue 
    stacks [-fs] [sp]...: list stacks 
    system: show system information 
    threads [-1] [-N <n>] [-abcdfhklmnor] [-s 
 <v>] [-tz] [id]...: list threads 
    tset [-chna] [-s <v>] <id> 
: set state of thread 
    versions: display versions 
    write <st>: write a string 
All keywords may be abbreviated: if the abbreviation is ambiguous, 
the first match will be used. For more help, type 'help <topic>'. 
DBG_1>
 
      

This command invokes the POSIX Threads debugger help file, then returns control to the OpenVMS debugger. To get specific help on a POSIX Threads debugger Help topic, type PTHREAD HELP topic .


QUIT

Ends a debugging session, or terminates one or more processes of a multiprocess program (similar to EXIT), but without allowing any application-declared exit handlers to run. If used within a command procedure or DO clause and no process is specified, it exits the command procedure or DO clause at that point.

Format

QUIT [process-spec[,...]]


Parameters

process-spec

(Kept debugger only.) Specifies a process currently under debugger control. 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 QUIT command is similar to the EXIT command, except that QUIT does not cause your program to execute and, therefore, does not execute any application-declared exit handlers in your program.

Ending a Debugging Session

To end a debugging session, enter the QUIT command at the debugger prompt without specifying any parameters. This causes orderly termination of the session: the debugger exit handler is executed (closing log files, restoring the screen and keypad states, and so on), and control is returned to DCL level. You cannot then continue to debug your program by entering the DCL command DEBUG or CONTINUE (you must restart the debugger).

Using the QUIT Command in Command Procedures and DO Clauses

When the debugger executes a QUIT command (without any parameters) in a command procedure, control returns to the command stream that invoked the command procedure. A command stream can be the terminal, an outer (containing) command procedure, or a DO clause in a command or screen display definition. For example, if the command procedure was invoked from within a DO clause, control returns to that DO clause, where the debugger executes the next command (if any remain in the command sequence).

When the debugger executes a QUIT command (without any parameters) in a DO clause, it ignores any remaining commands in that clause and displays its prompt.

Terminating Specified Processes

If you are debugging a multiprocess program, you can use the QUIT command to terminate specified processes without ending the debugging session. The same techniques and behavior apply, whether you enter the QUIT command at the prompt or use it within a command procedure or DO clause.

To terminate one or more processes, enter the QUIT command, specifying these processes as parameters. This causes orderly termination of the images in these processes without executing any application-declared exit handlers associated with these images. Subsequently, the specified processes are no longer identified in a SHOW PROCESS/ALL display.

In contrast to the EXIT command, the QUIT command does not cause any process to start execution.

Related commands:

DISCONNECT
@ (Execute Procedure)
Ctrl/C
Ctrl/Y
Ctrl/Z
EXIT
RERUN
RUN
SET ABORT_KEY
SET PROCESS

Examples

#1

DBG> QUIT
$
      

This command ends the debugging session and returns you to DCL level.

#2

all> QUIT %NEXT_PROCESS, JONES_3, %PROC 5
all>
      

This command causes orderly termination of three processes of a multiprocess program: the process after the visible process on the process list, process JONES_3, and process 5. Control is returned to the debugger after the specified processes have exited.


REBOOT (Integrity servers and Alpha Only)

When debugging operating system code with the OpenVMS System-Code Debugger, reboots the target machine running the operating system code and executes (or reexecutes) your system program.

The REBOOT command, in other words, is similar to the RUN or RERUN commands when you are within the OpenVMS System-Code Debugger environment. (The OpenVMS System-Code Debugger is a kernel debugger that is activated through the OpenVMS Debugger.)

Before you issue this command, you must create an Alpha or Integrity server device driver, activate the OpenVMS System-Code Debugger,and use the CONNECT command that provides debugging capability.

You must also have started the OpenVMS Debugger with the DEBUG/KEEP command.


Format

REBOOT


Description

For complete information on using the OpenVMS System-Code Debugger, see the OpenVMS Alpha System Analysis Tools Manual.

Related commands:

CONNECT
DISCONNECT

Example


DBG> REBOOT
      

This command reboots the target machine where you will be debugging the OpenVMS operating system and reruns your program.


REPEAT

Executes a sequence of commands a specified number of times.

Format

REPEAT language-expression DO (command[;...])


Parameters

language-expression

Denotes any expression in the currently set language that evaluates to a positive integer.

command

Specifies a debugger command. If you specify more than one command, you must 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 REPEAT command is a simple form of the FOR command. The REPEAT command executes a sequence of commands repetitively a specified number of times, without providing the options for establishing count parameters that the FOR command does.

Related commands:

EXITLOOP
FOR
WHILE

Example


DBG> REPEAT 10 DO (EXAMINE Y; STEP)
      

This command line sets up a loop that issues a sequence of two commands (EXAMINE Y, then STEP) 10 times.


RERUN

Reruns the program currently under debugger control.

Note

Requires that you started your debugging session with the DCL command DEBUG/KEEP and then executed the debugger RUN command. If you began your session with the DCL command RUN filespec instead, you cannot use the debugger RERUN command.

Format

RERUN


Qualifiers

/ARGUMENTS="arg-list"

Specifies a list of arguments. If you specify a quoted string, you might have to add quotation marks because the debugger strips them when parsing the string. If you do not specify arguments, any arguments that were specified previously when running or rerunning that program are applied, by default.

/HEAP_ANALYZER

(Applies only to workstation users.) Invokes the Heap Analyzer, a debugger feature that helps you understand how memory is used by your application. For more information on using the Heap Analyzer, see Chapter 12.

/SAVE (default)

/NOSAVE

Controls whether to save the current state (activated or deactivated) of all breakpoints, tracepoints, and static watchpoints for the next run of the program. The /SAVE qualifier specifies that their state is saved, and /NOSAVE specifies that their state is not saved. /SAVE may or may not save the state of a particular nonstatic watchpoint depending on the scope of the variable being watched relative to the main program unit (where execution restarts).

Description

If you invoked the debugger with the DCL command DEBUG/KEEP and subsequently used the debugger RUN command to begin debugging your program, you can then use the RERUN command to rerun the program currently under debugger control.

The RERUN command terminates the image you were debugging and then restarts that image under debugger control. Execution is paused at the start of the main program unit, as if you had used the debugger RUN command or the DCL command RUN/DEBUG.

The RERUN command uses the same version of the image that is currently under debugger control. To debug a different version of that program (or a different program) from the same debugging session, use the RUN command.

Related commands:

RUN (debugger command)
RUN (DCL command)
(ACTIVATE,DEACTIVATE) BREAK
(ACTIVATE,DEACTIVATE) TRACE
(ACTIVATE,DEACTIVATE) WATCH

Examples

#1

DBG> RERUN
      

This command reruns the current program. By default, the debugger saves the current state of all breakpoints, tracepoints, and static watchpoints (activated or deactivated).

#2

DBG> RERUN/NOSAVE
      

This command reruns the current program without saving the current state of breakpoints, tracepoints, and watchpoints---in effect, the same as using the RUN command and specifying the image name.

#3

DBG> RERUN/ARGUMENTS="fee fii foo fum"
      

This command reruns the current program with new arguments.


RUN

Runs a program under debugger control.

Note

Requires that you started your debugging session with the DCL command DEBUG/KEEP. If you began your session with the DCL command RUN filespec instead, you cannot use the debugger RUN command.

Format

RUN [program-image]


Parameters

program-image

Specifies the executable image of the program to be debugged. Do not specify an image if you use the /COMMAND=cmd-symbol qualifier.

Qualifiers

/ARGUMENTS="arg-list"

Specifies a list of arguments. If you specify a quoted string, you might have to add quotation marks because the debugger strips quotes when parsing the string.

/COMMAND="cmd-symbol"

Specifies a DCL foreign command for running the program.

Do not use this qualifier if you specify a program-image parameter.

Do not specify a DCL command or any other command definition that was created with the SET COMMAND command.

/HEAP_ANALYZER

(Applies only to workstation users.) Invokes the Heap Analyzer, a debugger feature that helps you understand how memory is used by your application. For more information on using the Heap Analyzer, see Chapter 12.

/NEW

Runs a new program under debugger control without terminating any programs already running.

Description

If you invoked the debugger with the DCL command DEBUG/KEEP, you can use the debugger RUN command at any time during a debugging session to start a program under debugger control. If you are in the midst of debugging a program when you issue the RUN command, that program will first be terminated unless you use the /NEW qualifier.

To run the same program again (that is, the same version of the program that is currently under debugger control), use the RERUN command. RERUN enables you to save the current state (activated or deactivated) of any breakpoints, tracepoints, and static watchpoints.

For a discussion of passing arguments when you use the RUN or RERUN command, see Chapter 1.

Note the following restrictions about the debugger RUN command:

Related commands:

RERUN
RUN (DCL command)
Ctrl/Y--DEBUG (DCL command)
DEBUG (DCL command)

Examples

#1

DBG> RUN EIGHTQUEENS
Language: C, Module: EIGHTQUEENS
      

This command brings the program EIGHTQUEENS under debugger control.

#2

$ RUNPROG == "$ DISK3:[SMITH]MYPROG.EXE"
$ DEBUG/KEEP
    ...
DBG> RUN/COMMAND="RUNPROG"/ARGUMENTS="X Y Z"
      

The first line of this example creates a command symbol RUNPROG (at DCL level) to run an image named MYPROG.EXE. The second line starts the debugger. The debugger RUN command then brings the image MYPROG.EXE under debugger control. The /COMMAND qualifier specifies the command symbol previously created (in this case RUNPROG), and the /ARGUMENTS qualifier passes the arguments X Y Z to the image.

#3

DBG> RUN/ARGUMENTS="X Y Z" MYPROG
      

This command brings the program MYPROG.EXE under debugger control and passes the arguments X Y Z.


Previous Next Contents Index