Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Debugger Manual
Previous Contents Index

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

This parameter applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS).

Specifies a process currently under debugger control. Use any of the following forms:
[%PROCESS_NAME] proc-name The process name, if that name contains no space or lowercase characters. The process name can include the asterisk (*) wildcard character.
[%PROCESS_NAME] " proc-name" The process name, if that name contains space or lowercase characters. You can also use apostrophes (') instead of quotation marks (").
%PROCESS_PID proc-id The process identifier (PID, a hexadecimal number).
%PROCESS_NUMBER proc-number
(or %PROC proc-number) 		The number assigned to a process when it comes under debugger control. Process numbers appear in a SHOW PROCESS display.
proc-group-name A symbol defined with the DEFINE/PROCESS_GROUP command to represent a group of processes. Do not specify a recursive symbol definition.
%NEXT_PROCESS The 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 call 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 using the multiprocess debugging configuration to debug a multiprocess program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 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/HOLD 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:

Examples

#1 

DBG> EXIT
$

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

#2 

JONES_1> EXIT %NEXT_PROCESS, %PROCESS_NAME JONES_3, %PROC 5
JONES_1>

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:

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 DECwindows Motif 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:

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.

/SUFFIX[=process-identifier-type]

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Appends a process-identifying suffix to a display name. Use this qualifier only directly after a display name. The suffix denotes the visible process at the time the command was issued.

The /SUFFIX qualifier is used primarily in command procedures when you specify display definitions or key definitions that are bound to display definitions.

Use any of the following process-identifier-type keywords:
PROCESS_NAME The display-name suffix is the process name.
PROCESS_NUMBER The display-name suffix is the process number (as shown in a SHOW PROCESS display).
PROCESS_PID The display-name suffix is the process identifier (PID).

If you specify /SUFFIX without a process-identifier-type keyword, the process identifier type used for the display-name suffix is, by default, the same as that used for the prompt suffix (see the SET PROMPT/SUFFIX command).

/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:

Examples

#1 

DBG> EXPAND/RIGHT:6

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 DECwindows Motif 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:

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.

/SUFFIX[=process-identifier-type]

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Appends a process-identifying suffix to a display name. Use this qualifier only directly after a display name. The suffix denotes the visible process at the time the command was issued.

The /SUFFIX qualifier is used primarily in command procedures when you specify display definitions or key definitions that are bound to display definitions.

Use any of the following process-identifier-type keywords:
PROCESS_NAME The display-name suffix is the process name.
PROCESS_NUMBER The display-name suffix is the process number (as shown in a SHOW PROCESS display).
PROCESS_PID The display-name suffix is the process identifier (PID).

If you specify /SUFFIX without a process-identifier-type keyword, the process identifier type used for the display-name suffix is, by default, the same as that used for the prompt suffix (see the SET PROMPT/SUFFIX command).

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:

Examples

#1 

DBG> EXTRACT SRC

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:

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:

If you are using the multiprocess debugging configuration to debug a multiprocess program (if the logical name DBG$PROCESS has the value MULTIPROCESS), note the following additional points:

Related commands:

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.

#3 

DBG> GO %LINE 42

This command resumes program execution at line 42 of the module in which execution is currently suspended.

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4538PRO_048.HTML