Document revision date: 30 March 2001

## 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

> 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

#1
    DBG> EXIT
    $

> 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 Compaq 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 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

#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 Compaq 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 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

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

> > 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.

#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

| privacy and legal statement |
4538PRO_047.HTML