Digital PDFs

AA-DO26A-TE

August 1978

108 pages

Original

4.6MB

view download

OCR Version

4.2MB

view download

Document:	VAX-11 Symbolic Debugger Reference Manual
Order Number:	AA-DO26A-TE
Revision:	0
Pages:	108
Original Filename:

OCR Text

August 1978

This document describes the VAX-11 Symbolic Debugger, a program used in
locating errors in executable user images. The information in this document is
particularly pertinent to programmers using the VAX-11 MACRO assembly
language.

VAX-11
Symbolic Debugger
Reference Manual
Order No. AA-DO26A-TE

SUPERSESSION/UPDATE INFORMATION:

This is a new document for this release.

OPERATING SYSTEM AND VERSION:

VAX/VMS VO1

SOFTWARE VERSION:

VAX/VMS V01

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation - maynard, massachusetts

First Printing,

August

1978

The
and

information in this document is subject to change
without notice
should not be construed as a commitment by Digital
Equipment
Corporation.
Digital Equipment Corporation assumes no respons
ibility
for any errors that may appear in this document
.

The

software described in this
and may only be used or copied

license.

responsibility

equipment

that

assumed

not

document is furnished under a license
in accordance with the terms of such

for

the

postage-prepaid READER'S
document requests the user's
paring future documentation.

COMMENTS

The

are

reliability of

its

trademarks

DIGITAL

critical

DECsystem-10
DECtape

PDP

DIBOL

DECUS
UNIBUS

form on the last page of this
evaluation to assist us in pre-

Digital Equipment

DEC

EDUSYSTEM
FLIP

CHIP

Corporation:

MASSBUS
OMNIBUS

0s/8
PHA
RSTS

COMPUTER LABS

FOCAL

COMTEX

RSX

INDAC

DDT

LAB-8

TYPESET-8

DECCOMM

TYPESET-11

DECSYSTEM~-20

TMS-11

ASSIST-11

RTS-8

ITPS-10

VAX

VMS

SBI

DECnet

software

affiliated companies.

1978 by Digital Equipment Corporation

The

following

use

supplied by DIGITAL or

IAS

CONTENTS

Page

vii
i
[

CONTROLLING PROGRAM EXECUTION

CHAPTER

INITIATING AND CONTINUING EXECUTION WITH GO

STEPPING THROUGH YOUR PROGRAM

EVALUATING ARITHMETIC EXPRESSIONS
*

NoOULe
WN

Ld
[]

L[]

el s

N
L]

L]
®

L
L]

Plus Sign (+)
Minus Sign (-)

Multiplication Operator (*)
Division Operator (/)
Shift Operator

(@)

Precedence Operators
Radix Operators

iii

SPECIAL CHARACTERS
*

CHAPTER

Showing Step Types
INTERRUPTING EXECUTION

Step Types
Setting Step Types

.1l
.2

dWWwwwhN

L]
° L] L ]
[
VbW

Startup Messages

Language Setting
Scope Setting
Setting Symbols
Entry and Display Modes
TERMINATING A DEBUGGING SESSION

N
o
o
o
&
o
e
o
e

INITIATING THE DEBUGGER
STARTUP CONDITIONS

=
w wwhn

Local Symbol Definition

(<...>)

S wWwWwwwhhN -

Pathnames

T Ot Ut SwwwdhhdhhNbDDDDO

|
BRI
L
l

Scope

Debugger Commands
SYMBOLIC REFERENCES
Debugger Symbol Table

Starting and Ending Debugging Sessions

|
NNNI})NNNN

Program Control

Evaluating Expressions

Examining and Modifying Locations

|
WWwwww

co~NoOYTUTdWNH

Tracepoints and Opcode Tracing

Watchpoints

Breakpoints

|
?hh?h#bh

WWwwwwddhhNhDNDNDDNDDNDHE

O HHEFEHRRERERERREERRE

VAX-11 SYMBOLIC DEBUGGER FACILITIES

BEGINNING AND ENDING A DEBUGGING SESSION

CHAPTER

INTRODUCTION TO DEBUGGING
USING THE VAX-1l DEBUGGER

whhvdbNpdDDDD
-

CHAPTER

PREFACE

(Cont.)

SN - S

N
N
N

T
Y

)

FOR ENTRY AND

CONTEXT MODES

DISPLAY MODES

Initial Modes
at Command Level

Effects of Context Modes
SYMBOLIC/NOSYMBQLIC Modes
INSTRUCTION/NOINSTRUCTION Modes
Evaluating VAX-1l MACRO Literals
ASCII/NOASCII Modes
DECIMAL Mode
HEXADECIMAL Mode

OCTAL Mode

LENGTH MODES

PATHNAMES

1
2
3

TRANSLATING

SYMBOLS INTO VALUES
TRANSLATING VALUES INTO PATHNAMES

T
N
I

a Debugging Session
Local Symbols
Global Symbols
THE DEBUGGER'S SYMBOL TABLE
Symbol Table Input (SET MODULE)
Symbol Table Status Report (SHOW MODULE)
Symbol Table Purging (CANCEL MODULE)

Permanent Symbols
Defining Symbols During

SYMBOL TYPES

3
4

PATHNAMES

AUTUTNND N

SEARCH MODES

GLOBAL/NOGLOBAL Modes
SCOPE/NOSCOPE Modes

whE=

RADIX MODES

1
2

DEBUGGING MODES

AND

N
I

St St St S
T

TN N

(

DISPLAY MODES

Changing Modes
Reporting Current Modes
Restoring the Debugger's
Overriding Current Modes

PATHNAME

N
I
D
{J

Bit Field Delimiters
Line Continuation Operator

SUMMARY

)

S I S

Delimiters

W N

)

(

(...)

Separator

String

(

)

Input

Delimiters

;

Argument

(

(=)

(\)

HHHOUOOOAOAOUIDBDWWNDNDND M

Separator

CONTROL OF

VbW

Delimiter

cuotutoootvitontoTtonotototgtoToTtTLT 1ot

Command Argument

Command

HHEFEFOUWVUWVWWOOOJ ()W We ) WS, NS, IS, BN

Command

P
=
HOOOOO

DEFINE

INITIALIZED MODES

NSNSt
UTe BB RBBRBWLWWWWWND
Ne)Wer e ) We Wer e Wer e
[]
L]
[
[]
[ ] L]
[
L]
[]

and

Symbolic Pathname Element Separator
DO Command Sequence Delimiters

OISOV

DEPOSIT

SYMBOLS

(\)

(@)

(:)
DELIMITING CHARACTERS
Keyword Delimiter (/)

KEYWORD

6
UG
WWWWwNDNDNNDDNMDN
e

Operator

(")

Symbol

Operator

ENTRY AND

(&) WA W
* L]
.

Displayed

EXPRESSIONS

(.)

[e)We AW e We Moy WarWerWe W e Wer We)We,

UGdwWwNH
WD
HWOOIAUI
o

@
e

o
o

e
e

¢
o

e
e
e

*
o

o
6

o
o

Range

IN ADDRESS
Symbol

Location Symbol

Value

Contents

CALL

o
o

s
o

o
o

Previous
Last

Mode

CHAPTER

CHARACTERS
Current Location

SPECIAL

WWWWWWwWwwwwwihdhdNNDNDN

A
o

CONTENTS

(Cont.)

[]

Continuing From a Watchpoint

Reporting

SETTING WATCHPOINTS

SHOWING WATCHPOINTS

CANCELING WATCHPOINTS
[]
L]
o
wN

WATCHPOINT EXAMPLES
AUV

|
I
T
WD

NNNNNNNI NN

|
=

Watchpoint

Examples of Setting Watchpoints
Examples of Showing Watchpoints
Examples of Canceling Watchpoints
WATCHPOINT RESTRICTIONS
EXAMINE AND DEPOSIT COMMANDS

EXAMINING MEMORY LOCATIONS AND REGISTERS
10.1
10.1.1
Examining Numeric Data
10.1.2
Examining Instructions
10.1.3
Displaying Locations As ASCII Characters
MODIFYING MEMORY LOCATIONS AND REGISTERS
10.2
10.2.1
Depositing Numeric Data
Depositing Instructions
10.2.2
10.2.3
Depositing ASCII Data

R WWWWNONNNE

USE OF WATCHPOINTS

WATCHPOINTS

00 00 00 00 00

Examples of Setting Tracepoints
Examples of Showing Tracepoints
Examples of Canceling Tracepoints

TRACING EXAMPLES

U
WD

Individual Tracepoints
Tracing All Call-Type Instructions
Tracing All Branch-Type Instructions
Tracing All Call-Type and Branch-Type
Instructions

\D\D\D\D\D\D\D\O\D\f@
|
T
T
T
I
|

[]
L[]

FACILITY

B
W W W

L[]
.

00 00 00 00 00 O

SHOWING TRACING MODES
CANCELING TRACING

TRACE

TRACEPOINTS

01100 001100 0 O11CO

SETTING

[]

USING THE

(SO S, S,y V)

TRACEPOINTS AND OPCODE TRACING

1
=

=
N

[

wNH-

[]

Examples of Setting Breakpoints
Examples of Showing Breakpoints
Examples of Canceling Breakpoints

=
O

®
*

L]
[]
[']
[]

SHOWING BREAKPOINTS

CANCELING BREAKPOINTS
BREAKPOINT EXAMPLES

CHAPTER

General Breakpoint Specification
DO Command Sequence at Breakpoint
Breakpoint "After" Option
Temporary Breakpoints

WOWOWWOWWOWVWYWOWYWWOWWYWWOWY

CHAPTER

OF BREAKPOINTS

Breakpoint Reporting at Program Stop
Continuing From a Breakpoint
SETTING BREAKPOINTS

W
N

GO WNDNNNN

USE

BREAKPOINTS

CHAPTER

o
Q
o

)

CONTENTS

10-1
10-2

10-5

CONTENTS

(Cont.)

Page

CHAPTER

USING THE

11.1
11.2
11.3
11.4

USING EVALUATE

EVALUATING VAX-1l MACRO LITERALS

11-2

EXCEPTION CONDITIONS

12-1

12.1
12.2

BREAK ON EXTERNAL EXCEPTION CONDITION

12-2

CALLING ROUTINES AND

SHOWING CALLS

13-1

13.1
13.2

CALLING

)

13-1

PROCESSOR STATUS

14.1
14.2

DISPLAYING THE PROGCESSOR STATUS. LONGWORD
ALTERING THE. PROCESSOR STATUS LONGWORD

14-1

DEBUGGER:

15-1

15.1
15.2

INFORMATIONAL MESSAGES (PREFIX:%DEBUG-I-)
WARNING' MESSAGES (PREFIX:%DEBUG-W-)

15-2
15-3

FATAL ERRQR. MESSAGES

15-8

15.3
15.4
APPENDIX A

EVALUATE COMMAND

EXPRESSION

11-1
11-1

EVALUATION

EVALUATING BIT

11-1

FIELDS

PROCESSING EXCEPTION

11-1

CONDITIONS

12-1

ROUTINES

13-1

SHOWING ACTIVE CALLS

LONGWORD" (PSL)

14-1

MESSAGES’

ERROR’ MESSAGES (PREFIX:%DEBUG-E-~)

COMMAND

(PREFIX:%DEBUG-F-)

SUMMARY

14-1

15-8

A-1

Index-1

INDEX

FIGURES

FIGURE

6-1

Debugger

Symbol-to-Value

Search Algorithm

6-8

TABLES

TABLE

Summary of VAX-11

Debugger

Arithmetic
Address

Symbolic

Special

Representation
Summary

Commands

Characters

Delimiting Characters
Keyword

Debugger

Initiation Qualifiers

2-2

4-1

Characters

for Entry

PSL Alteration Values:

1-4

4-4

4-7
and

Display Modes

5-1

14-

PREFACE

MANUAL OBJECTIVES

This manual describes the facilities supplied with the VAX-11l Symbolic
Debugger.
It
is
primarily
an aid in debugging programs written in
VAX-11 MACRO assembly language.
For information on debugging programs
written
in
other languages, such as VAX-11 FORTRAN IV-PLUS, refer to
the appropriate language user's guide.

INTENDED AUDIENCE

This manual is intended for programmers using VAX-1ll
MACRO.
To
get
the
most
out
of this manual, you should have a working knowledge of
VAX~-11 architecture and be familiar with the VAX/VMS operating system.
However,
while
not
a tutorial, the manual can be used by relatively
inexperienced programmers.

STRUCTURE OF THIS

DOCUMENT

This manual
comprises
15
characters
and
1
appendix.
Chapter
1
provides
a
functional
overview
of
the
VAX-1l1l Symbolic Debugger's
concepts and facilities, while each subsequent chapter discusses
each
concept
and
facility
individually.
Finally, there is a summary of
debugging

commands

in Appendix A.

ASSOCIATED DOCUMENTS

obtain

documents

For

supplemental

are

recommended:

information

you

VAX-11/780 Architecture Handbook

VAX/VMS

VAX~11

may

need,

the

following

Primer
Linker

Reference Manual

a complete list of VAX-11l documents,

Directory.

vii

see

the

VAX-1l1

TInformation

CONVENTIONS
The

USED

following

IN THIS

syntactic

Uppercase words

that you
Lowercase

should
words

that you

are

Brackets

([])

Braces
is

({})

DOCUMENT
conventions

are

Ellipses

(...)

repeated

one

used

and letters used
type the word or

this manual:

in command examples
letter as shown

and

letters used in format
substitute a word or value

indicate

to be chosen

are

used

indicate
more

optional

enclose

that

times

viii

indicate

examples
indicate
of your choice

elements

lists

the

from which

preceding

one

item(s)

element

can

CHAPTER 1
INTRODUCTION TO

DEBUGGING

One of the most difficult stages in the
program
development
process
involves
1locating and correcting errors, commonly called "debugging."
This stage is reached after you've
written
the
source
program
and
compiled
or
assembled
it
successfully, but have received erroneous
output when you tried to
run
the
executable
program.
This
means
you've
followed
all
the
rules
of the source language and have not
violated any constraints of the
compiler
or
assembler,
but
you've
probably
made
at
1least
one
programming
error
that
1is producing
incorrect results.
To help you find such errors, VAX-1ll
Symbolic
Debugger
(or, simply, the
control

the

locations;

execution

change

your

program

source program, recompile
corrected version.

The

VAX-11]
VAX-11

special program:
The debugger lets

you

can

the contents of locations;

program control;
and otherwise
occur.
After
you've
tracked

1.1

provides a
debugger).

SYMBOLIC
debugger

locate
down

monitor

check

specific

the sequence of

and
correct
errors
the mistakes, you can

re-assemble,

relink,

the
you

and

as
edit

they
your

execute

the

DEBUGGER FACILITIES
includes many

facilities

help you.

It is interactive - You control your
the debugger from your terminal.

converse

with

It is symbolic - You can
refer
to
locations
by
using
symbols you created in your source program.
The debugger
displays locations as symbolic expressions.

the
also

supports

converse
FORTRAN).

course
1-1

can

summary

change

your

from

session

variety of

can be

one

The

source

debugger
program

language

by means

1lets

