 |
HP OpenVMS Debugger Manual
EXIT
Ends a debugging session, or terminates one or more processes of a
multiprocess program, 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
EXIT [process-spec[,...]]
Parameters
process-spec
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 EXIT command is one of the four debugger commands that can be used
to execute your program (the others are CALL, GO, and STEP).
Ending a Debugging Session
To end a debugging session, enter the EXIT command at the debugger
prompt without specifying any parameters. This causes orderly
termination of the session: the program's application-declared exit
handlers (if any) are executed, the debugger exit handler is executed
(closing log files, restoring the screen and keypad states, and so on),
and control is returned to the command interpreter. You cannot then
continue to debug your program by entering the DCL command DEBUG or
CONTINUE (you must restart the debugger).
Because EXIT runs any application-declared exit handlers, you can set
breakpoints in such exit handlers, and the breakpoints are triggered
upon typing EXIT. Thus, you can use EXIT to debug your exit handlers.
To end a debugging session without running any application-declared
exit handlers, use the QUIT command instead of EXIT.
Using the EXIT Command in Command Procedures and DO Clauses
When the debugger executes an EXIT 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 an EXIT 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 EXIT
command to terminate specified processes without ending the debugging
session. The same techniques and behavior apply, whether you enter the
EXIT command at the prompt or use it within a command procedure or DO
clause.
To terminate one or more processes, enter the EXIT command, specifying
these processes as parameters. This causes orderly termination of the
images in these processes, executing any application-declared exit
handlers associated with these images. Subsequently, the specified
processes are no longer identified in a SHOW PROCESS/ALL display. If
any specified processes were on hold as the result of a SET PROCESS
command, the hold condition is ignored.
When the specified processes begin to exit, any unspecified process
that is not on hold begins execution. After execution is started, the
way in which it continues depends on whether you entered a SET MODE
[NO]INTERRUPT command. By default (SET MODE INTERRUPT), execution
continues until it is suspended in any process. At that point,
execution is interrupted in any other processes that were executing
images, and the debugger prompts for input.
To terminate specified processes without running any
application-declared exit handlers or otherwise starting execution, use
the QUIT command instead of EXIT.
Related commands:
DISCONNECT
@ (Execute Procedure)
Ctrl/C
Ctrl/Y
Ctrl/Z
QUIT
RERUN
RUN
SET ABORT_KEY
SET MODE [NO]INTERRUPT
SET PROCESS
Examples
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 (Alpha and I64 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 (Alpha and I64 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.
|
