OpenVMS Debugger Manual


Previous Contents Index

16.7.2 Automatic Stack Checking in the Debugger

In tasking programs, an undetected stack overflow can occur in certain circumstances and can lead to unpredictable execution. (For more information on task stack overflow, see the Compaq Ada or POSIX Threads documentation.) The debugger automatically does the following stack checks to help you detect the source of stack overflow problems (if the stack pointer is out of bounds, the debugger displays an error message):

The following examples show the kinds of error messages displayed by the debugger when a stack check fails. A warning is issued when most of the stack has been used up, even if the stack has not yet overflowed.


warning: %TASK 2 has used up over 90% of its stack 
  SP: 0011194C  Stack top at: 00111200  Remaining bytes: 1868 
 
error: %TASK 2 has overflowed its stack 
  SP: 0010E93C  Stack top at: 00111200  Remaining bytes: -10436 
 
error: %TASK 2 has underflowed its stack 
  SP: 7FF363A4  Stack base at: 001189FC  Stack top at: 00111200 

One of the unpredictable events that can happen after a stack overflows is that the stack can then underflow. For example, if a task stack overflows and the stack pointer remains in the top guard area, the operating system will attempt to signal an ACCVIO condition. However, because the top guard area is not a writable area of the stack, the operating system cannot write the signal arguments for the ACCVIO. When this happens, the operating system cuts back the stack: it causes the frame pointer and stack pointer to point to the base of the main program stack area, writes the signal arguments, and then modifies the program counter to force an image exit.

If a time-slice AST or other AST occurs at this instant, execution can resume in a different task, and for a while, the program may continue to execute, although not normally (the task whose stack overflowed may use---and overwrite---the main program stack). The debugger stack checks help you to detect this situation. If you step into a task whose stack has been cut back by the operating system, or if you use the SHOW TASK/ALL command at that time, the debugger issues its stack underflow message.

16.7.3 Using Ctrl/Y When Debugging Ada Tasks

Pressing Ctrl/C is the recommended method of interrupting program execution or a debugger command during a debugging session. This returns control to the debugger; pressing Ctrl/Y returns control to DCL level.

If you interrupt a task debugging session by pressing Ctrl/Y, you might have some problems when you then start the debugger at DCL level with the DEBUG command. In such cases, you should insert the following two lines in the source code at the beginning of your main program to name the Compaq Ada predefined package CONTROL_C_INTERCEPTION:


with CONTROL_C_INTERCEPTION; 
pragma ELABORATE(CONTROL_C_INTERCEPTION); 

For information on this package, see the Compaq Ada documentation.


Part VI
Debugger Command Dictionary

1 Overview

The Debugger Command Dictionary contains detailed reference information about all debugger commands, organized as follows:

2 Debugger Command Format

You can enter debugger commands interactively at the keyboard or store them within a command procedure to be executed later with the execute procedure (@) command.

This section provides the following information:

2.1 General Format

A command string is the complete specification of a debugger command. Although you can continue a command on more than one line, the term command string is used to define an entire command that is passed to the debugger.

A debugger command string consists of a verb and, possibly, parameters and qualifiers.

The verb specifies the command to be executed. Some debugger command strings might consist of only a verb or a verb pair. For example:


DBG> GO
DBG> SHOW IMAGE

A parameter specifies what the verb acts on (for example, a file specification). A qualifier describes or modifies the action taken by the verb. Some command strings might include one or more parameters or qualifiers. In the following examples, COUNT, I, J, and K, OUT2, and PROG4.COM are parameters (@ is the execute procedure command); /SCROLL and /OUTPUT are qualifiers.


DBG> SET WATCH COUNT
DBG> EXAMINE I,J,K
DBG> SELECT/SCROLL/OUTPUT OUT2
DBG> @PROG4.COM

Some commands accept optional WHEN or DO clauses. DO clauses are also used in some screen display definitions.

A WHEN clause consists of the keyword WHEN followed by a conditional expression (within parentheses) that evaluates to true or false in the current language. A DO clause consists of the keyword DO followed by one or more command strings (within parentheses) that are to be executed in the order that they are listed. You must separate multiple command strings with semicolons (;). These points are illustrated in the next example.

The following command string sets a breakpoint on routine SWAP. The breakpoint is triggered whenever the value of J equals 4 during execution. When the breakpoint is triggered, the debugger executes the two commands SHOW CALLS and EXAMINE I,K, in the order indicated.


DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I,K)

The debugger checks the syntax of the commands in a DO clause when it executes the DO clause. You can nest commands within DO clauses.

2.2 Entering Commands at the Keyboard

When entering a debugger command interactively at the keyboard, you can abbreviate a keyword (verb, qualifier, parameter) to as few characters as are needed to make it unique within the set of all debugger keywords. However, some commonly used commands (for example, EXAMINE, DEPOSIT, GO, STEP) can be abbreviated to their first characters. Also, in some cases, the debugger interprets nonunique abbreviations correctly on the basis of context.

Pressing the Return key terminates the current line, causing the debugger to process it. To continue a long command string on another line, type a hyphen (-) before pressing Return. As a result, the debugger prompt is prefixed with an underscore character (_DBG>), indicating that the command string is still being accepted.

You can enter more than one command string on one line by separating command strings with semicolons (;).

To enter a comment (explanatory text recorded in a debugger log file but otherwise ignored by the debugger), precede the comment text with an exclamation point (!). If the comment wraps to another line, start that line with an exclamation point.

The command line editing functions that are available at the DCL prompt ($) are also available at the debugger prompt (DBG>), including command recall with the up arrow and down arrow keys. For example, pressing the left arrow and right arrow keys moves the cursor one character to the left and right, respectively; pressing Ctrl/H or Ctrl/E moves the cursor to the start or end of the line, respectively; pressing Ctrl/U deletes all the characters to the left of the cursor, and so on.

To interrupt a command that is being processed by the debugger, press Ctrl/C. See the Ctrl/C command.

2.3 Entering Commands in Command Procedures

To maximize legibility, it is best not to abbreviate command keywords in a command procedure. Do not abbreviate command keywords to less than four significant characters (not counting the negation /NO...), to avoid potential conflicts in future releases.

Start a debugger command line at the left margin. (Do not start a command line with a dollar sign ($) as you do when writing a DCL command procedure.)

The beginning of a new line ends the previous command line (the end-of-file character also ends the previous command line). To continue a command string on another line, type a hyphen (-) before starting the new line.

You can enter more than one command string on one line by separating command strings with semicolons (;).

To enter a comment (explanatory text that does not affect the execution of the command procedure), precede the comment text with an exclamation point (!). If the comment wraps to another line, start that line with an exclamation point.

3 Commands Disabled in the Debugger's HP DECwindows Motif for OpenVMS User Interface

The following commands are disabled in the debugger's HP DECwindows Motif for OpenVMS user interface. Several of these commands are relevant only to the command interface's screen mode.
ATTACH SELECT
CANCEL MODE (SET,SHOW) ABORT_KEY
CANCEL WINDOW (SET,SHOW) KEY
DEFINE/KEY (SET,SHOW) MARGINS
DELETE/KEY SET MODE [NO]KEYPAD
DISPLAY SET MODE [NO]SCREEN
EXAMINE/SOURCE SET MODE [NO]SCROLL
EXPAND SET OUTPUT [NO]TERMINAL
EXTRACT (SET,SHOW) TERMINAL
HELP 1 (SET,SHOW) WINDOW
MOVE (SHOW,CANCEL) DISPLAY
SAVE SHOW SELECT
SCROLL SPAWN


1Help on commands is available from the Help menu in a debugger window.

The debugger issues an error message if you try to enter any of these disabled commands at the command prompt or when the debugger executes a command procedure containing any of these commands.

The MONITOR command works only with the HP DECwindows Motif for OpenVMS user interface (because the command uses the Monitor View).

4 Debugger Diagnostic Messages

The following example shows the elements of a debugger diagnostic message:


%DEBUG-W-NOSYMBOL, symbol 'X' is not in the symbol table
  (1)   (2)    (3)                        (4)

  1. The facility name (DEBUG).
  2. The severity level (W, in this example).
  3. The message identifier (NOSYMBOL, in this example). The message identifier is an abbreviation of the message text.
  4. The message text.

The identifier enables you to find the explanation for a diagnostic message from the debugger's online help (and the action you need to take, if any).

To get online help about a debugger message, use the following command format:


HELP MESSAGES message-identifier

The possible severity levels for diagnostic messages are as follows:

S (success)
I (informational)
W (warning)
E (error)
F (fatal, or severe error)