(for

another

a command

you

example,
in

(see

the

Table

commands).

the debugger

address

1languages

language

a debugging

It permits

in which

the

You

for

different

program and

data

forms

You

can

accepts

and displays

represented

symbolically

control

the

mode

addresses

and

data.

virtual

address,
1in
decimal,
octal,
or
hexadecimal.
Data can be
represented by symbols,
symbolic
expressions
(X+3),
VAX-1ll
MACRO
instructions,
ASCII
character
strings,
or
numeric

strings

in decimal,

octal,

hexadecimal.

INTRODUCTION

1.2

USING THE VAX-11

This section comprises
debugger,
and
how to
provide more detailed
utilized.

1.2.1

TO DEBUGGING

DEBUGGER

brief descriptions
of
the
functions
of
the
use them.
The remaining chapters of the manual
information
on
how
these
functions
can
be

Breakpoints

A breakpoint is a place in your program where execution
1is
suspended
so
the
debugger
can
get
control
and
request a command.
Program
execution is suspended
before
the
instruction
at
this
breakpoint
address
1is
executed.
Thus, by setting breakpoints, you are able to
examine the status of your program at key moments
of
its
execution.
See

Chapter

1.2.2

Tracepoints and Opcode Tracing

Tracepoints help you follow the sequence of program
execution.
When
you
set
a
tracepoint in your program, the debugger will momentarily
suspend execution at that point, display a message indicating that the
tracepoint was reached, and continue execution from that point.
Thus,
you can determine whether the program is being executed in the
proper
sequence.

You

can
also
trace
the
execution
of
instructions,
by specifying which set of
traced.
See Chapter 8.

1.2.3

Watchpoints

A watchpoint refers
stop
whenever
the
addresses to ensure

to a specific
1location
1is
that they are

an unspecified manner.

1.2.4

branch
and/or
call-type
instruction opcodes you want

Examining

and

location, and causes the program
to
modified.
Thus,
you
can monitor
not being modified inadvertently, or

See Chapter

Modifying

Locations

When execution of your program is
suspended,
you
can
look
at
the
contents
of
1locations and modify them as you wish.
For example, you
might examine a location to
verify
that
it
contains
the
expected
value.
You
might
then
change the value to determine the effect on
subsequent execution.
See Chapter 10.

1.2.5
You

can

Evaluating Expressions
use

the

debugger

expressions, perform
See Chapter 11.

radix

calculator,

conversions,

compute

the

address

wvalue

value,

etc.

INTRODUCTION TO DEBUGGING

1.2.6

Program Control

You can initiate and suspend program execution in a
number
of
ways.
For
example, you can set breakpoints (see Section 1.2.1), and specify
the GO command to start or continue execution.
You can
also
execute
the
program on a one by one basis by means of the STEP command.
This
is
slower
than
the
GO-~breakpoint
method,
but
allows
a
closer
examination
of
the
program,
particularly
in
those areas that are
especially complex and prone to obscure errors.

1.2.,7

Starting

and Ending Debugging Sessions

There are several methods of passing control to the
VAX-11
debugger.
Generally,
you
specify
a qualifier when you compile or assemble the
source program, to ensure that the symbols defined in the program
are
included in the debugger's symbol table (see Section 6.3).
Then, when
you link the object program, you
1include
a
qualifier
to
make
the
debugger available to the program.
For example:
$

LINK/DEBUG file~-spec

When you enter
debugger
gets
for

the

RUN command to begin executing
your
program,
the
control, displays its identifying message, and prompts

command.

The

prompt

has

the

form:

DBG>

You respond to the prompt with one of the commands recognized
by
debugger (see Section 1.2.8).
To terminate the debugging session,
the

EXIT

1.2.8

command.

Debugger

You use
general

the
use

Commands

a set of commands to
tell
form of a debugger command

cmd([/qualifier]

[keyword

[param

the
is:

debugger

...]][DO

command

what

do.

The

[;command...]]

cmd
command name (SET, CANCEL,
function to be performed.

/qualifier
modifies

the

effect

the

SHOW,

etc.)

indicating

the

general

the

command

command.

keyword

indicates

the

(MODULE,

SCOPE,

specific

function

LANGUAGE,

performed

etc.).

param

qualifies
locations
DO

the function in some
to be monitored.

way,

such

command(s)
list of debugger
BREAK

put
Table

1-1

commands to be performed.
If more than one command
semicolon between them.
commands.)

summarizes

the

debugger

commands.

specifying

range

(Used only
with
SET
specified, you must

INTRODUCTION TO DEBUGGING

Table

1-~1

Summary of VAX-11l Symbolic Debugger Commandsl
Command

Keyword

Parameter

CALL

routine

name

argument

SET

BREAK

address

SHOW

EXCEPTION BREAK

name

CANCEL

LANGUAGE

/ALL

MODE
MODULE

opcode

step

Function

list

Call

expression

list
type(s)
class(es)

subroutine.

Initialize

(SET),

display

(SHOW), or

delete

(CANCEL)

the

specified

Not
can

all

elements.

combinations
For

used.

SCOPE

example,

STEP

not

SET ALL

TRACE

See

individual

WATCHPOINT

descriptions.

valid

command.
command

ALL
DEFINE

symbol=value

Equate
a

symbol

and

value.

DEPOSIT [/mode]

address=data

Put data

"EVALUATE [ /mode]

expression

Compute the value
expressions.

EXAMINE [/mode]

address|[:address]

Display contents of
or

EXIT

range

Terminate

[address]

Start

a location.
of

address,

addresses.

debugger.
continue

program

execution.
STEP

SYSTEM/NOSYSTEM

[decimal

integer]

INTO/OVER
LINE/INSTRUCTION
Appendix A

covers

the debugger

commands

Execute

portion

the program,
stop.
in greater

then

detail.

Underlines indicate the abbreviated form of a command or keyword.

1.3

SYMBOLIC REFERENCES

The

debugger lets you
refer
to
1locations
symbolically.
Thus,
1if
you've
defined a symbol in your source program as MINIM, you can tell
the debugger to examine or
modify
the
contents
of
MINIM,
without
worrying about MINIM's location in the executable image.
The debugger
resolves symbolic references by using a symbol table and scope.

1.3.1

Debugger

Symbol

Table

The debugger maintains a table that describes the symbols that may
be
referenced
during
a
debugging
session.
The
debugger can resolve
symbolic references only to symbols described in this table.
When you
initiate
a
debugging
session
(assuming
you've
met the conditions

INTRODUCTION TO DEBUGGING

needed to supply symbol information), this table describes permanent
symbols (for example, general register definitions); global symbols;

Use the
and local symbols in the first module input to the linker.
currently
are
symbols
modules'
which
determine
to
command
SHOW MODULE
in the symbol table. You can add or delete symbols by means of the
SET

MODULE

command.

and

CANCEL

MODULE

the commands used to control

1.3.2

commands;

using the DEFINE

See Chapter 6 for more information on the symbol
its contents.

table

and

Scope

If a symbol is unique, there can be no ambiguity when you refer to it.
if there are two or more symbols with the same name,
However,

the
appearing in different modules, and these symbols are in
debugger's symbol table, you must indicate which of them you mean when
you
To do so,
you use the symbol's name in a debugger command.
or
name,
module
a
prefixing
by
either
symbol,
specify the scope of the
by means of a SET SCOPE command (if the current scope or the default
scope is not appropriate). The default scope is initialized to the
See Chapter 6 for a discussion of
first module input to the linker.
scope and

1.3.3

related commands.

Pathnames

A pathname comprises the complete, unambiguous identity of a location
For unique symbols, the symbol name alone
in your executable program.
is a pathname. For symbols that are not unique, a pathname comprises
the scope and the symbol name,

in the form:

scope\symbol

1.3.4

Local Symbol Definition

in the
source program appear
To ensure that symbols local to your
indicate to the assembler or
you must
debugger's symbol table,
compiler that you want local symbol information to be available to the
You do this by specifying the appropriate qualifier in the
debugger.
For VAX-11
command line when you assemble or compile the program.
The qualifiers used for other
is /ENABLE=DBG.
the qualifier
MACRO,
languages are described in the user's guides for those languages.

CHAPTER

BEGINNING AND ENDING A DEBUGGING SESSION

This chapter

tells you how to

initiate and

terminate the debugger.

2.1

INITIATING THE

DEBUGGER

The usual method of
$

RUN[/DEBUG]

initiating

the debugger

is by specifying:

file-spec

You need to express the qualifier, /DEBUG, only if you did not specify
/DEBUG
at link time;
"file-spec" is the file identification assigned
to your program at link time.
You cannot
initiate
the
debugger
by
this method if you specified NOTRACE at link time (LINK/NOTRACE ...).
You can inhibit or defer the debugger by specifying:
$

RUN/NODEBUG

file~-spec

You need not express the qualifier, /NODEBUG,

unless you specified the

interpreter's prompt with the

For

/DEBUG qualifier
when you 1linked
your
program.
If
you
specify
$ RUN/NODEBUG, but later decide you want the debugger, interrupt
your
program
by
typing
CTRL/Y
(echoed as "Y) and respond to the command
A

command DEBUG.

example:

$ DEBUG

The debugger
its

prompt,

your

program,

indicates its readiness to accept commands by

DBG>.

enter

To determine
the

the location at which you

displaying

interrupted

command

DBG>EXAMINE/INSTRUCTION

@PC

The debugger reports the current contents of the program counter (PC),
plus
the
instruction to be executed if your program continues at the
indicated

location,

location:

shown

below.

1instruction

Note that typing CTRL/C has the same result,

CTRL/Y

and echoes

the

same

1if your program does not include an exception handler for this

condition.

Table 2-1

summarizes

initiation.

the

command

qualifiers

that

affect

debugger

BEGINNING AND ENDING A DEBUGGING

Table 2-1
Initiation Qualifiers

Debugger

Command

SESSION

Sequence

Effect

LINK/NOTRACE

Inhibits

both debugging

LINK

Inhibits

debugging,

RUN

LINK

Allows

RUN/DEBUG
LINK/DEBUG

Allows

RUN

you

Inhibits

receive

command,

the

instead

RMS

"file

the

will

full

LINK/DEBUG
RUN/NODEBUG

allows

debugging,

debugging

not

symbolic

found"

debugger's

traceback

but

not be

debugging

and

full

symbolic

possible
debugging

but

message

allows

traceback

response

identification message,

to
it

RUN

may

mean

that you mistyped
the
program's
name,
or
that
the
corresponding
logical
name
for the Symbolic Debugger is not assigned to the system
directory that contains the debugger.
1In the latter case, you
should
log out and then log in again.

2.2

STARTUP CONDITIONS

The following sections describe how
to
exist when the debugger is initialized.

2.2.1

modify

the

conditions

that

Startup Messages

When

the debugger
following form:
VAX/VMS

first

DEBUG

gets

version

tDEBUG-I~INITIAL,

control,

number

language

displays

release
xxx,

scope

messages

the

date
and

module

set

yYvy

DBG>

The

first message identifies the installed
the
release
date.
The
second
message
automatically has:
®

Set

its

your

Set

language

the

source

of the
indicates that

language

the

debugger

and
debugger

the

first

module

program.

the

name

symbolic
®

version

the

pathnames;

Read

symbol

table

for

first

module

see

Chapter

6).

information

use

from

creating

the

first

symbolic

scope

(area

module

into

pathnames.

prefix

its

for

symbol

BEGINNING AND ENDING A DEBUGGING SESSION

If this message does not appear,
initialization

procedures.

the debugger has not performed

You must use the SET LANGUAGE,

these

SET SCOPE,

and SET MODULE commands to initialize the appropriate settings.
The debugger's prompt, DBG>,
your

indicates that it is now ready to process

commands.

2.2.2

Language Setting

of
syntax
the
The debugger can interpret input or display output in
The language is initially set to the
supported native-mode languages.
program.
your
1in
1linked
module
first
the
of
language
source
Thereafter, you can change to any supported language by the command
DBG>SET LANGUAGE

where "language-name"

VAX~11]

FORTRAN

2.2.3

Scope Setting

language-name

is MACRO

(for

VAX-1l1l

MACRO)

FORTRAN

(for

IV-PLUS).

in
When the debugger is invoked, the scope is set to the first module
1in this module, you need only
symbols
to
refer
To
program.
your
To refer to duplicate symbol names in other
specify the symbol names.

modules,
specifying
only
the
symbol name, you must either give the
whole pathname, or change the scope.
You must also
ensure
that
the
To
the symbol table (see Section 2.2.4).
in
is
information
symbol
For example:
change the scope, use the SET SCOPE command.
DBG>SET

SCOPE

AJAX

Whatever previous scope existed is superseded by
6.4

for more

2.2.4

AJAX.

Section

See

information on SCOPE commands.

Setting

Symbols

the
table
symbol
1its
into
reads
1initially
The debugger
information
associated with the first module in your program.
intend to make use of other modules'

use

the

SET

MODULE

command

symbols in

pathnames,

you

symbol
If you
must

to read in the symbol information from

specified modules.
The commands, SET MODULE, SHOW MODULE, and
CANCEL
MODULE
1let
you
read information into the table, display its status,
more
for
6.3
Section
See
respectively.
contents,
and purge its
information.

2.2.5

Entry and Display Modes

The debugger's entry/display modes determine how
it
interprets
your
The initial condition of these
and displays output.
entries
command
HEXADECIMAL,
NOGLOBAL,
NOASCII,
SYMBOLIC, NOINSTRUCTION,
modes is:
LONG,

and

SCOPE.

Chapter 5 describes these modes,
SHOW MODE,

and

CANCEL MODE.

and use of the

commands,

SET

MODE,

BEGINNING AND ENDING

2.3

A DEBUGGING

SESSION

TERMINATING A DEBUGGING SESSION

You indicate that you
with the command:

are

through

responding

the

DBG>

prompt

EXIT

You

can

also

terminate

the

debugger

The

VAX/VMS command interpreter
character
($).
After exiting

DEBUG

command

reinvoke

the

gains

from

typing

CTRL/Z.

control, and
the debugger,

debugger.

displays its prompt
you can not use the

CHAPTER 3
CONTROLLING PROGRAM EXECUTION

This chapter describes how you start your program with GO and continue
your
program
with
STEP
or
GO.
The chapter also describes how to
interrupt your program, for example, to return control to the debugger
when your

3.1

program

is looping.

INITIATING AND CONTINUING EXECUTION WITH GO

The GO command tells the debugger to let your program
run,
beginning
either
at the transfer address, at a starting address you specify, or
from a location at which the debugger stopped it.
Program
execution
continues
wuntil
an exception condition (such as a breakpoint) causes
the debugger to stop execution, or
the
program
runs
to
completion
(refer to Chapter 12 for information about exception conditions).
The

command

format

DBG>GO

is:

[address-expression]

The first GO command without an address
transfer address.
[routine]

"routine"

actual

module

start PC

the

program

1its

is 2 less than

the

is mod\rtn.

is included

value.

starts

Note that the debugger responds with the message

The

in the message,

"mod\rtn"

was at the beginning of routine "rtn"

"mod".

If you enter

following

a GO command subsequent to program

breakpoint)

and

not

resumes from the point at which it was suspended
instruction at

the breakpoint's address).

suspension

(such

specify an address, execution
(for example,

the

If you specify an address with GO, that address replaces
the
current
contents
of
the
program
counter
(PC)
and
execution starts at or
continues from the new
1location.
Your
program's
behavior
<can
be
unpredictable
if you initiate execution at any address other than its
transfer address, or if you attempt to restart
your
program
at
its
transfer

address or

any other

address.

CONTROLLING

3.2

STEPPING

The

STEP

PROGRAM EXECUTION

THROUGH YOUR PROGRAM

command

lets

you

specify

the

number

instructions

MACRO)
or
statements
(FORTRAN)
that your program can
the debugger regains control.
The basic command format
DBG>STEP

you

specify

include

value

decimal

the

statement)

and

stops

the

accepted,

but

step

large step counts, the
(see
Chapter
7)
at
specified location.

the step counter
been completed.
also

step

has

will

default

3.2.1
The

STEP

value

performed.)

or
instruction

zero

Although

you

how you

(or

will

can

a
to

you
be

specify

breakpoint
run to the

stops
your
program
before
the
specified
statements are executed, the debugger resets
as though the specified number of steps
had

determine

how

following

can express

for

types

the

debugger

sections

describe

them

command

stepping.

interprets
the

level

the

functions

set

them

are:

LINE

INSTRUCTION

INTO

OVER

can

NOSYSTEM

express

DBG>STEP

where

that
The

conditions

step

32767),

Step Types

SYSTEM

You

and

through

the

executes

recommended practice is
to
set
the
desired
1location and use GO

zero,

modes

increment.

these modes
as

integer

debugger

program.

If an exception condition
number of instructions or

STEP

before

is:

[decimal~integer]

not

(VvAaX-11

execute

command

SET

STEP,

The

STEP

types

[/typel[...]]

slash

these

(/)
level

must

types

precede

overrides

exert

the
Step

each

its

INTO

for

Step

into

over

step

the

program

instructions

languages,

routine

(CALLS,

the

corresponding

RET

type

default

1lines

such

(the

for

called

CALLG,
routine

JSB,

only

(see

valid

line-oriented

FORTRAN

BSBB,

called

expressed
level

stepping.

MACRO).

instruction;
that
routine
instructions
step.

follows:

MACRO).

instruction
OVER

VAX-11

1increments

VAX-11l

Step

type.

control

increments

(statement)

for

step

counterpart

following

increment
Step

level

[decimal-integer]

below).

INSTRUCTION

LINE

command

(ignored

call-type

BSBW).
a

call~type

is,
the
1instruction,
(or
lines),
and

instruction

are

treated

all
the
one

CONTROLLING PROGRAM EXECUTION

steps executed
Decrement the step count only for
1ignores
debugger
the
space;
in °~ nonsystem

NOSYSTEM

instruction/line steps executed in system space.

Decrement the

SYSTEM

step

count

for

instructions

(or

the

SET

are executed in system space as well
that
lines)
system
of
definition
a
(For
as process space.
space, see the VAX-1l1l Software Handbook.)

the initial STEP modes are:

For VAX-11 MACRO,
INSTRUCTION,

OVER,

and NOSYSTEM.

Setting Step Types

3.2.2

You can change the default types for STEP at any

time

with

STEP command.

DBG>SET STEP typel,type...]

Multiple type entries must be separated by commas.

3.2.3

Showing Step Types

The SHOW STEP command reports the current STEP types.
DBG>SHOW

STEP

step type:

3.3

For example:

nosystem, by line, over routine calls

INTERRUPTING EXECUTION

You can interrupt execution of your program or the debugger by typing
VAX/VMS stops your program and
CTRL/Y (echoed at the terminal as "Y).
the
to
To return control
displays the command interpreter prompt.
debugger,

you must type the command DEBUG.

$ DEBUG

You can also continue
The debugger in turn displays its prompt, DBG>.
execution of your program (or the debugger) from the location at which
you interrupted it by responding with the command CONTINUE rather than
DEBUG.

$ CONTINUE

Typing any VAX/VMS command other than DEBUG or CONTINUE will generally
cause your program to exit

immediately.

3-3

CHAPTER 4
SPECIAL

CHARACTERS

This chapter describes how the debugger
in
arithmetic
expressions, in address

with VAX~-11 MACRO as

the

current

summarize
the
arithmetic,
respectively.
Some characters

interprets special
characters
expressions, and as delimiters
language.
Tables 4-1, 4-2,
and
4-3

address,
and
delimiting
(such as @) appear
in
more
table because of multiple uses, based on context.

4.1

EVALUATING ARITHMETIC

functions,
than
one

EXPRESSIONS

The
debugger
performs
integer
arithmetic.
All
operations
are
performed
according
to the length mode currently in effect (that is,
BYTE, WORD, or
LONG)
with
arguments
and
results
1limited
to
the
corresponding value ranges.
The debugger truncates values that exceed

the current

positions.
is "typed,"

Table

4-1

1length

mode

discarding

the

most

significant

Note, however, that truncation does not occur
for example, FORTRAN double precision values.

lists

special

characters

Arithmetic

used

in arithmetic

on data

bit

that

expressions.

Table 4-1
Special Characters

Character

Interpretation

Arithmetic
sign.

addition

(binary)

Arithmetic subtraction
minus sign.

Arithmetic multiplication

Arithmetic

division operator.

Arithmetic

shift operator.

Cewse?

Precedence

operators;

Decimal

Octal

Hexadecimal

operator,

(binary)

unary

plus

unary

operator,

operator.

radix operator.

radix operator.
radix operator.

first.

SPECIAL

CHARACTERS

An arithmetic expression is evaluated in the context
of
the
current
language.
For VAX-11l MACRO, the debugger evaluates an expression from
left to right under the following rules of precedence:
l.

Terms

or expressions enclosed by angle brackets,
evaluated first. You can nest expressions to many
example:

<...>,
levels.

are
For

order

<BEGIN+<INDEX*100>>

The

debugger

innermost
2.

evaluates

nested

expressions

1in

the

outermost.

Unary
operators
and
arithmetic
(binary)

radix
operators
have
priority
over
operators;
thus
values are evaluated
according to their signs and radices, and indirect
"contents
of"
operations
(see Section 4.2.4) are performed before the
remaining arguments and terms are evaluated.
For example, in
the expression
A+-@B

the

value

then

addressed

added

equivalent
3.

Thus,

arithmetic

and

shift)

"D1000 +
in

contents

represented

first

by A.

negated

Thus,

A+-@B

and
is

equal

(add,

subtract,

multiply,

divide,

precedence.

expression

"D1000 / 2

the

the
value

operations

have

following

the

to A+<~<@B>>.

The

the

results

decimal

"D10O

value

10000

However,

"D1000
results

4.1.1

+ << “D1000 / 2
the

Plus

decimal

Sign

value

"D10

6000

(+)

A plus sign, as a binary operator, adds the following argument to
the
preceding
argument
(or interim result).
As a unary operator, a plus
sign means take the following argument as having an
unchanged
value.
The
debugger
interprets
value by default.

unsigned

argument

having

positive

Examples:

DBG>SET BREAK

DBG>EVALUATE

4.1.2
A

Minus

minus

from
negate

sign,

the
the

Sign
as

BEGIN

"D2000

“X10

"“X1000 +

~0777

(=)
a

binary

preceding
following

operator,

argument.
argument.

subtracts

unary

the

operator,

following

a minus

argument

sign

means

SPECIAL

CHARACTERS

Examples:
DBG>CANCEL

WATCH

DBG>EXAMINE

4.1.3
An

NAME

INQUEUE

OFFSET

1000

Multiplication Operator

asterisk

multiplies

INDEX

(*)

the

preceding

argument

argument.

the

following

Examples:

DBG>EVALUATE
DBG>DEFINE

4.1.4
A

"X50

PAGE

Division Operator

slash

divides

remainder

the

"D512

PAGE

256

(/)

preceding

discarded.

The

argument

debugger

rejects

the

following

argument.

attempt

zero.

Any

divide

Examples:
DBG>DEFINE

MODULO

DBG>SET WATCH

4.1.5

The

Shift Operator

shift

argument

operator
(or

PAGE

INDEX
/

+
*

POINTER

wraparound

contents

the

interim

occurs

unary

result)

contents

the

sign

QUEUE_SIZE

(@)

"at"

sign.

the

number

the following
argument.
A
positive
negative
value means shift right.
The

loss

GO_TO_ZEBRA

bit

logical

the

sign

fill

bit

value
shift

shift.

bit.

the

It means
of

the

Shifts
bit

the

preceding

specified

means
shift
is arithmetic;

Shifts

vacated

shift

positions

the

left;
that

left

right

a
is,

cause

the

positions.

Examples:
DBG>EVALUATE

OFO0OQFFF0

000FFFO00

DBG>EVALUATE

“XFOOOFF00

OFFOOOFFOQ

4.1.6
The

Precedence Operators

(<...>)

debugger first evaluates terms or expressions
enclosed
by
angle
brackets.
An expression can contain up to 20 levels of nesting, with
the debugger evaluating them in the order of innermost
to
outermost.
The left and right angle brackets must match.

SPECIAL CHARACTERS

4.1.7

Radix Operators

The debugger interprets numeric arguments in the
current
radix mode
(see
Entry and
Display Modes,
Chapter 5), unless you precede each
argument with an explicit radix operator.

only

the entry that it accompanies;

in which

The

radix

operator

affects

it has no control over the radix

the debugger displays a value.

radix operators

for VAX-11 MACRO are:

"D -~ Decimal

radix.

"X ~ Hexadecimal
"0 ~ Octal

radix.

No spaces or tabs are permitted between the

radix

operator

and

its

operand.
Examples:

DBG>EV "D10+°D10
00000014 (assumes hexadecimal
DBG>EV "077+"XFF

display mode)

0000013E

DBG>EV 77+ XFF
00000176

4,2

SPECIAL CHARACTERS

IN ADDRESS

EXPRESSIONS

This section describes the significance of special characters that can
be
used
to
represent
1locations
1in address expressions.
Table 4-2
lists

the

address

representation characters.

Table

4-2

Address Representation Characters

Character

Interpretation

Represents the location last addressed by an EXAMINE,
DEPOSIT,
SET BREAK, SET TRACE, or SET WATCH command.
This is called the "current" location.

Represents the location previous to the last location
addressed
(as
represented
by
.);
(equal to last
location less the current length mode;
that is, .-1,
-2,

~-4).

or
EXAMINE
by
displayed
Represents the value last
in INSTRUCTION mode
in NOINSTRUCTION mode;
EVALUATE
for
branch
instructions
only,
this
character
represents
the
effective destination address of the
branch.
(The
backslash
is
also
used
1in
forming

pathnames.

"Contents"

See Section 6.1.)

operator.

Range operator (low
address:high
address)
for
the
EXAMINE
command;
bit
field
operator for EVALUATE
command (DBG>EVALUATE value<high bit:low bit)>).
4-4

SPECIAL CHARACTERS

4.2.1
A dot

Current Location Symbol
represents

the

location

SET

(.)
last

addressed

by an

EXAMINE,

DEPOSIT,

value
in the

of
the
DEPOSIT

examined
command's

BREAK,
SET
TRACE,
or
SET
WATCH
command.
This value remains
unchanged until you use one of these commands
to refer to a
different

location.
Example:

DBG>EXAMINE /ASCII
ERR_MESSAGE\MSG 1:

MSG
1

DBG>DEPOSIT/ASCII/BYTE

. + 2 = 'X!'
ERR_MESSAGE\MSG 1
NEXT

DBG>EXAMINE/ASCII
ERR_MESSAGE\MSG_1:

The EXAMINE command
address.
You
can
address

4.2.2

expression

circumflex

DEPOSIT,

mode;

that

INSTRUCTION

vary

assigns
a
then
wuse
to

represent

Location

Symbol

represents

SET

the

BREAK,

SET

.-1,

-2,

is
mode

NEZT

not

dot
this

to
the
symbol

that

location.

(")

last

TRACE,

location

SET

-4.

The

recommended,

length.

addressed

WATCH)

use

because

less

the

