DEBUG — MicroVMS 4.4
Additional information available:
%LABEL%LINEALLOCATEATTACHCALLCANCELDBG$HELP
DBG$INITDEBUGDECLAREDEFINEDELETEDEPOSITDISABLE
DISPLAYEDITENABLEEVALUATEEXAMINEEXITEXITLOOP
EXPANDEXTRACTFORGOHELPIFMOVE
QUITREPEATSAVESCROLLSEARCHSELECTSET
SHOWSPAWNSS$_DEBUGSTEPSYMBOLIZE
TYPEUNDEFINEWHILE
@file-specAddress-exprControlKeypadLanguagesLexicalsNew Features
PathnamesRelease NotesScreen features
@file-spec
Execute DEBUG commands from the specified file. If you have
issued a "SET OUTPUT VERIFY", all commands read from a command
procedure are echoed on the terminal.
Parameters may be passed in to a command procedure. Parameters
can be address expressions, language expressions, or strings.
(Corresponding to the three kinds of DEFINE symbols.) Inside the
command procedure, the parameters get bound to names via the
DECLARE command.
Format:
@file-spec [ parameter [,parameter...]]
Additional information available:
Examples
The following example invokes a "SETUP" command file that
establishes a particular set of defaults. The commands in the
command file are echoed because of the "SET OUT VERIFY".
DBG> SET OUT VERIFY
DBG> @SETUP.COM
!entering command file SETUP.COM
! SET SOURCE [],SRC$
! SET MODE SCREEN
! SET STEP SILENT
! SET RADIX HEX
!exiting command file SETUP.COM
Parameters
file-specification
Specifies the command procedure to be executed. If the
file-specification does not include a file type, the default file
type .COM is used. A logical name may be given. The default
file specification can be modified by using the SET ATSIGN
command. (See the help on SET ATSIGN).
parameter
This can be an address or value expression in the current
language, or a quoted string. It is bound to a name within the
command procedure by using the DECLARE command. (See the help on
DECLARE).
For example:
DBG> @DUMP X
!entering command procedure DUMP.COM
! DECLARE P1:ADDRESS
! EXAMINE P1
X: 23
!exiting command procedure DUMP.COM
Address-expr
In many of the descriptions in this help library, you will see
the term "address-expression". An address-expression specifies a
location in your program. Commands that expect address
expressions are: EXAMINE, EVALUATE/ADDRESS, left-hand-side of
DEPOSIT, SET BREAK, SET TRACE, and SET WATCH.
In general, you can specify addresses using the syntax of the
currently set language. For example,
DBG> EXAMINE A(1) ! FORTRAN
DBG> SET WATCH A[1] ! PASCAL
DBG> EXAMINE C OF R ! COBOL
In addition, you can specify addresses numerically, and you can
also use the special DEBUG built-ins %LINE and %LABEL for
referring to code locations:
DBG> EXAMINE 512
DBG> SET BREAK %LINE 10
Finally, you can use the following operators to specify addresses
that you might not be able to get to by name:
+ - * / Arithmetic operators
@ or . Indirection
<p,s> Select bit field
! Examine the instruction 3 bytes after line 10
DBG> EXAMINE %LINE 10 + 3
! Examine the location pointed to by P
DBG> EXAMINE @P
The difference between address expressions and language
expressions can best be illustrated by an example:
DBG> EVAL/ADDR X
512
DBG> EXAM X
X: 0
DBG> EVAL X+1 ! Language expression: adds 0+1
1
DBG> EXAM X+1 ! Address expression: 1 byte beyond X
513: 0
Control
Format:
<CTRL/C>
<CTRL/Y>
<CTRL/Z>
Additional information available:
Key
Pressing CTRL/Y interrupts either your program or the debugger
(whichever was running) and brings you back to the DCL prompt.
You can then enter the DCL command "DEBUG" to get back to the
"DBG>" prompt. This mechanism (CTRL/Y, DEBUG) is the means by
which you can interrupt a program that is in a loop, or a
debugger command that is taking an inordinately long time to
execute.
You can also use CTRL/C for this purpose. It's effect is usually
the same as for CTRL/Y. The only difference is that your program
may have a CTRL/C handler which will get invoked upon a CTRL/C.
Note that the CTRL/Y, DEBUG sequence may also be used to
interrupt a program that was initially run without the debugger,
and then bring in the debugger.
Pressing CTRL/Z causes orderly termination of the debugging
session. It is identical in effect to the EXIT command.
Example:
DBG> WHILE TRUE DO (EXAMINE)
..
CTRL/Y ! Interrupt infinite loop
$ DEBUG ! Get back to debugger prompt
DBG>
Keypad
On VT100s and other Digital terminals, you can use the numeric
keypad to enter Debugger commands provided you are in "keypad
mode". Keypad mode is set by default, but can be disabled and
enabled by the commands SET MODE NOKEYPAD and SET MODE KEYPAD.
In keypad mode, each defined keypad key expands to a Debugger
command. Some keys are "terminated", meaning that the corre-
sponding command is executed immediately, while others are not
terminated, meaning that you can enter additional parameters to
the command before terminating it with a carriage return or the
ENTER key. Also, some keys echo on the terminal while others do
not, depending on the key. You can define your own keypad defi-
nitions with the DEFINE/KEY command.
Additional information available:
DEFAULTGOLDBLUEMOVE_DEFAULTEXPAND_DEFAULT
CONTRACT_DEFAULTMOVE_GOLDEXPAND_GOLDCONTRACT_GOLD
MOVE_BLUEEXPAND_BLUECONTRACT_BLUESUMMARY
DEFAULT
Keypad definitions when you do +--------+--------+--------+--------+
not use a color key. | | Help | Set | |
| GOLD | Keypad | Mode | BLUE |
For more keypad help, enter HELP | | Deflt | Screen | |
KEYPAD GOLD, HELP KEYPAD BLUE +--------+--------+--------+--------+
or HELP KEYPAD STATE_KEYS. | Src LH1| | | Disp |
|Inst RH1| Scroll | Disp | next |
Control-W does a Display/Refresh | Out S45| Up | next | S12345 |
to refresh screen in screen mode. +--------+--------+--------+--------+
| | Exam | | |
| Scroll | Source | Scroll | Go |
| Left | .0\%PC | Right | |
+--------+--------+--------+--------+
| | | Select | |
| Exam | Scroll | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
GOLD
Keypad definitions when you +--------+--------+--------+--------+
press the GOLD key first. | | Help | SetMod | |
| GOLD | Keypad | No | BLUE |
Reset cancels the GOLD key. | | Gold | Screen | |
+--------+--------+--------+--------+
For more keypad help, enter HELP |Inst LH1| | | |
KEYPAD BLUE, HELP KEYPAD DEFAULT | Reg RH1| Scroll | | |
or HELP KEYPAD STATE_KEYS. | Out S45| Top | | |
+--------+--------+--------+--------+
Control-W does a Display/Refresh | Scroll | | Scroll | |
to refresh screen in screen mode. | Left | Show | Right | |
| 255 | Calls | 255 | |
+--------+--------+--------+--------+
| Exam | | Select | |
| prev | Scroll | Output | E |
| | Bottom | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
BLUE
Keypad definitions when you +--------+--------+--------+--------+
press the BLUE key first. | | Help | | |
| GOLD | Keypad | Disp | BLUE |
"..." means that you must enter | | Blue | Gener | |
more input after pressing key. +--------+--------+--------+--------+
| | Scroll | | Disp |
Reset cancels the BLUE key. | | Up | | Src H1 |
| | ... | | Out S45|
For more keypad help, enter HELP +--------+--------+--------+--------+
KEYPAD GOLD, HELP KEYPAD DEFAULT | Scroll | Show | Scroll | Select |
or HELP KEYPAD STATE_KEYS. | Left | Calls | Right | Inst |
| ... | 3 | ... | next |
Control-W does a Display/Refresh +--------+--------+--------+--------+
to refresh screen in screen mode. | | Scroll | Select | |
| | Down | Source | E |
| | ... | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
MOVE_DEFAULT
Keypad definitions in the MOVE +--------+--------+--------+--------+
state when you do not use a color | | Help | Set | |
key. | GOLD | Keypad | Mode | BLUE |
| |MovDeflt| Screen | |
For more keypad help, enter HELP +--------+--------+--------+--------+
KEYPAD GOLD, HELP KEYPAD BLUE | Src LH1| | | Disp |
or HELP KEYPAD STATE_KEYS. |Inst RH1| Move | Disp | next |
| Out S45| Up | next | S12345 |
Control-W does a Display/Refresh +--------+--------+--------+--------+
to refresh screen in screen mode. | | Exam | | |
| Move | Source | Move | Go |
| Left | .0\%PC | Right | |
+--------+--------+--------+--------+
| | | Select | |
| Exam | Move | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
EXPAND_DEFAULT
Keypad definitions in the EXPAND +--------+--------+--------+--------+
state when you do not use a color | | Help | Set | |
key. | GOLD | Keypad | Mode | BLUE |
| |ExpDeflt| Screen | |
For more keypad help, enter HELP +--------+--------+--------+--------+
KEYPAD GOLD, HELP KEYPAD BLUE | Src LH1| | | Disp |
or HELP KEYPAD STATE_KEYS. |Inst RH1| Expand | Disp | next |
| Out S45| Up | next | S12345 |
Control-W does a Display/Refresh +--------+--------+--------+--------+
to refresh screen in screen mode. | | Exam | | |
| Expand | Source | Expand | Go |
| Left | .0\%PC | Right | |
+--------+--------+--------+--------+
| | | Select | |
| Exam | Expand | Scroll | E |
| | Down | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
CONTRACT_DEFAULT
Keypad definitions in the CONTRACT +--------+--------+--------+--------+
state when you do not use a color | | Help | Set | |
key. | GOLD | Keypad | Mode | BLUE |
| |CntDeflt| Screen | |
For more keypad help, enter HELP +--------+--------+--------+--------+
KEYPAD GOLD, HELP KEYPAD BLUE | Src LH1| Expand | | Disp |
or HELP KEYPAD STATE_KEYS. |Inst RH1| Up= | Disp | next |
| Out S45| -1 | next | S12345 |
Control-W does a Display/Refresh +--------+--------+--------+--------+
to refresh screen in screen mode. | Expand | Exam | Expand | |
| Left= | Source | Right= | Go |
| -1 | .0\%PC | -1 | |
+--------+--------+--------+--------+
| | Expand | Select | |
| Exam | Down= | Scroll | E |
| | -1 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
MOVE_GOLD
Keypad definitions in the MOVE +--------+--------+--------+--------+
state when you press the GOLD key | | Help | SetMod | |
first. | GOLD | Keypad | No | BLUE |
| |MoveGold| Screen | |
Reset cancels the GOLD key. +--------+--------+--------+--------+
|Inst LH1| Move | | |
For more keypad help, enter HELP | Reg RH1| Up= | | |
KEYPAD BLUE, HELP KEYPAD DEFAULT | Out S45| 999 | | |
or HELP KEYPAD STATE_KEYS. +--------+--------+--------+--------+
| Move | | Move | |
Control-W does a Display/Refresh | Left= | Show | Right= | |
to refresh screen in screen mode. | 999 | Calls | 999 | |
+--------+--------+--------+--------+
| Exam | Move | Select | |
| prev | Down= | Output | E |
| | 999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
EXPAND_GOLD
Keypad definitions in the EXPAND +--------+--------+--------+--------+
state when you press the GOLD key | | Help | SetMod | |
first. | GOLD | Keypad | No | BLUE |
| |ExpaGold| Screen | |
Reset cancels the GOLD key. +--------+--------+--------+--------+
|Inst LH1| Expand | | |
For more keypad help, enter HELP | Reg RH1| Up= | | |
KEYPAD BLUE, HELP KEYPAD DEFAULT | Out S45| 999 | | |
or HELP KEYPAD STATE_KEYS. +--------+--------+--------+--------+
| Expand | | Expand | |
Control-W does a Display/Refresh | Left= | Show | Right= | |
to refresh screen in screen mode. | 999 | Calls | 999 | |
+--------+--------+--------+--------+
| Exam | Expand | Select | |
| prev | Down= | Output | E |
| | 999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
CONTRACT_GOLD
Keypad definitions in the CONTRACT +--------+--------+--------+--------+
state when you press the GOLD key | | Help | SetMod | |
first. | GOLD | Keypad | No | BLUE |
| |CntrGold| Screen | |
Reset cancels the GOLD key. +--------+--------+--------+--------+
|Inst LH1| Expand | | |
For more keypad help, enter HELP | Reg RH1| Up= | | |
KEYPAD BLUE, HELP KEYPAD DEFAULT | Out S45| -999 | | |
or HELP KEYPAD STATE_KEYS. +--------+--------+--------+--------+
| Expand | | Expand | |
Control-W does a Display/Refresh | Left= | Show | Right= | |
to refresh screen in screen mode. | -999 | Calls | -999 | |
+--------+--------+--------+--------+
| Exam | Expand | Select | |
| prev | Down= | Output | E |
| | -999 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Into | Reset | R |
| | | |
+-----------------+--------+--------+
MOVE_BLUE
Keypad definitions in the MOVE +--------+--------+--------+--------+
state when you press the BLUE key | | Help | | |
first. | GOLD | Keypad | Disp | BLUE |
| |MoveBlue| Gener | |
"..." means that you must enter +--------+--------+--------+--------+
more input after pressing key. | | | | Disp |
| | Move | | Src H1 |
Reset cancels the BLUE key. | | Up=5 | | Out S45|
+--------+--------+--------+--------+
For more keypad help, enter HELP | | Show | | Select |
KEYPAD GOLD, HELP KEYPAD DEFAULT | Move | Calls | Move | Inst |
or HELP KEYPAD STATE_KEYS. | Left=10| 3 |Right=10| next |
+--------+--------+--------+--------+
Control-W does a Display/Refresh | | | Select | |
to refresh screen in screen mode. | | Move | Source | E |
| | Down=5 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
EXPAND_BLUE
Keypad definitions in the EXPAND +--------+--------+--------+--------+
state when you press the BLUE key | | Help | | |
first. | GOLD | Keypad | Disp | BLUE |
| |ExpaBlue| Gener | |
"..." means that you must enter +--------+--------+--------+--------+
more input after pressing key. | | | | Disp |
| | Expand | | Src H1 |
Reset cancels the BLUE key. | | Up=5 | | Out S45|
+--------+--------+--------+--------+
For more keypad help, enter HELP | | Show | | Select |
KEYPAD GOLD, HELP KEYPAD DEFAULT | Expand | Calls | Expand | Inst |
or HELP KEYPAD STATE_KEYS. | Left=10| 3 |Right=10| next |
+--------+--------+--------+--------+
Control-W does a Display/Refresh | | | Select | |
to refresh screen in screen mode. | | Expand | Source | E |
| | Down=5 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
CONTRACT_BLUE
Keypad definitions in the CONTRACT +--------+--------+--------+--------+
state when you press the BLUE key | | Help | | |
first. | GOLD | Keypad | Disp | BLUE |
| |CntrBlue| Gener | |
"..." means that you must enter +--------+--------+--------+--------+
more input after pressing key. | | Expand | | Disp |
| | Up= | | Src H1 |
Reset cancels the BLUE key. | | -5 | | Out S45|
+--------+--------+--------+--------+
For more keypad help, enter HELP | Expand | Show | Expand | Select |
KEYPAD GOLD, HELP KEYPAD DEFAULT | Left= | Calls | Right= | Inst |
or HELP KEYPAD STATE_KEYS. | -10 | 3 | -10 | next |
+--------+--------+--------+--------+
Control-W does a Display/Refresh | | Expand | Select | |
to refresh screen in screen mode. | | Down= | Source | E |
| | -5 | next | N |
+--------+--------+--------+ T |
| | | E |
| Step/Over | Reset | R |
| | | |
+-----------------+--------+--------+
State keys
The four scrolling keys (KP8, KP2, KP4, and KP6) can also be used
to expand, contract, and move displays. Just as they can perform
a SCROLL /UP, /DOWN, /LEFT, or /RIGHT, they can now perform a
MOVE, etc. in those directions as well. The GOLD key can be
used to cause the operation to advance more than one line or
column. The commands are directed at the current scrolling
display. The key KP3 can be used to select the current scrolling
display from the display circular list.
Four keys on the LK201 keyboard are used to facilitate this.
They place the numeric keypad in one of the following four
states: DEFAULT, MOVE, EXPAND, CONTRACT. This changes the
definition of the keys KP8, KP2, KP4, and KP6. The meaning of
all other keys remains unchanged.
For example, in the MOVE state (F18), pressing the key KP2 will
cause the default scrolling display to move down by one character
position. Pressing GOLD KP2 will cause the display to move down
by a larger increment. The keypad will remain in the MOVE state
until another state, such as the DEFAULT state (F17), is
selected. This restores the definition of the SCROLL operation.
If you do not have an LK201 keyboard with the F17-F20 keys on it,
you may get the same effect by typing the corresponding command:
F17 F18 F19 F20
SET KEY/STATE=DEFAULT or +--------+--------+--------+--------+
SET KEY/STATE=MOVE | | | | |
SET KEY/STATE=EXPAND | DEFAULT| MOVE | EXPAND |CONTRACT|
SET KEY/STATE=CONTRACT | | | | |
+--------+--------+--------+--------+
SUMMARY
Summary of DEBUG keypad definitions. +--------+--------+--------+--------+
| | | | |
For more keypad help, enter HELP | GOLD | Help | Screen | BLUE |
KEYPAD DEFAULT, HELP KEYPAD GOLD, | | | Mode | |
HELP KEYPAD BLUE, or HELP KEYPAD +--------+--------+--------+--------+
STATE_KEYS. | Select | | | Disp |
| Screen | Up | Disp | next |
Control-W does a Display/Refresh | Layout | | next | at FS |
to refresh screen in screen mode. +--------+--------+--------+--------+
| | | | |
| Left | Where | Right | Go |
| | am I? | | |
+--------+--------+--------+--------+
| | | | |
| Exam | Down | Select | E |
| | | next | N |
+--------+--------+--------+ T |
| | | E |
| Step | Reset | R |
| | | |
+-----------------+--------+--------+
Languages
This section gives help on each of the languages supported by the
debugger. The help information includes tables saying which
language operators and data types are supported by the debugger
in language expressions (e.g., in the EVALUATE command).
Additional information available:
ADABASICBLISSCCCOBOLDIBOLFORTRAN
MACROPASCALPLIRPGSCANUNKNOWN
ADA
The debugger completely supports the ADA language. It knows
about ADA names, operators, and data types when evaluating
expressions in an EXAMINE or EVALUATE command. It knows about
ADA packages, with clauses, and use clauses, and follows ADA
scoping rules when looking up symbols. There are a large number
of special-purpose commands to support debugging of ADA
multitasking programs and ADA exception events.
Additional information available:
Data TypesEventsExceptionsMultitaskingOperatorsNamesOverloading
PackagesSubunitsTick Operators
Data Types
Supported ADA Data Types
Integer
Float
Fixed
Enumeration
Arrays
Records
Pointers
Tasks
Events
DEBUG allows you to set breakpoints and tracepoints (known
generically as "eventpoints") on certain types of events
occurring during the execution of your program which are defined
and detected by the Ada RTL. These events would otherwise be
very difficult (or impossible) for you to set a breakpoint on.
They fall into two broad categories: exception events and
tasking events. Exception events allow you to break or trace on
any exception that is about to be handled by an Ada exception
handler. They are applicable to any Ada program. Tasking events
deal specifically with multitasking programs. They allow you to
break or trace on task scheduling, termination, and other state
transitions.
Additional information available:
CommandsEvent parametersExamples
Commands
To tell DEBUG to use the Ada RTL as the event detection facility
for succeeding commands, type the command "SET EVENT_FACILITY
ADA"
To see what the run time event facility is and what the defined
events are, type the command "SHOW EVENT_FACILITY".
To set an eventpoint for the Ada RTL to detect, use the commands
"SET BREAK/EVENT=keyword" or "SET TRACE/EVENT=keyword".
To display the eventpoints you have set, use the commands "SHOW
BREAK" or "SHOW TRACE".
To remove the eventpoints use the commands "CANCEL
BREAK/EVENT=keyword" or "CANCEL TRACE/EVENT=keyword"
Event parameters
Generally, the SET BREAK/EVENT and SET TRACE/EVENT commands can
take parameters which may be either address expressions or
language expressions. For Ada, the allowed parameters are task
names. Parameters are optional; omitting them implies a
"wildcard" as a parameter.
Examples
Initialize the debugger for Ada events:
DBG> SET EVENT_FACILITY ADA
Display the defined event names:
DBG> SHOW EVENT_FACILITY
event facility is ADA
Ada event names and definitions:
...
Set a breakpoint that is triggered whenever any exception is
handled by an Ada exception handler:
DBG> SET BREAK/EVENT=HANDLED
DBG> GO
...
break on Ada event HANDLED in %TASK 1
task %TASK 1 is about to handle an exception
the Ada exception handler is at: SCREEN_IO.%LINE 36
%ADA, Exception was copied at a "raise" or "accept".
Error PC=0000F60B
-ADA, Exception BAD_INPUT
-ADA, Exception raised prior to PC=00000670
Set two tracepoints that are triggered when either task GAMMA or
%TASK 1 respectively, make a transition to the RUN state. When
the event is triggered, execute the DEBUG command to display all
the tasks in the program:
DBG> SET TRACE/EVENT=RUN GAMMA, %TASK 1 DO (SHOW TASK/ALL)
DBG> GO
trace on ADA event RUN in %TASK 1
task %TASK 1 is about to run
task id pri hold state substate task object
* %TASK 1 7 RUN 81600
%TASK 2 7 READY SAMPLE.ALPHA
%TASK 3 7 READY SAMPLE.BETA
%TASK 4 7 READY SAMPLE.GAMMA
%TASK 5 7 READY SAMPLE.DELTA
trace on ADA event RUN in %TASK 4
task %TASK 4 is about to run
task id pri hold state substate task object
%TASK 1 7 SUSP Dependents 81600
%TASK 2 7 READY SAMPLE.ALPHA
%TASK 3 7 READY SAMPLE.BETA
* %TASK 4 7 RUN SAMPLE.GAMMA
%TASK 5 7 READY SAMPLE.DELTA
Set a breakpoint that is triggered whenever any task enters the
TERMINATED state. When the event is triggered, execute the DEBUG
command to display all the tasks in the program:
DBG> SET BREAK/EVENT=TERMINATED DO (SHOW TASK/ALL)
DBG> GO
break on ADA event TERMINATED in %TASK 5
task %TASK 5 is terminating normally.
task id pri hold state substate task object
%TASK 1 7 READY 81600
%TASK 2 7 READY SAMPLE.ALPHA
%TASK 3 7 READY SAMPLE.BETA
%TASK 4 7 READY SAMPLE.GAMMA
* %TASK 5 7 RUN Terminated SAMPLE.DELTA
DBG> GO
break on ADA event TERMINATED in %TASK 4
task %TASK 4 is terminating normally.
task id pri hold state substate task object
%TASK 1 7 READY 81600
%TASK 2 7 READY SAMPLE.ALPHA
%TASK 3 7 READY SAMPLE.BETA
* %TASK 4 7 RUN Terminated SAMPLE.GAMMA
%TASK 5 7 TERM Terminated SAMPLE.DELTA
Exceptions
DEBUG provides builtin lexical functions to provide information
about the current exception. See the HELP text on "Lexical
%ADAEXC" for Ada specific exceptions and "Lexical %EXC" for
non-Ada specific exceptions.
Also see "Languages ADA Events" for information on Ada specific
exception events and "SET BREAK/EXCEPTION" for non-Ada specific
exceptions events.
Multitasking
The debugger has a large number of commands to help you debug ADA
multitasking programs:
SHOW TASK -- lets you observe the state of the multitasking
system.
SET TASK -- lets you alter the state of the multitasking system.
SET BREAK/EVENT and SET TRACE/EVENT -- lets you set breakpoints
on tasking events of interest to you.
The HELP text for these commands will provide detailed
information. Also see the support for tasking events described
under "Language Ada EVENTS".
Operators
Supported ADA Operators in Expressions
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix MOD Modulus
Infix REM Remainder
Infix ** Exponentiation
Prefix ABS Absolute value
Infix & Concatenation
Infix = Equal to
Infix /= Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Prefix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Infix XOR Logical Exclusive OR
Names
Supported Constructs for ADA names
Symbol Construct
------ ---------
( ) Subscripting
. Record component selection
.ALL Pointer dereferencing
Overloading
If a function F is overloaded, then the debugger invents names of
the form F__1, F__2, and so on, to refer to the individual
instances of the overloaded function. You can find out about
these names as follows:
DBG> SET BREAK F
%DEBUG-W-NOUNIQUE, F is not unique due to overloading
DBG> SHOW SYMBOL F
Overloaded function F
Overloaded instance F__1
Overloaded instance F__2
DBG> SET BREAK F__1
The "SEARCH" command and the "EXAMINE/SOURCE" command may also be
useful in locating the source associated with the definitions of
F.
Packages
The debugger knows about ADA packages, and follows ADA scoping
rules (i.e., takes into account WITH and USE clauses) when
looking up symbols.
Library packages are treated as modules that can be set and
cancelled individually. If the library package has a spec and a
body then each has its own module. If the package name is "P",
then the module for the package body has the name "P", while the
module with the package spec gets the name "P_". Set the module
"P_" to make visible the names declared in the spec. Set the
module "P" to make visible the names local to the body.
The debugger will sometimes set package spec modules for you, in
order to be able to correctly follow ADA's scoping rules during
symbol lookup. See the help on "SET MODULE/RELATED", "SHOW
MODULE/RELATED" for details.
Example:
package P is
...
end P;
package body P is
...
end P;
with P;
procedure M is
...
end M;
DBG> SHOW MODULE
module name symbols
M no
P no
P_ no
DBG> SET MODULE M
module name symbols
M yes
P no
P_ yes
Subunits
The debugger knows about ADA subunits. A subunit is treated as a
debugger module. If S is a subunit of M, then the module
containing S has the invented name M__S. It has a special
relationship with the parent module M: if you set the subunit
module M__S, then the parent module M is also set by the
debugger. This is done in order to make visible symbols that are
up-level referenced.
Example:
procedure M is
...
procedure S is separate;
...
end M;
separate(M);
procedure S is
begin
...
end;
DBG> SHOW MODULE
module name symbols
M no
M__S no
DBG> SET MODULE S
DBG> SHOW MODULE
module name symbols
M yes
M__S no
Tick Operators
Supported ADA "Tick Operators"
'CONSTRAINED
'FIRST
'LAST
'LENGTH
'POS
'PRED
'SIZE
'SUCC
'VAL
Example:
DBG> EVAL DAY'SUCC(MONDAY)
TUESDAY
BASIC
Debugger Support for Language BASIC
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported BASIC Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition, String concatenation
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix ^ Exponentiation
Infix = Equal to
Infix <> Not equal to
Infix >< Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix => Greater than or equal to
Infix < Less than
Infix >= Less than or equal to
Infix => Less than or equal to
Prefix NOT Bit-wise NOT
Infix AND Bit-wise AND
Infix OR Bit-wise OR
Infix XOR Bit-wise exclusive OR
Infix IMP Bit-wise implication
Infix EQV Bit-wise equivalence
Expressions
Supported Constructs in Language and Address Expressions for BASIC
Symbol Construct
------ ---------
( ) Subscripting
:: Record component selection
Data Types
Supported BASIC Data Types
BYTE HFLOAT
WORD DECIMAL
LONG STRING
SINGLE RFA
DOUBLE Arrays
GFLOAT Records
Notes
Expressions that overflow in the BASIC language will not necessarily overflow when evaluated by the debugger. The debugger will try to compute a numerically correct result, even when the BASIC rules call for overflows. This difference is particularly likely to affect DECIMAL computations. BASIC constants of the forms [radix]"numeric-string"[type] (such as "12.34"GFLOAT) or n% (such as 25% for integer 25) are not supported in debugger expressions.
BLISS
Debugger Support for Language BLISS
Additional information available:
OperatorsExpressionsData Types
Operators
Supported BLISS Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix . Indirection
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix MOD Remainder
Infix ^ Left shift
Infix EQL Equal to
Infix EQLU Equal to
Infix EQLA Equal to
Infix NEQ Not equal to
Infix NEQU Not equal to
Infix NEQA Not equal to
Infix GTR Greater than
Infix GTRU Greater than unsigned
Infix GTRA Greater than unsigned
Infix GEQ Greater than or equal to
Infix GEQU Greater than or equal to unsigned
Infix GEQA Greater than or equal to unsigned
Infix LSS Less than
Infix LSSU Less than unsigned
Infix LSSA Less than unsigned
Infix LEQ Less than or equal to
Infix LEQU Less than or equal to unsigned
Infix LEQA Less than or equal to unsigned
Prefix NOT Bit-wise NOT
Infix AND Bit-wise AND
Infix OR Bit-wise OR
Infix XOR Bit-wise exclusive OR
Infix EQV Bit-wise equivalence
Expressions
Supported Constructs in Language and Address Expressions for BLISS
Symbol Construct
------ ---------
[ ] Subscripting
[fldname] Field selection
<p,s,e> Bit field selection
Data Types
Supported BLISS Data Types
BYTE BITVECTOR
WORD BLOCK
LONG BLOCKVECTOR
BYTE UNSIGNED REF VECTOR
WORD UNSIGNED REF BITVECTOR
LONG UNSIGNED REF BLOCK
VECTOR REF BLOCKVECTOR
CC
Debugger Support for Language C
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported C Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix * Indirection
Prefix & Address of
Prefix SIZEOF Size of
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix % Remainder
Infix << Left shift
Infix >> Right shift
Infix == Equal to
Infix != Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Prefix ~ Bit-wise NOT
Infix & Bit-wise AND
Infix | Bit-wise OR
Infix ^ Bit-wise exclusive OR
Prefix ! Logical NOT
Infix && Logical AND
Infix || Logical OR
Expressions
Supported Constructs in Language and Address Expressions for C
Symbol Construct
------ ---------
[ ] Subscripting
. Structure component selection
-> Pointer dereferencing
Data Types
Supported C Data Types
INT DOUBLE
SHORT INT ENUM
UNSIGNED INT STRUCT
UNSIGNED SHORT INT UNION
CHAR Pointers
UNSIGNED CHAR Arrays
FLOAT
Notes
Symbol names are case-sensitive for language C, meaning that upper-case and lower-case letters are treated as different characters. Since the exclamation point (!) is an operator in C, it cannot be used as the comment delimiter. When the language is set to C, the debugger instead accepts /* as the comment delimiter. The comment continues to the end of the current line. (A matching */ is neither needed nor recognized.) To permit debugger log files to be used as debugger input, the debugger still recognizes ! as a comment delimiter if it is the first non-blank character on a line. The debugger accepts the prefix asterisk (*) as an indirection operator in both C language expressions and debugger address expressions. In address expressions, prefix "*" is synonymous to prefix "." or "@" when the language is set to C. The debugger does not support any of the assignment operators in C (or any other language) in order to prevent unintended modifications to the program being debugged. Hence such operators as =, +=, -=, ++, and -- are not recognized. If you wish to alter the contents of a memory location, you must do so with an explicit DEPOSIT command.
COBOL
Debugger Support for Language COBOL
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported COBOL Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix = Equal to
Infix NOT = Not equal to
Infix > Greater than
Infix NOT < Greater than or equal to
Infix < Less than
Infix NOT > Less than or equal to
Infix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Expressions
Supported Constructs in Language and Address Expressions for COBOL
Symbol Construct
------ ---------
( ) Subscripting
OF Record component selection
IN Record component selection
Data Types
Supported COBOL Data Types
COMP Records
COMP-1 Numeric Unsigned
COMP-2 Leading Separate Sign
COMP-3 Leading Overpunched Sign
INDEX Trailing Separate Sign
Alphanumeric Trailing Overpunched Sign
Notes
The debugger can show source text included in a program with the COPY or COPY REPLACING verb. However, when COPY REPLACING is used, the debugger always shows the original source text as it appeared before text replacement. In other words, the original source file is shown instead of the modified source text generated by the COPY REPLACING verb. The debugger cannot show the original source lines associated with the code for a REPORT section. You can see the DATA SECTION source lines associated with a REPORT, but no source lines are associated with the compiled code that generates the report. VAX COBOL may use quadword, longword, or word to represent a COMP data type.
DIBOL
Debugger Support for Language DIBOL
Additional information available:
OperatorsExpressionsData Types
Operators
Supported DIBOL Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix # Round
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix // Division with fractional result
Infix .EQ. Equal to
Infix .NE. Not equal to
Infix .GT. Greater than
Infix .GE. Greater than or equal to
Infix .LT. Less than
Infix .LE. Less than or equal to
Prefix .NOT. Logical NOT
Infix .AND. Logical AND
Infix .OR. Logical OR
Infix .XOR. Exclusive OR
Expressions
Supported Constructs in Language and Address Expressions for DIBOL
Symbol Construct
------ ---------
( ) Substring
[ ] Subscripting
. Record component selection
Data Types
Supported DIBOL Data Types
Byte integer (I1)
Word integer (I2)
Long integer (I4)
Packed decimal (Pn)
Implied packed decimal (Pn.m)
Zoned decimal (Dn)
Implied zoned decimal (Dn.m)
Ascii (An)
Arrays
Records
FORTRAN
Debugger Support for Language FORTRAN
Additional information available:
OperatorsExpressionsPredefined SymbolsData TypesNotes
Operators
Supported FORTRAN Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix // Concatenation
Infix .EQ. Equal to
Infix .NE. Not equal to
Infix .GT. Greater than
Infix .GE. Greater than or equal to
Infix .LT. Less than
Infix .LE. Less than or equal to
Prefix .NOT. Logical NOT
Infix .AND. Logical AND
Infix .OR. Logical OR
Infix .XOR. Exclusive OR
Infix .EQV. Equivalence
Infix .NEQV. Exclusive OR
Expressions
Supported Constructs in Language and Address Expressions for FORTRAN
Symbol Construct
------ ---------
( ) Subscripting
. Record component selection
Predefined Symbols
Supported FORTRAN Predefined Symbols
Symbol Meaning
------ -------
.TRUE. Logical True
.FALSE. Logical False
Data Types
Supported FORTRAN Data Types
LOGICAL*1 REAL*16
LOGICAL*2 COMPLEX*8
LOGICAL*4 COMPLEX*16
INTEGER*2 CHARACTER
INTEGER*4 Arrays
REAL*4 Records
REAL*8
Notes
Even though the VAX type codes for unsigned integers (BU, WU, LU) are used internally to describe the LOGICAL data types, the debugger (like the compiler) treats LOGICAL variables and values as being signed when used in language expressions. The debugger prints the numeric values of LOGICAL variables or expressions instead of TRUE or FALSE. Normally, only the low-order bit of a LOGICAL variable or value is significant (0 is FALSE and 1 is TRUE). However, VAX FORTRAN does allow all bits in a LOGICAL value to be manipulated and LOGICAL values can be used in integer expressions. For this reason, it is at times necessary to see the entire integer value of a LOGICAL variable or expression, and that is what the debugger shows. COMPLEX constants such as (1.0,2.0) are not supported in debugger expressions. Floating point numbers of type REAL*8 and COMPLEX*16 may be represented by D_Floating or G_Floating depending on compiler switches.
MACRO
Debugger Support for Language MACRO
Additional information available:
OperatorsExpressionsData Types
Operators
Supported Operators in Language Expressions
Language MACRO does not have expressions in the same sense as
high-level languages. Only assembly-time expressions and only a
limited set of operators are accepted. To permit the MACRO programmer
to use expressions at debug-time as freely as in other languages, the
debugger accepts a number of operators in MACRO language expressions
that are not found in MACRO itself. In particular, the debugger
accepts a complete set of comparison and boolean operators modeled
after BLISS. It also accepts the indirection operator and the normal
arithmetic operators.
Kind Symbol Function
------ ------ --------
Prefix @ Indirection
Prefix . Indirection
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix MOD Remainder
Infix @ Left shift
Infix EQL Equal to
Infix EQLU Equal to
Infix NEQ Not equal to
Infix NEQU Not equal to
Infix GTR Greater than
Infix GTRU Greater than unsigned
Infix GEQ Greater than or equal to
Infix GEQU Greater than or equal to unsigned
Infix LSS Less than
Infix LSSU Less than unsigned
Infix LEQ Less than or equal to
Infix LEQU Less than or equal to unsigned
Prefix NOT Bit-wise NOT
Infix AND Bit-wise AND
Infix OR Bit-wise OR
Infix XOR Bit-wise exclusive OR
Infix EQV Bit-wise equivalence
Expressions
Supported Constructs in Language and Address Expressions for MACRO
Symbol Construct
------ ---------
<p,s,e> Bitfield selection as in BLISS
Data Types
Supported MACRO Data Types
Byte Unsigned (BU)
Word Unsigned (WU)
Longword Unsigned (LU)
Byte Integer (B)
Word Integer (W)
Longword Integer (L)
PASCAL
Debugger Support for Language PASCAL
Additional information available:
OperatorsExpressionsPredefined SymbolsData TypesNotes
Operators
Supported PASCAL Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition, concatenation
Infix - Subtraction
Infix * Multiplication
Infix / Real division
Infix DIV Integer division
Infix MOD Modulus
Infix REM Remainder
Infix ** Exponentiation
Infix IN Set membership
Infix = Equal to
Infix <> Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Prefix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Expressions
Supported Constructs in Language and Address Expressions for PASCAL
Symbol Construct
------ ---------
[ ] Subscripting
. Record component selection
^ Pointer dereferencing
Predefined Symbols
Supported PASCAL Predefined Symbols and Functions
Symbol Meaning
------ -------
TRUE Boolean True
FALSE Boolean False
NIL Nil pointer
Data Types
Supported PASCAL Data Types
INTEGER CHAR Subranges
UNSIGNED VARYING Typed
SINGLE SET Arrays
DOUBLE FILE Records
QUADRUPLE Enumerations Variant
BOOLEAN
Notes
The debugger accepts PASCAL set constants such as [1,2,5,8..10] or [RED, BLUE] in PASCAL language expressions. VAX PASCAL may use longword, word, or byte to represent INTEGER or UNSIGNED data types. DOUBLE precision floating point numbers may be represented by D_Floating or G_Floating depending on compiler switches.
PLI
Debugger Support for Language PL/I
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported PL/I Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix || Concatenation
Infix = Equal to
Infix ^= Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix ^< Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Infix ^> Less than or equal to
Prefix ^ Bit-wise NOT
Infix & Bit-wise AND
Infix | Bit-wise OR
Expressions
Supported Constructs in Language and Address Expressions for PL/I
Symbol Construct
------ ---------
( ) Subscripting
. Structure component selection
-> Pointer dereferencing
Data Types
Supported PL/I Data Types
FIXED BINARY CHARACTER VARYING
FIXED DECIMAL FILE
FLOAT BINARY Labels
FLOAT DECIMAL Pointers
BIT Arrays
CHARACTER Structures
Notes
The debugger treats all numeric constants of the form n or n.n in PL/I language expressions as packed decimal constants, not integer or floating-point constants, in order to conform to PL/I language rules. The internal representation of 10 is therefore 0C01 hexadecimal, not 0A hexadecimal. You can enter floating-point constants using the syntax nEn or n.nEn. There is no PL/I syntax for entering constants whose internal representation is Longword Integer. This limitation is not normally significant when debugging since the debugger supports the PL/I type conversion rules. However, it is possible to enter integer constants by using the debugger's %HEX, %OCT, and %BIN operators. VAX PL/I may use F_Floating, D_Floating, G_Floating, or H_Floating to represent FLOAT BINARY or FLOAT DECIMAL data types depending on compiler switches.
RPG
Debugger Support for Language RPG
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported RPG Operators in Language Expressions
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix = Equal to
Infix NOT = Not equal to
Infix > Greater than
Infix NOT < Greater than or equal to
Infix < Less than
Infix NOT > Less than or equal to
Prefix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Expressions
Supported Constructs in Language and Address Expressions for RPG
Symbol Construct
------ ---------
( ) Subscripting
Data Types
Supported RPG Data Types
Longword
Word
Packed Decimal
Character
Overpunched Decimal
Arrays
Tables
Notes
The debugger supports access to all RPG indicators and labels used in the current program. You can thus examine labels such as *DETL and indicators such as *INLR and *IN01 through *IN99.
SCAN
Debugger Support for Language SCAN
Additional information available:
EventsOperatorsExpressionsData Types
Events
DEBUG allows you to set breakpoints and tracepoints (known
generically as "eventpoints") on certain types of events
occurring during the execution of your program which are defined
and detected by the SCAN RTL.
SCAN defines several events. By setting breaks or traces on
these events, you can observe the picture matching process. To
see what the defined events are for SCAN, type the command "SHOW
EVENTS".
To set an eventpoint for the SCAN RTL to detect, use the commands
"SET BREAK/EVENT=keyword" or "SET TRACE/EVENT=keyword".
To display the eventpoints you have set, use the commands "SHOW
BREAK" or "SHOW TRACE".
To remove the eventpoints use the commands "CANCEL
BREAK/EVENT=keyword" or "CANCEL TRACE/EVENT=keyword"
Where "keyword" is one of the defined events listed by the "SHOW
EVENTS" command. SCAN events may be abbreviated to 3 or more
characters.
Additional information available:
Examples
Set two tracepoints that are triggered when a SCAN Trigger or Syntax
Macro is activated. Set a break point that is triggered whenever a
SCAN token is built.
DBG>SET TRACE/EVENT=TRIGGER
DBG>SET TRACE/EVENT=SYNTAX
DBG>SET BREAK/EVENT=TOKEN
The following example illustrates the output from the program
execution after setting the above eventpoints.
DBG>Go
trace on event TRIGGER_MACRO
Trigger Macro EXPRESSION_TEST\PRINT_STMT Activated
break on event TOKEN
Token built: PRINT Triggerable Length:5 Line:1 Column:1
Token text: 'print'
DBG>Go
trace on event SYNTAX_MACRO
Syntax Macro EXPRESSION_TEST\EXP Activated
Operators
Supported Operators in Language Expressions for SCAN
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix & Concatenation
Infix = Equals
Infix <> Not equals
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Prefix NOT Complement
Infix AND Intersection
Infix OR Union
Infix XOR Exclusive OR
Expressions
Supported Constructs in Language and Address Expressions for SCAN
Symbol Construct
------ ---------
( ) Subscripting
. Record component selection
-> Pointer dereferencing
Data Types
Supported SCAN Data Types
BOOLEAN
INTEGER
POINTER
STRING
TREE
TREEPTR
RECORD
OVERLAY
There is no specific support for the following datatypes: FILE,
TOKEN, GROUP, SET. Examining a FILL variable will produce the
contents of the specified variable displayed as a string by
default, and so may have little meaning. If the characteristics
of the fill are known, then the appropriate qualifier (/HEX...)
applied to the command will produce a more meaningful display.
Examining SCAN TREE and TREEPTR variables:
DBG>EXAMINE tree_variable( [ subscript ],...)
- To dump an entire SCAN tree or subtree
DBG>EXAMINE treeptr_variable
- To dump the contents of a SCAN treeptr
DBG>EXAMINE treeptr_variable->
- To dump an entire SCAN subtree
DEPOSIT is not supported for SCAN TREE variables at this time.
You may set breakpoints on any SCAN label, line number, MACRO, or
PROCEDURE.
UNKNOWN
Debugger Support for Language UNKNOWN
Additional information available:
OperatorsExpressionsData TypesNotes
Operators
Supported Operators in Language Expressions for UNKNOWN
Kind Symbol Function
------ ------ --------
Prefix + Unary plus
Prefix - Unary minus (negation)
Infix + Addition
Infix - Subtraction
Infix * Multiplication
Infix / Division
Infix ** Exponentiation
Infix & Concatenation
Infix // Concatenation
Infix = Equal to
Infix <> Not equal to
Infix /= Not equal to
Infix > Greater than
Infix >= Greater than or equal to
Infix < Less than
Infix <= Less than or equal to
Infix EQL Equal to
Infix NEQ Not equal to
Infix GTR Greater than
Infix GEQ Greater than or equal to
Infix LSS Less than
Infix LEQ Less than or equal to
Prefix NOT Logical NOT
Infix AND Logical AND
Infix OR Logical OR
Infix XOR Exclusive OR
Infix EQV Equivalence
Expressions
Supported Constructs in Language and Address Expressions for UNKNOWN
Symbol Construct
------ ---------
[ ] Subscripting
( ) Subscripting
. Record component selection
^ Pointer dereferencing
Data Types
Supported UNKNOWN Data Types When the language is set to UNKNOWN, the debugger understands all data types accepted by other languages except a few very language-specific types, such a picture types and file types. In UNKNOWN language expressions, the debugger accepts most scalar VAX Standard data types.
Notes
For language UNKNOWN, the debugger accepts the dot-notation for record component selection. If C is a component of a record B which in turn is a component of a record A, C can be referenced as "A.B.C". Subscripts can be attached to any array components; if B is an array, for instance, C may be referenced as "A.B[2,3].C". For language UNKNOWN, the debugger accepts both round and square subscript parentheses. Hence A[2,3] and A(2,3) are equivalent.
Lexicals
The lexical functions provide control over the scanning of
language expressions and offer additional capability in
specifying entities in your program. They are logically grouped
here according to their purpose.
%NAME -- used to construct identifiers.
%PARCNT -- used in command procedures.
%BIN, %DEC, %HEX, and %OCT, -- provide for better control over
radix.
%CURLOC, %NEXTLOC, and %PREVLOC -- useful with EXAMINE and
DEPOSIT.
%LABEL and %LINE -- used to indicate program locations.
%ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME, %EXC_NUM, and
%EXC_SEVERITY -- builtins to provide information about the
current exception.
%ACTIVE_TASK, %CALLER_TASK, %NEXT_TASK, %TASK, and %VISIBLE_TASK
-- builtins used for support of ADA multitasking:
Additional information available:
%NAME%PARCNT%BIN%DEC%HEX%OCT%CURLOC
%NEXTLOC%PREVLOC%LABEL%LINE%ADAEXC_NAME%EXC_FACILITY
%EXC_NAME%EXC_NUM%EXC_SEVERITY%ACTIVE_TASK
%CALLER_TASK%NEXT_TASK%TASK%VISIBLE_TASK
%NAME
%NAME allows identifiers to be constructed which are not
ordinarily legal in the current language.
Format:
%NAME id-char-string
%NAME 'any-char-string'
Examples:
EX %NAME 12 ! Allows examination of variable with name '12'
EX %NAME 'P.AAA' ! Allows examination of generated label P.AAA
%PARCNT
The %PARCNT symbol specifies the number of actual parameters to
the current command procedure (indirect command file). For
example, suppose the command file ABC is invoked with the command
@ABC 111,222,333. Inside ABC, %PARCNT then has the value 3
because there are three parameters on this particular call to
ABC. %PARCNT is used in command procedures that can take a
variable number of actual parameters. %PARCNT can only be used
inside command files; it is not defined when commands are entered
from the terminal.
Sample Format:
EVAL %PARCNT
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVAL X)
%BIN
Specifies that the following numeric literal (or all numeric
literals in the following parenthesized expression) be
interpreted in binary radix.
Sample Format:
DBG> EVALUATE/DEC %BIN 10
2
DBG> EVALUATE/DEC %BIN (10 + 10)
4
%DEC
Specifies that the following numeric literal (or all numeric
literals in the following parenthesized expression) be
interpreted in decimal radix.
Sample Format:
DBG> EVALUATE/HEX %DEC 10
0A
DBG> EVALUATE/HEX %DEC (10 + 10)
14
%HEX
Specifies that the following numeric literal (or all numeric
literals in the following parenthesized expression) be
interpreted in hexadecimal radix.
Sample Format:
DBG> EVALUATE/DEC %HEX 10
16
DBG> EVALUATE/DEC %HEX (10 + 10)
32
%OCT
Specifies that the following numeric literal (or all numeric
literals in the following parenthesized expression) be
interpreted in octal radix.
Sample Format:
DBG> EVALUATE/DEC %OCT 10
8
DBG> EVALUATE/DEC %OCT (10 + 10)
16
%CURLOC
This is a DEBUG permanent symbol which represents the current
logical entity, i.e. the program location last referenced by an
EXAMINE or DEPOSIT command. The period character "." can also be
used for this purpose.
Sample Format:
DBG> EXAMINE RADIUS
CIRCLE\RADIUS: 0.0000000E+00
DBG> DEPOSIT %CURLOC = 1 ! Set RADIUS to 1
DBG> DEPOSIT . = 2 ! Set RADIUS to 2
%NEXTLOC
This is a DEBUG permanent symbol which represents the logical
successor to the current entity, i.e. the program location that
logically follows the location last referenced by an EXAMINE or
DEPOSIT command. Note that the EXAMINE command without a
parameter is equivalent to EXAMINE %NEXTLOC.
Sample Format:
DBG> EXAMINE PRIMES(4)
SIEVE\PRIMES(4): 7
DBG> EXAMINE %NEXTLOC
SIEVE\PRIMES(5): 11
DBG> EXAMINE ! Equivalent to EXAMINE %NEXTLOC
SIEVE\PRIMES(6): 13
%PREVLOC
This is a DEBUG permanent symbol which represents the logical
predecessor to the current entity, i.e. the program location
that logically preceeds the location last referenced by an
EXAMINE or DEPOSIT command. The circumflex character "^" can
also be used for this purpose.
Sample Format:
DBG> EXAMINE PRIMES(6)
SIEVE\PRIMES(6): 13
DBG> EXAMINE %PREVLOC
SIEVE\PRIMES(5): 11
DBG> EXAMINE ^
SIEVE\PRIMES(4): 7
%LABEL
"%LABEL n" is the debugger syntax for referring to label n in
your program. This is intended for languages like FORTRAN which
have numeric program labels. You can qualify the label with a
pathname specifying the containing module. For example:
SET BREAK MODULENAME\%LABEL 10
The "old" syntax of "%LABEL MODULENAME\10" is no longer accepted.
%LINE
"%LINE n" is the debugger syntax for referring to line n in your
program. You can qualify the line number with a pathname
specifying the containing module. For example:
SET BREAK MODULENAME\%LINE 10
The "old" syntax of "%LINE MODULENAME\10" is no longer accepted.
%ADAEXC_NAME
"%ADAEXC_NAME is a special form of %EXC_NAME for ADA programs.
In ADA, an exception can be raised with syntax such as "raise
XXX;". In this case, the exception name in the VMS sense is just
"EXCEPTION", and that is what %EXC_NAME will return. The ADA
exception name ("XXX") will be returned by %ADAEXC_NAME.
Example:
DBG> SET BREAK/EXCEPTION WHEN (%ADAEXC_NAME = "XXX")
%EXC_FACILITY
"%EXC_FACILITY" gives you the facility of the current exception.
This provides a way of qualifying exception breaks.
Example:
DBG> EVAL %EXC_FACILITY
"SYSTEM"
DBG> SET BREAK/EXC WHEN (%EXC_FAC = "SYSTEM")
%EXC_NAME
"%EXC_NAME" gives you the name of the current exception. This
provides a way of qualifying exception breaks.
Example:
DBG> EVAL %EXC_NAME
"FLTDIV_F"
DBG> SET BREAK/EXC WHEN (%EXC_NAME = "FLTDIV_F")
%EXC_NUM
"%EXC_NUM" gives you the current exception number. This provides
a way of qualifying exception breaks.
Example:
DBG> EVAL %EXC_NUM
12
DBG> EVAL/COND %EXC_NUM
%SYSTEM-F-ACCVIO, access violation at PC !XL, virtual address !XL
DBG> SET BREAK/EXC WHEN (%EXC_NUM = 12)
%EXC_SEVERITY
"%EXC_SEVERITY" gives you the severity code of the current
exception. This provides a way of qualifying exception breaks.
Example:
DBG> EVAL %EXC_SEVERITY
"F"
DBG> SET BREAK/EXC WHEN (%EXC_SEV = "F")
%ACTIVE_TASK
(Only valid for ADA multitasking programs).
"%ACTIVE_TASK" gives you the currently active task (the one that
was running when the debugger last took control). See the
command "SET TASK/ACTIVE".
Example:
DBG> EVALUATE %ACTIVE_TASK
%TASK 2
%CALLER_TASK
(Only valid for ADA multitasking programs).
"%CALLER_TASK" gives you the task which is the entry caller of
the active task during a task rendezvous.
If the active task (%ACTIVE_TASK) is not currently executing an
accept statement (i.e. a rendezvous is not in progress),
%CALLER_TASK returns %TASK 0.
Example:
The following command sets a breakpoint within an accept
statement. The breakpoint is triggered only when %TASK 3 is the
task making the entry call of the rendezvous.
DBG> TYPE 51:53
module SAMPLE
51: accept RENDEZVOUS do
52: PUT_LINE("Beginning the rendezvous");
53: end RENDEZVOUS;
DBG> SET BREAK %LINE 52 WHEN (%CALLER_TASK = %TASK 3)
%NEXT_TASK
(Only valid for ADA multitasking programs).
"%NEXT_TASK" gives you the "next" task after the one that is
currently visible (%VISIBLE_TASK). "Next" in this context is
just an internal ordering that cycles through all the tasks.
This lets you set up command procedures that cycle through all
tasks.
Example:
DBG> WHILE %NEXT NEQ %ACTIVE DO -
(SET TASK %NEXT; SHOW CALLS)
%TASK
(Only valid for ADA multitasking programs).
"%TASK n" (where "n" is a positive decimal integer) is the
debugger syntax for referring to an ADA task by its task ID. The
task ID is a unique number that is associated with a task at the
time the task is created. The task number "n" can be obtained
using the "SHOW TASK/ALL" command or by examining ADA task
objects.
Example:
DBG> EXAMINE T1
T1: %TASK 2
DBG> SET TASK %TASK 2
%VISIBLE_TASK
(Only valid for ADA multitasking programs).
"%VISIBLE_TASK" gives you the task that DEBUG is using to do
symbol lookups. It is the default task assumed by debugging
commands when you don't (or can't) specify a task. For example,
the debugger command EXAMINE %R0 displays register 0 of the
visible task.
This is normally the same as %ACTIVE_TASK but can be changed
using the SET TASK command.
Example:
DBG> SET TASK %TASK 2
DBG> EVALUATE %VISIBLE
%TASK 2
New Features
Additional information available:
V4.2
This section points out which features and commands are new in
version 4.2 of DEBUG. These are documented elsewhere in this
help library:
Ada language support. See help on LANGUAGE ADA.
Aggregate watchpoints. See help on SET WATCH aggregate.
Dynamic module setting. See help on SET MODE DYNAMIC.
Enable and Disable AST. See help on ENABLE and DISABLE.
Exception lexicals. See help on "Lexical %EXC".
Exit handlers. See help on SHOW EXIT_HANDLERS.
Instruction display. See help on "Screen Instruction-display".
Large terminal support. See help on SET TERMINAL.
Noline mode. See help on SET MODE NOLINE.
Parameters to SHOW MODULE. See help on SHOW MODULE Parameters.
Scroll mode. See help on SET MODE SCROLL.
Setting the DEBUG prompt. See help on SET PROMPT.
%SOURCE_SCOPE. See help under "Screen Source-display".
V4.4
This section points out which features and commands are new in
version 4.4 of DEBUG.
DIBOL language support. See help on "Language DIBOL".
DISPLAY/[NO]POP and DISPLAY/[NO]PUSH.
EXAMINE/TYPE
New screen windows. See help on "Screen_Features Windows".
Scan language support. See help on "Language SCAN".
Scope default of 0,1,2,3,...N. See help on "SET SCOPE Default".
SELECT/INPUT, SELECT/ERROR, SELECT/PROGRAM.
SET ATSIGN and SHOW ATSIGN.
SET EDITOR and SHOW EDITOR.
Shareable Image support. See the "Shareable_Image" subtopic.
SHOW STACK
SS$_DEBUG signal parameters. See help on "SS$_DEBUG".
STEP/[NO]JSB and STEP/[NO]SHARE.
There are also various new screen features that are discussed in
the subtopics:
Additional information available:
Display AttributesExtracting DisplaysKey DefinitionsMoving Displays
PROMPT DisplayResizing DisplaysVertically Divided Windows
Shareable ImagesWindow Definitions
Display Attributes
In addition to the attributes INSTRUCTION, OUTPUT, SCROLL, and
SOURCE, the debugger now provides the following attributes, which
are also selected with the SELECT command:
ERROR --- A display with the ERROR attribute displays
debugger diagnostic messages.
INPUT --- A display with the INPUT attribute echoes your
debugger input.
PROGRAM --- A display with the PROGRAM attribute displays
program output. Currently, only the new predefined PROMPT
display can have the PROGRAM attribute.
PROMPT --- A display with the PROMPT attribute is where the
debugger prompts for input. Currently, only the new
predefined PROMPT display can have the PROMPT attribute.
For example, the following command will cause your input,
debugger output, and debugger diagnostic messages to be logged in
the OUT display in the proper sequence:
DBG> SELECT/INPUT/ERROR OUT
Type HELP Screen_Features Display_Attributes for information on
assigning display attributes.
Extracting Displays
You can now save screen displays into a file, or create a file
with all the DEBUG commands necessary to re-create the current
screen state at a later time. Type HELP EXTRACT for a
description of the EXTRACT command.
Key Definitions
The default definitions for keypad keys KP7 and MINUS have been
changed to accommodate changes in predefined display and window
definitions. The new definitions are as follows:
KP7 = DISPLAY SRC AT LH1, INST AT RH1, OUT AT S45,PROMPT AT S6
GOLD KP7 = DISPLAY INST AT LH1, REG AT RH1, OUT AT S45,PROMPT AT S6
BLUE KP7 = Not defined
MINUS = DISPLAY %NEXTDISP AT S12345
GOLD MINUS = Not defined
BLUE MINUS = DISPLAY SRC AT H1, OUT AT S45, PROMPT AT S6 (this is the
default for high-level languages)
See the "Window_Definitions" sub-topic for more information on
the new windows.
Moving Displays
You can move a display vertically and/or horizontally across the
screen by means of the MOVE command. Type HELP MOVE for a
description of the MOVE command.
PROMPT Display
There is a new PROMPT built-in display where the debugger prompts
for input, forces program output, and (by default) prints
debugger diagnostic messages. By default, PROMPT occupies the
bottom sixth of the screen (the predefined window S6). On a
VT100 or VT200 series terminal, S6 includes lines 21 through 24.
The PROMPT display is of the new display kind "PROGRAM". PROMPT
is the only display of that kind (no other PROGRAM displays can
be created). Note that, compared to other displays, PROMPT has
several restrictions. To eliminate possible confusion when
manipulating that display:
o PROMPT can never be hidden by another display. It is always
on top of the display "pasteboard".
o PROMPT can be moved anywhere on the screen, expanded to fill
the full screen height, and shrunk down to two lines. But
PROMPT must always occupy the full width of the screen and,
therefore, can not be moved, expanded, or shrunk
horizontally.
Type HELP Screen_Features Display_Attributes for information on
assigning display attributes to various displays, including the
PROMPT display.
Resizing Displays
You can expand and contract displays by means of the EXPAND
command. Type HELP EXPAND for a description of the EXPAND
command.
Vertically Divided Windows
Previously, display windows had to occupy the full width of the
screen (columns 1-80). Now, windows can be defined to occupy any
rectangular region of the screen. Windows occupying the left or
right half of the screen (columns 1-40 and 42-80, respectively)
are predefined. With these predefined displays, column 41 is
reserved as a border.
To observe the effect, invoke the debugger, use the command SET
MODE SCREEN, then press keypad key 7 (KP7). That key definition
has been changed to show the SRC display in the top left half of
the screen (LH1), the INST display in the top right half (RH1),
the OUT display under these two, and the new PROMPT display under
OUT.
Shareable Images
With version 4.4 of DEBUG, you can debug shareable images in the
same way as you debug your main image. That is, full symbol
table information is now available for shareable images.
To build a shareable image with symbol table, you would compile
your modules with the /DEBUG qualifier, and then link the image
with the /SHARE and /DEBUG qualifiers. For example:
$ LINK/SHARE/DEBUG FOO
Then, once you've run your main program with the debugger, you
can load the symbol table information for the shareable image FOO
using the command:
DBG> SET IMAGE FOO
See the individual help topics for information on the commands
"SET IMAGE", "CANCEL IMAGE", and "SHOW IMAGE".
Window Definitions
Previously, the bottom sixth of the screen (lines 21-24 on a
VT100 or VT200 series terminal) could not be used for defining
display windows. That area was reserved for the debugger prompt,
debugger diagnostic messages, and program output. Also, windows
had to occupy the full width of the screen.
Now, windows can be defined to occupy any rectangular region of
the screen. The SET WINDOW, SET DISPLAY, and DISPLAY commands
now accept horizontal (column) as well as vertical (line)
coordinates. The general form of a window specification is
illustrated for the SET WINDOW command:
SET WINDOW wname AT (start-line,line-count
[,start-column,column-count])
Type "HELP SET WINDOW", "HELP SET DISPLAY", and "HELP DISPLAY"
for more information.
Old and new default windows have been defined to cover the
greater usable screen height and to account for vertically
defined windows. For example, on a VT100 or VT200 series
terminal, FS (full screen) now covers lines 1-24, H1 lines 1-12,
H2 lines 13-24, and so on. A new symbol prefix, S, denotes a
multiple of one sixth of the screen. For example, S56 is the
bottom two sixths of the screen. And for each of the full-width
predefined windows (for example, FS, H2, T12, Q3, S45, and so on)
there is also a left-half and a right-half predefined window.
These window names have the prefix L and R, respectively.
Examples of predefined windows follow:
Window Location
Name (start-line,line-count,start-column,column-count)
FS (1,23,1,80)
LFS (1,23,1,40)
RH1 (1,11,42,39)
LH2 (13,11,1,40)
LT12 (1,15,1,40)
Q234 (7,17,1,80)
RS56 (17,7,42,39)
Pathnames
If you have multiple symbols with the same name, you may need to
use pathnames to disambiguate symbol references. For example,
you may have a variable X in procedure A, another variable X in
procedure B which is nested in procedure A, and still another
variable X in procedure C. If you say:
DBG> EXAMINE X
then the debugger will attempt to resolve which X you mean, based
on your current PC. If it cannot do so, it will give the error
message:
%DEBUG-W-NOUNIQUE, X is not unique.
In this case, you can specify which X you want using pathnames:
DBG> EXAMINE A\X
DBG> EXAMINE A\B\X
DBG> EXAMINE C\X
Also see the help on "SET SCOPE".
Release Notes
Additional information available:
V4.2
This section notes any incompatible changes that have been made
for version 4.2 of DEBUG that you should be aware of.
New features in version 4.2 are listed seperately, under "HELP
New_features".
Additional information available:
Register WindowsMacro-defaultsBasic-defaults
Register Windows
In version 4.0 of DEBUG, the register display occupied 5 lines of
the screen. Special windows were invented to accomodate a
display of this size, and these were named R1, R2, R3, R12, and
R23.
For version 4.2 of DEBUG, the register display has been squeezed
down to occupy just four lines. This was done by making more
efficient use of space and also by removing the translation of R0
as an error message. (The translation of R0 can still be
obtained by doing EXAMINE/CONDITION R0).
Now that the register display occupies 4 lines, it fits in the
standard windows Q1, Q2, Q3, and Q4 (one quarter of the screen).
So the special purpose windows R1, R2, and R3 have been dropped.
If you refer to them in any command files, you should change your
command file to use one of the "Q" (quarter) displays instead.
Example:
old DBG$INIT file:
DISPLAY REG AT R1
DISPLAY OUT AT R23
new DBG$INIT file:
DISPLAY REG AT Q1
DISPLAY OUT AT Q234
Macro-defaults
In version 4.0, the screen default for MACRO was to display the
registers on the top of the screen, and the output display in the
rest of the screen. Because of the addition of the instruction
display in version 4.2, this default was changed to be the
assembly language instructions (INST display) in H1 and the
output display in H2. This make the MACRO default closer to the
rest of the languages.
If you want to display the registers for MACRO, you now need to
specify that in a DISPLAY command. For example, the following
puts the registers in the top quarter and the assembly
instructions in the second quarter:
DBG> DISPLAY REG AT Q1
DBG> DISPLAY INST AT Q2
Basic-defaults
In version 4.0, the screen-mode defaults for language BASIC were
the same as for language MACRO. This was because, at that time,
the BASIC compiler was not generating the symbol table records
needed to do source display.
With version 2.4 of BASIC, source display is available for that
language. So the screen mode default for BASIC has been changed
to be the source display in the top half of the screen, and the
output display in the bottom half of the screen (the same as for
the other high-level languages).
V4.4
This section notes any known bugs that could not be fixed in time
for the version 4.4 release. Also noted are any incompatible
changes that have been made for Version 4.4 of DEBUG that you
should be aware of. New features are listed separately under
HELP New_Features.
Additional information available:
Key DefinitionsRegister DisplayScreen ManagementShareable Images
VaxstationsWindow Definitions
Key Definitions
The default definitions for keypad keys KP7 and MINUS have been
changed to accommodate changes in predefined display and window
definitions. The new definitions are as follows:
KP7 = DISPLAY SRC AT LH1, INST AT RH1, OUT AT S45,PROMPT AT S6
GOLD KP7 = DISPLAY INST AT H1, OUT AT S45, PROMPT AT S6
BLUE KP7 = Not defined
MINUS = DISPLAY %NEXTDISP AT S12345
GOLD MINUS = Not defined
BLUE MINUS = DISPLAY SRC AT H1, OUT AT S45, PROMPT AT S6
Type "HELP New_Features V4.4 Window_Definitions" for more
information on the new window definitions.
Register Display
The screen mode register display (REG) has been reformatted to
take advantage of the new window capabilities. REG is now a
square display that fits in one of the quarters of the screen
(for example, the top left-hand window LH1 or the top right-hand
window RH1). If your debugger initialization file had a command
like
DBG> DISPLAY REG AT Q3
then you may want to change it to something like
DBG> DISPLAY REG AT RH1
to accommodate the re-shaped register display.
Screen Management
In version 4.4 the debugger uses the SMG screen package to
implement its screen mode. If your program also calls SMG
routines, and you debug it with the debugger running on the same
terminal, then there probably will be interference between your
program and the debugger.
Our recommended solution is to debug the program using two
terminals. For a description of how to do this, see appendix D
of the DEBUG manual.
Shareable Images
Support for debugging shareable images is new in version 4.4 of
DEBUG and is described under "New_Features". There is one
restriction you should be aware of when debugging shareable
images. The shareable image must have been linked with the
/DEBUG qualifier in order for shareable image debugging to work.
If the image was not linked with the /DEBUG qualifier, then the
debugger may allow you to SET IMAGE to that image but then it may
show you incorrect results.
In summary:
$ LINK/SHARE/DEBUG X can SET IMAGE, everything OK
$ LINK/SHARE X can SET IMAGE, get incorrect results
$ LINK/SHARE/NOTRACE X cannot SET IMAGE
In a future release of the debugger we will correct this problem,
and make the debugger work correctly on shareable images that
were not linked with /DEBUG.
Vaxstations
You will notice that in version 4.4, the debugger comes up in its
own window when you run it on the Vaxstation.
There is a problem with control-Y handling when the debugger is
running in its own Vaxstation window. The control-Y will be
ignored when the keyboard is attached to the debugger window.
What you have to do to make the control-Y take effect is attach
the keyboard to the original window (by pointing at it with the
mouse), and then type the control-Y.
We expect to fix this problem in a future release.
Window Definitions
If you use predefined windows such as H2 in your initialization
file or in your own command or key definitions then you should be
aware of the following changes.
Changes to display window definitions and the addition of a
PROMPT predefined display have caused some incompatibilities with
earlier versions of DEBUG.
Previously, the bottom sixth of the screen (lines 21-24) on a
VT100 or VT200 series terminal) could not be used for defining
display windows. That area was reserved for the debugger prompt,
debugger input, debugger diagnostic messages, and program output.
Now, display windows can occupy any part of the screen, and a new
predefined PROMPT display shows the debugger prompt, debugger
input, and program output.
The boundaries of the default windows have been redefined to
cover the greater usable screen height. For example, on a VT100
or VT200 series terminal, FS (full screen) now covers lines 1-24,
H1 lines 1-12, H2 lines 13-24, and so on. A new symbol prefix,
S, denotes a multiple of one sixth of the screen. For example,
S56 is the bottom two sixths of the screen. (There are other new
predefined windows that occupy only the left or right halves of
the screen. Type "HELP New_Features V4.4
Vertically_Divided_Windows".)
The PROMPT display occupies S6 by default, but can be moved
elsewhere, like any display. Note that, to avoid confusion, the
PROMPT display is always on top of the display "pasteboard" and
therefore will hide the part of any display that overlaps the
PROMPT window.
By default, the OUT display is now at S45 (not, as previously, at
H2), so it will not be hidden by the PROMPT display. And the
keypad keys that manipulate display windows have been redefined
so that no display is positioned behind S6 (Type "HELP
Release_Notes V4.4 Key_Definitions"). If your DEBUG
initialization file contains DISPLAY or SET DISPLAY commands to
locate displays near the bottom of the screen (for example, at
H2, T3, or Q34) you may want to modify these window definitions
so the displays will not be hidden.
Type "HELP New_Features V4.4 Window_Definitions" for more
information on the new window definitions.
Screen features
The debugger provides a set of screen features designed to be
used on VT52, VT100 and VT200 series terminals and MicroVAX
workstations. The command SET MODE SCREEN activates screen mode
and SET MODE NOSCREEN deactivates it. In screen mode, "screen
displays" can be defined and viewed through windows on the
terminal screen. A screen display is a data structure which
contains lines of text. The text may be normal debugger output,
the text of a source file, a special register display, or a
special assembly-language instruction display. The text of a
display may be viewed through a window on the terminal screen and
can be scrolled back and forth through that window. When screen
mode is first set, the debugger provides the following predefined
displays: a source display (SRC), a debugger output display
(OUT), and a special display (PROMPT) where the debugger prompts
for input. For language MACRO, an instruction display (INST)
takes the place of the source display. Optionally, a register
display (REG) can also be displayed.
Additional information available:
CommandsBuilt-in DisplaysDisplay AttributesDisplay Kinds
ExamplesInstruction DisplayKeypadMoving DisplaysPROMPT Display
Resizing DisplaysScreen ModeScrollingSource DisplayWindows
Commands
A number of commands are used to control the debugger's screen
features. They are grouped here according to their general
purpose.
Control overall operation: SET MODE SCREEN SET TERMINAL
SET MODE NOSCREEN SHOW TERMINAL
Create screen windows: SET WINDOW CANCEL WINDOW
SHOW WINDOW
Create screen displays: SET DISPLAY CANCEL DISPLAY
SHOW DISPLAY
Modify screen displays: DISPLAY SCROLL
EXPAND SELECT
MOVE SHOW SELECT
Preserve screen displays: EXTRACT SAVE
You can get further information on each of these commands through
HELP. The most frequently used commands are DISPLAY, SCROLL,
EXPAND and MOVE. The DISPLAY command is used to modify the
absolute position of displays on the screen, to modify display
attributes, and to refresh the screen, among other things. The
SCROLL command scrolls the text of a display through its screen
window. The EXPAND and MOVE commands are use to modify the
relative position of displays on the screen.
The EXPAND, MOVE, and SET TERMINAL commands are especially useful
for manipulating displays on the larger screen of a MicroVAX
workstation.
Built-in Displays
The debugger defines five built-in displays which are available
when you invoke screen mode:
(1) A source display called SRC, which is automatically
positioned at your current PC, can be repositioned using the TYPE
or EXAMINE/SOURCE commands, and can be scrolled up and down using
keys KP8 and KP2. See the Source_Display subtopic for more
information.
(2) An assembly-language instruction display called INST, which
is automatically positioned at your current PC. INST takes the
place of SRC when the language is set to MACRO. INST is
initially removed for high-level languages but can be made to
appear using "DISPLAY INST". It can be selected as the scrolling
display by using key KP3 to rotate the scroll attribute to the
INST display, and then scrolled up or down using KP8 and KP2.
See the Instruction_Display subtopic for more information.
(3) A register display called REG, which is automatically updated
to show the current values of your registers. REG is initially
removed but can be made to appear using "DISPLAY REG".
(4) An output display called OUT, where debugger output is
directed. If you want to intermix debugger input and output in
the same display, you can copy debugger input to the OUT display
with "SELECT/INPUT OUT".
(5) A prompt display called PROMPT, where the debugger prompts
for input, forces program output, and (by default) prints
debugger diagnostic messages. See the PROMPT_Display subtopic
for more information.
Display Attributes
You can assign attributes to displays by means of the SELECT
command. The possible display attributes are:
o ERROR --- A display with the ERROR attribute displays
debugger diagnostic messages.
o INPUT --- A display with the INPUT attribute echoes your
debugger input.
o INSTRUCTION --- A display with the INSTRUCTION attribute
displays the decoded MACRO instruction stream of the module
being debugged. The keypad-key sequence BLUE-COMMA selects
the next instruction display on the display list as the
current instruction display.
o OUTPUT --- A display with the OUTPUT attribute displays
debugger output. The keypad-key sequence GOLD-KP3 selects
the next output display on the display list as the current
output display.
o PROGRAM --- A display with the PROGRAM attribute displays
program output.
o PROMPT --- A display with the PROMPT attribute is where the
debugger prompts for input.
o SCROLL --- A display with the SCROLL attribute can be
scrolled with the SCROLL command (or keypad keys KP2, KP8,
KP4, and KP6). KP3 selects the next display on the display
list as the current scrolling display (except for PROMPT,
which cannot be scrolled).
o SOURCE --- A display with the SOURCE attribute displays the
source code of the module being debugged, if available. The
keypad-key sequence BLUE-KP3 selects the next source display
on the display list as the current source display.
Although a display can have more than one attribute, subject to
the kind of display it is, only one display can have a particular
attribute. That display is then known as the "current" display
with that attribute (for example, current scrolling display,
current input display).
In the following example, the display OUT is selected as the
current input, error, and scrolling display. After the command
is executed debugger input, debugger output (assuming OUT was
previously selected for output), and debugger diagnostic messages
will be logged in the OUT display in the proper sequence, and OUT
will be the current scrolling display:
DBG> SELECT/INPUT/ERROR/SCROLL OUT
Attributes can be assigned to the various display kinds only as
follows:
Display Kind:
DO INSTRUCTION OUTPUT PROGRAM REGISTER SOURCE
Attribute:
ERROR yes yes
INPUT yes yes
INSTRUCTION yes
OUTPUT yes yes
PROGRAM yes
PROMPT yes
SCROLL yes yes yes yes yes
SOURCE yes
You unselect one or more attributes (deassign the attribute(s))
by issuing the SELECT command with the appropriate qualifier(s)
but without specifying a display. For example, the following
command unselects the INSTRUCTION and ERROR attributes:
DBG> SELECT/INSTRUCTION/ERROR
After the command is executed, no display has the INSTRUCTION or
ERROR attribute. When the ERROR, OUTPUT, or PROGRAM attribute is
unselected only the PROMPT display shows diagnostic messages,
debugger output, or program output, respectively. When the
INPUT, INSTRUCTION, SCROLL, or SOURCE attribute is unselected, no
display, including the PROMPT display, has that attribute. The
PROMPT attribute cannot be unselected.
By default, when you invoke screen mode, the built-in displays
are selected for attributes as follows:
Attribute: Built-in Display:
ERROR
INPUT
INSTRUCTION INST (for language MACRO only)
OUTPUT OUT
PROGRAM PROMPT
PROMPT PROMPT
SCROLL SRC
SOURCE SRC (for high level languages only)
Display Kinds
There are five kinds of screen displays: output displays, source
displays, register displays, instruction displays, and program
displays (only the built-in display named PROMPT has the display
kind PROGRAM). An output display holds normal debugger output
lines up to some maximum number of lines. An output display may
also have a debug command list which is automatically executed to
create the display text each time the debugger gets control from
the user program. A source display displays the user's source
program. The output from TYPE and EXAMINE/SOURCE commands can be
directed to a source display, and a source display can be
automatically updated through a debug command list. An
instruction display is much like a source display, except that it
holds assembly language instructions instead of source lines.
The output from an EXAMINE/INSTRUCTION command can be directed to
an instruction display, and an instruction display can be
automatically updated through a debug command list. A register
display shows the contents of the VAX registers, and is
automatically updated as the user program runs. The register
display is primarily intended for MACRO programmers. Except for
the PROGRAM display named PROMPT, displays of all kinds are
created with the SET DISPLAY command. They are manipulated on
the screen with the DISPLAY command, which takes a number of
qualifiers.
Examples
The following command places the source display SRC in the left
top half of the screen, the instruction display INST in the right
top half, the output display OUT under these two in the fourth
and fifth sixths of the screen, and the PROMPT display in the
bottom sixth.
DBG> DISPLAY SRC AT LH1, INST AT RH1, OUT AT S45, PROMPT AT S6
The following set of commands place the register display REG at
the top of the screen, create a new display WATCHABCD in the
middle of the screen to watch variables A,B,C, and D, and place
the OUT display below these, above the PROMPT display.
DBG> DISPLAY REG AT T1
DBG> SET DISP/MARK WATCHABCD AT T2 DO (EXAMINE A,B,C,D)
DBG> DISP OUT AT S5
Instruction Display
An instruction display gives you a scrollable window into the
assembly-language instruction stream. The built-in display INST
is an instruction display which is automatically updated so that
the arrow points to the instruction at your current PC. DISPLAY
INST makes it appear. The numbers to the left of the
instructions are line numbers.
If you select the instruction display using "SELECT/INST INST"
(or, PF4-COMMA on the keypad), then output of an
EXAMINE/INSTRUCTION command is directed to the instruction
display.
If you select the instruction diplay as the scrolling display
using SELECT/SCROLL INST (or by rotating the scrolling attribute
with KP3), then you can scroll it up, down, left, or right.
Pressing keypad-key KP7 places the built-in source display SRC in
the upper left half of the screen (LH1), INST in the upper right
half of the screen (RH1), the built-in output display OUT below
these two at S45, and the PROMPT display below OUT at S6.
Pressing the combination BLUE-MINUS redisplays SRC across the
entire top half of the screen (this is the default for high-level
languages).
Keypad
Many of the keypad keys are predefined to be screen commands.
For example:
KP8, KP6, KP2, and KP4 are "scroll/up", "scroll/right",
"scroll/down", and "scroll/left", respectively. The display that
is scrolled is determined by which display has the "scroll"
attribute. This attribute can be cycled through the displays
using the KP3 key.
There are a few built-in screen layouts that can be selected with
keypad keys: (1) A source display on the top half of the screen,
and an output display on most of the bottom half, above the
prompt display. This is the default layout for most languages.
The screen can always be put in this state with the keypad key
sequence BLUE-MINUS. (2) A source display in the top left half,
and instruction display in the top right half, and an output
display under these two, above the prompt display. This can be
selected with key KP7. (3) An instruction display in the top
left half, a register display in the top right half, and an
output display under these two, above the prompt display. This
is the default for language MACRO, and can always be selected
with the key sequence GOLD-KP7.
Moving Displays
You can move a display vertically and/or horizontally across the
screen by means of the MOVE command. Type HELP MOVE for a
description of the MOVE command.
PROMPT Display
The PROMPT built-in display is a non-scrollable display that
shows the debugger prompt, debugger input, and (by default)
program output and debugger diagnostic messages. By default,
PROMPT occupies the bottom sixth of the screen (the predefined
window S6). On a VT100 or VT200 series terminal, S6 includes
lines 21 through 24.
The PROMPT display is of the new display kind "PROGRAM". PROMPT
is the only display of that kind (no other PROGRAM displays can
be created). Note that, compared to other displays, PROMPT has
several restrictions, to eliminate possible confusion when
manipulating that display:
o PROMPT can never be hidden by another display. It is always
on top of the display "pasteboard".
o PROMPT can be moved anywhere on the screen, expanded to fill
the full screen height, and shrunk down to two lines. But
PROMPT must always occupy the full width of the screen and,
therefore, can not be moved, expanded, or shrunk
horizontally.
See the Display_Attributes subtopic for information on assigning
display attributes to various displays, including the PROMPT
display.
Resizing Displays
You can expand and contract displays by means of the EXPAND
command. Type HELP EXPAND for a description of the EXPAND
command.
Screen Mode
The first time you enter screen mode with the SET MODE SCREEN
command, the debugger creates three displays for you: a source
display (SRC) which is automatically updated as you STEP or GO
through your program, an output display (OUT) which captures your
normal debugger output, and a prompt display (PROMPT) where the
debugger prompts for your input. If your language is MACRO, an
instruction display (INST) display is substituted for the source
display. In addition, a register display REG is available but is
not displayed by default. Except for the PROMPT display, each
display can be scrolled back and forth with the SCROLL command.
You can turn off screen mode with the command SET MODE NOSCREEN,
after which you can use the terminal in the normal manner without
the display windows. The displays still exist, however, and can
be brought back at any time by again entering SET MODE SCREEN.
Scrolling
All screen displays except for the PROMPT display can be scrolled
through their screen windows by entering the SCROLL command. For
example, SCROLL/UP SRC scrolls the window up over display SRC.
To avoid having to specify the display name on your SCROLL
commands, you can select the display you want to scroll as the
"current scrolling display" with the SELECT command. Thus
SELECT/SCROLL SRC followed by SCROLL/UP causes the debugger to
scroll up through display SRC even through SRC was not explicitly
named on the SCROLL command. For more information, see the
SCROLL and SELECT commands.
Source Display
A source display gives you a scrollable window into your source
code. The built-in source display SRC has associated with it the
command "EXAMINE/SOURCE .%SOURCE_SCOPE\%PC". This is what causes
it to be automatically centered at your current source line.
%SOURCE_SCOPE is a built-in scope which means the same as scope 0
when source lines are available in scope 0. Otherwise, it means
the same as scope N, where N is the first level going down the
stack where source lines are available.
What this means is that if your PC is located in a place where
source lines are not available (e.g., in an RTL routine), the
debugger will attempt to display source in the caller of your
current routine (i.e., scope 1 or 1 level down the stack). If
source lines are still not available at that level, it tries
scope 2, and so on. When you are seeing source which is not the
top-of-the-stack source, an informational to that effect is
displayed.
Pressing the keypad-key combination BLUE-MINUS displays SRC in
the top half of the screen, the built-in display OUT below SRC at
S45, and the PROMPT display at the bottom of the screen at S6.
This is the default for high-level languages. Pressing
keypad-key KP7 places SRC in the upper left half of the screen
(LH1), the built-in instruction display INST in the upper right
half of the screen (RH1), OUT below these two at S45, and PROMPT
below OUT at S6.
Windows
A screen window is a rectangular region on the terminal screen
defined by the four quantities (RBEG, RLEN, CBEG, CLEN). RBEG is
the line number at which the window starts and RLEN is the number
of lines of text in the window. CBEG is the column number at
which the window starts and CLEN is the number of columns (width)
of the window. If the CBEG and CLEN numbers are omitted from a
window definition then the window defaults to the full width of
the screen.
The debugger provides a number of predefined windows for regions
such as the top half of the screen, the top left quarter of the
screen, and so on. For example:
H1 = top half of screen = (1,11,1,80)
H2 = bottom half of screen = (13,11,1,80)
LH1 = top left quarter of screen = (1,11,1,40)
There are also T1, T2, and T3 for thirds of the screen, Q1
through Q4 for quarters, and S1 through S6 for sixths. Each of
these also has a "L" for left half (e.g., LQ1) and and "R" for
right half (e.g., RQ1). FS denotes the full screen.
You can see all defined windows through the SHOW WINDOW command.
You can also define your own named windows with the SET WINDOW
command, or delete window names with the CANCEL WINDOW command.
Windows are specified on the DISPLAY and SET DISPLAY commands to
indicate where displays are to be shown on the terminal screen.
Example:
DBG> DISPLAY SRC AT LH1
DBG> DISPLAY INST AT RH1
DBG> DISPLAY OUT AT S4
DBG> DISPLAY PROMPT AT S56