 |
OpenVMS Debugger Manual
This command ends the debugging session and returns you to DCL level.
| #2 |
all> EXIT %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.
EXITLOOP
Exits one or more enclosing FOR, REPEAT, or WHILE loops.
Format
EXITLOOP [integer]
Parameters
integer
A decimal integer that specifies the number of nested loops to exit
from. The default is 1.
Description
Use the EXITLOOP command to exit one or more enclosing FOR, REPEAT, or
WHILE loops.
Related commands:
FOR
REPEAT
WHILE
Example
|
DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN EXITLOOP)
|
The WHILE 1 command generates an endless loop that executes a STEP
command with each iteration. After each STEP, the value of X is tested.
If X is greater than 3, the EXITLOOP command terminates the loop
(Fortran example).
EXPAND
Expands or contracts the window associated with a screen display.
Note
This command is not available in the HP DECwindows Motif for OpenVMS user interface to
the debugger.
|
Format
EXPAND [display-name[,...]]
Parameters
display-name
Specifies a display to be expanded or contracted. 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 bottom border of the display down by n lines (if
n is positive) or up by n lines (if n is
negative). If you omit n, the border is moved down by 1 line.
/LEFT[:n]
Moves the left border of the display to the left by n lines
(if n is positive) or to the right by n lines (if
n is negative). If you omit n, the border is moved to
the left by 1 line.
/RIGHT[:n]
Moves the right border of the display to the right by n lines
(if n is positive) or to the left by n lines (if
n is negative). If you omit n, the border is moved to
the right by 1 line.
/UP[:n]
Moves the top border of the display up by n lines (if
n is positive) or down by n lines (if n is
negative). If you omit n, the border is moved up by 1 line.
Description
You must specify at least one qualifier.
The EXPAND command moves one or more display-window borders according
to the qualifiers specified (/UP:[n], /DOWN:[n], RIGHT:[n], /LEFT:[n]).
The EXPAND command does not affect the order of a display on the
display pasteboard. Depending on the relative order of displays, the
EXPAND command can cause the specified display to hide or uncover
another display or be hidden by another display, partially or totally.
Except for the PROMPT display, any display can be contracted to the
point where it disappears (at which point it is marked as
"removed"). It can then be expanded from that point.
Contracting a display to the point where it disappears causes it to
lose any attributes that were selected for it. The PROMPT display
cannot be contracted or expanded horizontally but can be contracted
vertically to a height of 2 lines.
A window border can be expanded only up to the edge of the screen. The
left and top window borders cannot be expanded beyond the left and top
edges of the display, respectively. The right border can be expanded up
to 255 columns from the left display edge. The bottom border of a
source or instruction display can be expanded down only to the bottom
edge of the display (to the end of the source module or routine's
instructions). A register display cannot be expanded beyond its full
size.
For a list of the key definitions associated with the EXPAND command,
type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to
determine the current key definitions.
Related commands:
DISPLAY
MOVE
SELECT/SCROLL
(SET,SHOW) TERMINAL
Examples
This command moves the right border of the current scrolling display to
the right by 6 columns.
| #2 |
DBG> EXPAND/UP/RIGHT:-12 OUT2
|
This command moves the top border of display OUT2 up by 1 line, and the
right border to the left by 12 columns.
| #3 |
DBG> EXPAND/DOWN:99 SRC
|
This command moves the bottom border of display SRC down to the bottom
edge of the screen.
EXTRACT
Saves the contents of screen displays in a file or creates a debugger
command procedure with all of the commands necessary to re-create the
current screen state later on.
Note
This command is not available in the HP DECwindows Motif for OpenVMS user interface to
the debugger.
|
Format
EXTRACT [display-name[,...]] [file-spec]
Parameters
display-name
Specifies a display to be extracted. 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
You can use the asterisk (*) wildcard character in a display name. Do
not specify a display name with the /ALL qualifier.
file-spec
Specifies the file to which the information is written. You can specify
a logical name.
If you specify /SCREEN_LAYOUT, the default specification for the file
is SYS$DISK:[]DBGSCREEN.COM. Otherwise, the default specification is
SYS$DISK:[]DEBUG.TXT.
Qualifiers
/ALL
Extracts all displays. Do not specify /SCREEN_LAYOUT with this
qualifier.
/APPEND
Appends the information at the end of the file, rather than creating a
new file. By default, a new file is created. Do not specify
/SCREEN_LAYOUT with this qualifier.
/SCREEN_LAYOUT
Writes a file that contains the debugger commands describing the
current state of the screen. This information includes the screen
height and width, message wrap setting, and the position, display kind,
and display attributes of every existing display. This file can then be
executed with the execute procedure (@) command to reconstruct the
screen at a later time. Do not specify /ALL with this qualifier.
Description
When you use the EXTRACT command to save the contents of a display into
a file, only those lines that are currently stored in the display's
memory buffer (as determined by the /SIZE qualifier on the DISPLAY
command) are written to the file.
You cannot extract the PROMPT display into a file.
Related commands:
DISPLAY
SAVE
Examples
This command writes all the lines in display SRC into file
SYS$DISK:[]DEBUG.TXT.
| #2 |
DBG> EXTRACT/APPEND OUT [JONES.WORK]MYFILE
|
This command appends all the lines in display OUT to the end of file
[JONES.WORK]MYFILE.TXT.
| #3 |
DBG> EXTRACT/SCREEN_LAYOUT
|
This command writes the debugger commands needed to reconstruct the
screen into file SYS$DISK:[]DBGSCREEN.COM.
FOR
Executes a sequence of commands while incrementing a variable a
specified number of times.
Format
FOR name=expression1 TO expression2
[BY expression3]
DO
(command[;...])
Parameters
name
Specifies the name of a count variable.
expression1
Specifies an integer or enumeration type value. The
expression1 and expression2
parameters must be of the same type.
expression2
Specifies an integer or enumeration type value. The
expression1 and expression2
parameters must be of the same type.
expression3
Specifies an 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 behavior of the FOR command depends on the value of the
expression3 parameter, as detailed in the following
table:
| expression3 |
Action of the FOR Command |
|
Positive
|
name parameter is incremented from the value of
expression1 by the value of
expression3 until it is greater than the value of
expression2
|
|
Negative
|
name is decremented from the value of
expression1 by the value of
expression3 until it is less than the value of
expression2
|
|
0
|
The debugger returns an error message
|
|
Omitted
|
The debugger assumes it to have the value +1
|
Related commands:
EXITLOOP
REPEAT
WHILE
Examples
| #1 |
DBG> FOR I = 10 TO 1 BY -1 DO (EXAMINE A(I))
|
This command examines an array backwards.
| #2 |
DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0)
|
This command initializes an array to zero.
GO
Starts or resumes program execution.
Format
GO [address-expression]
Parameters
address-expression
Specifies that program execution resume at the location denoted by the
address expression. If you do not specify an address expression,
execution resumes at the point of suspension or, in the case of
debugger startup, at the image transfer address.
Description
The GO command starts program execution or resumes execution from the
point at which it is currently suspended. GO is one of the four
debugger commands that can be used to execute your program (the others
are CALL, EXIT, and STEP).
Specifying an address expression with the GO command can produce
unexpected results because it alters the normal control flow of your
program. For example, during a debugging session you can restart
execution at the beginning of the program by entering the GO %LINE 1
command. However, because the program has executed, the contents of
some variables might now be initialized differently from when you first
ran the program.
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 invoked. If you
then resume execution with the GO command, the behavior is as follows:
- Entering a GO command to resume execution from the current location
causes the debugger to resignal the exception. This enables you to
observe which application-declared handler, if any, next handles the
exception.
- Entering a GO command to resume execution from a location other
than the current location inhibits the execution of any
application-declared handler for that exception.
If you are debugging a multiprocess program, the GO 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.
Related commands:
CALL
EXIT
RERUN
SET BREAK
SET MODE [NO]INTERRUPT
SET MODE [NO]WAIT
SET PROCESS
SET STEP
SET TRACE
SET WATCH
STEP
WAIT
Examples
| #1 |
DBG> GO
...
'Normal successful completion'
DBG>
|
This command starts program execution, which then completes
successfully.
| #2 |
DBG> SET BREAK RESTORE
DBG> GO ! start execution
...
break at routine INVENTORY\RESTORE
137: procedure RESTORE;
DBG> GO ! resume execution
...
|
In this example, the SET BREAK command sets a breakpoint on routine
RESTORE. The first GO command starts program execution, which is then
suspended at the breakpoint on routine RESTORE. The second GO command
resumes execution from the breakpoint.
This command resumes program execution at line 42 of the module in
which execution is currently suspended.
HELP
Displays online help on debugger commands and selected topics.
Note
This command is not available in the HP DECwindows Motif for OpenVMS user interface to
the debugger. Help on commands is available from the Help menu in a
DECwindows debugger window.
|
Format
HELP topic [subtopic [...]]
Parameters
topic
Specifies the name of a debugger command or topic about which you want
help. You can specify the asterisk (*) wildcard character, either
singly or within a name.
subtopic
Specifies a subtopic, qualifier, or parameter about which you want
further information. You can specify the asterisk wildcard (*), either
singly or within a name.
Description
The debugger's online help facility provides the following information
about any debugger command, including a description of the command, its
format, explanations of any parameters that can be specified with the
command, and explanations of any qualifiers that can be specified with
the command.
To get information about a particular qualifier or parameter, specify
it as a subtopic. If you want information about all qualifiers, specify
"qualifier" as a subtopic. If you want information about all
parameters, specify "parameter" as a subtopic. If you want
information about all parameters, qualifiers, and any other subtopics
related to a command, specify an asterisk (*) as a subtopic.
In addition to help on commands, you can get online help on various
topics such as screen features, keypad mode, and so on. Topic keywords
are listed along with the commands when you type HELP.
For help on the predefined keypad-key functions, type Help
Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the
current key definitions.
Example
This command displays help for the GO command.
IF
Executes a sequence of commands if a language expression (Boolean
expression) is evaluated as true.
Format
IF Boolean-expression THEN (command[;...])
[ELSE (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, you
must separate the commands with semicolons (;).
Description
The IF command evaluates a Boolean expression. If the value is true (as
defined in the current language), the command list in the THEN clause
is executed. If the expression is false, the command list in the ELSE
clause (if any) is executed.
Related commands:
EXITLOOP
FOR
REPEAT
WHILE
Example
|
DBG> SET BREAK R DO (IF X .LT. 5 THEN (GO) ELSE (EXAMINE X))
|
This command causes the debugger to suspend program execution at
location R (a breakpoint) and then resume program execution if the
value of X is less than 5 (Fortran example). If the value of X is 5 or
more, its value is displayed.
MONITOR
Displays the current value of a program variable or language expression
in the monitor view of the HP DECwindows Motif for OpenVMS user interface.
Note
Requires the HP DECwindows Motif for OpenVMS user interface.
|
Format
MONITOR expression
Parameters
expression
Specifies an entity to be monitored. With high-level languages, this is
typically the name of a variable. Currently, MONITOR does not handle
composite expressions (language expressions containing operators).
If you specify the name of an aggregate variable (a composite data
structure such as an array or record structure), the monitor view lists
"Aggregate" for the value of the variable. You can then
double-click on the variable name to get the values of all the elements
(see Section 10.5.4.1).
To specify an individual array element, array slice, or record
component, follow the syntax of the current language.
Qualifiers
/ASCIC
/AC
Interprets each monitored entity as a counted ASCII string preceded by
a 1-byte count field that gives the length of the string. The string is
then displayed.
/ASCID
/AD
Interprets each monitored entity as the address of a string descriptor
pointing to an ASCII string. The CLASS and DTYPE fields of the
descriptor are not checked, but the LENGTH and POINTER fields provide
the character length and address of the ASCII string. The string is
then displayed.
/ASCII:n
Interprets and displays each monitored entity as an ASCII string of
length n bytes (n characters). If you omit
n, the debugger attempts to determine a length from the type
of the address expression.
/ASCIW
/AW
Interprets each monitored entity as a counted ASCII string preceded by
a 2-byte count field that gives the length of the string. The string is
then displayed.
/ASCIZ
/AZ
Interprets each monitored entity as a zero-terminated ASCII string. The
ending zero byte indicates the end of the string. The string is then
displayed.
/BINARY
Displays each monitored entity as a binary integer.
/BYTE
Displays each monitored entity in the byte integer type (length 1 byte).
/DATE_TIME
Interprets each monitored entity as a quadword integer (length 8 bytes)
containing the internal OpenVMS representation of date and time.
Displays the value in the format dd-mmm-yyyy hh:mm:ss.cc.
/DECIMAL
Displays each monitored entity as a decimal integer.
/DEFAULT
Displays each monitored entity in the default radix.
/EXTENDED_FLOAT
(Integrity servers and Alpha only) Displays each monitored entity in
the IEEE X_floating type (length 16 bytes).
/FLOAT
On Alpha, displays each monitored entity in the IEEE T_floating type
(double precision, length 8 bytes).
/G_FLOAT
Displays each monitored entity in the G_floating type (length 8 bytes).
/HEXADECIMAL
Displays each monitored entity as a hexadecimal integer.
/INSTRUCTION
Displays each monitored entity as an assembly-language instruction
(variable length, depending on the number of instruction operands and
the kind of addressing modes used). See also the /OPERANDS qualifier.
/INT
Same as /LONGWORD qualifier.
/LONG_FLOAT
(Integrity servers and Alpha only) Displays each monitored entity in
the IEEE S_floating type (single precision, length 4 bytes).
/LONG_LONG_FLOAT
(Integrity servers and Alpha only) Displays each monitored entity in
the IEEE T_floating type (double precision, length 8 bytes).
/LONGWORD
/INT
/LONG
Displays each monitored entity in the longword integer type (length 4
bytes). This is the default type for program locations that do not have
a compiler-generated type.
/OCTAL
Displays each monitored entity as an octal integer.
/OCTAWORD
Displays each monitored entity in the octaword integer type (length 16
bytes).
/QUADWORD
Displays each monitored entity in the quadword integer type (length 8
bytes).
/REMOVE
Removes a monitored item or items with the address expression specified
from the Monitor View.
/SHORT
Same as /WORD qualifier.
/TASK
Applies to tasking (multithread) programs. Interprets each monitored
entity as a task (thread) object and displays the task value (the name
or task ID) of that task object. When monitoring a task object, use
/TASK only if the programming language does not have built-in tasking
services.
/WORD
/SHORT
Displays each monitored entity in the word integer type (length 2
bytes).
Description
You can use the MONITOR command only with the debugger's HP DECwindows Motif for OpenVMS
user interface, because the output of that command is directed at the
monitor view. With the command interface, you typically use the
EVALUATE, EXAMINE or SET WATCH command instead.
The MONITOR command does the following:
- Displays the monitor view (if it is not already displayed by a
previous MONITOR command).
- Puts the name of the specified variable or expression and its
current value in the monitor view.
The debugger updates the monitor view whenever the debugger regains
control from the program, regardless of whether the value of the
variable or location you are monitoring has changed. (By contrast, a
watchpoint halts execution when the value of the watched variable
changes.)
For more information about the monitor view and the MONITOR command,
see Section 10.5.4.
|