(by

this

VAX-11

EXAMINE,

current

length

character

MACRO

1in

instructions

Examples:

DBG>EXAMINE/ASCII
TEXT1l:

TEXT1+4:

TEXT1:TEXT1+4

WEET

DBG>DEPOSIT

/ASCII/BYTE

DBG>EXAMINE/ASCII

TEXT1l:

TEXT1+4:

4.2.3

"g"

TEXT1:TEXT1+4

WEET

Last Value Displayed

Symbol

(\)

A backslash can be used to
represent
NOINSTRUCTION
mode.
In INSTRUCTION

effective

operand

the

last

branch

in
either
mode
remains
unchanged
value or a new branch instruction.

the
mode,

value
a

last

displayed

backslash

represents

the

instruction displayed.

until

the debugger

The

displays

value

new

Example:

DBG>EV/ADDR

1028
DBG>EXAMINE\
CIRCLE\PI:
3.141593

The

EVALUATE

symbolized

location.

command
by PI.

produces
The

EXAMINE\

address

command

value

produces

for
the

the

contents

1location
of

that

SPECIAL CHARACTERS

4,2.4

Contents Operator

(@)

The unary "contents" operator (@) requests that the debugger evaluate
the expression following it and then extract the contents of the
location addressed by the expression value rather than use the
expression value

itself.

Examples:
DBG>EXAMINE

PC:

00000448

DBG>EXAMINE/INSTRUCTION @QPC

00000448:

(R7)
,W 0400 F
#OF

MOVB

The first EXAMINE reports the
EXAMINE reports the current
location

The

(00000448)

the second
PC's current contents;
(in INSTRUCTION mode) of the
contents

addressed by the PC's contents.

command

DBG>DEPOSIT MASK = @MASK @ 4

shifts the current contents of the location MASK four bit positions to
(Note that this example shows how the @ character is used
the left.

as both a shift and a "contents of" operator.)
The

command

DBG>EXAMINE @R7

@R7 +20

displays the current contents of the 21 bytes beginning with the
location addressed by the current contents of general register R7.

4.2.5

Range Operator

(:)

A colon is used in specifying an address range for an EXAMINE command.
The colon is also used as a range operator in bit field specifications
for an EVALUATE command

(see Chapter 11).

Examples:

DBG>EXAMINE INBUFFER:INBUFFER + 6
DBG>EXAMINE .:. + X200
@PC : @PC+10
DBG>EXAMINE/INSTRUCTION

4.3

SPECIAL DELIMITING CHARACTERS

This section describes the significance of special characters that can
be used to delimit various debugger expressions. Table 4-3 lists the

delimiting characters.

SPECIAL CHARACTERS

Table 4-3
Delimiting Characters

Character

Interpretation

Precedes

used

mode

Separates

entries

keywords

override
an

address

commands

expression

DEPOSIT

from

its

elements

symbol name
command.
Separates

after

that

can

current modes.

command;
definition

symbolic

from
data
separates
a

DEFINE

pathname.

Enclose DO command specifications in a SET BREAK
command,
or
argument
list
in a CALL command.
Note

that

the debugger does

not

use parentheses

to control the order of evaluation of arithmetic
expressions (see Table 4-1).
-e

Separates
individual
commands
in
a
command
line,
or
1in
a
DO
command
associated with a SET BREAK command.

(comma)

Separates multiple

Apostrophes

Enclose

Quote

ASCII:

arguments

string

instruction

input.

Enclose bit
command.

field

VAX-11]

specification

MACRO

for

EVALUATE

Hyphen
as
1last
printing
character
signifies
line
continuation.
The
prompts with an underline as the first

on
line
debugger
character

command
does
not

each
continued
execution until you
end with a hyphen.

1input

input.

marks
<

4.3.1

for

multiple
sequence

Mode

slash

Keyword

must

precede

Delimiter
each

1line,
enter a

and

defers

line

that

(/)

mode

keyword

entered

after

command.

Example:

DBG>EXAMINE/ASCII/BYTE

This

command

INBUF,

are

specifies
be

that

displayed

INBUF:INBUF+8

the
as

contents

ASCII

characters.

bytes,

beginning

SPECIAL CHARACTERS

4.3.2

DEPOSIT and DEFINE Command Delimiter

(=)

In a DEPOSIT command, an equal sign separates the
address
from the data entries.
1In a DEFINE command, an equal sign
symbol

name

from

the

definition.

expression
separates a

Examples:

DBG>DEPOSIT XRAY=0F15,0FFFF5C

This

command

successive

causes

the

longwords,

values

OF15

starting

and

OFFFF5C

deposited

location X_RAY.

DBG>DEFINE OFFSET="X200
This command specifies
hexadecimal value 200.

4,3.3

Symbolic

A backslash

that

the

symbol

OFFSET

Pathname Element Separator

separates

individual

elements

defined

the

(\)
of

symbolic

pathname.

Examples:

DBG>SET BREAK

In module
the local

MAIN CODE, set
symbol BEGIN.

break
The

breakpoint

the

1location

identified

at pc = CODE2\LOOP3+10

debugger

the

MAIN_CODE\BEGIN

reports

location

the

bytes

occurrence

after

the

breakpoint

location

identified

module

CODE2,

local

symbol

LOOP3.

A pathname identifies the program elements needed
to
completely
unambiguously
identify
a
1location.
In VAX-11 MACRO, a pathname
be:

A
symbol (a global symbol, or one that you created with
the
DEFINE
command,
or
any symbol that is unique in the symbol
table)
.

)

symbol

)

local

(see
®

the

symbol

SET MODULE,

local

symbol

name\symbol) .
classified as
A

pathname

value

and
can

for

can

the

module
that

Section

which

unique

scope

among

the

preceded

1its

module

names

used

any

1its

location

represents.

available
symbolic
required location.

expression;

information

modules

set.

current

set

6.3.1).

Program
section
local symbols.

currently

This

not

value

feature

name

VAX-11l

1is

sufficient

the

useful

(module

MACRO

are

address

when

identify

the

SPECIAL

4.3.4

DO Command

Sequence Delimiters

A SET BREAK command

semicolons,

the

that

can

the

breakpoint

command

CHARACTERS

sequence,

include

1list

debugger executes
watchpoint.

must

This

enclosed

commands,

whenever
command

separated

your program stops

1list,

known

by parentheses.

Example:
DBG>SET

After

the
then

BREAK

ALPHA

DO (EXAMINE

COUNT_l:COUNT_?;GO)

the debugger stops the program at location
current
contents
of the locations, COUNT_1
resumes execution of the program.

4.3.5

CALL Command Argument Delimiters

command

CALL

Parentheses

can

must

include

enclose

any

list

(

(eoe)

arguments,

supplied

argument

ALPHA,

through

it
displays
COUNT
7, and

)
separated

commas.

arguments.

Examples:
DBG>CALL

COMP (A)

DBG>CALL

SORT (BASE,ITEMS)

DBG>CALL

CALC

4.3.6
A

Command

Separator

(

;

)

semicolon

separates individual commands in a multiple
individual commands in a DO command sequence.

command

1line,

Examples:

DBG>SET

WATCH

RAIN

DBG>SET

BREAK

CLOSEUP

BOW;SET

BREAK

LOOP3;GO

DO (EXAMINE

WHERE;GO)

If GO, STEP, or CALL is used in a DO command sequence
, it must be
the
last
command
specified.
If not, the debugger prints a message, and
the GO, STEP, or CALL and any subsequent commands
in the
DO
sequence
are ignored.

4.3.7
A

Argument

comma

Separator

separates

(

individual

)
arguments

Examples:

DBG>SET

MODULE

DBG>DEFINE

X_RAY,CLOSE_UP,BAKE

INDEX

"X200,0PEN="D512

argument

list.

SPECIAL CHARACTERS

4.3.8

Input String Delimiters

The debugger requires that input strings in ASCII or INSTRUCTION modes
If you wish
be enclosed by matching apostrophes or quotation marks.
the
wuse
to enter a literal apostrophe or quotation mark in a string,
Refer
Otherwise, use either type.
type to delimit the string.
other
input
to ASCII mode and INSTRUCTION mode (Chapter 5) for mode use and
restrictions.

Examples:

DBG>DEPOSIT/ASCII

2500="IT'S"

DBG>DEPOSIT/INSTRUCTION SHUT='MOVL #30,R0O’

4.3.9

Bit Field Delimiters

A colon within angle brackets signifies a bit field specification that
the EVALUATE command is to report on.

The syntax is:

DBG>EVALUATE value<high bit:low bit>

The bit positions are numbered 0

(lowest bit)

(for a word), and 0 through 31

0 through 15

through 7

(for a

(for a longword).

byte),

The following procedure is recommended when you want to evaluate a bit
field when you know the corresponding longword value:
DBG>EV

2468A<9:7>

00000005

you
when
recommended
1is
sequence
command
The following
evaluate a bit field for which you know only the address.

want

DBG>EXAMINE address~expression
address:

contents

DBG>EVALUATE \<high bit:low bit>
bit-field

value

the value
The EXAMINE command establishes the location's contents as
This
represented by the backslash, the "last value displayed" symbol.
the
from
field
sequence is useful when you want to extract a bit
contents of

a location.

Examples:

DBG>EXAMINE LOOP3
WATCH\LOOP3:
OFFFF8FDO
DBG>EVALUATE \<6:4>
00000005

then
Use the EXAMINE command to display the contents of the location,
("last value displayed" symbol) with the EVALUATE
backslash
the
use
command, indicating the bit positions to be evaluated.

To display other bit patterns of the same location,
the

following:

DBG>EXAMINE

OFFFF8FDO
WATCH\LOOP3:
DBG>EVALUATE \ <8:6>
00000007

you

can

specify

SPECIAL

4.3.10

CHARACTERS

Line Continuation Operator

(

)

hyphen
as
the
last
printing
character
on
a
line
requests
continuation of the command line.
The debugger echoes an underline as
the prompt instead of DBG> for each continued line.
You may
continue
a

and

command

line

horizontal

tab

approximately

characters.

Example:

DBG>EXAMINE/ASCII/BYTE

_BUFFER:BUFFER+20

500

characters,

exclusive

space

CHAPTER
ENTRY

The entry and
entries
and
describes the
pathname
commands
CANCEL

search.
It tells you
establish and report

MODE

command

EVALUATE

in Chapter

5.1

(or

commands.

10;

KEYWORD

Table

5-1

letters
C
L

the

SUMMARY

summarizes

are

used

Context

Length

R -

Radix

Pathname

DISPLAY

MODES

display modes determine how the debugger interprets your
displays
solicited or unsolicited output.
This chapter
four classes of
modes:
context,
length,
radix,
and

debugger's initial modes.
override
current modes at
and

AND

the

The
the

The

how to use the
current modes,
CANCEL

chapter
command

EXAMINE

EVALUATE

ALL

also
level

and

command

SET
and

MODE
how

command)

and
to
to

SHOW
use

MODE
the

restore

the

describes
how
for the EXAMINE,

DEPOSIT

commands

is described

are

in Chapter

you
can
DEPOSIT,
described

11.

FOR ENTRY AND DISPLAY MODES
the mode
indicate

keywords.
mode

1In

the

table,

the

following

class:

Keyword

Summary

Table 5-1
for Entry and

Display

Modes

Mode
Class

Keyword

Function

ASCII

Interpret/display data

ASCII

BYTE

Interpret/display

data

byte

DECIMAL

Interpret/display

data

decimal

GLOBAL

Use

symbolic

entry

first

characters.
lengths.
radix.

pathname

search.
R

HEXADECIMAL

Interpret/display

data

hexadecimal

radix.
C

INSTRUCTION

Interpret/display

data

VAX-1l1

MACRO

instructions.

(continued

page)

ENTRY AND DISPLAY MODES

Table

Keyword Summary

5-1

for

(Cont.)

Entry and Display Modes

Mode

Class

Keyword

Function

LONG

Interpret/display data

NOASCII

Inhibit entry/display of ASCII

characters.

NOGLOBAL

Use symbolic

pathname

entry

longword

last

lengths.

search.

NOINSTRUCTION

Inhibit

entry/display

NOSCOPE

Inhibit SCOPE's contribution to pathname.

NOSYMBOLIC

Inhibit display of symbolic addresses.

OCTAL

Interpret/display data

SCOPE

instructions.

VAX-11

in octal

MACRO

radix.

Prefix entry with SCOPE's contents

form

pathname.

SYMBOLIC

Display symbolic

WORD

Interpret/display data in word lengths.

5.2

For

addresses.

INITIALIZED MODES

VAX~-1l

MACRO,

NOINSTRUCTION,
NOTE:

the modes

NOASCII,

are

NOGLOBAL,

high-level

initialized

HEXADECIMAL,

languages,

such

follows:

SYMBOLIC,

LONG,

and SCOPE.

FORTRAN,

these

defaults

are overridden by the data typing of variables.

5.3

CONTROL

DEBUGGING

MODES

The SET MODE, SHOW MODE, and
modes,
current
report
the
respectively.

5.3.1

Changing

CANCEL
modes,

change
MODE
commands
1let
you
initial modes,
restore
the
or

Modes

You can change one or more modes with

the

SET MODE command.

DBG>SET MODE mode~keyword[,mode-keyword,

...]

ENTRY

The

following

mode

choices

AND

are

DISPLAY

MODES

available:

Context modes:
SYMBOLIC

INSTRUCTION

ASCII

both

NOTE:

NOSYMBOLIC
or

NOINSTRUCTION

NOASCII
INSTRUCTION

and

ASCII

modes

are

time
(or
if
you
enter them both at
debugger defaults to INSTRUCTION mode.

active

command

the

same

level),

the

Radix modes:
DECIMAL
HEXADECIMAL

OCTAL

Length modes:
LONG
WORD
BYTE

Pathname

search modes:

GLOBAL

SCOPE

5.3.2
You
the

Reporting

debugger

etc.).

Current Modes

For

Debugger

5.3.3

the

entry

reports

the

mode

instruction,

Restoring
the

DBG>CANCEL

states

are

the

noascii,

You

can

display

keyword

usually

Debugger's

debugger's

scope,

lower

modes

using

(symbolic,

ascii,

initial

restore

DBG>CANCEL

This
command
watchpoints.

decimal,

long

entry

Modes
and

display modes,

type

MODE

noinstruction,

also

noglobal,

case.

Initial

Whatever mode changes you have made
re~initializes the mode state to:

symbolic,

and

example:

messages

restore

MODE

symbolic,

NOGLOBAL

NOSCOPE

can determine the state
SHOW MODE command.
DBG>SHOW

The

the

noascii,

are

canceled

noglobal,

debugger's

initial

and

hexadecimal,
modes

the

long,

debugger

scope

typing

ALL

also

cancels

all

breakpoints,

5-3

tracepoints,

and

ENTRY AND DISPLAY

5.3.4

Overriding Current Modes

MODES

at Command

Level

The EXAMINE,
DEPOSIT,
and
override
<current
modes by
verb.

For

example,

the

EVALUATE
commands
let
specifying mode keywords
command

you
after

temporarily
the command

DBG>EXAMINE/BYTE/ASCII BUFFER:BUFFER+
D10
causes the debugger to report the current
contents
of
eleven
bytes
beginning
with
BUFFER
as
ASCII
characters regardless of the modes
currently active.

This mode override feature lets you
DEPOSIT
command
without having to
current,
Each mode keyword entered
preceded by a slash.

specify an EXAMINE,
remember (or check)
after the
command

EVALUATE,
what modes
verb

must

or
are
be

With the exception of the INSTRUCTION and ASCII modes,
mode
keywords
entered
at the command level simply override their counterpart modes.
The following summarizes the relationships between command level modes
and

current modes.

ASCII/INSTRUCTION modes:
these modes are mutually
exclusive.
The
debugger
defaults
to
INSTRUCTION mode if it finds both
ASCII and INSTRUCTION active
or
requested.
You
can
avoid
getting
unexpected
results
by
leaving
both modes in their
initialized NO ...
states and requesting the particular
mode
only

command

Radix mode:
a radix mode specified at command
the
debugger's
interpretation
and
display
information

5.4

level.

for

the

level
controls
of
all numeric

command.

Length
mode:
overrides the

a
length
mode
specified
current length mode.

Symbolic mode:
you can set (SYMBOLIC)
the symbolic mode as you require.

Pathname search modes:
inhibit
the GLOBAL and
as you require.

command

inhibit

1level

(NOSYMBOLIC)

as with symbolic mode, you can set
or
SCOPE mode conditions at command level

CONTEXT MODES

The context modes allow the entry and display of addresses and data in
various
forms.
An
address
can be represented symbolically or as a
virtual address.
Data can be represented
by
symbols,
VAX-11
MACRO
instructions,
or
ASCII character strings.
The context mode keywords
are:

SYMBOLIC and NOSYMBOLIC
INSTRUCTION and NOINSTRUCTION
ASCII and NOASCII

The above
inhibit a
The

keyword pairs
condition.

debugger

NOINSTRUCTION,

function

initializes
and NOASCII.

the

on-off

context

switches

modes

as:

allow

SYMBOLIC,

ENTRY

5.4.1

The
and

Effects

MODES

Context Modes

following summarizes
display of addresses

Address

AND DISPLAY

the
and

effect
data.

the

context modes

the

Entry:

The debugger is insensitive to the [NO]SYMBOLIC mode for
entries.
You
can
express
an
address
either
as
a
pathname or as a virtual address.
Address

entry

address
symbolic

Display:

In
SYMBOLIC
mode,
the
debugger
displays
all
1locations
by
pathnames
when
possible.
Offsets are expressed in the current
radix
mode.
When
the
pertinent
symbolic
information
is
unavailable,

SYMBOLIC mode

ignored.

In NOSYMBOLIC mode, the debugger displays
addresses in the current radix mode.
Data

1locations

virtual

Entry:

In INSTRUCTION mode, the
debugger
interprets
a
quoted
string
entry as a VAX-11l MACRO instruction, interprets numeric values in
the current radix mode, and ignores the current length mode.
The
debugger rejects ‘instructions not enclosed in quotes.
In ASCII mode,
.the ‘debugger interprets a quoted string
entry
ASCII
characters.
The string is deposited as entered (that
the current length mode is overridden if necessary).
Data

as
is,

Display:

In INSTRUCTION mode, the debugger displays the
current
contents
of
specified
1locations
as
VAX-1l1
MACRO
instructions.
Most
numeric values are displayed in the current radix.
The
current
length
mode
1is
ignored
and the debugger increments sequential
instruction
1locations
on
the
basis
of
each
instruction's
allocated
storage.
The
debugger
tries to display instruction
operands in symbolic form if the addressing mode
1is
PC-relative
or

absolute.

In ASCII mode, the debugger
displays
the
current
contents
of
specified
1locations
as
ASCII
characters.
The character count
associated with each requested location is limited by the current
length mode, to four characters (LONG), two characters (WORD), or
one character (BYTE).
The current radix mode is ignored.
When

both NOASCII

and

NOINSTRUCTION
.are in

:weffect

the

debugger

displays
the
current contents of ‘the specified locations in the
current radix mode.
The debugger inctrements -sequential locations
on
the
basis
of
the
current
length
mode, if no data typing
information

available

(such

in FORTRAN programs)..

ENTRY

5.4.2

AND

DISPLAY

MODES

SYMBOLIC/NOSYMBOLIC Modes

The SYMBOLIC/NOSYMBOLIC
locations
symbolically,
pathname
e

can
A

symbol

allow
or
inhibit
1is,
by
pathname.

the
reporting
of
In VAX-11l MACRO, a

be:

DEFINE

modes
that

global

command

local

symbol,

see

symbol

Section

preceded

one

that

you

defined

with

the

6.2.2).

its

module

name

(module

name\symbol)
.
In

SYMBOLIC

mode,

NOSYMBOLIC

addresses
You

can

the

enter

current

locations

Refer to Chapter
pathnames,
and
expressions.

5.4.3

the debugger reports all
the
debugger
reports

mode,

radix

mode.

symbolically

6 for more
translates

locations by pathnames.
1In
locations
as
wvirtual

all

regardless

which

mode

set.

information on
how
the
debugger
builds
pathnames to values and values to symbolic

INSTRUCTION/NOINSTRUCTION Modes

The INSTRUCTION/NOINSTRUCTION modes allow or
inhibit
the
entry
and
display
of
data
as VAX-11] MACRO instructions.
In INSTRUCTION mode,

the

debugger

only

interprets

VAX-11l

MACRO

quoted

data

entries

instructions.

your entry as an instruction, it reports
instruction.
If
it
cannot
translate
location as an instruction, the debugger

the

displays

debugger

current

cannot

data

interpret

that
it
cannot
encode
the
the
current
contents
of a
reports that it cannot decode

instruction.

NOINSTRUCTION
The
to
the

and

the

inhibits

the

entry

display

data

instructions.

storage requirements of VAX-1l1l MACRO instructions
vary
according
the instruction type and number of operands.
The debugger ignores
current length mode when it enters or displays instructions;
the

debugger
number of

instead
increments
the
<current
address
according
bytes required or occupied by an instruction.

instruction string
quotation marks.
DBG>DEPOSIT

When
data

entering
string

entry

/INSTRUCTION

must

PLUNK

delimited

'ADDL3

the

apostrophes

#5,R3,R4'

an instruction, you must verify that
can be accommodated by the number of

the length
of
the
bytes you intend to

overwrite.
The
debugger
neither
guards
against
spillover
into
subsequent
bytes,
nor
pads
memory
left vacant when you replace an
instruction with
another
instruction
that
requires
1less
storage.

While

you

cannot

deposit more

the NOP instruction to
complete the deposit of
You

should

before

and

than can

fill
bytes
that
an instruction or

examine

the

location

after

the

deposit

to
to

changed

verify

accommodated,

are
unoccupied
instructions.

that

you

can

use

after

you

following

1it,

and

those

the

contents

are

correct

ENTRY

before

you

example

attempt

occupies

from

one

address

ADDL3

new

the

CMPB

mode,

the

debugger
parts

locations
cannot

the

given

debugger

interprets

return

the

translates
the

does

not

effect

the

ADDL2

SORT\BEGIN+14:

intact:

the

EMODF

DEPOSIT

command

for

other

independent
each

that

can

error.

The

allows

you

DEPOSITs

DBG>DEPOSIT

byte
If

and

subsequent

continue

eventually

reports

determines

a VAX~-11/780

byte

bytes,

that

bytes

examining

that

the

data

instruction.
you

must

it
in

enter

one

.='NOP'

reveals

that

the

desired

instruction

BEGIN+12:TEST SEQ

you

instruction

usually

following
to

without having

must

command

enter

sequence

reenter

compute

the

address—expression='instruction

'instruction

n+1'

'instruction

n+2'

for

the

sequence

series

INSTRUCTION

DBG>EXAMINE

DBG>DEPOSIT

that

#10,R2"

you

into

DBG>EXAMINE

DBG>DEPOSIT

instruction

@(R1)+, (RO) [R2], (RO) [R4],#0400C7FF
D157
,@W
(R6)

command,

MODE

verb

case.
DBG>SET

with

the

ADDL2 #10,R2
NOP
CMPB (R0) [R2]
(RO) [R4]
,

The

make

the

after

BEGIN+12

locations