Success and informational messages inform you that the debugger has performed your request.

Warning messages indicate that the debugger might have performed some, but not all, of your request and that you should verify the result.

Error messages indicate that the debugger could not perform your request, but that the state of the debugging session was not changed. The only exceptions are if the message identifier was DBGERR or INTERR. These identifiers signify an internal debugger error, and you should contact your HP support representative.

Fatal messages indicate that the debugger could not perform your request and that the debugging session is in an indeterminate state from which you cannot recover reliably. Typically, the error ends the debugging session.

5 Debugger Command Dictionary

The Debugger Command Dictionary describes each debugger command in detail. Commands are listed alphabetically. The following information is provided for each command: command description, format, parameters, qualifiers, and one or more examples. See the preface of this manual for documentation conventions.


@ (Execute Procedure)

Executes a debugger command procedure.

Format

@file-spec [parameter[,...]]


Parameters

file-spec

Specifies the command procedure to be executed. For any part of the full file specification not provided, the debugger uses the file specification established with the last SET ATSIGN command, if any. If the missing part of the file specification was not established by a SET ATSIGN command, the debugger assumes SYS$DISK:[]DEBUG.COM as the default file specification. You can specify a logical name.

parameter

Specifies a parameter that is passed to the command procedure. The parameter can be an address expression, a value expression in the current language, or a debugger command; the command must be enclosed within quotation marks ("). Unlike with DCL, you must separate parameters by commas. Also, you can pass as many parameters as there are formal parameter declarations within the command procedure. For more information about passing parameters to command procedures, see the DECLARE command.

Description

A debugger command procedure can contain any debugger commands, including another execute procedure (@) command. The debugger executes commands from the command procedure until it reaches an EXIT or QUIT command or reaches the end of the command procedure. At that point, the debugger returns control to the command stream that invoked the command procedure. A command stream can be the terminal, an outer (containing) command procedure, a DO clause in a command such as SET BREAK, or a DO clause in a screen display definition.

By default, commands read from a command procedure are not echoed. If you enter the SET OUTPUT VERIFY command, all commands read from a command procedure are echoed on the current output device, as specified by DBG$OUTPUT (the default output device is SYS$OUTPUT).

For information about passing parameters to command procedures, see the DECLARE command.

Related commands:

DECLARE
(SET,SHOW) ATSIGN
SET OUTPUT [NO]VERIFY
SHOW OUTPUT

Example


DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> SET OUTPUT VERIFY
DBG> @CHECKOUT
%DEBUG-I-VERIFYICF, entering command procedure CHECKOUT 
 SET MODULE/ALL 
 SET BREAK SUB1 
 GO 
break at routine PROG5\SUB2 
 EXAMINE X 
PROG5\SUB2\X:  376
    ...
%DEBUG-I-VERIFYICF, exiting command procedure MAIN
DBG>
 
      

In this example, the SET ATSIGN command establishes that debugger command procedures are, by default, in USER:[JONES.DEBUG] and have a file type of .DBG. The @CHECKOUT command executes the command procedure USER:[JONES.DEBUG]CHECKOUT.DBG. The debugger echoes commands in the command because of the SET OUTPUT VERIFY command.


ACTIVATE BREAK

Activates a breakpoint that you have previously set and then deactivated.

Format

ACTIVATE BREAK [address-expression[,...]]


Parameters

address-expression

Specifies a breakpoint to be activated. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER.

Qualifiers

/ACTIVATING

Activates a breakpoint established by a previous SET BREAK/ACTIVATING command.

/ALL

By default, activates all user-defined breakpoints. When used with /PREDEFINED, activates all predefined breakpoints but no user-defined breakpoints. To activate all breakpoints, use /ALL/USER/PREDEFINED.

/BRANCH

Activates a breakpoint established by a previous SET BREAK/BRANCH command.

/CALL

Activates a breakpoint established by a previous SET BREAK/CALL command.

/EVENT=event-name

Activates a breakpoint established by a previous SET BREAK/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET BREAK/EVENT command.

To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command.

/EXCEPTION

Activates a breakpoint established by a previous SET BREAK/EXCEPTION command.

/HANDLER

Activates a breakpoint established by a previous SET BREAK/HANDLER command.

/INSTRUCTION

Activates a breakpoint established by a previous SET BREAK/INSTRUCTION command.

/LINE

Activates a breakpoint established by a previous SET BREAK/LINE command. Do not specify an address expression with this qualifier.

/PREDEFINED

Activates a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, activates all predefined breakpoints.

/SYSEMULATE

(Alpha only) Activates a breakpoint established by a previous SET BREAK/SYSEMULATE command.

/TERMINATING

Activates a breakpoint established by a previous SET BREAK/TERMINATING command.

/UNALIGNED_DATA

(Integrity servers and Alpha only) Activates a breakpoint established by a previous SET BREAK/UNALIGNED_DATA command, or reactivates a breakpoint previously disabled by a DEACTIVATE BREAK/UNALIGNED_DATA command.

/USER

Activates a specified user-defined breakpoint without affecting any predefined breakpoints. To activate all user-defined breakpoints, use the /ALL qualifier.

Description

User-defined breakpoints are activated when you set them with the SET BREAK command. Predefined breakpoints are activated by default. Use the ACTIVATE BREAK command to activate one or more breakpoints that you deactivated with DEACTIVATE BREAK.

Activating and deactivating breakpoints enables you to run and rerun your program with or without breakpoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all breakpoints (activated or deactivated).

You can activate and deactivate user-defined breakpoints or predefined breakpoints or both. To check if a breakpoint is activated, use the SHOW BREAK command.

Related commands:

CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) BREAK
(SET,SHOW) EVENT_FACILITY


