OpenVMS Debugger Manual


Previous Contents Index

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:

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

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:

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.


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


DBG> HELP GO
      

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:

  1. Displays the monitor view (if it is not already displayed by a previous MONITOR command).
  2. 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.


Previous Next Contents Index