SORT\BEGIN+12:
SORT\BEGIN+14:
SORT\TEST_SEQ:

you

because

#10,

DBG>EXAMINE/INSTRUCTION

debugger

leftover

DBG>DEPOSIT/INSTRUCTION

sequence

leftover

byte.

DBG>EXAMINE/INSTRUCTION

Examination

translate

DBG>EXAMINE/INSTRUCTION

me thod

command

directly

display

instruction.

instruction,

SORT\BEGIN+12:

any

EXAMINE

typed

BEGIN+12='ADDL2

meaningless

instruction per

which

@(R1)+, (RO) [R2],(RO) [R4] ,#0400C7FF,@W D157 (R6)

instructions,

bytes

suppress

NOP

some

decode

#10,R2,

BEGIN+12

(carriage

EMODF

typically

ADDL2

follows.

SORT\BEGIN+14:

location

(RO) [R2]1
(RO) [R4]
,

DBG>DEPOSIT/INSTRUCTION
DBG>EXAMINE/INSTRUCTION

The

following

1in

/INSTRUCTION

expression

change

The

instruction

#10,R2,R4

and mode keywords, if
any)
to
mean
follows the location last displayed.
Make

MODES

instruction.

#10,R2,R4

ADDL3

SORT\TEST_ SEQ:
INSTRUCTION

the

change

/INSTRUCTION

DBG>EXAMINE

DISPLAY

byte.

SORT\BEGIN+12:

the

less

DBG>EXAMINE

null

execute

illustrates

SORT\BEGIN+12

AND

entry,

entire

suggested

instructions

actual

but,

command

address

ENTRY AND DISPLAY MODES

of
Each EXAMINE command increments the previous address by the number
thus sets up the
and
instruction
entered
the
for
required
bytes
(.)

current address symbol

correct

for

address

the

illustrates this method.

example

5.4.4

the

with

The deposit of the NOP instruction in the previous

command.

DEPOSIT

Evaluating VAX~-11l MACRO Literals

not
it does
symbolic mode,
in
displays data
Thus, a
their symbolic equivalents.
into
values

debugger
When the
1literal
translate

the

displayed instruction may not appear exactly as you entered it in
ADDL3

#literal-value,

is displayed

ADDL3

the instruction

For example,

source code.

RO,

#3F4,

RO,

if literal-value was previously assigned the value 3F4.

The EVALUATE command can help you gquickly verify that the instructions
are

same.

the

If you

type

DBG>EVALUATE/LITERAL expression

of
the value
The debugger displays all pathnames it finds that have
It is then a simple
the expression as their 1literal assignment.

wish

matter to scan the pathname list for the literal symbol name you
to verify.

ASCII/NOASCII Modes

5.4.5

The ASCII/NOASCII modes allow or inhibit the entry and display of data
ASCII means interpret or display the data as
as ASCII characters.
ASCII characters. NOASCII means do not interpret the input as ASCII

not

initialized

display

the

current

in NOASCII mode.

data

string

with

either

provision lets you include
within a

string.

For

apostrophes

literal

must

enclose

quotation

marks

You

ASCII character input is usually by quoted string.

each

The debugger is

ASCII.

quotation

apostrophes

marks.

This

example,

DBG>DEPOSIT /ASCII
WINK
DBG>DEPOSIT /ASCII THINK
DBG>DEPOSIT /ASCII PLINK

=
=
=

'ZZZZ'
"IT'S"
'"1"'

The delimiter at the string's end must match the beginning
and must not appear within the string.

The current length mode (LONG, WORD, or BYTE)

1is

delimiter,

overridden

the

length of the string.

horizontal
Nonprinting ASCII characters (carriage return, line feed,
For example, you
must be entered as numeric equivalents.
etc.)
tab,
can enter a carriage-return, line-feed combination between strings as
follows.

DBG>DEPOSIT/ASCII/HEXADECIMAL/WORD

TEXT="IT'S",0D0OA,

"NEXT LINE"

The

debugger

enters

the

ENTRY

AND

value

ODOA

IT'S.
By
specifying
/WORD,
deposited as a longword value.
You

can

verify

the

DISPLAY

into memory

you

presence

MODES

ensure

the

following

that

the

value

nonprinting

string,

ODOA

is not

characters

displaying
the
contents
of
the
specific locations.
Note that the
debugger displays numeric data in the order that it resides in
memory
(that
1is,
the
contents
of
lower
addresses
appear
1in
the least
significant
digits)
whereas
it
displays
ASCII
characters
1in
a
left-to-right reversal of the actual character storage.

5.5

The

RADIX MODES

radix mode

keywords

are:

DECIMAL

HEXADECIMAL

OCTAL
The

base

used

performing

arithmetic

mode specified.
The radix mode
entered and displayed.
You can
the

radix

mode.

DBG>SET

Numeric
decimal

For

MODE

operations

depends

the

radix

also determines how numeric values are
use the SET MODE
command
to
specify

example:

DECIMAL

values specified in subsequent commands will be interpreted as
values,
and numeric displays will also be in decimal, unless

you override the current radix mode
with the command.
For example:
DBG>EVALUATE/HEX

including

radix mode

keyword

15+15

000600022
You

can

using

also

specify

radix

DBG>EV

that

operator.

"X15 +

data

For

entered

specific

displayed

the

current

example:

radix,

“X15

42
Note

that

the

resulting

(in
this
example,
radix operators.

5.5.1
In

DECIMAL

characters

in
0

See

Section

4.1.7

for

radix

mode

information

Mode

mode,

information

value

decimal).

the

through

can
use
the radix
as decimal when the

the

debugger

decimal
9.

With

interprets

radix.
the

entries

A decimal

debugger

set

and

entry can

for

VAX-1l

displays

include

the

MACRO,

you

operator "D to identify individual entry arguments
current radix mode is set to another radix.

ENTRY AND

5.5.2

DISPLAY MODES

HEXADECIMAL Mode

In HEXADECIMAL mode, the
debugger
interprets
entries
and
displays
information in the hexadecimal radix.
A hexadecimal entry can include
the characters 0 through 9 and A through F.
You
can
use
the
radix

operator
‘"X to identify individual entry arguments as hexadecimal when
the current radix mode

set

another

radix.

If an entry has an alphabetic as
the
1leftmost
character,
you
must
include
a
1leading
2zero
or
use
the
hexadecimal radix operator to
differentiate hexadecimal constants from symbols.

5.5.3

OCTAL Mode

In
OCTAL
mode,
the
debugger
interprets
entries
and
displays
information
in
the
octal
radix.
An
octal
entry can include the
characters 0 through 7.
With the debugger set for VAX-11
MACRO,
you

can
use
the radix operator "0 to identify individual entry arguments
as octal when the current radix mode is set to another radix.

5.6

The

LENGTH MODES

length mode
LONG

(for

keywords

are:

longword)

WORD
BYTE

The current length mode specifies the value (4, 2, or 1) by which
the
debugger
increments memory addresses for the entry or display of data
forms other than VAX-11 MACRO instructions.
In INSTRUCTION mode,
the
debugger
ignores
the
current length mode and increments memory as a
function of each instruction's storage requirements.
In NOINSTRUCTION mode, the results of all
arithmetic
operations
are
limited to value ranges corresponding to the current length mode.
The
debugger truncates values that
exceed
the
current
1length
mode
by
discarding most significant bit positions.

5.7
The

PATHNAME
pathname
GLOBAL

SCOPE

SEARCH
search

and

MODES
mode

keywords

are:

NOGLOBAL

NOSCOPE

The following sections summarize the use of these mode keywords.
a
complete
description
of their use and how such use relates to
debugger's search rules for translating pathnames to values, refer
Chapter

5.7.1

For
the
to

GLOBAL/NOGLOBAL Modes

In GLOBAL mode, the debugger searches its symbol table for a
symbolic
match to the pathname as you entered it (that is, it does not prefix a
scope to the entry).
In NOGLOBAL
mode,
the
debugger
prefixes
the

ENTRY

AND

DISPLAY

MODES

entry
with the contents of scope, or a PC-implied scope,
the symbol table.
If it does not find a match, it
then
find a match for the entry exactly as you entered it.

5.7.2
In

SCOPE/NOSCOPE

SCOPE

mode,

the

SCOPE

contents

SCOPE
a

prefix

pathname

(PC)

fails

Modes

debugger
and

entry with

currently

points

prefixes

searches

not

the

name

and

CANCEL

See

SCOPE

commands

the

pathname

symbol

applied

the

module

for

with the
can then

set,

Figure 6-1 for a diagram of the
resolving references to symbols.

the

that

with

for

the

current

match.

1If the
prefixes

debugger
the

program

counter

a match.

name of
use the

display,

entry

table

(NOSCOPE),

searches

The debugger initializes SCOPE
into
the
symbol
table.
You
SCOPE.

and searches
attempts
to

algorithm

the first module
read
SET SCOPE, SHOW SCOPE,

delete

the

followed

contents

the

debugger

CHAPTER

SYMBOLS

Pathnames

AND

PATHNAMES

symbolically

locations

represent
address
values
that
program.
This
chapter
describes

your

refer

to
symbol

how

information is entered in the debugger's symbol table for your use
in
specifying pathnames.
The chapter also describes how you control both
the contents of the symbol table and the manner in which the
debugger
translates

pathname

into

value

into

symbolic

expression.

6.1

PATHNAMES

The

debugger uses pathnames
avoid
the
possibility
of

to
symbolically
ambiguous
1local

program.

components:

pathname

has

two

1identify
symbols in

scope

and

locations
to
a multimodule

symbol.

The

form

unique

(the

can ignore the
the debugger

command.

is:

scope\symbol
Scope identifies the
module
backslash separates scope and
If

symbol

pathname
search
value

correct

The

If,

know

(or

simply

rules that
guarantee

accessed.
must

reference

and

govern

that

however,

debugger's

unambiguous,

specify

default)

location

you
the

MACRO,

module

time, and
identity

the

ambiguous
a

scope

symbol

symbols,
so

algorithm

name

See

the

that

defines

how

and

Section

6.4.

performs

symbols

the

that

scope

you

can

a pathname

you

that

have
names.

equivalent

can

appending

expression

They

specify

numeric

identifies

global

the

offset

address

pathname

unlabeled

scope

and

for

pathname

location.

any

a
The

debugger
access

when

function

define

a symbol into a
element will be

the debugger's permanent symbols do not require
since
they are, by definition, known throughout

represents,

example,

implicitly.

symbols,

(and to the debugger).
are simply their symbol

Since

you

symbol

specify
scope

symbol-to-value

Global

the
symbol
pathname).

data.

explicitly

VAX-11

the

the debugger's translation of
the specified location or data

expressed

symbols.

1in
which
symbol in

for

run

a
regional
the program
pathnames

1location

expression.

creates

local

debugger

their

the

scope

the

it
For

address

SYMBOLS AND PATHNAMES

6.2
The

SYMBOL TYPES
symbol

types

you

can

use

are:

Permanent

symbols

Symbols

Your

program's

local

Your

program's

global

you

create with

the

DEFINE

command

symbols
symbols

symbol is usually regarded
as
a
way
to
specify
a
value.
For
example, symbolic labels point to locations in your program.
However,
most data symbols represent a sequence of bytes, that is, a
range
of
values.
A
PSECT
name,
for
example,
refers
to an entire program
section within a given module.

While the concept of a symbol representing
an
address
pair
1is
not
always
pertinent (after all, you can't deposit a single value into an
entire program section with one command), it is a useful
concept
for
many cases, particularly when dealing with a language such as FORTRAN:
Both EXAMINE and DEPOSIT work with a range of bytes for
all
standard
FORTRAN data types.
1In VAX-11l MACRO, SET WATCH and translation from a
value to a symbol also depend on this view of symbols,

6.2.1

Permanent Symbols

The debugger has
the
symbols.
They cannot

Refer

e¢

Argument pointer

Frame

pointer

Stack

pointer

Program

PSL

Processor

6.2.2

RI11

following
VAX-1ll
redefined.

Chapter

Defining

General

abbreviations

permanent

for

registers

counter

Status

Longword

information on

Symbols During

the

a Debugging

Processor

Status

Longword.

Session

The DEFINE command lets you define global-type
symbols
at
any
time
during
a debugging session to supplement or override existing symbols
in your program.
The command format is:
DBG>DEFINE

symbol=expression[,symbol=expression

...]

Symbol is a name, and expression is
any
valid
expression.
Symbols
appearing
1in
an expression must be resident in the debugger's symbol
table.
You
must
separate
multiple
symbol-expression
pairs
with
commas.

You can, for example, create explicit
and/or
assign
various
data
values

6-2

symbols for unlabeled
to symbols for ease of

1locations
reference

SYMBOLS

AND

PATHNAMES

during
the
session.
The
debugger
always
searches
these
symbol
definitions
first when it translates a symbolic entry into a value or
when it translates an address location into a symbolic
equivalent
in
SYMBOLIC
mode.
Because the debugger treats these defined
first priority global symbols, your defined
symbols
have
over

all

other

definitions.
For

symbols

This

example,

rather

DBG>SET BREAK

you

could

define

DBG>DEFINE

than

the

BREAK

You

can disable

value

BP7,

displayed.

request

location

having

create

identical

symbolic

breakpoint

names

and/or

shorthand.

BP7

with

the

command

LOOP3\SILO_
3.

You

can

now

request

the

debugger

reports

the

BP7

stops

breakpoint,

BP7

the
by

For

DBG>SET

program

lets you

BP7=LOOP3\SILO_3

When your program
location by:
break

your

LOOP3\SILO
3

BP7 assumes the value
breakpoint as follows:
DBG>SET

priority

symbols as
precedence

shorthand

redefining

notation,
it,

and

then

determine

causing

the

symbolic

breakpoint

example:
BP7

DO (DEF

BP7=BP7-BP7)

DBG>GO

start pc
break at

is
pc

BP7
= BP7

LOOP3\SILO_
3

DBG>GO

start pc
The

debugger

exactly

requires

that

match

the

symbolic

symbol.
The
describes the
6.5.

section
complete

symbol

Symbolic
@
®

®
The

names
No

definition
value

equivalent

the

VAX/VMS

than

the

rather

user~-defined

debugger

than

global

Include

only

characters

wunderline
1lowercase
"loop" are

Begin with

and

symbol

report

that

1local

into pathnames
See
Section

conventions:

from

symbol
issues

the

character

set:

-2,

(_),
and dollar sign ($).
The debugger
alphabetics
to
be
uppercase.
Thus,
the same to the debugger.

alphabetic

truncates

characters.

dot
(.),
interprets
"LOOP" and

characters

1if

on
translating
output
values
rules on
translation
priority.

debugger

leftmost

the

address

character,
that

exceeds

message.

underline,
15

characters

dollar
to

sign.

the

SYMBOLS

The values
limits.

that you

assign

symbols

unsigned value must be within
®

Decimal:

Hexadecimal:

Octal:

signed

value

Decimal:

Hexadecimal:

Octal:

0
must

4294967295

37777777777

-80000000

symbol

For

symbol).

include

not

cannot

its

LOOP

also

commas

canceled

the

could be

ranges:

2147483647
7FFFFFFF

17777777777

with

you

either

character

tries

once

the

value

have

definition

1is

(2024;

defined

BP7

the

not

1it,

with

the

radix

alphabetic,

interpret

a different value

changed

the

character

2,024).

but

you

DEFINE

represent

A -

can

command.

the

1location

follows.

BP7=SORT\TEST_END

redefine

represent

DBG>DEFINE

following

are:

within

symbol

current definition.

the

ranges:

value

first

debugger

specifying

value

the

DBG>DEFINE

can

string

example,

value

values

the

LOOP3\SILO
3

You

for

(otherwise,

hexadecimal

operator

observe

following

~-20000000000

Precede

redefine

the

2147483648

must

FFFFFFFF

within

restrictions

the

Additional

AND PATHNAMES

value

created

For

1000

DEFINE

example,

you

plus

current

its

can

command,

1in

terms

redefine

the

symbol

definition.

loop=loop+1000

NOTE

The

DEFINE

command

circumstances,
create

With

the

any

symbol

EVALUATE
and

You

cannot,

command,
it

you
in

can

any

not,

used

a multi-element

express

DBG>EVALUATE

can

translate

any

pathname.

determine

radix.

For

[/radix~-mode-keyword]

however,

under

redefine

the

current definition of

example:

symbol

numeric

value

learn

its

symbolic

equivalent(s).
Refer

the

information
the

use

values

description

1its

wuse.

the

debugger's

for

your

defined

the

EVALUATE

Refer

special

symbols.

also

command

to Chapter

characters

(Chapter

for

11)

for

information on

expressions

create

SYMBOLS AND

6.2.3

Local

symbol

Symbols

information

includes:

Module names assigned by the VAX-11
MACRO
directive,
.TITLE
(they can be used only as the scope of pathnames, because they
have no values)

Program section names assigned by the VAX-11] MACRO
directive,
.PSECT
(program
section
names
assigned
by default are not
normally

e
For

PATHNAMES

All

accessible)

symbols and associated definitions not identified as being

global,

but not

the debugger

"n$"

type

symbols

to have access to local

symbol

information,

you must:

Request that the assembler produce debugging
assembles each module (/ENABLE=DEBUG)

Use

At run time, use SET MODULE to ensure that symbol
information
for
a
particular
module is present in the symbol table when
you intend to specify any local symbols from
that
module
1in
pathnames
or
you
want
the debugger to represent any of its

the /DEBUG qualifier

locations

local

at link

symbol

records

when

time

pathnames

If you prefer to enter or
have
the
debugger
display
locations
as
program
section
names
plus
offsets
(some
programmers
find
this
convenient when referring to assembly listings), you can request
that
the
1image
«contain
only
traceback records.
This request limits the

debugger's access

6.2.4

Global

symbols

to only module

and program

section names.

Symbols

include:

Those symbols identified as labeling external definitions
module by the VAX-11l MACRO directive, .GLOBL

Those

symbols

Those

symbols

delimited

that

1label

the double

the

double

global

equal

(==)

colon

1literals
operator)

(::)

in a

operator

