 |
OpenVMS Debugger Manual
Related commands:
DEPOSIT
EVALUATE
EXAMINE
SET WATCH
Example
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:
- A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Integrity servers and Alpha only)
IREG
- A display previously created with the DISPLAY command
- A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
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
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:
- SET EVENT FACILITY
- SET TASK|THREAD
- SHOW EVENT FACILITY
- SHOW TASK|THREAD
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
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
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
This command reruns the current program. By default, the debugger saves
the current state of all breakpoints, tracepoints, and static
watchpoints (activated or deactivated).
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:
- You can use the RUN command only if you started the debugger with
the DCL command DEBUG/KEEP.
- You cannot use the RUN command to connect the debugger to a
running program. See the description of Ctrl/Y.
- You cannot run a program under debugger control over a
DECnet link. Both the image to be debugged and the debugger
must reside on the same node.
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.
|