Examples

#1

DBG> ACTIVATE BREAK MAIN\LOOP+10
 
      

This command activates the user-defined breakpoint set at the address expression MAIN\LOOP+10.

#2

DBG> ACTIVATE BREAK/ALL
      

This command activates all user-defined breakpoints.

#3

DBG> ACTIVATE BREAK/ALL/USER/PREDEFINED
 
      

This command activates all breakpoints, both user-defined and predefined.


ACTIVATE TRACE

Activates a tracepoint that you have previously set and then deactivated.

Format

ACTIVATE TRACE [address-expression[,...]]


Parameters

address-expression

Specifies a tracepoint to be activated. Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify an address expression when using any qualifiers except /EVENT, /PREDEFINED, or /USER.

Qualifiers

/ACTIVATING

Activates a tracepoint established with a previous SET TRACE/ACTIVATING command.

/ALL

By default, activates all user-defined tracepoints. When used with /PREDEFINED, activates all predefined tracepoints but no user-defined tracepoints. To activate all tracepoints, use /ALL/USER/PREDEFINED.

/BRANCH

Activates a tracepoint established with a previous SET TRACE/BRANCH command.

/CALL

Activates a tracepoint established with a previous SET TRACE/CALL command.

/EVENT=event-name

Activates a tracepoint established with a previous SET TRACE/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET TRACE/EVENT command.

To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command.

/EXCEPTION

Activates a tracepoint established with a previous SET TRACE/EXCEPTION command.

/INSTRUCTION

Activates a tracepoint established with a previous SET TRACE/INSTRUCTION command.

/LINE

Activates a tracepoint established with a previous SET TRACE/LINE command.

/PREDEFINED

Activates a specified predefined tracepoint without affecting any user-defined tracepoints. When used with /ALL, activates all predefined tracepoints.

/TERMINATING

Activates a tracepoint established with a previous SET TRACE/TERMINATING command.

/USER

Activates a specified user-defined tracepoint without affecting any predefined tracepoints. To activate all user-defined tracepoints, use the /ALL qualifier.

Description

User-defined tracepoints are activated when you set them with the SET TRACE command. Predefined tracepoints are activated by default. Use the ACTIVATE TRACE command to activate one or more tracepoints that you deactivated with DEACTIVATE TRACE.

Activating and deactivating tracepoints enables you to run and rerun your program with or without tracepoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all tracepoints (activated or deactivated).

You can activate and deactivate user-defined tracepoints or predefined tracepoints or both. To check if a tracepoint is activated, use the SHOW TRACE command.

Related commands:

CANCEL ALL
RERUN
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL,DEACTIVATE) TRACE

Examples

#1

DBG> ACTIVATE TRACE MAIN\LOOP+10
 
      

This command activates the user-defined tracepoint at the location MAIN\LOOP+10.

#2

DBG> ACTIVATE TRACE/ALL
 
      

This command activates all user-defined tracepoints.


Previous Next Contents Index