(that

1is,

those

The debugger
references
global
1literals
only
when
translating
a
pathname
1into a value.
It ignores them in the translation of a value
into a pathname.
You can, however, determine the correspondence of
a
value
to
a
global
1literal name by use of the EVALUATE command (see
Chapter

11).

You can access your program's global symbols
only
if
you
specified
/DEBUG
when
vyou
1linked
your
program.
Refer to the VAX~-1ll Linker
Reference Manual and the VAX~1l MACRO User's Guide for information
on
how to make global symbols available to the debugger.

SYMBOLS

6.3

THE DEBUGGER'S

AND PATHNAMES

SYMBOL TABLE

The

debugger translates pathnames into values and values into symbolic
expressions
on
the
basis
of
information in its symbol table.
The
debugger has no knowledge of symbol information not
present
1in
this
table.
After
the debugger is initialized, this information consists
of permanent symbols, any symbols
created
by
DEFINE
commands,
all
global
symbols,
and local symbol information for the first module in
your image, if
you
specified
the
appropriate
qualifier
when
vyou
compiled
or
assembled the source program.
For example, for a VAX-11
MACRO program, /ENABLE=DBG.
When you initiate the debugger, it establishes a
data
modules
1in
your
program and reads symbol information
module into the symbol table.
The

following

sections

contents with

the

6.3.1

Table

The

Symbol

tells the
module(s)

modules,

debugger

to
you

entered

the

how
you
SHOW MODULE,

control

and

the
symbol
table
CANCEL MODULE commands.

(SET MODULE)

can

6.3.2

module-name|[,module-name,...]

add local symbol information
symbol
table.
Rather
than

the

request

that

all

symbol

table

the

for

the
specified
specify
individual
information for
all
modules

symbol

specifying:

MODULE/ALL

debugger

a message

The

Input

MODULE

DBG>SET
If

describe

MODULE,

for
the
the first

command
DBG>SET

SET

base
from

not

indicating

Symbol

Table

able

include

those

modules

Status

Report

some

that

were

the

not

modules,

prints

included.

(SHOW MODULE)

command
DBG>SHOW

produces
modules

MODULE

a status
1in
the

associated local
table.
e

report on the
program
and

symbol

information

The

report also

includes

the

approximate

number

accommodate

respective

the

total

the

amount

the

name

the

same

name

number

appears

modules.

into

free

the

bytes

language
in

the

following
bytes
of

the

modules

language
only

The
yes

report
lists
all
no whether their

is currently present

the

entry

modules

symbol table.
indicates
by

the

(in

decimal)

symbol

required

information

from

table
in

(in

your

which

used

line

the

for

that

to
the

program

decimal)

was

symbol

information:

available
modules

all

were

modules,

indicates

the

the
total

table
written.

language
number

SYMBOLS

6.3.3
The

Symbol

Table

Purging

AND PATHNAMES

(CANCEL MODULE)

command

DBG>CANCEL MODULE module-name{,module-name,

...]

purges symbol information associated with the specified module(s) from
the
symbol
table.
Typically, it is used to make space available for
symbol information associated with other modules.
The
CANCEL
MODULE
command
does
not
affect
global symbols or symbols that you defined
during

this debugging

You can delete
table

the

all

session.

local

symbol

information currently

the

symbol

command

DBG>CANCEL MODULE/ALL

6.4

TRANSLATING

SYMBOLS

INTO VALUES

The debugger's translation of symbolic entries into values is governed
by the GLOBAL/NOGLOBAL and SCOPE/NOSCOPE modes, which give you control
of the debugger's search rules.
Figure
6-1
1illustrates
the
search
algorithm.

The debugger evaluates an expression in which a symbolic entry appears
only if a definition was located for the entry under the search rules.
If it fails to locate a match for a pathname, the debugger reports the
search failure and the symbol name.
The expression becomes undefined.
If you specify GLOBAL, the debugger first assumes the
symbolic
entry
represents
the
entire
pathname,
and tries to find a match for that
pathname.
1If the search is unsuccessful, or if NOGLOBAL is in effect,
the debugger then tries all the other search possibilities.

If you specify NOGLOBAL,
represents
the
-entire
search possibilities.

the debugger assumes that the symbolic
entry
pathname
only
after
first trying all other

You might set the mode to GLOBAL if your program
contained
a
global
symbol and a local symbol with the same names, and you wanted to set a
breakpoint (or execute any debugger
command)
at
the
global
symbol
location.
Another

use would

be when you are working

one

your

program's

modules
and
want
to
execute the debugger command in another module
without having to change the current contents of SCOPE.
In this case,
you
would
enter the complete pathname, module name and local symbol,
in the command.
For

example,

this

sequence

DBG>EVALUATE/GLOBAL

SORT\SEQ CHECK

00003AF2

DBG>SET BREAK

makes the debugger determine the
value
of
the
given
pathname
and
display
1it.
The display in turn assigns the value to the last value
displayed symbol (see Section 4.2.1) for use as the operand in the SET
BREAK

command.

SYMBOLS

A DEFINED OR

YES

AND

PATHNAMES

o SUCCESS

PERMANENT

SYMBOL?

YES

SEARCH SYMBOL TABLE

YES

MODE GLOBAL

FOR PATHNAME TO
MATCH THE ENTRY

FORM NEW PATHNAME

YES

MODE SCOPE

MATCH

BY PREFIXING SCOPE,

FOUND?

SEARCH SYMBOL TABLE

FORM NEW PATHNAME BY

PREFIXING SCOPE BASED

ON CURRENT PC CONTENTS.
SEARCH SYMBOL TABLE

1S MODE

YES

NOGLOBAL?

USE ENTRY AS COMPLETE

»! PATHNAME. SEARCH
SYMBOL TABLE

MATCH

YES

FOUND?

PRINT ERROR

MESSAGE AND
PROMPT

Figure

6-1

Debugger

Symbol-to-Value

Search Algorithm

SYMBOLS AND PATHNAMES

NOSCOPE tells the debugger that you do not want the
current
contents
of
SCOPE
to be prefixed to a pathname entry.
The debugger then uses
the name of the module that the
program
counter
(PC)
1is
currently
pointing
to
as
the scope, and searches the symbol table for a local
symbol

The

from

that module

that matches your

entry.

sequence

DBG>EVALUATE/NOSCOPE
00003AF2
DBG>SET BREAK \

SEQ_ CHECK

directs the debugger to construct a pathname by prefixing the name
of
the
currently
executing
module to SEQ CHECK, determine the value of
this pathname, and display it.
The display, as
before,
assigns
the
value to the last value displayed symbol for use as the address in the
SET

BREAK

command.

The

command

DBG>SET SCOPE module~name

establishes the specified module name as the explicit scope to be used
under the search rules for the translation of local symbol and program

information
symbol
reads
The debugger also
section name pathnames.
associated
with
the
specified
module
1into the symbol table if the
necessary number of bytes are free in the table.
1If the
table
lacks
the
number
of
bytes
required
to
accommodate
the module's symbol
information, the debugger aborts the SET SCOPE command
and
prints
a

message.

The

command
DBG>SHOW

SCOPE

requests that the debugger

<null>

report

symbols.

The

command
DBG>CANCEL

report the current contents

SCOPE

enters a null string in SCOPE.
If you subsequently specify
SCOPE, the previous contents of SCOPE are restored.

6.5

TRANSLATING VALUES

In SYMBOLIC mode,
pathname

SET

MODE

INTO PATHNAMES

the debugger translates

address

value

1into

follows.

permanent
1its
with
wvalue
the
The debugger first compares
symbol definitions, then with the symbol definitions, if any,
that you created with the DEFINE command.
If it
locates
an
exact match
(no offset permitted), the debugger reports the
found

SCOPE.

1indicates that the SCOPE rule has no effect in looking

symbol

the

pathname.

If step 1 fails, the debugger compares
the
value
with
the
global
and
local
symbol
definitions.
A
global
symbol
definition is sought only if no local
definition
1is
found.
If
an
exact match is found, the debugger reports the symbol
as

the

pathname.

6-9

SYMBOLS AND

If no exact match can be
symbol
definitions
for

PATHNAMES

found,

the

debugger

the

that

one

searches

nearest

to,

yet

all
less

in value than, the value to be translated, and expresses
the
initial
value
as
that
pathname plus the necessary offset.
The debugger rejects a global symbol definition as being
the
nearest

and

value

the

value

unless

less

than

the

100

difference

between

the

symbol

(hexadecimal).

If the debugger does not find a suitable definition by
means
of
steps
1,
2,
and
3,
it reports the address value as a
virtual address in the
current
radix
mode.
The
probable
cause

is that
present

the

virtual

address

display

the respective module's
in the debugger's symbol

symbol
table.

rather

than

information

pathname

1is

not

CHAPTER

BREAKPOINTS

Breakpoints stop your program at selected locations to let you observe
and
change
the
context of your program while it is suspended.
This
chapter describes breakpoints, their options (command sequences to
be
executed
at
breakpoints),

CANCEL

the
and

BREAK,

breakpoint,
deferred
breakpoints,
how you use the commands, SET BREAK,

establish,

report

the

breakpoints.

7.1

USE OF

prematurely,
to

your

enter

contains.

analysis

breakpoint
®

can

data

produced,

program

specified

option

encountered

The

to
a

option

to
debugger

The

program

When

observations

exited

with

option to specify a
executes
automatically
associated breakpoint.

The

stops

and

delete

testing

any,

several

and

the

would

possibly

because

commands
your

breakpoint
of

options.

time

number

completion,

during

prematurely

each

depending

sequence

ignore

specified

run

1loop,

of
limited
general

violated

They

include:

that

the

program

until

exit

type

debugger

stops

has

the

been

times.

specify

a temporary
(or
one-time)
breakpoint.
automatically cancels the breakpoint after your

the

breakpoint

location.

Breakpoint Reporting at Program Stop
your

reports

program

the

break

suspended

location

at pc

example,

occurrence

break

breakpoint

SORT\INSEQ

breakpoint,

the

debugger

usually

LOCATION
given

where the location is
virtual
address
1in

where

might

infinite

The

7.1.1

program

Your

of,

BREAKPOINTS

Without breakpoints,
errors

status

and
temporary
SHOW BREAK, and

the

symbolically

current

(SYMBOLIC
mode)
or
as
a
radix mode (NOSYMBOLIC mode).
For

could

reported

SORT\INSEQ

the

pathname

that

uniquely

identifies

the

location

BREAKPOINTS

labeled
by
1local
symbol
1INSEQ in the object module
NOSYMBOLIC mode, the location would be reported by
break
The

at pc

debugger

SORT.

1In

00000846

sometimes displays

routine

named

break

at pc

the

report as

LOCATION

Note that in this case the value shown is 2 less than
the
actual
PC
contents.
This is the case whenever symbolic information is available
indicating that a
1location
or
symbol
1is
an
entry
point
or
the
beginning of a routine.

7.1.2

Continuing

From a Breakpoint

To continue your program from a breakpoint, you can enter a GO command
or a STEP command.
After GO, program execution continues until either
a breakpoint or another condition causes the program to
stop.
After
STEP,
program
eXxecution continues either through the number of steps
you specified (the default is one) or until some condition causes
the
program

stop.

The debugger

usually reports the

start pc

resumption of program execution by

is location

where "location" is again
given
as
a
pathname,
or
as
a
virtual
address.
If
the
report
1is
displayed
as
"routine
start
pc
1is
location”, the value
of
"location"
is
actually
2
1less
than
the
contents of

7.2

the

PC,

and

"location"

an entry point.

SETTING BREAKPOINTS

Breakpoints

are

set

and

identified

address.

Once

set,

breakpoint
remains
active
until
you
cancel
it
or
terminate the
debugging session.
No breakpoints are set when you begin the session.
The debugger's breakpoint table stores
the
information
relating
to
each breakpoint.
This table can accommodate many breakpoints.
If the
debugger reports a full table, simply cancel one or
more
breakpoints
to

clear

sufficient

table

space

for

the

new

entry.

The debugger does not protect current breakpoints against
overwriting
by
a
new
request.
The
debugger
simply
replaces
the
previous
specification with
the
new
command
entry
without
warning.
This
condition works to your advantage when you want to modify a breakpoint
specification.
1Instead of having to
cancel
a
breakpoint
and
then
specify
the new conditions for the breakpoint, you can just enter the
new specification for the same location.

7.2.1

General

Breakpoint Specification

You set
a
breakpoint
at
the
address
of
the
first
byte
of
an
instruction (your program stops at the breakpoint before executing the
instruction).
The debugger accepts the address specification
without
verifying
that
it
represents
the
first
byte of the instruction's
storage.

BREAKPOINTS

Warning:
middle of
The

Run-time errors
an instruction.

general

command

DBG>SET

BREAK

verify the

(see

Section

usually

format

for

result

specifying

address-expression

breakpoint,
4.2.1)

you

can

use

[DO

breakpoint

set

the

is:

(command-list)]

the

"current

1location"

symbol

follows:

DBG>EXAMINE/INSTRUCTION
The

debugger

7.2.2

When

displays

DO Command

specifying

the

instruction

Sequence

which

breakpoint,

The

command

STEP,

BREAK

list

CALL

you

can

sequence.

The

commands

address—expression

can

include

command

specified.

The

any

include

are

sequence
program

Note

that a
defined
at

symbol

the

evaluate
program

that
time

debugger defers binding
encountered.
You
can
time.
You

can

nest

SET

BREAK

debugger

must

set.

symbols
define

last

regardless

not

necessary

DO
the

the

GO,

the

within

until
at any

command
the

number

you

include

one

command,
you
last character

proper

command
sequence
SET BREAK command,

and values
the symbol

commands

command.

the

command sequence for
at the breakpoint.

stops

appears in
you
enter

of
stops

command.
For DO sequences that comprise more than
one
may
want
to
wuse
1line
continuation (a hyphen as the
before carriage return) and/or abbreviated keywords.

The debugger does not
or context until your

DO (command|[;command...])

required

semicolon

your

complete

included,

parentheses

breakpoint

Breakpoint

that
the
debugger
executes
whenever
breakpoint.
The command format is
DBG>SET

the

syntax

needn't
because

be
the

the
breakpoint
is
point prior to that

command

segquences.

For

example:

DBG>SET B
_DO

LOOP DO

(E/WORD

(E/BYTE

BUF:BUF+ X10;SET B

The

sequence above shows one level of SET BREAK
extend
this
nesting
to
any
1level,
as long
initiating and terminating parentheses match.

All

command sequences
breakpoint occurs.

To cancel or alter
command
with
the

associated

LOOP2

BUFX+4))

are

executed

the

context

nesting.
you ensure

effect

the DO command sequence,
enter
a
desired
content.
1If you cancel a

command

sequence

also canceled.

7-3

You

can

that

the

when

the

new
SET
BREAK
breakpoint, any

BREAKPOINTS

7.2.3

Breakpoint

"After"

Option

If your program
is
to
stop
only
after
the
nth
pass
through
a
breakpoint
location,
as in an iteration or conditional program loop,
specify the breakpoint as follows:
DBG>SET

where

Once

"after"

stop

your

BREAK/AFTER:n

decimal

address-expression

integer

breakpoint

program

has

each

the

range

stopped

time

through

your

32767.

program,

encountered

(that is, the breakpoint functions as if the
include the "after" option in any breakpoint

will

until

you

continue

cancel

You

can

count
is
1).
specification.

The SHOW BREAK command (see below) displays an
"after"
count
for
a
breakpoint only if it is other than 1l;
that is, the debugger must see
the location n more times before the breakpoint takes effect.

7.2.4

Temporary Breakpoints

temporary

canceled

(or

one

time)

breakpoint

automatically.

DBG>SET BREAK/AFTER:0

You

stops

your

specify such

address~expression

program

[DO

You

can

determine

DBG>SHOW

debugger

where

current

any breakpoint

breakpoints

actions

are

that were

[

set,

radix mode

along

with

typing:

BREAK

responds

[

debugger

(SYMBOLIC

with:

mode)

identifies
or

(decimal,

CANCELING

etc.

If the debugger
does
appropriate message.

7.4

(see below)
1lists
until the debugger

specified,

breakpoint/after:n at location etc.
breakpoint at location do-command-sequence,

The

then

SHOWING BREAKPOINTS

description of

The

and

(command)]

The breakpoint status report produced by SHOW BREAK
a
temporary
breakpoint
(by
displaying /AFTER:0)
executes 1it,.

7.3

once

breakpoint by

the

virtual

breakpoint
address

hexadecimal,
not

find

or
any

1locations

(NOSYMBOLIC

mode)

pathnames
the

current

octal).
breakpoints,

displays

the

BREAKPOINTS

' You cancel a breakpoint when you
program.

All

breakpoints

current

debugging

session.

are

1longer

automatically

want

canceled

to
when

stop
you

end

your
the

BREAKPOINTS

cancel

specific

DBG>CANCEL

When
or

canceling
options

address
If

the

breakpoint,

BREAK

address-expression

breakpoint,

that

you can not identify DO command sequences
previously established for the breakpoint.
An
the correct value is sufficient information.

were

expression
debugger

type:

cannot

find

specified

breakpoint,

prints

message.

cancel

all

breakpoints,

DBG>CANCEL

7.5
The

type

BREAK/ALL

BREAKPOINT EXAMPLES
following

examples

BREAK

commands.

7.5.1

Examples

DBG>SET

BREAK

Sets

Setting

TERMINAL

interprets

the

value

breakpoint

BREAK

Sets

breakpoint

The

program

the

location

pathname

the

bytes

stops

the

location

Sets

7.5.2

and

CANCEL

after

the

1location

debugger

(EXAMINE/ASCII/BYTE

the

debugger
at

stop your

1location

executes

this

breakpoint.
ASCII characters

the

command

the

pathname

sequence

The
sequence
the contents of

pathname

until

@R7:@R7+°D10)

identified

the DO

program

indirectly

after

tells
the
the eleven

addressed

"X7249

breakpoint

Examples

SHOW,

identified

not

debugger to report as
bytes beginning with the location that
the contents of general register R7.
DBG>SET BREAK

SET,

TERMINAL IO\BEGIN
(the
current radix mode).

debugger does
this location.

SORT\INSEQ

SORT\INSEQ.
the

the

SORT\SEQCHK

SORT\SEQCHK.
The
sixth pass through
DBG>SET

Breakpoints

the

BREAK/AFTER:6

Sets

use

IO\BEGIN+30

breakpoint

identified

DBG>SET

illustrate

’

virtual

Showing

SYMBOLIC
DBG>SHOW

mode

address

7249

(hexadecimal).

Breakpoints

(the

initialized

condition):

BREAK

routine breakpoint at SORT\INSEQ do(set scope inseq)
breakpoint at SORT\SEQCHK do (examine BUF:BUF+6,R8,COUNT)
The debugger reports the
associated DO sequences.

current

breakpoint

locations

and

BREAKPOINTS

In NOSYMBOLIC
DBG>SHOW

mode:
BREAK

breakpoint at
breakpoint at

0000846
000082A do

The

debugger reports
addresses
in
the
hexadecimal)
.

7.5.3

Examples

Canceling

(examine

the

breakpoint
current
radix

Breakpoints

DBG>CANCEL

BREAK TERMINAL IO\BEGIN
DBG>CANCEL BREAK SORT\SEQCHK

DBG>CANCEL BREAK
The

debugger

cancels

DBG>CANCEL

The

debugger

"X7249

the

specified

breakpoints.

BREAK/ALL

cancels

all

breakpoints.

BUF:BUF+6,R8,COUNT)
1locations

mode

(in

virtual
this
case

CHAPTER
TRACEPOINTS

Tracing

the

process

AND OPCODE

observing

the

TRACING

sequence

which

program

executed.
By
using the SET TRACE command, you can monitor the
in which your program executes its instructions
or
statements.
debugger
occurring
tracing:

can let you know whether unanticipated
as your program is running.
There are
tracepoints, and tracing on opcodes.

order
The

control transfers
two
basic
forms

are
of

A tracepoint is similar to a breakpoint.
When your program reaches
a
tracepoint,
it
momentarily
suspends
execution
and
reports
the
tracepoint.
It then automatically resumes execution.
Thus
you
can
see
1if
your
program
1is reaching specified locations in the correct
sequence.

Tracing on opcodes means
requesting
that
the
debugger
occurrence
of each instruction of a specified type, such
instructions and branch-type instructions.

8.1

You

USING THE

can

specify

At all
CALLG,

At all branch-type
branches and JMP;

follows:

(that

is,

call-type instructions in your
program
(includes
CALLS, RET, JSB, BSBW, BSBB, and RSB instructions).

all

both

call-type

degrades

examples,

the

specified

instruction

locations

instructions in your program (includes
excludes subroutine-type instructions).
instructions

performance

and

your

branch~type

program.

instructions.
this

concerns

breakpoints
with DO command sequences that include
only) command instead of using
tracing
(see
SET

Chapter

all

GO as
BREAK

7).

tracepoint, the debugger reports the
1location
and
then
allows
program to proceed automatically.
The report has the form:

trace
where

tracing

At the first byte
set tracepoints).

you,
enter
the last (or

a
your

FACILITY

Tracing

TRACE

report
the
as call-type

location

is given

instruction

symbolically or

virtual

address,

and

TRACEPOINTS

AND OPCODE

TRACING

instruction
1is the instruction at the location
tracepoint occurrence could be reported as:
trace

SORT\INSEQ

where
SORT\INSEQ
addressed
by
the

instruction at
be

reported
trace

the

routine
the

value

8.2

1is
the
pathname
program
counter

that

location.

00000846

displayed

trace

at pc

location

CMPB

location

actually

entry point

tracepoints.
more

8.2.1

the

location

would

(RO)[R2],
(RO) [R4]

instruction

less

than

beginning

the

current

PC,

and

routine.

clear

cancel it or
set when you

terminate
begin the

stores
the
information
relating
can
accommodate
a
1large
number

reports

sufficient

full

table,

table

space

simply
for

cancel

the

new

to
of

one

entry.

1Individual Tracepoints

set

tracepoint

must

TRACE

sure

that

(The
address-expression.)
verify

specifying

command

the

form:

address—-expression

instruction.

that
represents
the
location
CMPB (RO) [R2],
(RO) [R4] is the

and

until you either
tracepoints
are

table
table

the debugger

tracepoints

DBG>SET

You

SETTING TRACEPOINTS

The debugger's tracepoint
each
tracepoint.
This

You

example,

(R0O)[R2],
(RO) [R4]

1In NOSYMBOLIC mode,

Once set, a tracepoint remains
the
debugging
session.
No
debugging session.

CMPB

For

message

location

shown.

address-expression

debugger

tracepoint

you

does

can

follows:

use

not

the

verify

"current

first

the

location"

byte

wvalidity

symbol,

DBG>EXAMINE /INSTRUCTION

The

debugger

8.2.2
To

displays

Tracing All

trace

all

DBG>SET

the

instruction

Call-Type

call-type

TRACE/CALL

which

Instructions

instructions,

specify:

the

tracepoint

set.

TRACEPOINTS

8.2.3
To

Tracing All

trace

all

DBG>SET

8.2.4

branch-type

both

forms

TRACING

Instructions

instructions,

specify:

TRACE/BRANCH

Tracing All

trace

both

Branch-Type

AND OPCODE

Call-Type

forms

and

control

SET TRACE

Branch-Type

transfer

commands

Instructions

instructions,

either

order.

For

simply

enter

example:

SET TRACE/BRANCH
SET TRACE/CALL

8.3

SHOWING TRACING MODES

You

can

effect

determine

using

where

the

tracepoints

command

are

set,

and

the

form

tracing

DBG>SHOW TRACE

The

debugger

responds

with:

tracepoint at location
tracepoint at location
tracing /CALL instructions: list-of-opcodes
tracing /BRANCH instructions: list-of-opcodes
The

debugger identifies the
numeric
virtual
address
hexadecimal, or octal).
If

the

8.4

debugger

effect,

You

can

current

cancel

locations by
pathnames
or
by
current
radix
mode
(decimal,

tracepoints

set,

and

cancel

1longer

opcode

want

type:

tracing,

type:

TRACE/CALL

instruction

tracing,

type:

TRACE/BRANCH

tracepoints

TRACE/ALL

and

opcode

tracing,

both forms
when
you

address-expression

instruction

branch-type

CANCEL

you

tracepoint,

TRACE

call-type

all

when

can also disable one or
automaticglly
canceled

session.

specific

DBG>CANCEL
To

the

message.

tracepoint

debugging

DBG>CANCEL

find

location.
You
All tracing is

DBG>CANCEL

not

tracing

CANCELING TRACING

program
tracing.

does

it prints

tracepoint

type:

monitor

of opcode
end
the

TRACEPOINTS AND OPCODE TRACING

8.5

TRACING EXAMPLES

The following examples illustrate the

SET,

SHOW,

and

CANCEL

TRACE

commands.

8.5.1

Examples of Setting Tracepoints

DBG>SET TRACE TERMINAL_IO\BEGIN+30

Sets a tracepoint at the location 30
bytes
after
TERMINAL_ IO\BEGIN
pathname
the
by
identified
interprets the value 30

DBG>SET TRACE

in the current radix mode).

"X7249

Sets a tracepoint at virtual address 7249

8.5.2

the
1location
(the debugger

(hexadecimal).

Examples of Showing Tracepoints

1In SYMBOLIC mode (the
initialized
condition)
the
debugger
reports the current tracepoint locations.
For example:
DBG>SHOW

TRACE

tracepoint at SORT\INSEQ
tracepoint at SORT\SEQCHK

In NOSYMBOLIC mode
the debugger
reports
the
tracepoint
locations as virtual addresses in the current radix mode (in
this case hexadecimal).

For

example:

DBG>SHOW TRACE

tracepoint at 0000846
tracepoint at 000082A

8.5.3

Examples of Canceling Tracepoints
DBG>CANCEL TRACE TERMINAL_IO\BEGIN
DBG>CANCEL TRACE SORT\SEQCHK

DBG>CANCEL TRACE "X7249

The debugger cancels the specified tracepoints.
DBG>CANCEL TRACE/ALL

The debugger cancels all tracepoints and opcode tracing.

CHAPTER 9
WATCHPOINTS

Watchpoints

are selected program locations

instructions

that

watchpoints and
CANCEL
WATCH,
watchpoints.

9.1

modify

these

you

1locations.

the use of the commands,
to
establish,
report

monitor
This

SET WATCH,
the
status

identify

chapter

describes

SHOW
of,

WATCH,
and
and
delete

USE OF WATCHPOINTS

If an instruction modifies a watchpoint location, the
debugger
stops
your
program after the instruction completes execution.
The debugger
then reports the watchpoint location, the location of the instruction,
and
both
monitored.

the

The

number

and

the

bytes monitored

current

contents

watchpoint

the

depends

location

whether

being

the

location
has
a
data type.
For example, if the location is a double
precision FORTRAN variable, eight bytes are monitored.
However, if no
data
type
1is associated with the location (as in VAX-11l MACRO), four
bytes are monitored.
The current LENGTH mode 1s ignored.

9.1.1

Watchpoint Reporting

When your program writes into
a
watchpoint
stops the program and reports the following:
write

location at pc

old value
new value

=
=

1location,

the

debugger

location

value
value

The "write to location" indicates
"at
pc = location" indicates the
the writing.

the location that was medified.
The
location of the instructiion that did

The debugger reports the locations either symbolically or
as
virtual
addresses;
it reports the old (previous) value and the new {current)
value in hexadecimal.
For

example,

write

a watchpoint modification could be

to TERMINAL_IO\OUTLENGTH at
old value
new value

reported as

pc = TERMINAL_IO\MAIH_CODE*Si

000008A2
00000000

where
TERMINAL_IO\OUTLENGTH
1is
location
labeled
OUTLENGTH

the
pathname
in
‘module

that
identifies
TERMINAL IO,

the
and

WATCHPOINTS

TERMINAL_IO\MAIN_CODE+51

the

location

NOSYMBOLIC

For

example:

write

Note

that

mode,

at pc =

value

000008A2

new

value

00000000

Continuing

your
command.

continue

STEP,

The

condition
debugger

where

9.2

program

from

After

GO,

causes

location

are

displayed

that

identifies

virtual

addresses.

hexadecimal.

watchpoint,

enter
execution

program

condition causes
continues

specified

reports

start pc

offset

From a Watchpoint

execution

you

plus

000006A2

displayed

another

program

instructions
some

locations

00000432

are

pathname

instruction.

values

watchpoint

the

old

9.1.2

STEP

is
trapped

the

the
the

(the

the

program

resumption

GO
command
or
continues
until

program

either

default

through

is one

stop.
the

instruction)

After

number

a
a
of

until

stop.
of

program

execution

location

given

either

pathname

virtual

address.

SETTING WATCHPOINTS

You specify a watchpoint requést by,
DBG>SET

Once

set,
terminate

initialize

WATCH

address~expression

watchpoint remains active until you either
cancel
it
the
debugging
session.
No
watchpoints are set when

the

debugging

session.

The debugger's watchpoint table stores
each
watchpoint.
The space allocation
of

watchpoints.

9.3

information
accommodate

relating
a

large

number

SHOWING WATCHPOINTS

You

can

determine

DBG>SHOW

The

debugger

The

current

location

for

location

for

mode

current
1in

associated

are

set

typing

responds with:

watchpoint

the

watchpoints

WATCH

debugger

nnn,

where

watchpoint

(SYMBOLIC

the
can

or
you

identifies
on)

radix mode

decimal,

the

bytes
nnn bytes

watchpoint

numeric

virtual

(decimal,

indicates

watchpoint.

nnn

how

1locations
address

hexadecimal,

many

are

bytes

(NOSYMBOLIC

octal).

pathnames
mode

The

monitored

on)

value
by

the

WATCHPOINTS

9.4

CANCELING WATCHPOINTS

You

can cancel a watchpoint when you no longer
specified
1location(s).
All
watchpoints
are
when you end the current debugging session.

cancel

specific

DBG>CANCEL

If you

specify

watchpoint,

WATCH

want

to
monitor
the
automatically canceled

type:

address—expression

CANCEL WATCH/ALL,

If the debugger cannot

find the

all watchpoints

are

canceled.

specified watchpoint,

displays

message.

9.5
The

WATCHPOINT EXAMPLES
following

examples

illustrate

commands.

9.5.1

Examples of

DBG>SET

WATCH

The

9.5.2

watches

CANCEL

WATCH

the

location

identified

the

pathname,

virtual

address

7249

(hexadecimal).

Showing Watchpoints

With SYMBOLIC
DBG>SHOW

MODE

watchpoint
debugger

(the

initialized

condition):

WATCH

watchpoint

at SORT\INSEQ for 4.
at SORT\SEQCHK for 2.

reports

the

current

pathnames.

and

"X7249

debugger

The

SHOW,

TERMINAL IO\BEGIN

Examples of

SET,

Setting Watchpoints

The debugger watches
TERMINAL IO\BEGIN.

DBG>SET WATCH

the

With NOSYMBOLIC

mode

bytes
bytes

watchpoint

locations

on:

DBG>SHOW WATCH

watchpoint

0000846

for

watchpoint

bytes

000082A

for

bytes

The debugger reports
the
watchpoint
1locations
virtual
addresses.
The addresses are displayed
the current radix mode.

as
numeric
according to

WATCHPOINTS

9.5.3

Examples of Canceling Watchpoints
DBG>CANCEL WATCH

TERMINAL IO\BEGIN

DBG>CANCEL WATCH SORT\SEQCHK

DBG>CANCEL WATCH

"X7249

The debugger cancels the

9.6

specified watchpoints.

WATCHPOINT RESTRICTIONS

When you set a watchpoint, the entire page containing
the
watchpoint
location
is
protected.
When an instruction attempts to write to any
location on that page, at user mode level, the
modification
1is
made
and
execution continues unless the modification was to the watchpoint
location.
the
o0ld
caused

the

In this case, the debugger suspends execution
and
reports
and
new
contents, and the location of the instruction that
change.

If a system service needs to write to a location on a protected
page,
it
will
return
failure
status.
Therefore,
you
should
not
set

watchpoints on pages that contain locations that may
be
modified
system
software;
for
example,
I/O
status
blocks
subject

modification by Record Management Services.

by
to

CHAPTER 10
EXAMINE AND DEPOSIT COMMANDS

This chapter describes how to use the EXAMINE and DEPOSIT commands
display and change the contents of selected memory locations.

10.1

EXAMINING MEMORY LOCATIONS AND REGISTERS

The EXAMINE command displays the contents of selected memory locations
and

registers.

The

command

format

is:

DBG>EXAMINE [ /mode] address|:address]
[ ,address[:address]]

You can specify a value for /mode,
described

in Section 5.3.4.

to override the current

modes,

You can use EXAMINE to display any combination of the following:
e

A single location

Multiple

A range of contiguous

Multiple

locations

ranges of

locations

If you specify more than one address, and separate them
with
commas,
the
contents
of
the locations specified are displayed.
However, if
addresses
all
then
you use a colon to separate a pair of addresses,
within that range

are displayed.

DBG>EXAMINE/WORD
00001028:
00001040:

For

1028,1040

046b
OEF40

DBG>EXAMINE/WORD
00001028:
0000102A:
0000102C:
0000102E:
00001032:
00001034:

046B
0000
08C2
OD7EF
OFFF3
OAEFF

00001036:
00001038:
0000103A:
0000103C:
0000103E:
00001040:

0DOO4
04AE
9850
22A0
0D450
OEF40

1028:1040

10-1

example

EXAMINE

specify multiple

ranges,

DBG>EXAMINE/WORD

The

results

use

DEPOSIT

command

COMMANDS

such

as:

1028:102E,103A:1040

are:

00001028:

046B

0000102A:

0000
08C2

0000102C:

AND

0000102E:

ODOSE

0000103Aa:
0000103C:

9850
22A0

0000103E:

0D450

00001040:

OEF40

When
When

you specify a
you
specify
order.

range, you must
specify
more than one individual

the
low
location,

address
you can

first.
use any

If you wish to display the
next
address.
Thus,
after
you've
address,

you

don't

example:

DBG>SET

MODE

DBG>EXAMINE

1028:

have

location,
you
needn't
specify
an
examined
a location by specifying an
specify the next contiguous location.
For

WORD
1028

046B

DBG>EXAMINE

102a:

10.1.1

Examining Numeric Data

modes,

examples

LONG,

DBG>SET

range

illustrate
of

WORD,

and

MODE

HEXADECIMAL

DBG>EXAMINE

00004000:
00004004:

0ADO

00004002:
00004004:
00004006:

5000

LONG

4000:4006

01DO
4000:4007

0DO0

00004001:
00004002:

(17:
50

00004003:

0Do
00

00004006
00004007:

0DO50

DBG>EXAMINE/BYTE

use
as

EXAMINE

hexadecimal

to
data

respectively.

0DO500ADO
01D05000

00004000:

00004004:
00004005:

BYTE,

4000:4004

DBG>EXAMINE/WORD

00004000:

the

locations

50
0DO
01

following

contents

[\S}

The

0000

NOINSTRUCTION

display
in

the

length

NOSYMBOLIC

EXAMINE

The
current
contents
instructions by

AND

these

DBG>EXAMINE/INSTRUCTION

The

4000:

MOVL

#0A,

4003:

MOVL

#00,

example

affect

10.1.2

how

above
the

Examining

locations

could

displayed

that

the

current

increments memory

length

display

mode
the

does

not

instructions.

Instructions

The following example
several
locations

illustrates
as
VAX-11]

information on examining

data as

DBG>EXAMINE/INSTRUCTION

SORT\BEGIN+12:
SORT\TEST_SEQ:
In

COMMANDS

4000:4004

illustrates

debugger

DEPOSIT

how EXAMINE displays
MACRO
instructions.

instructions,

SORT\BEGIN+12

ADDL3
CMPB

INSTRUCTION mode,

the

debugger

refer

the contents of
For
complete

Section

5.4.3.

TEST SEQ

#10,R2,R4
(RO) [R2],
(RO) [R4]
ignores

the

current

length

mode

and

displays
whatever
storage
the
instruction
occupies.
With
the
exception of PC relative displacements, literals and displacements
1in
instructions
are
displayed
1in
the current radix mode.
PC relative
displacements are evaluated and displayed symbolically (SYMBOLIC mode)
or as virtual addresses (NOSYMBOLIC mode).

10.1.3

Displaying

Locations As ASCII

Characters

The following example illustrates how EXAMINE displays the contents
a range of locations as ASCII characters.
For complete information

examining

data as ASCII

characters,

DBG>EXAMINE/ASCII/LONG
CHARS:
1IT'S
CHARS+4:

CHARS+8:
CHARS+0C:
CHARS+10:

10.2

DEPOSIT

and

registers.

Section

5.4.5.

CHARS:CHARS+7"X13

"
SMAL
L" W
ORLD

MODIFYING MEMORY

The

refer

of
on

command

The

LOCATIONS AND REGISTERS

lets

you

command

DBG>DEPOSIT[/mode,...]

alter

the

format

is:

contents

memory

1locations

address-expression=datal,data,...]

With DEPOSIT, you can
enter
data
sequential locations beginning with

1in
a

10-3

one

location
or
location.

specified

several

EXAMINE

10.2.1

Depositing Numeric

AND

DEPOSIT

COMMANDS

Data

The following examples illustrate the entry of
a byte, a word, and a longword, respectively.
The

suggested

location.

method

For

00004000:
byte

data

00004000:
of

is deposited

4000

and

deposited

DBG>DEPOSIT/WORD
00004000

the

verified

by,

“XFF

4000

and

verified

by,

“XFFFF

ODOSOFFFF

data

deposited

DBG>DEPOSIT

4000

DBG>EXAMINE

.
OFFFFFFFF

00004000:

The following example
in
an
intermediate
777777717,
DBG>SET

contents

ODOS5S500AFF

data

longword

current

DBG>EXAMINE

The

the

4000

DBG>EXAMINE

word

display

value

ODO500ADO

DBG>DEPOSIT/BYTE

The

first

hexadecimal

example:

DBG>EXAMINE

The

MODE

verified

by,

“XFFFFFFFF

illustrates
byte
of
a

LONG

DBG>EXAMINE

and

the entry
longword

and verification
that
initially

of
data
contains

HEXADECIMAL

4000

00004000:
77777777
DBG>DEPOSIT/BYTE
4002

OFF

DBG>EXAMINE 4000
00004000:
77FF7777

Note

that

with

10.2.2

must

used

prefix

character.

Depositing

Instructions

This
section
instructions.
refer

alphabetic

describes
how
For
complete

Section

hexadecimal

number

that

starts

to
use
DEPOSIT
to
enter
data
as
information on depositing instructions,

5.4.3.

The storage requirements of VAX~1l MACRO instructions
vary
according
to
the
instruction type, and number and complexity (addressing mode)
of operands.
The debugger ignores the current
1length
mode
when
it

enters
instructions;
according to the number
An instruction
apostrophes.

string

instead
of bytes

entry must

DBG>DEPOSIT/INSTRUCTION

The

debugger

interprets

the
<current
address
1is incremented
required by the instruction.
be

INCRS

numeric

enclosed

'ADDL3

values

10-4

with quotation

marks

#5,R3,R4'

the

current

radix mode.

EXAMINE

AND

DEPOSIT

COMMANDS

When entering an instruction, you must verify that the length
of
the
data
string
can be accommodated by the number of bytes you intend to
overwrite.
While you cannot deposit more than there is space for, you
can
you

use
the
NOP instruction
complete the deposit of an

You must also
from

enter

a B",

For

W',

fill

bytes

instruction

L”

that

are

unoccupied

after

instructions.

when you specify

example:

value

offset

B4 (R5)
Leading zeros must be specified for hexadecimal constants
that
begin
with
alphabetic
characters, to differentiate them from symbols.
For
example:

B OF (R5)
Symbols can be included in
instructions
symbolic expressions must not contain the

10.2.3
ASCII

Depositing ASCII
character

input

being
deposited.
However,
backslash character.

Data
by quoted

string.

You

must

enclose

string
with
quotation marks or apostrophes.
This provision lets
include literal quotation marks within a string.
For example,
DBG>DEPOSIT/ASCII

DBG>DEPOSIT/ASCII

WINK
THINK

=
=

'72ZZ'
"IT'S"

DBG>DEPOSIT/ASCII

PLINK

'"1"TM!

The

ending

The

current

The

string

delimiter

must match

length

has

mode

deposited

the

beginning

effect

specified,

10-5

the

with

each

you

delimiter.
string

being

truncation

deposited.

padding.

CHAPTER
USING

THE

EVALUATE

COMMAND

The EVALUATE command lets
you
use
the
debugger
as
a
expression
analyzer, radix converter, bit field examiner,

calculator,
and literal

verifier.

11.1

USING

EVALUATE

interprets

input

expression

reduces
the
expression
to
a
value,
current modes.
The command format is:
DBG>EVALUATE [/mode] [...]

terms

and

EXPRESSION

EVALUATE

current

the

modes,

value

the

are

displayed

list,

EVALUATION

performs

according
to
with arguments
The
debugger

the

expression[,...]

The evaluations of multiple input expressions
which is ordered to match the input order.

11.2

displays

integer

arithmetic

with

all

operations

performed

the
current length mode (that is, BYTE, WORD, or LONG)
and results limited to the corresponding value
ranges.
truncates values that exceed the current length mode by

discarding most-significant~bit
EVALUATE

analyzes

language.
described

The
rules
of
in Section 4.1.

positions,

expression

precedence

and

the

prints

a message.

context

applicable

the

to VAX-1ll

current

MACRO

are

11.3
You

EVALUATING
can

use

BIT FIELDS

EVALUATE

location.

The

DBG>EVALUATE

You

display

syntax

value

the

current

contents

specified

bits

is:

<high

bit:low

bit>

specify

the bounds of a bit field by decimal integers,
regardless
the
<current
radix
mode.
Bit
positions
are
from
0
(least
significant) through 31 (most significant).
The debugger extracts the

contents

reports

the

mode

ignored.

the

bit

contents

positions,
in

the

right

current

justifies
radix

11-1

mode.

them

The

longword,

current

and

length

USING

The

following method

THE

EVALUATE

recommended

for

COMMAND

evaluating

bit

fields

location.
DBG>EXAMINE address—expression
address:
contents
DBG>EVALUATE \ <high bit:low bit>

bit-field
The

EXAMINE

value

command

represented

establishes

the

backslash

the

(\),

location's

which

contents

the

"last

value

the

value

displayed"

symbol.
This sequence is necessary because EVALUATE simply reduces
input
expression
to a value, but EXAMINE reduces an expression to
address and displays the contents of that address.

an
an

Examples:

DBG>EXAMINE

LOOP3

WATCH\LOOP3:
DBG>EVALUATE

OFFFF8FDO
<6:4>

00000005
To
of

display other bit
the
fact
that

that you

last

patterns of the same location, you can
make
use
the "current location" symbol retains the address

examined.

DBG>EXAMINE

For

example:

WATCH\LOOP3:
DBG>EVALUATE

OFFFF8FDO
<8:6>

00000007

11.4

When

EVALUATING VAX-11l

SYMBOLIC

mode

MACRO LITERALS

effect,

the

debugger

does

not

translate

literal
values
1into
their
symbolic
equivalents
for
purposes
of
displaying these values.
Thus, a displayed instruction may not appear
exactly
as
you
entered
it
1in
the
source code.
For example, the
instruction
MOVL
would

#6,0FFSET (FP)

be displayed

MOVL

46 ,W OFFDC
(FP)
| 3

where

OFFSET

represents

The EVALUATE command
same.
If you type

the

can

DBG>EVALUATE/LITERAL

literal

-24.

help you verify

that

instructions

are

the

expression

The debugger displays every literal pathname that has the value of the
expression
as
1its literal assignment.
It is then a simple matter to
scan the pathname list for the literal symbol name you wish to verify.

11-2

CHAPTER
EXCEPTION

Exception

conditions

program.

the

are

CONDITIONS

conditions

context

the

that

interrupt

debugger,

execution

exception

either forced by the debugger, or external to
the
exception
conditions
include:
the
occurrence
tracepoint, or watchpoint;
or the completion of a
step or

debugger

cause

System

and

how

effect

12.1

write

Services

the VAX-11/780

command.

chapter
describes
the
debugger's
response
exception
conditions
and
external exceptions.
It
the

your

debugger.
Forced
of
a
breakpoint,
requested
program

This

describe

condition

external

handler

Reference

Manual,

Architecture

PROCESSING

exception

routines
the

Handbook

for

conditions,

them.

VAX~1ll

for

to
both
forced
does not describe

Refer

MACRO

nor

User's

appropriate

the

does

VAX/VMS

Guide,

and

information.

EXCEPTION CONDITIONS

Exception conditions
are
processed
in
the
following
manner.
An
exception condition interrupts your program and causes VAX/VMS to pass
control to the debugger.
The debugger must
first
determine
if
the
exception
was
forced.
1If it was, the debugger reports the condition
by printing the appropriate message.
For example:
Breakpoint

exception:

[routine]

break

Tracepoint

exception:

[routine]

trace

at pc

WATCHPOINT

EXCEPTION:

WRITE

Step
If

the

exception:
debugger

returns

EXCEPTION
to
react

location.
exception

determines

BREAK
as

LOCATION

value

new

value

you

that

the

VAX/VMS

(described

Generally,
break

had-

you

exception

LOCATION

condition

unless you previously

Section

specified

will

LOCATION: INSTRUCTION

old

stepped

LOCATION

[routine]

control

have

occurs.

12.2).
a

exit

This

causes

breakpoint

from

the

1is

external,

specified
the

the

SET

debugger

exception

debugger. when

If you did not
specify
this
option,
VAX/VMS
gets
control.
What
happens
next
depends on whether you provided a condition handler for
the exception condition.
If VAX/VMS finds such a handler,
it
allows

the handler to decide the future of your program.
If a handler is not
found, or if all handlers resignaled the condition, the debugger again
acquires
control,
reports the type of exception condition, and waits
for your command.

12-1

EXCEPTION

12.2

BREAK

EXTERNAL

CONDITIONS

EXCEPTION CONDITION

Rather than have
the
debugger
return
control
to
VAX/VMS
for
an
external
exception condition, you can request that the debugger treat
all such exceptions as breakpoints.
The command is
DBG>SET

EXCEPTION

The

debugger
printing
the

BREAK

reports
the
occurrence
of
exception
conditions
error
message for the exception, and then printing

by
the

following:

exception break

at pc

LOCATION

Where LOCATION indicates where the error
occurred
The debugger then prints its prompt message.
To

cancel

this

option,

enter

DBG>CANCEL EXCEPTION

the

command

BREAK

12-2

1in

your

program.

CHAPTER
CALLING

The

debugger's

your

program

CALL

ROUTINES

command

lets

use

the

report

all

currently

13.1

CALLING

The

debugger's

your

The

CALL

where

name

that

format

DBG>CALL

routine.

the

can

The

thus

debugger

easily
You

for

statements

frames

for

symbolic

assumes

call

your

in
how
to

program.

directly

for

also

not

your

any

routine

program

actually

that

the

or
must
be

its

virtual

address.

be separated by commas;
passed
to
the
called

called

routine

(refer

conforms
the

the

VAX-11/780

details).
any

routine

debug

The

unrelated

dummy module

image.

argument

name

standard

access

can

the

and

whether

argument list
arguments
to

calling

dummy main module.

address

subroutines

routine.

routine's

procedure

purposes.

[ (argument-list)]

Architecture Handbook
You

procedures

level.
This chapter tells you
use
the
SHOW
CALLS
command

executes

space,

Arguments
in
the optional
these arguments are actual
VAX-11

call

CALLS

is:

name

command

address

call

command

call

SHOWING

ROUTINES

program's

includes

active

AND

you

directly from command
CALL command, and how to

You

lists.

need
You

your

need

not
can

program

routines

only

for

debugging

linking

provide

concerned

express

with

them

with

transfer

coding

call

the

CALL

with

command.

The debugger
interim
wuse
called

and

complete set of pseudo-register
1locations
<called
routine.
When control returns from

the

context,

The

routine

discards

13.2

creates
the

point

1interim

displays

which

registers,

the

was

called,

restores

value

returned

reports

various

the

for
the

the

debugger

called

routine.

SHOWING ACTIVE CALLS
SHOW

current

CALLS
level

DBG>SHOW

where

you

have

command
of

nested

procedure

information

calls.

The

command

concerning
format

the

is:

CALLS [decimal-integer]

the

reported

(the

specified

number

option

default)

call

of
or

requesting
requesting

levels.

The

13-1

that
that

call

the

count

all

call

debugger

can

levels
report

any

be
on

decimal

CALLING

integer
number

the

in
of

the

calls

command

Normally,

the

MODULE

range

ROUTINES

through

currently

accepted,
debugger

NAME

responds

ROUTINE

SHOWING CALLS

32767.

active,

but

AND

output
with

NAME

1If

the

call

ignored.

count exceeds
you

the

specify

RELATIVE

results.

the

following

LINE

report:

ABSOLUTE

The first line in the report refers to the current
call
1level.
The
remaining lines report all (or the requested number) of call levels in
the order of most recent call through first call.
For
VAX-1ll
MACRO,
the report presents the following information.
MODULE

NAME

Reports

the

module

which

the

call

occurred.

the

debugger's
symbol
table
does
not
include
symbol
information for the module in which the call
occurred,
the
module name remains blank and the debugger reports
the routine name by the appropriate global symbol.
ROUTINE

NAME

Reports

the
LINE

Left

the

call

routine

program

blank

for

VAX-1]1

MACRO

meaning).
Used
only
for
languages (such as FORTRAN)
of the call.
RELATIVE

Reports

the

expressed

address

under

Reports

the

regardless
If

there

CALLS

are

with

corrupted,

active

error

that

the

virtual

call

the

user

name

call

relative

The

hexadecimal,

the

1in

which

13-2

has

(statement)
line number

the

symbol

debugger-displays

regardless

call

the

hexadecimal,

mode.

debugger

indicates
has

is,

NAME.

address.
of the

This

program

(that

1line-oriented
to identify the

current radix

frames,

message.

the

ROUTINE

the relative address
current radix mode.
ABSOLUTE

section

occurred.

that

terminated.

responds

SHOW

the

has

been

stack

CHAPTER
PROCESSOR

This

chapter

Processor

support

PSL,

your

see

14.1

describes

Status

debugger
PSL:

where

"n"

EXEC,

You

current

You

word

contents

current
how

the

CURMOD

PREMOD

IPL

mode

The

interrupt

value,

priority

contents

the

DBG>EXAMINE/NOSYMBOLIC/HEXADECIMAL

PSL

SUPR,

alter

the

can

PROCESSOR STATUS
PSL's

low-order

cannot

alter

allocated

CMP

current

regardless

you

Status

Longword

level,

Mode

nnnnnhn

1lv,

1is

expressed

displayed
as:

KERN,

USER.

ALTERING THE

(PSW),

the

your

PSL

hexadecimal

value

LONGWORD

word, which is the processor
status
privileges allocated to your account.

following

conditions,

regardless

compatibility mode

interrupt

stack

current

PREMOD

previous mode

compute

the

value

mode

DBG>EVALUATE /HEXADECIMAL

entered

:in

the

PSL

expression

where "expréssion" is the sum of key numbers selected from Table
reentered

change.

the

account.

CURMOD

according

of' the

with:

FPD

the

PSL

contents

description

Processor

its

LONGWORD

contents

alter

Handbook.

1F.

However,

detailed

through

can

(PSL)

CMP

hexadecimal

privileges

You

responds

can display
specifying:

14.2

For

Architecture

DBG>EXAMINE/SYMBOLIC

the
and

DISPLAYING
THE PROCESSOR STATUS

To display the
(PSL), type:

The

(PSL),

debugging.

VAX-11/780

LONGWORD

to display

Longword

program

the

how

STATUS

the

they

conditions

were

that

displayed)

and

14-1

must

maintained

the wconditions

that

(that

you

wish

14-1
is,

PROCESSOR STATUS LONGWORD

replace

the

current

PSL

contents,

DBG>DEPOSIT/HEXADECIMAL

PSL =

(PSL)

type:

value

Table 14-1
PSL Alteration Values

Bit

Key

Key Number

Description

(Hex)

CMP

80000000

Compatibility mode

40000000

Trace

Pending

MBZ

(Must

Part Done

Zero)

FPD

First

Interrupt

25
24

CURMOD

2000000
1000000

23
22

PREMOD

800000
400000

MBZ

IPL

100000

Stack

Current mode:
2000000=supr,

3000000=user,
1000000=exec, O=kern

Previous mode:
0C00000=user
800000=supr, 400000=exec, O=kern
(Must

Zero)

Interrupt priority level: 0 - 1F.
Enter the displayed or desired
priority level in hexadecimal
and append 0000 to the value.

80000

40000

20000

Remember to precede the leftmost
character, if an alphabetic,
with a zero.

10000-+

EXAMPLE:

0C0000

(must

zero)

(must

zero)

(must

zero)

(must

zero)

(must

zero)

(must

zero)

(must

zero)

(must

zero)

Decimal

overflow

for

trap

level

enable

(continued

14-2

12,

next page)

PROCESSOR

STATUS

LONGWORD

(PSL)

Table 14~1 (Cont.)
PSL Alteration Values

Bit

Key

Key Number

Description

(Hex)

Floating

Integer

Trace

Negative

Zero

Overflow

Carry

14-3

underflow
overflow

trap

trap enable

trap

enable

condition

code

condition

code

CHAPTER 15
DEBUGGER

The

debugger
e

provides

four

Informational

MESSAGES

classes

of messages:

informational

messages

are

provided

let

you

know
the status of the debugger or your program.
While not,
strictly speaking, error messages, they may indicate erroneous
command input.
For example, the message
3DEBUG-I-NOSUCHBPT,
means

you
Informational

such

breakpoint

have
specified
a
messages are prefixed:

breakpoint

incorrectly.

3¥DEBUG-I-

Warning level
of

warning
errors

unaffected

after

messages are displayed for
detected.
Your debugging
a warning

respecify
the erroneous
are prefixed:

message,

command

the least
severe
session continues

providing

you

operand.

Warning messages

chance

3sDEBUG~-W®

Error

error

condition

messages

that

indicate

prevents
Software

should submit a
receive
a
severe
error
errors are prefixed:

that

the

debugger

has

detected

it from continuing the session.
Performance
Report
(SPR)
if

message

from

the

debugger.

You
vyou

Severe

$DEBUG~E®

Fatal

fatal

debugger.

errors

are

Following

appropriate message

and

errors

fatal
returns

that

error,

directly

the debugger

affect

prints

control

the

VAX/VMS

Command

receive

fatal

error

message

Interpreter.

You

should

from

the

submit

debugger.

SPR

Fatal

you

error

the

messages

are

prefixed:

$DEBUG~F-~
Each

message

within

listed

the

following

subsection.

15-1

subsections,

alphabetically

DEBUGGER MESSAGES

15.1

INFORMATIONAL MESSAGES

DBGBUG, DEBUG coding error,

(PREFIX:$DEBUG-I-)

please report no.

‘'number'

If you receive this message, please submit
an
SPR
stating
the
conditions
that existed when the message appeared, including the
number

EXITSTATUS,

specified

the message.

'xxx'

This message is displayed to indicate that
the
user
image
has
exited,
with
the
status
specified
by xxx.
The string xxx is
produced by the system's error message facility.
INITIAL,

language is

‘'aaa',

scope and module set to

'name'

You usually receive this message when you initiate the
debugger,
to inform you of the debugger's settings for language, scope, and
initial symbol table contents (for local symbols).
LONDST,

too many modules - some

ignored

This message indicates that when the debugger was initialized,
found
more
modules
1in the image than it could accommodate;

determine which

modules

were

included,

use

it
to
the
SHOW
MODULE
relink the image,

command.
If
crucial
modules
were
omitted,
specifying those modules before modules not needed for

debugging

purposes.

MODNOTADD,

no space to add module

'name'

A SET MODULE command has failed because
of
insufficient
symbol
To make room, use CANCEL MODULE to remove modules
space.
table
with symbols that are no longer needed, then retry the SET MODULE
You can use SHOW MODULE to see how much space is needed
command.
and

available.

NOBREAKS,

no breakpoints are set

This is the response to SHOW BREAK when no breakpoints are set.

some or all global symbols not accessible

NOGLOBALS,

This message indicates an error or overflow in the global
Reduce the number of global symbols.
table of the image.
NOLOCALS,

image does not contain local

symbol

symbols

This message indicates that when the debugger was initiated there

Recompile
were no local symbols to be put into its symbol table.
or reassemble, specifying DEBUG or TRACEBACK, and then relink the
image.

NOSUCHBPT,

no such breakpoint

This is the response to CANCEL BREAK address-expression
breakpoint is set at the specified address.
NOSUCHTPT,

when

no such tracepoint

This is the response to CANCEL TRACE address-expression
is set at the specified address.

tracepoint

DEBUGGER MESSAGES

NOSUCHWPT,

This

such

the

response

watchpoint
NOTALLSYM,

The

cannot

Use

NOTRACES,

the

MODULE

could

for

SET

set

the

initialize

debugger

table

watchpoint

not

symbols

put

first
to

CANCEL WATCH address—-expression
specified address.

symbol

module

initialize

tracepoints

are

for

set,

the

image

symbol

opcode

This

NUMTRUNC,

The

watchpoints

the

response

number

The
the

truncated

mode,

cannot

SHOW WATCH

numeric

could

The

string

tracing

scope

have

pathname
module

not

1is

name

BADSTEP,
A

STEP

cannot

set,

watchpoints

are

set.

that exceeded the
current
accommodated
in the specified

'xxx'

an ASCII

reached

SET

SCOPE

MACRO)

access

not

valid

opcode

module

reached

entry

otherwise

that

exceeded

inappropriate

for

the
the

unknown

the

decode

was

(PREFIX:3%DEBUG-W-)

module

string

specified.

was

with

Specify

Check

end

(VAX-11

cannot

when no

to ignore the OVER mode when
it
An INTO step will be performed.

unrecognized

not

command

debugger.

'xxx'

must

indicated

executed.

are

entry

mode,

MESSAGES

specified

BADSTARTPC,

The

which

opcode

specified

BADSCP,

You

WARNING

BADOPCODE,

You

over

truncated

length

context

tracepoints

truncated

debugger

current

15.2

step

debugger was forced
location indicated.

STGTRUNC,

symbol
module).

set

context.

STEPINTO,

the

default

truncated

debugger

length

are

1into

(the

table.

This is the response to SHOW TRACE when no
and no opcode tracing is in effect.
NOWATCHES,

modules

information

the

default

when

command,

routine

start

readable
start

but

name

address,

debugger.

the

SCOPE

symbol type
of
the
entry must end with a

(VAX-11

FORTRAN

IV-PLUS).

'xxx'

therefore

can

not

the

location.

instruction

that

the

routine

routine.

instruction

sure

your

15-3

address

'xxx'

that

not

image

has

not

recognized

been

overwritten.

DEBUGGER MESSAGES

cannot watch protected address

BADWATCH,

'xxx'

You have requested a watchpoint for a protected location.
bit range out of limits

BITRANGE,

You have specified a bit range in an EVALUATE command that exceeds the
The valid range is <31:0>,
range of bits that can be evaluated.
Only numeric characters are valid in a bit range.
decimal.
is too far for branch operand

BRTOOFAR, destination 'xxx'
target location.

DIVBYZERO,

instruction

branch

You deposited a

unreachable

contained

that

attempted to divide by zero

attempt

An expression can not be evaluated because it contains an
use

a divisor

equal

zero.

ENDWITHGO, cannot imbed GO, STEP, or CALL in command sequence

A command sequence contained a GO, STEP, or CALL that was not the last
Commands up to, but not including, the GO,
in the sequence.
command
The rest of the sequence is ignored.
STEP, or CALL are executed.
invalid

EXARANGE,

range of addresses

You specified the address range in the wrong order.
is:

The correct order

low bound:high bound.

EXPSTKOVR,

expression exceeds maximum nesting level

An expression containing more than 20 nesting levels was encountered.
this operation only valid on integers

INTEGER,

computation

You attempted to perform

that

accepts

integer

only

values.

INVARRDSC,

invalid array descriptor

If this message
The debugger detected an invalid array descriptor.
than an incorrect specification in a
occurs for any reason other
command you entered to the debugger, please submit an SPR.
INVCHAR,

invalid character

current

A character you entered in a command is not acceptable in the
context.

INVDIM,

subscript error, was declared DIMENSION

A subscript was specified
statement

INVNUMBER,

invalid numeric string

'nn'

unrecognized operator

expression

recognize,

according

the

DIMENSION

the FORTRAN program.

The number specified as
INVOPR,

1incorrectly,

'xx'

contained

'nn'

is invalid in the current context.
in expression

character

in place of a valid operator.

15-4

that

the

debugger

did

not

DEBUGGER MESSAGES

INVPATH,

improperly

terminated

pathname

beginning

improperly-formatted
pathname
has
followed
by
\
must begin a pathname.
not constitute a valid symbol.

LASTCHANCE,
A

stack

user-program

error

mechanism

MAXDIMSN,

maximum

This

used

exception

fail.

handlers

has

The

caused

probable

number

been
The

lost,
the

debugger

You

multiple

entered

characters
NEEDMORE,

The

subscripts

'nn'

command

The

NOACCESSW,

was

read

not
'loc'.

you

right

have

angle

virtual

the

addr='BNEQ

active

call

Response

CALLS

SHOW

Your

decode

is produced
mode,
and

instruction.

reference was

have

made

1is
the

with

two

operator

address

contained

complete

'loc'

privileges

always

address

access

to
the
hexadecimal.

address

'loc'

privileges

the

address

expression

left

angle

branch-type

bracket

that

has

operand

which

did

field.

not

For

contain

example,

RO'.

valid

you

cannot

active

frames
command

image

corrupted.

cannot

virtual

given

reference

termination.

'loc'

destination

frames.

access

contains

requires

NOCALLS,

VAX-11

write

array

declared

expression

before

point

handling

stack.

line

the

instruction was

DEPosit/Instruction

instruction

bracket.

instruction

This message

command

brackets

entered

angle

for

NODECODE,

the

contains

terminated
to

access

does

branch-type

call

access

write

expression

operand

end

valid

unmatched

NOBRANCH,

that

does not have
read
'loc'.
The value of

The debugger
specified as

expression

was

The debugger
specified as

operators

array was

stack

condition

overwritten

succession.

1line

NOACCESSR,

matching

successive

unexpected

command.

NOANGLE,

VAX/VMS

indicated number of dimensions (nn), but
either too few or too many subscripts.
MULTOPR,

re-~initializing

cause

expression.

'xxx'

encountered:
"symbol"
characters following \ do

FORTRAN-only message produced when

with

may

when

have

the

debugger

exited,

the

locates

stack

may

have

been

instruction

when
you
specify
the
indicated
byte

15-5

EXAMINE
command
in
sequence is not a valid

DEBUGGER MESSAGES

NODELIMTR, missing or invalid instruction operand delimiter

the
at
An instruction has been given that contains a syntax error
point where one operand has been terminated and another is supposed to
For example, MOVL RO Rl (you forgot the ',' as in RO,R1l).
begin.
is missing end delimiter x

NOEND, string beginning with 'xxx'

end with either
INSTRUCTION string must begin and
An ASCII or
the ending delimiter is not encountered
If
apostrophes or quotes.
The message dgives
before the string ends, this message is produced.
find (shown as x,
to
expected
the debugger
the ending delimiter
entered.
you
string
the
of
characters
10
first
the
and
above),
NOINSTRAN, cannot translate opcode at location 'loc'

The contents of the location indicated as 'loc' are not a recognizable
The value of 'loc' is always hexadecimal.
opcode.
has no %label

routine 'name'

NOLABEL,

'label'

You attempted to refer to a label that does not exist in the indicated
routine.

NOLINE,

routine

has no %$line

'name'

'line'

The indicated line number does not exist in the subroutine specified
This message is also
Consult the compiler 1listing.
'name'.
as
not
but does
exists,
1line number
indicated
produced when the
correspond to executable code. An example of this is the line number
of

FORMAT

statement.

NOLITERAL, no literal translation exists for

not

The value indicated as 'xxx' has
equivalent of type literal

NOOPRND, missing operand

(absolute).

been

'=xxx'

assigned

to
:

symbolic

explicit

in expression

One or more operands have been omitted from an expression.

NOSUCHLAB, no scope exists to look up %label

You referenced the indicated label without

'label’

implicit

1If you specifically indicated that the scope was
associated pathname.
to be ignored, or scope was <null>, and a PC-implied scope cannot be

derived,

this message

NOSUCHLAN,

is produced.

'name'

language

is unknown

The debugger does not recognize the language specified.
NOSUCHLIN, no scope exists to look up %line

'line'

If
You referenced the indicated line without an associated pathname.
specifically indicated that the scope was to be ignored, or scope
you

was <null>, and a PC-implied scope cannot be derived, this message
produced.

NOSUCHMODU, module

'name'

The specified module

does not exist

is not part of the image.

15-6

DEBUGGER MESSAGES

NOSYMBOL,

The

specified

NOTDONE,
You

The

symbol

cannot

not

yet

not

exist

located

supported

tried

'xxx'
to

but

OPSYNTAX,

SET

does

not

the

not

have

For

example,

specified

PARSEERR,

MOVL

PARSTKOVR,

invalid

command

syntax

parsing

this

parse

operand

that is not
requested.

LANGUAGE,

implement

debugger's

symbol

table.

yet

implemented.

level

which

the

fully-supported

debugger

knows

language.

error

operand

within

instruction.

(RO],Rl.

internal

receive

implemented

indicated

yet

instruction

You

you

the

feature

attempted to use a debugger feature
message indicates which feature was

about,

does

symbol

'xxx'

NOTIMPLAN,
You

'name'

error

message,

stack

please

overflow,

submit

simplify

SPR.

expression

The expression you entered contains too many levels of angle
brackets
Cenode
Reenter
the expression, reducing the number of angle bracket
levels.
If this message recurs frequently, submit an SPR.
PATHTLONG,
You

entered

REDEFREG,

You

too

qualifiers

pathname

attempted

DEFINE

name

use

that

name

comprised

already

than

elements.

defined

name

symbol

defined

use

only.

the

command.

RESOPCODE,

The

many

opcode

operand

SUBSTRING,

you

'xxx'

specified

invalid

reserved

substring

reserved

(a:b),

for

was

DIGITAL's

declared

CHARACTER*

You specified a
string declared

substring that is
not
entirely
within
in a FORTRAN CHARACTER declaration.

SYNTAX,

syntax

command

Your command
indicated by

contains
'xxx'.

error

incorrect

near

syntax

15-7

NN
character

'xxx'

point

1in

the

1line

DEBUGGER MESSAGES

15.3

ERROR MESSAGES

(PREFIX:$%DEBUG-E-)

The

following error messages indicate that the debugger is
continue
execution
of
your
program.
The image exits,
returns

you

the VAX/VMS

receive

DBGERR,

any of

internal

Command

Interpreter.

these messages,

DEBUG

coding

internal

DEBUG

coding

error;

FRERANGE,

storage

package

range

error

storage

package

INVDSTREC,

invalid

NOFREE,

free

storage

cannot

build

symbol

table

NORSTBLD,

RSTERR,

15.4

The

error

FATAL

DST

size

submit

SPR.

error

DEBUGBUG,

FRESIZE,

please

unable
to
and control

please

report

no.

'number'

error

record
available

ERROR MESSAGES

table

(PREFIX:$DEBUG-F-)

following messages indicate
errors
fatal
to
execution
Control returns to the VAX/VMS Command Interpreter.

debugger.

receive

any of

these messages,

NOWBPT,

cannot

insert

please

submit

breakpoint

NOWOPCO,

cannot

replace

NOWPROT,

cannot

set

breakpoint

with

protection

15-8

opcode

SPR.

of
If

the
you

APPENDIX

SUMMARY

COMMAND

This appendix summarizes the commands that can be
wused
1in
debugging
VAX~-11 MACRO programs.
Refer to the appropriate language user's guide
for information regarding the use of the debugger for programs written
in

The

other

languages.

summary presents the commands

Brackets

([...]), where

they are not part of

See SET MODE

the

shown,

syntax.

in alphabetical order.

enclose

for entry/display mode

optional

command

elements;

keywords.

With
the
exception
of
ASCII
character
input,
the
debugger
uppercase (that is, the
to
input
lowercase
automatically converts
debugger is not sensitive to the case of an input character).

the
"Address-expression" in the command syntax representations can be
(see SET SCOPE) of a local or global symbol in your program,
pathname

this debugging
that you defined during
a numeric value, a symbol
a debugger special character, or an expression that combines
session,
any of

these

elements.

image

The term "program" means an executable

information).

In VAX-11 MACRO,

for

entries

are:

the radix indicators

(for

hexadecimal),

(refer

Linker Reference Manual for additional

numeric

VAX-11

the

address

data

"D (for decimal), and "0 (for

octal).

The debugger supports command line continuation.
A command
1line
can
contain
up
to
approximately
500
characters, including nonprinting
characters.
You indicate continuation with the hyphen (-) as the last
character
prior
to
the
carriage
return.
The debugger indicates a
continued line by displaying
an
underline
character
as
the
first
character

the

line

rather

than

the

DBG>

prompt.

CTRL/"x" refers to the simultaneous typing of the
CTRL
key
and
the
respective
character
key,
that is, C, Y, or Z (refer to the VAX/VMS

Command Language User's Guide for information on the complete list
CTRL functions).
CTRL/"x" echoes at the terminal as “x.

With the exception of the CTRL functions, you
lines with a
>CALL

name

carriage

must

end

all

command

return.

[ (argument,...)]

address
virtual
1its
by
or
name
Call routine by its symbolic
not valid) with optional argument list.
1is
expression
(address

An argument list must be enclosed

A-1

by parentheses.

COMMAND SUMMARY

>CANCEL

ALL

Cancel

all

breakpoints,

entry/display
command
symbol

modes.

at debugger

MODULE

command,

debugging
BREAK

>CANCEL

BREAK/ALL

breakpoint
breakpoints.

>CANCEL

EXCEPTION
the

any

SCOPE

The

symbols

current

through

that

you

language

use

defined

not

the

SET

during

this

changed.

set

that

your

specified

address,

cancel

all

BREAK

request

exception

initial

current

>CANCEL

MODULE

>CANCEL

MODULE/ALL

Purge

program

stop,

condition.

entry/display modes.
language.

breakpoint,

Command

does

not

change

module-name-~list

symbolic

information

the
debugger's
information from
space

associated

with

the

named

modules

symbol
table,
or
purge
all
module
the symbol table.
The typical use
is

from

related
to
make

available for local symbols associated with another module
modules (see SET MODULE).
Global
symbols
and
any
symbols

defined
>CANCEL

any

MODE

Restore

and
user-set
entry/display modes.
This

address-expression

Cancel

for

initialization or

session).

>CANCEL

Cancel

watchpoints,

initial

does not change the current contents
of
the
debugger's
table
(that
1is,
those
symbols
acquired
from program

modules

>CANCEL

tracepoints,

Restore

during

this debugging

session

are

not

affected.

SCOPE

Enter

null

contents

SCOPE

scope)
.
>CANCEL

TRACE

>CANCEL

TRACE/CALL

>CANCEL

TRACE/BRANCH

>CANCEL

TRACE/ALL

Cancel

(that

is,

delete

the

previously

set

address-~expression

tracepoint

tracing
at
branch-type

tracing.
>CANCEL

WATCH

>CANCEL

WATCH/ALL

set at specified
address,
cancel
all
opcode
call-type instructions, cancel all opcode tracing at
instructions, or cancel all
tracepoints
and
opcode

address—~expression

Cancel
watchpoint
watchpoints.

set

specified

address,

cancel

all

COMMAND

SUMMARY

CTRL/C

Has same effect, and echoes at terminal, as CTRL/Y (see below) if
your
program does not include an exception condition handler for
CTRL/C.

CTRL/Y
Interrupt

$).

the

debugger

the VAX/VMS

command

executing

interpreter

program

(signaled

and

transfer

by the

control

system prompt

Type
DEBUG

after

the

system

prompt

return

control

the

debugger.

Type

CONTINUE

after the system prompt to
return
control
to
the
interrupted
program.
Typing any VAX/VMS command other than DEBUG or CONTINUE
will probably force the premature exit of your program.
You
can
use
CTRL/Y
to
1interrupt
a
1looping program.
To determine the
point at which you interrupted your program, type

DBG>EXAMINE/INSTRUCTION

@PC

CTRL/Z
Same

and
>DEFINE

result as EXIT;
transfer control

that is, terminate
the
debugging
to the VAX/VMS command interpreter.

session

symbol-name=valuel[,symbol-name=value...]

Equate name(s) of
use
during
this

name=value list with
associated
value(s)
for
debugging session.
The debugger searches these
first whenever it requires a definition
for
a
symbolic

symbols
entry,
and
location.

whenever

>DEPOSIT[/mode[...]]

requires

symbolic

name

report

address-—expression=datal,data,...]

Enter data specified
in
data
1list
beginning with the specified address.
>EVALUATE [/mode[...]]

1in

sequence

1locations

expression|,...]

transform
input
(which
can
be
arithmetic
expression,
ASCII
string,
VAX-1l1l
MACRO
instruction, symbol, or numeric value) to
associated value(s) and display result(s).
Can be used
as
desk
calculator,
radix
displays result(s)
>EXAMINE[/mode[...]]

converter, symbol verifier, etc.
The debugger
in the order in which you specified the input.

address

[:address][,address|[:address]...]

Display current contents of
specified
address(es).
The
colon
signifies range;
that is, display contents of addresses from low
address through high address.
>EXIT

Terminate debugging session
command interpreter.

and

transfer

control

the

VAX/VMS

COMMAND SUMMARY

>GO[address-expression]
Start or continue program execution.
First GO command without an
address
starts the program at its transfer address.
GO commands
thereafter continue execution from
a
stopped
point
(as
at
a
breakpoint or watchpoint, or because of an exception condition).
An

address

entry

contents;
Once

you

have

restart

behavior

>SET BREAK

replaces

started
the

Establish

breakpoint

[DO

any

counter

(PC)

the

new

location.

not

attempt

other

address.

Program

restarted.

specified

list)]

address

the

(the

breakpoint

instruction

beginning

stops

with

is executed).

The debugger executes commands
in
DO
whenever
your program stops because of
Parentheses

are required as
must be separated

commands

program

from

should

(command

before

"address-expression”

you

address

unpredictable when

program

current

continues

program,

transfer

address-expression

your

the

execution starts

sequence

command
format
specified breakpoint.

the

command
1list
by semicolons.

delimiters.
Any complete

Multiple
debugger

command

can be used in this context, including GO, STEP, or CALL.
If GO, STEP, or CALL is specified, it must be the last command in
the sequence.

You

can

specify

SET
Your

the

"after"

program

range

does

through

each

time
can

not

debugger

your

program

EXCEPTION

the

LANGUAGE

because

the

breakpoint.

address-expression

until

encounters

temporary

first

defer

the

breakpoint

the

"n"th

(that

pass

through

1is,

the

an interation, where "n" is within
the
Thereafter, the breakpoint takes effect

(or

it.

one

time)

breakpoint

by:

address-expression

automatically

cancels

the

breakpoint

time

the

breakpoint

report

the

current

after

stops

encountered.

BREAK

program

and

if
an
exception
debugger command.
>SET

as in
32767.

BREAK/AFTER:0

The

Stop

stop

ignored)

the debugger

specify

SET

>SET

BREAK/AFTER:decimal-integer

the
breakpoint
1is
specified location,

You

option

condition

occurs

program

that was

counter

not

contents

initiated

by a

language-name

Let

the

debugger

of
are

the
not

specified
1language.
valid in the specified

recognizes
the
contains symbol

interpret

language

input

information.

the

and

display

output

the

syntax

The debugger rejects commands that
syntax.
The
debugger
initially

first module

in your

program

that

COMMAND SUMMARY

>SET MODE mode-keyword[,mode~keyword...]
Allow or

and

inhibit the entry

display

data

specified

formats.
(refer
The following list describes the function of each keyword
SET SCOPE for additional information regarding the use of the
to
symbol search control keywords, [NO]JGLOBAL and [NO]SCOPE):

ASCII

Interpret/display data as ASCII characters.

BYTE

Interpret/display data in byte lengths.

DECIMAL

Interpret/display data in decimal radix.

GLOBAL

Use symbolic entry as first pathname in search.

HEXADECIMAL

Interpret/display data in hexadecimal radix.

INSTRUCTION

Interpret/display VAX-11 MACRO instructions.

LONG

Interpret/display data in longword lengths.

NOASCII

Inhibit entry/display of ASCII characters.

NOGLOBAL

Use symbolic entry as last pathname in search.

NOINSTRUCTION

Inhibit

NOSCOPE

Inhibit SCOPE's contribution to pathname.

NOSYMBOLIC

Inhibit display of symbolic addresses.

OCTAL

Interpret/display data in octal radix.

SCOPE

Add SCOPE's contents to entry to form pathname.

SYMBOLIC

Display symbolic addresses.

WORD

Interpret/display data in word lengths.

The

debugger's

NOASCII,

VAX-~-11

entry/display

MACRO

instructions.

initial

NOGLOBAL,

modes

SYMBOLIC,

are:

HEXADECIMAL, and LONG.

NOINSTRUCTION,

SCOPE is initialized

to contain the name of the first module in your program.

DEPOSIT,
commands
You can also enter the mode keywords with the
override the current associated mode
to
EXAMINE
and
EVALUATE,
must
slash
A
type).
or
search,
(radix, data length, symbol
precede each mode keyword entered after these command verbs.

command-verb/keyword/keyword
>SET

...

MODULE module-name-~list
>SET MODULE/ALL

Enter local symbols and program section names associated with the

symbol table, or enter
debugger's
the
1in
list
program~module
debugger
The
information from all modules in the symbol table.

symbols unless their associated module
interpret 1local
cannot
SHOW MODULE
the
by
names appear in the status report produced

command with a "yes"

indication.

COMMAND

>SET

SCOPE

SUMMARY

module-name

Retain module~name entry as SCOPE's contribution to creation of a
pathname
under control of the debugger's symbol search rules.
A
pathname completely and unambiguously
identifies
a
symbol
and
points
to
that
symbol's
definition
(that is, its translation
value) .
For
VAX-11
MACRO,
a
pathname
is
symbol-name
or
module~name\symbol-name.
The

debugger
only

fails

locate

search
>SET

evaluates

appears

STEP

failure

keyword

Establish

keywords

a match
and

the

default
are:

LINE

step

increment

INTO ~

allow

stepping

OVER

step over

SYSTEM

NOSYSTEM

The

allow

and

>SET

TRACE

>SET

TRACE/CALL

>SET

TRACE/BRANCH

increment

which

located

pathname,

for

the

symbolic
the

entry

entry.

debugger

reports

for

line

VAX-11l

(for

stepping

system

conditions

MACRO

call

valid

instruction.

languages).

transparent).

space.

system

for

command.

routine.

(make

into

STEP

line-oriented

called

routine
into

the

space.

VAX-11

MACRO

are:

OVER.

INSTRUCTION,

address—expression

Set tracepoint at specified address, or specify
tracing
of
call-type
instructions,
or
all branch-type instructions.

tracepoint,
contents
>SET

WATCH

Report

the

name.

through

stepping

inhibit

was

...]

called

initialization

NOSYSTEM,

for

conditions

step

expression

symbol

[,keyword

INSTRUCTION

definition

the debugger

and

then

reports

continues

the

program

current

execution

program

all
At

counter

automatically.

address—expression

the

contents

the

specified

location(s)

The locations watched can be individual addresses
number
of
bytes specified by the length mode in

watchpoint was

set),

entire

program

name)
.

The debugger stops the program
both
the
previous
contents
location.

(as
and

the

modified.

(including
effect when

the
the

(specified

section

breakpoint)
current

are

and

contents

reports
of

the

COMMAND

>SHOW

BREAK

Report the locations of
information
associated
and "after" options.
>SHOW

SUMMARY

CALLS
Report

current
breakpoints
and
any
with
them, such as DO command

relevant
sequences

[n]
current

call

level

and

the

hierarchy

call

1levels

that

preceded it (that is, trace your program's call history).
If "n"
(a decimal integer) is expressed, the debugger reports
"n"
call
levels

back

32767).

from

"n"

the

current

level

omitted,

all

("n"

has

the

preceding

range

call

through

1levels

are

reported.
>SHOW

MODE

Report
>SHOW

the

current entry/display modes

(see

SET

MODE).

MODULE

List

program modules by
name,
indicate
whether
or
not
their
associated
1local
symbol
data
exists
in the debugger's symbol
table (by yes or no), and indicate the approximate space required
for

the

space

program
>SHOW

entry

the

creation of

The

not

reported

this

current

contents

SCOPE.

data.

debugger

List

has

status

also

the

amount

knowledge

any

report.

that
a

SCOPE

makes

null

effective

string

(<null>)

contribution

the

pathname.

STEP

Report

current

default

conditions

for

STEP

(see

SET

STEP).

tracepoints,

that

TRACE

Report the
tracing is
>SHOW

symbol

unused.

module

indicates

>SHOW

each module's

SCOPE

Report

>SHOW

currently

locations
in effect.

current

opcode

WATCH

Report

the

locations

bytes monitored
>STEP[/keyword]

current

watchpoints

and

the

number

each watchpoint.

[decimal~integer]

Stop the program after executing the next instruction
only
(the
default condition if you do not specify an instruction count), or
after executing the next "n" instructions, where "n" is a decimal
integer from 2 through 32767.
The following keywords can either
verb
(STEP/keyword)
or
be
set

be used after the STEP
command
with
the
SET STEP command to

establish the default conditions
for STEP.
displays the current defaults.

The

SHOW

STEP

command

COMMAND SUMMARY

The

keywords

have

the

SYSTEM/NOSYSTEM ~
INTO/OVER -

step

allow or
into or

LINE/INSTRUCTION ~
The

following

inhibit steps

over

a called

step by lines or

initialized defaults

INSTRUCTION,

relationships:

NOSYSTEM,

for VAX-11l

OVER.

into

system

routine.

instructions.

MACRO

are:

space.

INDEX

A
Address expressions, 4-4
AFTER:n option, 7-4
Angle brackets, 4-3
Apostrophes, 4-10
Arithmetic expressions, 4-1
Arithmetic operator s, 4 -1
ASCII' 10-3’ 10-5
ASCII mOde, 5_4, 5-5, 5—
Asterisk, 4-3
At sign, 4-3, 4-6

Context modes, 5-4
Continuation, line, 4-11
Controlling execution, 3-1
Control of program execution,
Current location, 4-4, 4-5

1-3

D
Data display,

5-1

Data entry, 5-1
DECIMAL mode, 5-9

DEFINE command, 4-8, 6-2
Defining symbols, 6-2
Delimiting characters, 4-6
Backslash, 4-5, 4-8
Bit fields, 4-10
Bit fields, evaluating, 11-1
Break on exception, 12-2
Breakpoints, 7-1
CANCEL, 7-4
SET, 7-3
SHOW, 7-4
temporary, 7-4

4-9,

2-1,

4-3

sequence,

4-9,

7-3

session,

1-3,

2-4

5-1
2-3

Equal sign, 4-8
EVALUATE command, 4-10, 11-1
Evaluating arithmetic expressions,

4-5
4-10

4-1

A-1l

operator,

10-3

Entry, data,
Entry modes,

CTRL/C, A-3
CTRL/Y, A-3
CTRL/Z, A-3
DEFINE, 4-8, 6-2, A-3
DEPOSIT’ 4—8' 10—1' A-3
EVALUATE, 4-10, 11-1, A-3
EXAMINE, 4_10, 10-1' A-3
EXIT' 2-4, A-3
GO, 3-1’ 7-2' 9—2' A-4
SET' A—4
SHOW, A-7
STEP, 3-2, 7-2, 9-2, A-7
Contents

as ASCII,

Display modes, 2-3
Division operator,

Ending a debugging

Characters,
delimiting, 4-6
special, 4-1

Commands, 1-3,
CALL, 13-1
CANCEL, A-2

10-1

13-1

Calling routines, 1 3~-1
Calls, showing, 13-1
Changing memory, 10 -1
Changing modes, 5-2

Circumflex,
Colon, 4-6,
Comma, 4-9

4-8,

Depositing,
ASCII data, 10-5
instructions, 10-4
numeric data, 10-4
Display, data, 5-1
Displaying memory, 10-1

DO command
DOt, 4-5

C
CALL command,

DEPOSIT command,

4-4,

4-6

Evaluating,
bit fields, 1l1-1
expressions, 1-3, 1l1l-1
literals, 5-8, 11-2
EXAMINE command, 4-10, 10-1
Examining,
instructions, 10-3
locations, 1-2, 10-1
numeric data, 10-2
registers, 10-1
Exception conditions, 12-1
break on, 12-2
Execution, controlling, 3-1
Expressions,
address, 4-4
arithmetic, 4-1
evaluating, 1-2, 1ll-1

Index-1

INDEX

(Cont.)

Modes (Cont.),
DECIMAL,

GLOBAL mode, 5-10
GO command, 3-1, 7-2,

9-2

GLOBAL, 5-10
HEXADECIMAL,

5-=10

INSTRUCTION, 5-4, 5-6

HEXADECIMAL mode,
Hyphen, 4-11

keywords, 4-7, 5-1
length, 4-1, 5-10
OCTAL, 5-10
radix, 5-9
reporting, 5-3

5-10

restoring, 5-3
SCOPE,

Initiating the debugger, 2-1
Input strings, 4-10
INSTRUCTION mode, 5-4, 5-6
Instructions,
depositing, 10-4

examining,

5-9

display, 2-3
entry, 2-3

5-11

SYMBOLIC, 5-4, 5-6
Modifying locations,
MODULE commands,
CANCEL, 6-7
SET, 6-6

SHOW,

10-3

1-2,

10-3

6-6

Multiplication operator,

4-3

K
Keywords,

mode,

5-1

Numeric data,
depositing,

L
Language setting,

2-3

Last value displayed, 4-5

Length mode, 4-1
LENGTH mode, 5-10
Line continuation, 4-11
Literals, evaluating, 5-8,
Local symbols, 1-5, 6-5
Location,
current,

()
OCTAL mode,

11-2

5-10
Opcode tracing, 1-2,
Operators,
arithmetic, 4-1
contents, 4-4, 4-6

4-4

division,

last addressed,
last displayed,
previous, 4-5

4-4
4-4

15-8

fatal,

15-8

ASCII,

Pathname,
ermangnt

Plus

ggg?Egizs 3
SHOW,

5-8

informational,
warning, 15-3
Minus sign, 4-2
MODE commands,
_

15-2

5-4,

4-8,

symbols,

5-10,

6=1,

6-2

4-2

4-3
Previous location, 4-5
Processor Status Longword,
Program control, 1-3
PSL, 14-1

14-1

Purging the symbol table, 6=7
()

5-8

changing, 5-=2
context, 5-4

sign,

1-5,

Precedence operators,

5-3

Modes, 5-1

’

P
evaluating,

15-1

error,

4-3

M
essages,

8-1

4-3

precedence,
radix, 4-4
range, 4-6
shift,

fiACRO literals,

10-4

examining, 10-2

Qualifiers, 2-2
Quotation marks,
Index-2

4-10

6-9

INDEX

R
Radix modes,

Range

Symbol (Cont.),

into values, 6-7
6-5
permanent, 6=2

5-9

Radix operators,
Range,

(Cont.)

local,

4-4

10-2
operator,

4-6

References, symbolic, 1-4
Restrictions, watchpoint,

purging,

6-7

setting,

2-3

table, 1-4, 6-6
SYMBOLIC mode, 5-4, 5-6
Symbolic references, 1-4

9-4

S
Scope,

SCOPE

1-5

commands,

CANCEL,

SET,

Table,

6-9

SHOW,

SCOPE mode,

5-11
setting, 2~3, 6-9
Search modes, pathname,
Search rules, 6-7
Semicolon, 4-9

Shift operator,
Sign,
4-8

4-2
4-2

plus,
Slash,

4-3,

STEP

CANCEL,
5-10

1-2,

8-2
SHOW, 8-3
Tracing opcodes,

8-1
branch-type, 8-3
call-type, 8-2
4-1

4-7

3-2,

7-2,

8-1

8-3

Typed data,

command,

Stepping,

session,

SET,

4-3

2-2

\V/

1-3,

Value displayed,

Values

last,
into pathnames,

9-2

3-2

Step types,

7-4

a debugging

Tracepoints,

Special characters, 4-1
Starting a debugging session,
2-1
Startup,

6-6

2-4

Scope

equal,

1-4,

breakpoints,

Terminating

6-9

minus,

symbol,

Temporary

3-2

setting, 3-3
showing, 3-3
Strings, input,
Symbol, 6-1
defined, 6-2
global, 6-5

w
4-10

Watchpoints,

CANCEL,

1-2,

restrictions,
SET, 9-2
SHOW, 9-2

Index-3

9-1

9-3
9-4

4-5

6-9

VAX~-11

Symbolic Debugger
Reference Manual
AA-D026A-~TE

READER'S

NOTE:

This
use

form is
comments

COMMENTS

for document

comments

submitted on

this

only.

form at

the

DIGITAL will
company's

discretion.
If you require a written reply and are
eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR
form.

Did you find this manual understandable,
- Please make suggestions for improvement.

Did you
page

find errors

in this manual?

usable,

so,

number.

indicate

Oooodaagd

Please

the

Assembly

type of

language

Higher-level

reader

and well-organized?

specify

the error and the

that you most nearly represent.

programmer

language programmer

Occasional programmer

(experienced)

User with little programming

experience

Student programmer

Other

(please specify)

Name

Date

Organization
Street

City.

State

Zip Code
or

Country

—

Do Not Tear- Fold HereandTape

—

—_——

—

—_—

No Postage
Necessary
if Mailed in the

United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.

POSTAGE WILL BE PAID BY ADDRESSEE

RT/C SOFTWARE PUBLICATIONS

TW/A14

DIGITAL EQUIPMENT CORPORATION

1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

- —

Do Not Tear- FoldHee'

@~ @~ —

—

01876

—