Digital PDFs

AA-BH82B-TB

May 1986

130 pages

Original

4.7MB

Document:	DDT Manual Apr86
Order Number:	AA-BH82B-TB
Revision:	0
Pages:	130
Original Filename:	AA-BH82B-TB_DDT_Manual_Apr86.pdf

OCR Text

TOPS-10

DDT Manual
AA-BH82B- TB

April 1986
This manual describes the use of TOPS-1 0 DDT, the
Dynamic Debugging Tool for MACRO-10 programs.
This document su·persedes the previous version of the same
name, order number AA-BH82A-TB.

OPERATING SYSTEM:

TOPS-10 V7.03

SOFTWARE:

DDT V44

Software and manuals should be ordered by title and order number. In the United States. send orders
to the nearest distribution center. Outside the United States. orders should be directed to the nearest
DIGITAL Field Sales Office or representative.

Western Region

Northeast/Mid-Atlantic Region

Central Region

Digital Equipment Corporation
PO Box CS2008
Nashua, New Hampshire 03061
Telephone:(603)884-6660

Digital Equipment Corporation
Digital Equipment Corporation
Accessories and Supplies Center Accessories and Supplies Center
1050 East Remington Road
632 Caribbean Drive
Schaumburg, Illinois 60195
Sunnyvale. California 94086
Telephone:(312,)640-5612
Telephone:(408)734-4915

digital equipment corporation. marlboro. massachusetts

First Printing, September 1984
Revised, April 1986
Copyright ©1984, 1986 by Digital Equipment Corporation. All Rights Reserved.

The information in this document is subject to change without notice and should not
be construed as a commitment by Digital Equipment Corporation. Digital Equipment
Corporation assumes no responsibility for any errors that may appear in this document.
The software described in this document is furnished under a license and may be
used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is
not supplied by Digital Equipment Corporation or its affiliated companies.
The following are trademarks of Digital Equipment Corporation:
DEC
DECmate
DECsystem-10
DECSYSTEM-20
DECUS
DECwriter
DIBOL

MASSBUS
PDP
P/OS
Professional
Q-BUS
Rainbow
RSTS

RSX
RT
UNIBUS
VAX
VMS
VT
Work Processor

The postpaid READER'S COMMENTS form on the last page of this document requests
the user's critical evaluation to assist us in preparing future documentation.

CONTENTS
PREFACE
CHAPTER 1
1.1
1.2
CHAPTER 2
2.1
2.2
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5
2.4
2.5
CHAPTER 3
3.1
3.2
3.2.1
3.2.2
3.3
CHAPTER 4
4.1
4.1.1
4.1.2
4.2
4.3
4.4
4.4.1
4.4.2
4.4.3
4.5
4.6
4.7
4.8
4.9
4.10
4.11
CHAPTER 5
5.1
5.2
5.2.1
5.2.2
5.2.3
5.2.4
5.3

INTRODUCTION TO DDT
SYMBOLIC DEBUGGING •
TOPS-10 VARIANTS OF DDT

• 1-1
• 1-1

GETTING STARTED WITH DDT
INTRODUCTION • • •
LOADING DDT
BASIC FUNCTIONS
Error Conditions • •
• • •
Basic Concepts •
• •
Starting and Stopping the Program • • • •
Examining and Modifying Memory
Executing Program Instructions
A SAMPLE DEBUGGING SESSION USING DDT •
•
PROGRAMMING WITH DDT IN MIND • •

•
• • •
•
• • •
•
• • •

2-1
2-1
2-2
2-3
2-3
2-4
2-5
• • 2-8
• • • 2-8
2-18

DDT COMMAND FORMAT
COMMAND SYNTAX • • • • • • • •
INPUT TO DDT • • • • • • • • •
Values in DDT Expressions
Operators in DDT Expressions •
COMMAND FILES • • • • •

• • • • •
•
• •
•
• •

3-1
3-2
3-2
3-6
3-9

DISPLAYING AND MODIFYING MEMORY
DISPLAY MODES • • • • • •
• • • •
• • • 4-1
Default Display Modes
• • • •
• • 4-1
Selecting Display Modes
• • • • • • 4-2
DISPLAYING EXPRESSIONS • •
4-5
DISPLAYING BYTE POINTERS • •
• 4-5
DISPLAYING AND DEPOSITING IN MEMORY • •
• • 4-6
Commands That Use the Current Location • • • • • 4-8
Commands That Use the Location Sequence Stack • 4-9
Commands That Use an Address Within the Command 4-10
DISPLAYING ASCIZ STRINGS
4-15
ZEROING MEMORY • • • • • • • • • • • • • • •
4-16
AUTOMATIC WRITE-ENABLE • • • • • • • • • •
4-16
AUTOMATIC PAGE CREATION • • • • • • • • •
4-17
DISPLAYING PAGE ACCESSIBILITY INFORMATION
4-17
WATCHING A MEMORY LOCATION
4-18
TTY CONTROL MASK • • • • • • • • • • • • • •
4-19
CONTROLLING PROGRAM EXECUTION
BEGINNING EXECUTION • • • • • • • • •
•
USING BREAKPOINTS • • • • • •
Setting Breakpoints • • • •
Proceeding from Breakpoints
• • • •
Conditional Breakpoints
The "Unsolicited" Breakpoint • •
•
EXECUTING EXPLICIT INSTRUCTIONS
iii

• • 5-1
• • 5-1
• '3-3

• • 5-6
• • 5-8
• • 5-8
• 5-9

April 1986

5.4
5.5
5.5.1
5.6

SINGLE-STEPPING INSTRUCTIONS • • • • • • • • • •
EXECUTING SUBROUTINES AND RANGES OF INSTRUCTIONS
Single-Stepping "Dangerous" Instructions •
USER-PROGRAM CONTEXT
••••
•• • • • ••

CHAPTER 6

SEARCHING FOR DATA PATTERNS IN DDT

CHAPTER 7

MANIPULATING SYMBOLS IN DDT

7.1
7.2
7.3
7.4
7.5
7.6
7.7
7.8

OPENING AND CLOSING SYMBOL TABLES
DEFINING SYMBOLS • • • • •
SUPPRESSING SYMBOL TYPEOUT • • • •
KILLING SYMBOLS • • • • • • • • •
CREATING UNDEFINED SYMBOLS a • • •
FINDING WHERE A SYMBOL IS DEFINED
LISTING UNDEFINED SYMBOLS
LISTING SYMBOLS
• • • •

CHAPTER 8

INSERTING PATCHES WITH DDT

CHAPTER 9

FILDDT

9.1
9.2
9.2.1
9.2.2
9.2.3
9.2.4
9.2.5
CHAPTER 10
10.1
10.2

• • • •
• • •
• •
•

• • • • 7-1
••
7-2
• • • • 7-2
• • • • 7-3
•
•
•
•
•
•
•
•
7-3
• • • • ••
7-3
• • • • 7-3
• • • • • • • • 7-4

INTRODUCTION
• • ••
•• • •
USING FILDDT • • • •
• • • • • • •
FILDDT Commands
• • • •
•
Symbols • • • • • • • •
• • • • • • • •
Establishing Formats and Parameters • • • • • •
Selecting the Target •
• ••
Exiting FILDDT • • •
••••• •
•
EDDT

10-1
10-2

BREAKPOINTS
The Breakpoint Block • • • • • • • • • • • • •
Enabling and Disabling Intersection Breakpoints
DISPLAYING SYMBOLS IN NON-ZERO SECTIONS
DEFAULT SECTION NUMBERS • • • • • • • • • •
Permanent Default Section • • • • •
Floating Default Section • • • • • •
EXECUTING SINGLE INSTRUCTIONS • • • •
ENTERING PATCHES IN EXTENDED SECTIONS

12-2
12-2
12-3
12-4
12-4
12-5
12-5
12-7
12-7

PHYSICAL AND VIRTUAL ADDRESSING COMMANDS

CHAPTER 12

EXTENDED ADDRESSING

APPENDIX A

9-1
9-1
9-2
9-3
9-3
9-3
9-4

.. ..

EXECUTIVE MODE •
USER MOOT!:

CHAPTER 11

12.1
12.1.1
12.1.2
12.2
12.3
12.3.1
12.3.2
12.4
12.5

5-10
5-11
5-13
5-13

ERROR MESSAGES

GLOSSARY
INDEX

April 1986

FIGURES
2-1
2-2
2-3
4-1
8-1
8-2
8-3

Sample Program X.MAC • • • • • • • • • •
• 2-9
Annotated Debugging Session • • • • • •
2-10
Terminal Display of Debugging Session
2-17
DDT Session Showing Columnar Output
4-20
Annotated Patching Session • • • • • • •
8-3
Terminal Display of Patching After an Instruction 8-4
Terminal Display of Patching Before an Instruction 8-5

3-1
3-2
4-1
4-2
4-3
4-4
4-5
5-1
5-2

Commands That Return Values • • • • • • • • • • • 3-3
Effects of Operators When Evaluating Expressions • 3-7
Evaluation of Symbolic Display Mode
• • • • • 4-1
DDT Display Modes • • • • • • • • • • • •
4-4
Commands to Display Expressions
• • • 4-5
DDT Commands to Display Memory • •
• • • 4-8
TTY Control Mask • • • • • • • • •
4-19
Breakpoint Locations of Interest •
• • • 5-2
User-Program Context Values
• • • • 5-14

TABLES

PREFACE

MANUAL OBJECTIVES AND AUDIENCE
This manual explains and illustrates the features of TOPS-10 DDT, the
debugger for MACRO-10 programs, Although TOPS-10 DDT can be used to
debug the compiled code of programs written in higher-level languages,
this manual
illustrates the use of TOPS-10 DDT to debug programs
written in MACRO-10 only.
This manual is both an introduction to the basic functions of TOPS-10
DDT and a reference guide to all TOPS-10 DDT commands and functions.
This manual assumes that the reader is familiar with using TOPS-10,
has done some programming in MACRO-10, and is familiar with the format
of MACRO-10 instructions.
STRUCTURE OF THIS DOCUMENT
This manual has 12 chapters, 1 appendix, and 1 glossary.
o

Chapter 1 introduces the concept of symbolic
describes the variants of TOPS-10 DDT.

Chapter 2 describes loading TOPS-10 DDTwith your program,
discusses basic TOPS-10 DDT commands, and illustrates a
sample debugging session.

Chapter 3 explains the syntax of a DDT command.
Chapter 3
also describes expressions to enter data and explains how
TOPS-10 DDT evaluates expressions.

Chapter 4 discusses how to examine and modify a program using
TOPS-10 DDT.

Chapter 5 describes the use of TOPS-10 DDT to control program
execution:
how to start, stop, and monitor the running of a
program.

Chapter 6 explains how to perform
address space using TOPS-10 DDT.

Chapter 7 discusses the manipulation of program symbols using
TOPS-10 DDT.

Chapter 8 describes how to use the TOPS-10 DDT patching
function to insert and test a new series of instructions in
your program without reassembling the program.

vii

searches

debugging

and

program's

April 1986

Chapter 9 describes the use of FILDDT.

Chapter 10 describes the use of EDDT.

Chapter 11 describes special-use commands that
control
physical and virtual addressing. These commands are useful
primarily when running EDDT and FILDDT.

Chapter 12 describes the use
(NZS) •

Appendix A explains DDT and FILDDT error messages.

The glossary defines important TOPS-10 DDT terms.

DDT

non-zero

sections

OTHER DOCUMENTS
Other documents to which the reader should have access are:
o

MACRO Assembler Reference Manual

LINK Reference Manual

TOPS-10 Operating System Commands Manual

DECsystem-10/DECSYSTEM-20 Processor Reference Manual

TOPS-10/TOPS-20 RSX-20F System Reference Manual

CONVENTIONS
The following conventions are used in this manual in
of DDT commands and concepts.

the

description

{}

Curly brackets (braces)
is optional.

• (period)

The address contained in DDT's location
called the current location.

addr

A symbolic location within a program, a symbolic or
absolute address in memory, an AC, or ".", the current
location.

A single ASCII or SIXBIT character.

expr

Any expression that is legal in DDT.

filnam

One or more components of a file specification.

instr

Any instruction in the PDP-10 machine instruction set.

indicate that the enclosed item
counter;

also

location sequence stack
A circular stack of memory locations that is used to
store the addresses of certain previously referenced
locations.
n

A numeric argument.

page

A page in memory.

DDT V44

A page equals 512 words of memory_

viii

April 1986

symbol

A symbol name of up to 6 RADIX50 characters.

text

Any string of ASCII or SIXBIT characters.

word

Any 36-bit value occupying one word of memory.

<ESC>

Represents pressing the ESCAPE or ALTMODE key once.

Represents pressing the ESCAPE or ALTMODE key twice.

Represents pressing a key (represented by X)
same time as you press the key labeled CTRL.

<BKSP>

represents pressing the BACKSPACE key or <CTRL/H>.

<LF>

Represents pressing the LINE FEED key.

<RET>

Represents pressing the RETURN key.

<TAB>

Represents pressing the TAB key or <CTRL/I>.

the

Numbers are in octal radix unless otherwise specified.
Examples of interaction between the user and DDT show
lowercase and DDT output in uppercase.
The symbols <BKSP>, <CTRL/x>, <ESC>, <LF>,
represent user input.

<RET>,

and

user

input

<TAB>

NOTE
The descriptions of many DDT commands list the actions
and effects of those commands.
The actions and
effects may not occur in
precisely
the
order
specified, but this has no effect on the user.

always

CHAPTER 1
INTRODUCTION TO DDT

DDT is a utility program you can use that will help you debug your
MACRO-10 programs. This manual describes how to use the DDT utility.

1.1

SYMBOLIC DEBUGGING

It is sometimes difficult to understand precisely the operation of a
program by reading the source code. DDT is a tool for interactively
examining the operation of a MACRO-10 program while it is running.
DDT is useful for finding programming errors (bugs) in programs that
do not run correctly. You can also use DDT to analyze the flow of
control in a program that is to be revised or rewritten.
With DDT, you can interrupt the execution of your program at locations
(breakpoints)
you choose, and then examine and modify the program's
address space as required. You can execute instructions one-by-one to
check whether the effect of each instruction is what is intended. You
can then set other breakpoints in your program before continuing
execution.
When you refer to program locations and values, DDT allows you to use
the symbols that are defined in the program rather than absolute
values and addresses. This makes it much easier to refer to the
source listing and to find specific locations in memory.
After modifying the program's instructions or data, you can exit DDT
and save (with the monitor-level SAVE command) the changed version of
the program for further testing.

1.2

TOPS-10 VARIANTS OF DDT

There are several variants of DDT,
circumstances or for specific tasks.
The variants of TOPS-10 DDT are:
o

DDT.REL

DDT.EXE

VMDDT.EXE

FILDDT.EXE

EDDT.EXE

1-1

each

useful

under

specific

INTRODUCTION TO DDT
DDT.REL is the re10catab1e variant of DDT, and can be loaded directly
with your MACRO-10 program by using (at TOPS-10 command level) the
TOPS-10 command DEBUG command.
For example, enter the command string:
DEBUG filnam
where filnam is the name of your MACRO-10 program
(with default
extension .MAC). The DEBUG command causes LINK to retain your program
symbol table and to merge DDT.REL with your program modu1e(s).
See
the TOPS-10 Operating System Commands Manual for a description of the
DEBUG command.
If you use the DEBUG command with a program written in a higher-level
language,
such
as
COBOL
or
FORTRAN,
you will
invoke the
language-associated debugging tool, such as COBDDT or FORDDT,
rather
than DDT. To use DDT.REL to debug a program written in a higher-level
language, you can explicitly run LINK and load DDT.REL with your
program. See the LINK Reference Manual for a description of the /TEST
and /DEBUG switcheS:--you can also use the DEBUG command with the /DDT
switch, as:
DEBUG/DDT filnam
where filnam is the name of your program. The /DDT switch tells LINK
that you wish to use DDT, rather than the associated debugging tool.
DDT.EXE is a stand-alone variant of DDT that you can use to enter
MACRO-10 instructions directly for testing.
You run DDT.EXE as a user
program by using the TOPS-10 RUN command:
R DDT
DDT.EXE has system symbols defined as in UUOSYM and MACTEN, and
recognizes hardware instructions
(for example, MOVE and ADDI) and
TOPS-10 UUOs (for example, TTCALL and CORE).

VMDDT.EXE is the variant that is merged with
TOPS-10 command level, you enter:

your

program

when,

DDT
Your program must be loaded in memory, such as by using the TOPS-10
GET command, or the TOPS-10 RUN command.
You can use the DDT command
to load VMDDT, whether your program has just been loaded, if it ran to
completion,
if it crashed, or if you used <CTRL/C> to exit from your
program.
If JOBDAT location .JBDDT is zero, indicating that there is
no other debugger (for example, FORDDT) loaded with your program, the
DDT command loads and starts VMDDT.
Pages 700-777 are reserved for
VMDDT.EXE.
If, during the debugging session, your program executes a CORE UUO to
shrink core,
the monitor reclaims the memory used by VMDDT, and your
program will get an Illegal memory reference error if it reaches a
breakpoint.
If your program was not saved with symbols, VMDDT can display only
numeric values and may not be of much use.
See the LINK Reference
Manual for a description of how to use the /SYMSEG--and /LOCALS
switches to save your program symbols when loading your program.

1-2

INTRODUCTION TO DDT
FILDDT.EXE is used to examine a~d modify disk files and structures,
the monitor, and other running jobs.
FILDDT is discussed in Chapter

EDDT.EXE is used to debug and patch the monitor.
Chapter Ie.

1-3

EDDT is discussed in

CHAPTER 2
GETTING STARTED WITH DDT

2.1

INTRODUCTION

This chapter is an introduction to using DDT.
It describes how to
load DDT.REL with your program and shows how to perform basic DDT
functions.
It then illustrates a sample session debugging a simple
MACRO-Hi7 program, using basic DDT functions.
You can use DDT to debug
programs, using only the commands described in this chapter. Once you
are familiar with using these commands, you may wish to learn how to
use the commands and functions that are described in the rest of the
manual, to perform more sophisticated debugging.
The commands used in this chapter are described only in sufficient
detail
for
the debugging task being performed;
all commands are
thoroughly described in Chapters 3 through 11 of this document.
The best way to learn is by doing.
You will learn the commands and
techniques discussed in this manual if you use them as you read about
them.
If you have a MACRO-10 program that you wish to debug,
use it
to practice the commands discussed here.
If not, type in the program
X.MAC listed in Figure 2-1.

2.2

LOADING DDT

It is much easier
are defined
in
symbols, DDT must
to provide
this
DDT.REL with your
existing MACRO-10

to debug a program when you can use the symbols that
the program.
For you to be able to use program
have access to your program's symbol table. One way
access
is to use the TOPS-10 DEBUG command to load
program and retain your program symbols.
Load an
program with the TOPS-10 DEBUG command as follows:

DEBUG filnam
where filnam is the name of your MACRO-10 program.
The following
appears on your terminal (if your .REL file is older than your .MAC
file, MACRO-10 reassembles your program, otherwise the second line
does not appear):
.DEBUG PROG
MACRO:
filnam
LINK:
Loading
[LNKDEB DDT execution]
DDT
where filnam is the name of your MACRO-10 program (with default
extension
.MAC).
The last line (DDT) indicates that DDT is loaded,
and is ready to accept your commands.

2-1

GETTING STARTED WITH DDT
2.3

BASIC FUNCTIONS

You must be able to perform certain basic functions
debug a program. Basic DDT functions are:
o

starting the program

stopping the program at specified locations

examining and modifying memory

executing program instructions one-at-a-time

continuing execution of the program

deleting input

exi ting DDT

interactively

You must give DDT commands to tell DDT what functions to perform. DDT
does not wait for a line terminator (such as a carriage return) to
indicate the end of your command. Instead, DDT reads your commands
character-by-character as you enter them.
When you enter a DDT
command, you almost never have to press the RETURN key.
This manual
explicitly indicates the occasions when a command requires you to
press the RETURN key.
NOTE
You must press the ESCAPE key as part of entering many
DDT commands.
This manual uses the symbol <ESC> to
indicate where you press the ESCAPE key.
When you
press the ESCAPE key, DDT displays a dollar sign ($)
on the screen. DDT never displays <ESC> when you
press the ESCAPE key.
NOTE
This manual uses the symbols <BKSP>, <ESC>, <LF>,
<RET>, and <TAB> to indicate where you press the
BACKSPACE, ESCAPE, LINE FEED, RETURN, and TAB keys,
respectively.
This manual also uses the symbol
<CTRL/X> to indicate where you simultaneously press
the CONTROL key and the key indicated by X. These
symbols ALWAYS indicate where you press the specific
keys noted here. You need NEVER enter the characters
<BKSP>, <ESC>, <LF>, <RET>, <TAB>, or <CTRL/X>, to
enter a DDT command.
Your commands appear on the screen as you type them. Use the DELETE
key to delete partially entered commands character-by-character. If
you try to delete more characters than you have entered, DDT displays:

xxx
You can delete an entire command line with <CTRL/U>.
displays:

xxx
To exit DDT, enter:
<CTRL/Z>

2-2

When you do, DDT

GETTING STARTED WITH DDT
The other basic DDT functions
chapter.

2.3.1

are

described

the

rest

this

Error Conditions

If DDT cannot execute a command, it displays a message to let you
know.
The message may be only a single character (such as M or U, for
Multiply-defined symbol or Undefined symbol), a question mark (?), or
complete message string~ For most errors, DDT also sets a pointer
to the error string, so that if DDT did not display it, you can enter
a command to display the error string. The error string is available
for display until another error occurs, when DDT changes the pointer.
To display the error string that describes the last DDT error, enter:

<ESC)?
(press the ESCAPE key, followed by a question mark) •

2.3.2

Basic Concepts

A very useful DDT concept is that of the current location.
The
current location is a memory location that you have referenced, either
implicitly or explicitly, with your last command, and that is the
default point of reference of your next command. The current location
can be thought of as the location "where you are".
The symbol "."
(period)
refers to the address of the current location, and can be
used as an argument in DDT commands.
The location counter is a DDT pointer that contains the address of the
current location. The location counter performs a function similar to
that of a bookmark. You can enter a command to display the contents
of a
specific location but not change the address of the current
location, in order to maintain a specific point of reference for your
next command.
Most DDT commands change the address of the current
location, and therefore also change the location counter.
The
commands that do not change the current location are so indicated.
The open location is a memory word that can be modified by your next
command
DDT "opens" the location as a result of a command you give
to examine or modify memory.
There is never more than one location
open at any given time.
The open location is usually also the current
location.
8

To find the symbolic address of the current location, enter:
(a period followed by an underscore)
This causes DDT to display the following:
ADDRl+n
where ADDRI is a label defined in your program, and n is the offset of
the current location from that label
(if the current location is
ADDRl, DDT does not display +n).
Another useful DDT concept is that of the current quantity.
This is a
value that is the contents of the last word that DDT displayed, or the
value that you last deposited in memory.
The current quantity is the
most recent of those values. Many DDT commands use arguments that
default to the current quantity.
2-3

GETTING STARTED WITH DDT
The location sequence stack is a DDT storage area used to store the
addresses of previous current locations. Certain DDT commands store
the address of the current location on the location sequence stack.
Other DDT commands change the address of the current location to an
address that has already been stored on the location sequence stack.
The location sequence stack functions in a fashion similar to
inserting place-markers in a source code listing, to be able to "get
back" to prior references.

2.3.3

Starting and Stopping the Program

When your program is loaded and DDT is ready to accept your commands
(as indicated by DDT appearing on the terminal display), you can begin
execution of your-p(ogram at its start address by entering:
<ESC>G
Unless you set one or more breakpoints before you start the program,
your program runs either to completion or until it commits a fatal
error. A breakpoint is a location in a program's executable code that
has been modified so that if the program attempts to execute the
instruction at that location,--control passes to DDT before the
instruction is executed.
The command to set a breakpoint is:
addr<ESC>B
where addr is the address at which to stop execution.
If the
user-program PC reaches addr, DDT interrupts execution of the program
before the program executes the instruction at the specified address.
When DDT interrupts program execution at a breakpoint, it changes the
current location to the breakpoint and opens the current location (the
breakpoint).
While program execution is stopped at a breakpoint, you can display
and change the contents of instruction and data words, remove
breakpoints, set new breakpoints, and execute instructions one at a
time
(single-step).
As you examine memory, you may find an
instruction that is incorrect, and modify it. You can also examine
and
modify
data
words in memory.
After modifying incorrect
instructions and data in memory, you can immediately execute the
instructions to check the effects of the modifications, without having
to reassemble the source code.
Once you have made your changes, you can continue program execution at
the place where execution was interrupted, restart the program at the
beginning, or start execution at any other location you choose.
The
program will run to completion, until it reaches a breakpoint, or
until it gets a fatal error.

2-4

GETTING STARTED WITH DDT
2.3.4

Examining and Modifying Memory

One command to examine memory Is:
addrl
where addr is the address of the memory word you wish to examine
(display) ,
and can be numeric or symbolic.
DDT displays the contents
of the word located at addr.
If the opcode field (bits 0-8)
of the
memory word matches a recognized instruction or user-defined OPDEF,
DDT displays the contents of addr as an instruction (or OPDEF).
If
DDT finds (in the symbol table) any of the values to be displayed, DDT
displays those symbols rather than the numeric values.
For example,
either of the following display lines might appear on your terminal
(depending on the address and contents of the word):
ADDRII
ADDRl+51

MOVE 2,SYMI
SYMl"SYM2

where ADDRl, SYMl, and SYM2 have been defined in the program.
If you enter a symbol that DDT does not find in the symbol table, DDT
sounds the terminal buzzer or bell, and displays U on the screen.
If
you enter a symbol that is defined as a local symbol in-more than one
module,
DDT sounds the terminal buzzer or bell and displays M.
You
can eliminate the multiply-defined symbol problem by "opening" the
symbol
table of the module in which the correct symbol is defined.
See Chapter 7 (Manipulating Symbols in DDT) for more information.
When searching for a symbol to display, DDT uses global symbols in
preference to local symbols. However, DDT searches the "open" symbol
table first, and treats local symbols found in the open symbol table
as global symbols.
If DDT finds only a local symbol that is not in
the open symbol table, DDT displays the symbol with a pound-sign
(#)
appended to the symbol. For example, DDT might display:
ADDR#I

MOVE 2,SYMI

See Chapter 7 (Manipulating Symbols in DDT) for
symbols and symbol tables.

information

The command addrl changes the current location to addr and
word at addr.

opens

on
the

If you omit addr from an examine-memory command, such as addr/,
DDT
uses the current quantity to determine the address of the location to
display.
For example, after DDT displays the contents of ADDRl+5 as
above, if you enter "I", DDT displays the contents of the word located
at SYM2. The display line then appears:
ADDRl+51

SYMl"SYM2

value

where value is the contents of the word located at SYM2.
DDT displays value symbolically if it can.

default,

The command I by itself (without addr) does not change the current
location.
Both forms of the I command open the location displayed,
enabling you to modify the location with your next command.

2-5

GETTING STARTED WITH DDT
Another very useful command for examining memory is <TAB>.
This
command starts a new display line before displaying the contents of
addr, making the display easier to read. For example,
if you enter
<TAB> after DDT displays the address and contents of ADDRI+5 (as
above) on your terminal, the terminal display appears:
<TAB>

ADDRI+5/
SYMI"SYM2
SYM2/
value

where value is the contents of the word located at SYM2.
<TAB> does
not appear on the screen, but is shown above to indicate where you
press the <TAB> key. <TAB> changes the current location to SYM2 and
opens the word at SYM2.
In this example, the current quantity becomes
value.
<TAB> also stores the address of the current location (ADDRI+5) on the
location sequence stack before changing the current location to the
location just displayed (SYM2). DDT uses the location sequence stack
to "remember" previous values of the location counter. To "get back"
to the previous current location, enter:
<ESC><RET>
In the above example, after you press <TAB> at ADDRI+5, DDT displays
the contents of SYM2 and changes the current location to SYM2. When
you enter <ESC><RET>, DDT changes the current location to ADDRI+5,
opens the location at ADDRI+5, and again displays the contents of
ADDRI+5.
If you use the command addr<TAB>, DDT deposits addr in the open
location and closes the location before opening the location at addr
and displaying its contents.
<TAB> by itself does not deposit
anything, but does save the current location on the location sequence
stack, making <TAB> more useful than / (slash by itself).
You can display and open
entering:

the

word

after

the

current

location

<LF>
DDT changes the current location to the next word in memory, starts a
new line, and displays the address of the (new) current location (as a
symbol or a symbol plus an offset, if it can find a corresponding
symbol
in the symbol table), displays the contents of the current
location, and opens the current location. For example, to display the
next word in memory after ADDRI+5, enter:
<LF>
DDT changes the current location to ADDRI+6, starts a new line, and
displays the address and contents of ADDRI+6. The screen display then
appears as follows:
ADDRl+5/
ADDRl+6/

SYMl"SYM2
-1"SYM3

<LF>

Note that DDT does not display the characters
affect the location sequence stack.

<LF>.

<LF>

does

Entering another <LF> causes DDT to display and open the next word.

2-6

not

GETTING STARTED WITH DDT
To display and open the word previous to the current location, enter:
(BKSP>
DDT changes the current location to the previous word, starts a new
line, displays the address and contents of the (new) current location,
and opens the current location. (BKSP> does not affect the location
sequence stack. For example, if you enter <BKSP> to open and display
the location before ADDRI+5, the screen appears as follows:
ADDRl+5/
ADDRl+4/

SYMl"SYM2
-3"SYM2

<BKSP>

Note that <BKSP> does not appear on the screen.
To change the contents of the open location, enter:
value<RET>
where value can be an instruction, a symbol, or a numeric expression.
For example, if you enter the command LABL2/, DDT displays the
contents of the memory word at LABL2, and "opens" that word.
If the
word at LABL2 contains:
MOVE l,SYMI
and you wish to change SYMl to SYM2, enter:
MOVE l,SYM2<RET>
DDT stores the new instruction in the location at LABL2 and "closes"
the location.
DDT does NOT display <RET>.
The terminal display
appears as follows (your input is in lowercase):
labl2/

MOVE l,SYMI

move 1,sym2<RET>

The current location is still LABL2, but there is no open location.
To check whether the instruction is now correct, you can enter:

./
to display the contents of the current location.
now appears (your input is in lowercase):
.
labl2/
MOVE I,SYMl
./
MOVE l,SYM2

The

screen

display

move l,sym2<RET>

After entering a command to display and open a location, if you enter:
value<LF>
DDT stores the new value, changes the current location to the next
location in memory, starts a new display line and opens and displays
the new current location. The example above would then appear as
follows (your input is in lowercase):
labl2/
MOVE I,SYMI
LABL2+1/
CONTENTS

move l,sym2(LF>

where CONTENTS is the value stored at LABL2+1.

2-7

GETTING STARTED WITH DDT
2.3.5

Executing Program Instructions

When you have interrupted program execution at a breakpoint, you can
execute the next instruction (the one at the breakpoint), by entering:
<ESC>X
DDT executes the instruction, displays the results of executing the
instruction, and displays the address and contents of the next
instruction to be executed. This command changes the current location
to the next instruction to be executed. For example, assume that the
next instruction to be executed is located at LABELl, which contains:
MOVE 1,VARIBL
If the word at VARIBL contains SYMl, when you enter <ESC>X, DDT starts
a new line and displays:
1/
SYMI
VARIBL/
LABELl+l/
instr

SYMI

where instr is the contents of LABELl+l, and is the next instruction
to
be
executed.
You
can
continue to execute instructions
one-at-a-time by entering successive <ESC>X commands. This is known
as single-stepping.
To execute ~ subroutine, enter:
<ESC><ESC>X
DDT executes the subroutine and returns control to you if the
subroutine returns to a location +1, +2, or +3 from the instruction
that calls the subroutine. DDT changes the current location to the
address of the next instruction to be executed.
To continue execution of the program
until program completion, enter:

until

the

breakpoint

<ESC>P
DDT starts the program running again, beginning with the next
instruction
to
be executed.
If you did not single-step any
instructions, the program begins by executing the instruction at the
breakpoint. If you have executed any instructions by single-stepping,
the program continues where you stopped. The effect is as if the
program were running without DDT in control.

2.4

A SAMPLE DEBUGGING SESSION USING DDT

This section describes a debugging session using DDT.
The program
being debugged is X.MAC, shown in Figure 2-1. The program and the
sample session are for illustration only. There are many styles of
programming and debugging, and these examples are descriptive rather
than prescriptive in intent.
You will understand this section and learn the commands described more
easily if you type in the program listed in Figure 2-1 and use the
commands as they are described.

2-8

GETTING STARTED WITH DDT
Figure 2-1:

Sample Program X.MAC

SEARCH
TITLE

UUOSYM
X

R0=0
IDX=6
P=17

iAC0
iINDEX REGISTER
iSTACK COUNTER

START: : MOVE
MOVE I
PUSHJ
MOVEI
MOVE
JFCL
EXIT
ADDEM:
MOVE
ADD
MOVE
POPJ

P,PWORD
IDX,TABLEl
P,ADDEM
IDX,TABLEl
R0,ANSWER(IDX)
0
R0,X(IDX)
R0,Y(IDX)
R0,ANSWER(IDX)
P,

TABLEl: BLOCK
3
X==0
Y==l
ANSWER==2
STKSIZ==10
PWORD:
IOWD STKSIZ,STACK
STACK:
BLOCK
STKSIZ
END
START

iSet up stack counter
iAddress of table with X & Y
iDo the addition
iAddress of table
iAnswer to R0
iAll donel
iLoad X
iX

+ Y

iStore answer
;Return

;3 words
iOffset for X
;Offset for Y
;Offset for answer
;Stack size
,Stack pointer
,Staok

Figure 2-2 is an annotated session debugging X.MAC,
the program in
Figure
2-1.
In the annotated session, the DDT terminal display is on
the left, user input is in the center 1n lowercase, and explanatory
comments about the session are on the right.
This is not always the
way it appears on the terminal.
Figure 2-3 shows the session as it
actually appears on the terminal.
The program is designed to pass the address of a
table to a
subroutine.
The table contains three elements. The subroutine is to
add the first two elements of the table and store the result in the
third element before returning to the main program.
There are no
input or output routines in the program.
The table is initialized
using DDT, and the result is checked while in DDT.
NOTE
DDT does not display <LF>, <RET>, or <TAB>.
These are
shown in the sample session to indicate user input.
NOTE
DDT does not display the AC field of an instruction if
it
is zero.
This means that if your program contains
the instruction MOVE R0,LABL1, where
R0=0,
DDT
displays the instruction as MOVE LABL1.

2-9

GETTING STARTED WITH DDT
Figure 2-2:

Annotated Debugging Session

SCREEN DISPLAY

USER INPUT

EXPLANATION
TOPS-lei prompt.

debug x<RET>

MACRO reassembles your program
(if needed), and LINK loads
your program with DDT. DDT
displays the "DDT" prompt.

MACRO: X
LINK:
Load ing
[LNKDEB DDT execution]
DDT
start/
MOVE P,PWORD#

Begin examining code at
label "START".
DDT displays the instruction
at START.
Press <LF> to display the next
instruction.

<LF>
DDTEND+l/

Begin the session by entering
"debug x<RET>", where x is the
name of your MACRO program.

MOVEI IDX,TABLEl#

The first symbol in this
program happens to coincide
with DDTEND, a DDT symbol.
When DDT scans the symbol
table, it finds DDTEND before
it finds START, and displays
DDTEND instead. DDT still
accepts START as an input
symbol.
Also note the pound-sign (#)
appended to TABLEI and
PWORD. PWORD and TABLEI are
local symbols that are not
in the open symbol table.

ddtend<ESC>k

Enter ddtend<ESC>k
to suppress DDT typeout of
symbol DDTEND. DDT will
display START rather than
DDT END from now on.

x<ESC>:

Enter the module name (X)
followed by <ESC> and a
colon to open the symbol
table associated with
X. DDT will not append any
more pound-signs.

2-lel

GETTING STARTED WITH DDT
Figure 2-2:

Annotated Debugging Session (Cont.)

SCREEN DISPLAY

USER INPUT
<TAB>

Press <TAB> to start a new
display line, evaluate the
current quantity as if it
were an instruction, and
display the contents of the
location addressed by the Y
field of the instruction.
(Entering / (slash) displays
the same word as <TAB>, but
does not start a new line.)
<TAB> also saves your place
(like a bookmark) on the
location sequence stack, so
you can get back here easily.

TAB LEI/

When you enter the <TAB>
command, DDT displays the
address and the contents of
the location. The first
element of the table contains
zero. The <TAB> command also
opens the location.
2<LF>

Enter "2" followed by <LF> to
deposit the value "2" in the
first element, and to open and
display the second element.

TABLEl+l/

The second element contains
zero.
3<LF>

Enter "3" followed by <LF> to
deposit the value "3" in the
second element and open and
display the third element.
The addition to be performed
by the program is 2+3.
The third element (the answer)
contains zero.

TABLEl+2/
<ESC><RET>

START+l/

EXPLANATION

Press <ESC>, then press <RET>
to return to the address you
saved on the location sequence
stack.
DDT displays the address and
contents of the last location
you displayed before you
entered <TAB>.

MOVEI IDX,TABLEI

Press <LF> to look at the
next locatioh.

<LF>

2-11

GETTING STARTED WITH DDT
Figure 2-2:

Annotated Debugging Session (Cont.)

SCREEN DISPLAY
START+2/

USER INPUT

This is the call to the
subroutine that does the
computation.

PUSHJ P,ADDEM

$lB»START+2/

.<ESC>b

Enter ".", press <ESC>, and
enter "b" to set a
breakpoint at the current
location.

<ESC>g

Enter <ESC>g to start
program execution.

PUSHJ P,ADDEM

DDT disp~ays the breakpoint
number, the address of the
breakpoint, and the
instruction at the breakpoint.
This instruction has not yet
been executed.

<ESC><ESC>x

START+3/

MOVEI IDX,TABLEI

START+4/

TABLEI

Press <ESC> twice, then
enter "x" to let DDT
execute the subroutine.
DDT returns from the
subroutine at the next
instruction, and displays the
address and contents of the
instruction. If there is a
"skip return", DDT displays
"<SKIP>" if the program
skipped one instruction. If
the program skips 2 or 3
instructions, DDT displays
"<SKIP n>", where n is the
number of instructions
skipped.

<ESC>x
IDX/

EXPLANATION

TABLEI

Press <ESC> and enter "x"
to execute the instruction.
DDT displays the address and
contents of lOX (the result of
executing the instruction),
and also displays "TABLEI"
(the result of evaluating the
Y field of the instruction).

MOVE 2 (IDX)

DDT then starts a new line and
displays the address and
contents of the next
instruction. Note that
DDT does not display the
zero in the AC field of
the instruction.

2-12

GETTING STARTED WITH DDT
Figure 2-2:

Annotated Debugging Session (Cont.)

SCREEN DISPLAY

USER INPUT
<ESC><TAB>

TABLE1+2/

TABLE1+l/

That

Press <BKSP> again to check
the previous element.
This element contains 2.
That
is also correct. One way to
find the error is to
single-step through the
program.

$2B»START/

Press <BKSP> to see the
previous element in the table.
This element contains 3.
is correct.

3
<BKSP>

start<ESC>b

Enter "start", press <ESC>,
and enter Db" to set a
breakpoint at the beginning of
the program.

<ESC>g

Press <ESC> and enter "gO to
start the program again.
DDT displays the breakpoint
number, and the address and
contents of the instruction
at the breakpoint.

MOVE P,PWORD

<ESC>x

Press <ESC>, then <TAB> to
display the contents of the
location addressed by the
instruction, using any
indexing and indirection.
(If you omit <ESC>, DDT uses
only the Y field, without
indexing and indirection.)
The location addressed by the
instruction is TABLEl+2, and
its contents is zero.
This is
the table element that
contains the answer, which
should be 5.

<BKSP>

TABLE1/

EXPLANATION

-10"PWORD

PWORD/

Press <ESC>, then enter "x" to
execute the instruction. This
instruction moves a memory
word to a register.

-10" PWORD
DDT displays the address and
new contents of the register,
and the address and contents
of the memory word.

2-13

GETTING STARTED WITH DDT
Figure 2-2:

Annotated Debugging Session (Cont.)

SCREEN DISPLAY

USER INPUT

MOVEI IOX,TABLEl

START+l/

DDT then displays the address
and contents of the next
instruction.
<ESC>x

IOX/

DDT displays the address and
new contents of the register,
and the immediate value.

PUSHJ P,ADDEM

DDT then displays the address
and contents of the next
instruction.
<ESC>x

DDT displays "<JUMP>" if the
change in PC is less than one
or greater than 4.

ADD EM/

MOVE 0 (IDX)

DDT displays the address and
contents of the next
instruction to be executed.
<ESC>x

ADDEM+l/

TABLE1/

ADD l(IDX)

ADDEM+2/

TABLE1+l/

Press <ESC> and enter "x" to
execute the instruction.
The instruction moved the
contents of the word at
TABLEl (which is 2) to ACfJ.
Looks OK so far.

DDT displays the next
instruction.
<ESC>x

fJ/

Press <ESC>, then enter "x"
to execute the instruction.
DDT displays the address and
new contents of the stack
pointer used by the PUSHJ.

-7"STACK

<JUMP>

Press <ESC>, then enter "x" to
execute this instruction,
which moves an immediate value
to a register.

TABLEl

START+2/

EXPLANATION

Press <ESC> and enter "x"
to execute the instruction.
The instruction added the
contents of the word at
TABLE1+l (which is 3) to ACfJ,
which now contains 5. OK.

MOVE 2 (IDX)

DDT displays the next
instruction.
<ESC>x

2-14

Press <ESC> and enter "x"
to execute the instruction.

GETTING STARTED WITH DDT
Figure 2-2:

Annotated Debugging Session (Cont.)

SCREEN DISPLAY

ADDEM+3/

USER INPUT

TABLEl+2/

The instruction moved the
contents of the word at
TABLEl+2 to AC0.
The MOVE
instruction at ADDEM+2 should
be MOVEM.

POPJ P,0

DDT displays the next
instruction (as a result of
the <ESC>x).
<BKSP>

ADDEM+2/

EXPLANATION

MOVE 2 (lOX)

Press <BKSP> to display and
open the location with the
incorrect instruction.
DDT displays the previous
instruction. This is the
incorrect instruction.

movem r0,answer{idxJ<RET>
Enter the new instruction
and press <RET> •

Check the current location
to see what you deposited.

MOVEM 2{IDX)

Looks OK.

$2B»START/

.<ESC>b

Set a breakpoint at
".", the current location.

<ESC>g

Restart the program at
the beginning.

MOVE P,PWORD

DDT displays the breakpoint
information.
<ESC>p

$lB»START+2/

DDT displays the breakpoint
information.

PUSHJ P,ADDEM
<ESC>p

$3B»ADDEM+2/

MOVEM 2 (lOX)

TABLEl+2/

Proceed from breakpoint 1.
DDT displays the breakpoint
information. This is the
instruction you changed.

<ESC>x

Press <ESC> and enter "p" to
proceed from breakpoint 2
to the next breakpoint.

Single-step the instruction
to watch what it does.
The instruction moves the
contents of AC0 to the word
at TABLEl+2. OK!!

2-15

GETTING STARTED WITH DDT
Figure 2-2:

Annotated Debugging Session (Cont.)

SCREEN DISPLAY
ADDEM+31

USER INPUT

DDT also displays the address
and contents of the next
instruction.

POPJ P,0

start+4<ESC>b

<ESC>p
$4B»START+4I

MOVE 2(IDX}

START+51

TABLEl+21

Set a breakpoint at
START+4 to check the results.
Proceed from breakpoint 3.
DDT displays the breakpoint
information.

<ESC>x

EXPLANATION

Single-step the instruction.
The instruction moves the
contents of the word at
TABLEl+2 to AC0. The new
value of AC0 is 5. OK!

JFCL 0

DDT displays the address and
contents of the next
instruction.
<CTRL/Z>

Quit.
Back at TOPS-10 command level.

2-16

GETTING STARTED WITH DDT
Figure 2-3 shows the session as it actually appears on the terminal
screen.
Again, user input is in lowercase. Comments on the right
indicate where you enter characters that do not echo.
Figure 2-3:

Terminal Display of Debugging Session

.debug x
MACRO:
X
Load ing
LINK:
[LNKDEB DDT execution]
DDT
start/
MOVE P,PWORD#
DDTEND+l/
MOVEI IDX,TABLEl#
ddtend$k
x$:
TABLEl/
0
2
TABLEl+l/
0
3
TABLEl+2/
0
$
START+l/
MOVEI IDX,TABLEl
START+2/
PUSHJ P,ADDEM
.$b
$g
$$x
$lB»START+2/
PUSHJ P,ADDEM
START+3/
MOVEI IDX,TABLEl
$x
IDX/
TABLEl
TABLEl
START+4/
MOVE 2(IDX)
$
TABLEl+2/
0
TABLEl+l/
3
TABLEl/
2
start$b
$g
$2B»START/
MOVE P,PWORD
$x
P/
-l0"PWORD
PWORD/
-l0"PWORD
START+l/
MOVEI IDX,TABLEl
$x
lDX/
TABLEl
TABLEl
START+2/
PUSHJ P,ADDEM
$x
P/
-7"STACK
<JUMP>
ADDEM/
MOVE 0(lDX)
$x
2
0/
2
TABLEl/
$x
ADDEM+l/
ADD l(IDX)
0/
5
TABLEl+l/
3
ADDEM+2/
MOVE 2(lDX)
$x
0/
0
TABLEl+2/
o
ADDEM+3/
POPJ P,0
ADDEM+2/
MOVE 2(IDX)
movem r0,answer(idx)
•/
MOVEM 2 (IDX)
• $b
$g
$2B»START/
MOVE P,PWORD
$p
$p
$lB»START+2/
PUSHJ P,ADDEM
$x
$3B»ADDEM+2/
MOVEM 2(IDX)
0/
5
TABLEl+2/
5
$p
ADDEM+3/
POPJ P,0
start+4$b
$4B»START+4/
MOVE 2(IDX)
$x
0/
5
TABLE1+2/
5
START+5/
JFCL 0
Z
A

2-17

Enter
Enter
Enter
Enter
Enter
Enter

<LF>.
<TAB>.
<LF>.
<LF>.
<ESC><RET>.
<LF>.

Enter <ESC><TAB>.
Enter <BKSP>.
Enter <BKSP>.

Enter <BKSP>.
Enter <RET> •

GETTING STARTED WITH DDT
2.5

PROGRAMMING WITH DDT IN MIND

There are a few MACRO-10 programming techniques that make debugging
with DDT easier. These techniques primarily concern the use of labels
and symbols.
Labels that meaningfully describe (perhaps mnemonically) the function
of the code are more helpful when examining code and setting
breakpoints than labels that are alphanumerically coded
(such as
A0001).
When using symbols as offsets into tables, you can prevent DDT from
displaying the offset symbol in place of the symbol's numeric value if
you define the symbol in this way:
symbol==expression
Symbol is still entered in the symbol table, and you can use symbol as
input to DDT, but DDT does not display symbol on output.
For example, if you have defined:
OFFSET==3
DDT displays the contents of a word that contains the value of 3 as:
addr/

rather than:
addr/

OFFSET

where addr is the address of the word.
See the MACRO Assembler
Reference Manual for more information about defining symbols.

2-18

CHAPTER 3
DDT COMMAND FORMAT

3.1

COMMAND SYNTAX

The complete syntax of a DDT commana is:
{argl<}{arg2>}{arg3}{<ESC>{<ESC>}{arg4}}c{arg5}
where argl, arg2, arg3, arg4, and arg5 are arguments to the command c.
Argl,
arg2,
and arg3 can be any legal DDT expression. Argl must be
followed by a left angle bracket «), and arg2 must be followed by a
right angle bracket (». Arg4 can only be a number. Arg5 is a text
argument of the form:
Itextl

c<ESC>

where text is a string of characters, the slashes (I)
are delimiters
that can be any character not contained in text, and c is a single
character.
DDT commands never use all five arguments.
Each argument is
or required according to the syntax of the specific command.
commands are not more complicated than:
arg3<ESC>c

optional
Most DDT

arg3<ESC>arg4c

You can enter alphabetic commands and text arguments in
lowercase.

uppercase

An argument to a command can be the result of executing another
command.
For example,
you can enter a command to evaluate a text
string, and then enter another command to deposit in memory the result
of evaluating the text string. The entire command line would be:
"/abcd/<RET>
where labcdl is the argument to the command" (quotation mark).
The
function of the quotation mark command
is to evaluate the string
(abcd) within the delimiters (I) as a left-justified ASCII string.
The left-justified ASCII string abcd is then the argument to the
command <RET> (entered by pressing the RETURN key). The function of
the <RET> command is to deposit an argument (in this case, the string
abcd) into the open location. The" command is described
in this
chapter,
and the <RET> command is described in Chapter 4 (Displaying
and Modifying Memory).

3-1

DDT COMMAND FORMAT
Most commands produce results that are immediately visible, such as
commands that display the contents vf memory locations. However,
commands such as those that invoke search functions or those that
evaluate text expressions (as above) may not produce immediately
visible results. If you enter a question mark (?) while DDT is
performing a function invoked by one of these commands, DDT displays a
message that tells you what DDT is currently doing. For example, such
a message might be:
Searching: addr/

value

where addr is the address that DDT is to next test as part of a
search, and value is the contents of the memory location at addr.
Still other commands return values that DDT does not display, but--can
use as arguments to other commands.

3.2

INPUT TO DDT

You enter arguments to DDT as expressions. An expression can be a
single value, or a combination of two or more values with one or more
operators.

3.2.1

Values in DDT Expressions

Values in DDT expressions can be:
o

octal or decimal integers

floating point numbers

symbols

values that are returned by commands

text

To enter an octal integer value, simply enter
digits. For example:

the

integer

octal

To enter a decimal integer value, enter the integer in decimal
and follow the value with a decimal point. For example:

digits

7e707065

9876.

To enter a floating point number, use regular or scientific notation.
For example, you can enter the value .034 as one of the following:
.034
3.4E-2
Note that L.
number.

is a decimal integer, while

3-2

1.0

floating

point

DDT COMMAND FORMAT
To enter a symbol as a value in an expression, type in the symbol name
as defined in your program. To enter an undefined symbol that you can
define later, enter:
symbo1#
where symbol is the symbol that you will later define. See Chapter 7
(Manipulating Symbols in DDT)
for more
information about using
undefined symbols.
You can enter a command that returns a
expression.
DDT commanas--that return
return are listed in Table 3-1.
Table 3-1:

value as a value in an
values and the values they

Commands That Return Values

COMMAND

VALUE RETURNED

VALUE ALSO
KNOWN AS

The address of the current location.

The address of the next user program
instruction to be executed.

The previous value of "<ESC>.".

$$.

<ESC>nB

The address of the DDT location that
contains the address of breakpoint n.

$nB

<ESC>nI

The address of the DDT location that
contains the saved machine state flags
(user-program context).

<ESC>nM

The address of DDT "mask" n.

<ESC>Q

The current quantity.

<ESC>.
<ESC><ESC>.

<ESC><ESC>Q
<ESC>nU

The
current
swapped.

quantity,

with

$$Q

halves

The address of the DDT location that
contains the argument (or default) that
was given in the virtual addressing
command: expr<ESC>nU.

The commands <ESC>nB, <ESC>nI, <ESC>nM, and <ESC>nU,
return values
that are the addresses of locations internal to DDT, which contain
information that you can use and modify.
For brevity, these commands
are said to address those internal DDT locations.
For example, the command <ESC>nB returns (but does not display)
the
address of the DDT location that contains the address of breakpoint n,
and the command addr/
(address followed by slash)
displays the
contents of the location at addr.
To display the address of
breakpoint n, enter:
<ESC>nB/
where you enter the command <ESC>nB
evaluate as addr.

3-3

the

expression

for

DDT

DDT COMMAND FORMAT
You can enter text to be interpreted in the following ways:
o

left-justified ASCII strings

left-justified SIXSIT strings

single right-justified ASCII characters

single right-justified SIXSIT characters

RADIX50 words

You can enter text expressions in uppercase or lowercase.
DDT
translates strings to uppercase for SIXSIT or RADIX50 text as
required.
The term long text string refers to an expression in a DDT command
that is a string of text characters that requires more than one 36-bit
expression for full evaluation. You can enter long text strings in
SIXSIT and ASCII as DDT expressions.
If you use a long text string as
an expression, DDT assumes that you will enter a command that deposits
the expression in memory.
DDT evaluates the string one 36-bit expression at a time.
After
evaluating the first 36-bit expression, DDT deposits the expression in
the open location, closes the open location, and opens the next
location.
DDT then evaluates the next 36-bit expression contained in the string,
and deposits that expression in the (new) open location. This process
continues until you enter c, the command.
If you enter a command that
does deposit to memory,-DDT deposits the final 36-bit expression in
the open location, and updates the location counter according to the
rules of that particular command. The current quantity is the last
36-bit expression that DDT evaluated.
If you do not enter a command that deposits to memory, DDT uses, as
the argument to the command, the 36-bit expression that was last
evaluated. All other 36-bit expressions that were evaluated as part
of the string have been deposited, and the current and open locations
were updated accordingly. The current quantity is then the last
36-bit expression that DDT evaluated.
If there is no open location when you begin typing the long text
string, DDT evaluates only the first 36-bit expression, ignores the
rest of the string, and uses the first 36-bit expression as the
argument to the command.
The current quantity is then the first
36-bit expression that DDT evaluated in the string.
If you enter a
command that deposits to memory, it has no effect because there was no
open location.
The syntax to enter an ASCII string is:
"/textl
where text is the
character that is
as a series of
(left-justified),

string, and the slashes (I) represent any printing
not contained within text. DDT evaluates the string
36-bit expressions, -each in 7-bit ASCII format
with all unused bits reset.

3-4

DDT COMMAND FORMAT
For example, if you enter:
"+abc/def+
DDT evaluates one 36-bit expression as the 7-bit ASCII string abc/d in
bits 0-34, and bit 35 reset.
If there is no open location, DDT uses
that expression as the argument to the command, and that expression
becomes the current quantity.
If there is an open location, DDT deposits abc/d in the open location,
closes it, and opens the next location in memory. DDT then evaluates
a second 36-bit expression as the 7-bit ASCII string ef in bits 0-13,
and bits 14-35 reset. The last 36-bit expression evaluated becomes
the current quantity.
NOTE
You cannot use this format to enter an ASCII string
that begins with the ESCAPE character, because <ESC>
terminates the
command
that
enters
a
single
right-justified ASCII character
(in this case, your
intended delimiter).
The syntax to enter a SIXBIT string is:
<ESC>"/text/
where text is the string,and the slashes (/)
represent any printing
character that is not contained within text.
DDT evaluates the string
as a series of 36-bit
expressions-,---each
in
SIXBIT
format
(left-justified), with any unused bits in the last 36-bit expression
reset. DDT translates lowercase characters to uppercase;
all other
non-SIXBIT characters cause DDT to sound your terminal buzzer or bell
and display a question mark.
For example, if you enter:
<ESC>">qwertyu>
DDT evaluates one 36-bit expression as the SIXBIT string QWERTY in
bits 0-35.
If there is no open location, DDT uses that expression as
the argument to the command, and that expression becomes the current
quantity.
If there is an open location,
DDT deposits QWERTY in the open
location, closes it, and opens the next location in memory. DDT then
evaluates a second 36-bit expression as the SIXBIT character U in bits
0-5, with bits 6-35 reset.
The last 36-bit expression evaluated
becomes the current quantity.
NOTE
You cannot use this format to enter a SIXBIT string
that begins with the ESCAPE character, because <ESC>
terminates the
command
that
enters
a
single
right-justified SIXBIT character (in this case, your
intended delimiter).
The syntax to enter a right-justified ASCII character is:
"c<ESC>
where c is the character. DDT evaluates this as one 36-bit expression
with the 7-bit ASCII character ~ in bits 29-35, and bits 0-28 reset.
3-5

DDT COMMAND FORMAT
The syntax to enter a right-justified SIXBIT character is:
<ESC>"c<ESC>
where c is the character. DDT evaluates one 36-bit expression with
the SIXBIT character c
in bits 30-35, and bits 0-29 reset. DDT
translates lowercase characters to uppercase;
all other non-SIXBIT
characters cause DDT to sound your terminal buzzer or bell and display
a question mark.
The syntax to enter a RADIX50 word is:
text<ESC>5"
where text is any string of RADIX50 characters up to six characters
long. DDT evaluates one 36-bit expression with bits 0-3 reset and the
RADIX50 string text in bits 4-35. DDT ignores any characters in text
after the sixth-.--For example, if you enter:
poiuytr<ESC>5"
DDT evaluates one 36-bit expression with bits 0-3 reset and the
RADIX50 string POIUYT in bits 4-35. DDT ignores the character r. DDT
translates lowercase characters to uppercase.
Characters in text not
in the RADIX50 character set that are DDT commands use, as an argument
to the command, any characters already entered.
Characters in text
not in the RADIX50 character set that are not DDT commands cause DDT
to sound your terminal buzzer or bell and display a question mark.

3.2.2

Operators in DDT Expressions

When you enter an expression, DDT evaluates the expression to create a
36-bit quantity but does not necessarily use all 36 bits when it
executes the command. For example, you can enter a complete MACRO
instruction when giving an argument to a command that requires an
address, but DDT uses only the address specified by the instruction
(and ignores the rest of the evaluated expression) when it executes
the command.
Table 3-2 lists DDT's expression operators and the effects those
operators produce on the evaluation. The term value so far represents
the accumulated 36-bit value resulting from evaluation of
the
expression to that point.

3-6

DDT COMMAND FORMAT
Table 3-2:

Effects of Operators When Evaluating Expressions

OPERATOR

EFFECT ON EVALUATION

Add the 36-bit value on the left to the 36-bit
value on the right,
using two's complement
addition.
Subtract the 36-bit value on the right from the
36-bit value on the left, using two's complement
subtraction.

(apostrophe)

Multiply the 36-bit value on the left by the
36-bit
value
on
the right,
uSlng PDP-10
full-word integer multiplication. DDT uses only
the low-order 36 bits of the result.
Divide the 36-bit value on the left by the
value
on
the right,
using PDP-10
36-bit
full-word
integer division. DDT ignores any
remainder.
NOTE
Apostrophe
is
DDT's
division
operator.
/
(slash)
is a DDT
command to examine memory,
and
is
never
used
in DDT to indicate
division.

space

Add the previous expression (normally an opcode)
to the value so far, and add the low-order 18
bits of the value at the right of the space to
the low-order 18 bits of the value so far.
DDT
ignores carries resulting from the addition, and
does not change the left half of the value so
far.

(comma)

If you are entering an I/O instruction, shift
the low-order 18 bits of the expression at the
left of the comma 26 bits to the left (to the
device field of the
instruction), otherwise
shift the low-order 18 bits of the expression at
the left of the comma 23 bits to the left (to
the A field of an instruction). Then logically
OR the result into the value so far.
NOTE
DDT does not check whether the
value at the left of the comma is a
legitimate device or AC address,
and may overwrite other parts of
the instruction.

3-7

DDT COMMAND FORMAT
Table 3-2:

Effects of Operators When Evaluating Expressions (Cont.)

OPERATOR

EFFECT ON EVALUATION

()

Swap the halves of the expression within the
parentheses and add the resulting expression to
the value so far. This makes it possible to
enter
an
instruction
that uses an index
register.
NOTE
DDT does not check whether the
value within the parentheses is a
legitimate AC address, and
may
overwrite
other
parts
of the
instruction.

(two commas)

Assume the expression is an instruction and set
the indirect bit (bit 13) of the value so far.
Move the low-order bits of the expression at the
left of the commas to bits 0-17 and build a new
18-bit expression in the right half.

The nonarithmetic operators allow you to
instruction format as well as in data format.

enter

To enter an instruction, format the instruction
MACRO-10 program. For example:

expressions
you

would

in
in

MOVE R4,@VAR1+0FFSET{R5)
NOTE
Follow an opcode (such as MOVE) with a
<TAB>.

space,

not

To enter halfwords, enter the values (numbers or symbols) separated by
two commas (,,).
The halfwords can be symbolic or absolute values.
For example:
-1"SYM1
NOTE
DDT is not designed to evaluate complicated arithmetic
expressions.
The
nonarithmetic
operators
are
implemented to enable DDT to evaluate expressions you
enter as MACRO-10 instructions and halfwords. Using
values and operators for other purposes may not
produce the results you intend.

3-8

April 1986

DDT COMMAND FORMAT
3.3

COMMAND FILES

If you frequently use DDT or FILDDT to debug the same file
(such as
the monitor), and execute the same commands each time (such as loading
symbols, suppressing symbols, applying patches, and setting virtual
addressing conditions),
you can save time by creating a file that
contains these commands. At any time that you are in DDT you can give
the command:
<ESC>Y
to indicate that you wish to load a command file.

DDT prompts:

File:
Enter the file specification, followed by <RET>.
You can enter a
complete TOPS-10 file specification. DDT reads the file and executes
the commands.
If you append /A after the file specification, DDT
stops executing the command file if it encounters any errors while
executing the commands in the file.
If you do not use the /A switch,
DDT executes all legal commands in the control file regardless of any
errors.
An alternate form of the command is:
filnam<ESC>Y
where filnam is a SIXBIT file name up to six characters long, with
default device DSK:
and default extension .DDT.
For example, to have
DDT execute the DDT commands contained in frre-DSK:PROG.DDT, enter:
<ESC>"/PROG/<ESC>Y
The delimiters (/) can be any character not in filnam.
If bit 15 of the TTY control mask is reset, DDT displays the commands
and resulting output as i~xecutes them.
If bit 15 is set, DDT
suppresses the display. The command <ESC>IM returns the address of
the DDT location that contains the TTY control mask.
See Chapter 4
(Displaying and Modifying Memory) for more information about the TTY
control mask.

3-9

CHAPTER 4
DISPLAYING AND MODIFYING MEMORY

4.1

DISPLAY MODES

A major function of DDT is displaying the contents of memory words,
both data and instructions.
You can choose whether to display the
contents of memory words as symbols or as numeric values.
You can
also select the radix in which DDT displays numeric values.
DDT displays symbols, labels, and most messages in uppercase.

4.1.1

Default Display Modes

There is no sure way for DDT to distinguish between instruction
data words, or between data words of different formats.

and

DDT displays memory words in symbolic mode by default. Symbolic mode
is described in Table 4-1. DDT tests for the condition on the left,
and if the condition is met, displays the word in the format described
on the right.
DDT performs the tests in descending order.
Table 4-1:

Evaluation of Symbolic Display Mode
CONDITION

DDT DISPLAYS

EXAMPLE

Bits 0-18 are all set.

A negative number
in
the current
radix.

-45

The 36-bit value is defined
in the user program symbol
table.

The symbol.

SYMBLl
HALT

The opcode field is zero.

Halfwords.

345,,-27

The opcode and I, X, and Y
fields, or the opcode and A
fields match an OPDEF in the
user program symbol table.

The OPDEF.

CORE 6,

The
opcode
matches
a
definition in DDT's internal
hardware instruction table.

The instruction.

MOVE 3,SYMBL

No match.

Halfwords.

3445,,-23

4-1

DISPLAYING AND MODIFYING MEMORY
By default, DDT displays numeric values in radix 8.
always suppressed.

4.1.2

Leading zeros are

Selecting Display Modes

You can select display modes to control:
o

the format in which DDT tries to interpret the contents
memory
locations; for example, as instructions, or
floating-point numbers.

whether
values.

the radix in which numeric values are displayed.

addresses

are

displayed

In addition, you can specify these modes on
mode) or long-term (prevailing mode) basis.

symbolic

short-term

of
as

numeric

(temporary

A prevailing display mode remains in effect until you select another
prevailing mode, but may be overridden by a temporary mode until you
enter a command that restores the prevailing display mode.
DDT
commands that restore the prevailing display mode are:
0

{expr}<RET>

(deposit expr and close location)

<ESC>G

(start program execution)

<ESC>P

(proceed from a breakpoint)

<ESC>W, <ESC>E, <ESC>N

(perform a search)

<ESC>Z

(zero memory)

instr<ESC>X

(execute instr)

<ESC>Y

(execute DDT command file)

<ESC>V

(watch a location)

The syntax of commands that set the prevailing mode is:
<ESC><ESC>mode
where mode is one of the display modes shown in Table 4-2.
The syntax of commands that set a temporary mode is:
<ESC>mode
where mode is one of the display modes shown in Table 4-2.
The current display mode is the mode (prevailing or temporary)
in
which DDT will display the next word (unless you enter a .command to
change the display mode).

4-2

DISPLAYING AND MODIFYING MEMORY
DDT has two "masks" that control the action
modes.

two

the

display

<ESC>3M is a command that addresses a DDT location that contains the
output byte size mask. When the current display mode is 0, each bit
that is set in the mask indicates the position of a low order bit of a
byte in the word being displayed.
In this mode, bit 35 is always
assumed to be set.
For example,
if the output byte size mask
contains:
510410100400

(octal)

the byte sizes specified are, from left to right, 1, 2, 3, 4, 5, 6, 7,
and 8. When displaying a word in 0 mode that contains 777777,,777777,
and the current radix is 8, DDT displays:
1,3,7,17,37,77,177,377
The default value of the output byte size mask is zero, specifying one
36-bit byte.
You can set the output byte size mask with the command:
expr<ESC>3M
where expr evaluates to the bit pattern required.
You can also examine and change the output byte size mask with
examine and deposit commands described later in this chapter.

the

<ESC>2M is a command that addresses a DDT location that contains the
maximum symbolic offset. When DDT displays an address in R(elative)
mode, it displays the address symbolically, that is, as a symbol, or
as a symbol + the numeric offset of the address from that symbol. The
maximum symbolic offset
(minus 1)
determines the maximum offset
address that DDT displays symbolically, and defaults to 1000 (octal).
DDT displays addresses beyond that offset in A(bsolute)
mode.
For
example, assume that the maximum symbolic offset is 2, and that you
are examining subroutine ADDEM in program X.MAC (Fig 2-1), using <LF>
to display instructions in sequence. DDT displays:
ADDEM/
MOVE 0(6)
ADDEM+1/
ADD 1(6)
addr/
MOVE 2(6)
where addr is
location:-

the

absolute

address

(for

example,

14414)

the

You can also examine and change the maximum symbolic offset with
examine and deposit commands described later in this chapter.

the

You can set the maximum symbolic offset with the command:
expr<ESC>2M
where expr evaluates to the offset required.

4-3

DISPLAYING AND MODIFYING MEMORY
DDT display modes and the commands that select them are
Table 4-2.
Table 4-2:

described

DDT Display Modes
FORMAT MODES

MODE

EFFECT

Display memory word as numbers in the current radix (see
Radix Modes).

Display m,emory word as a floating point decimal number.

Display memory word as two halfword addresses
Address Modes) separated by two commas ( , ,)

(see

Display memory word as numeric bytes of sizes
specified by the <ESC>3M mask.

are

Display memory word as n-bit numeric
trailing remainder byte, as required) •

Display memory word in symbolic mode (default) •

Search DDT's internal hardware opcode table before
searching the user's symbol table, otherwise follow
rules for symbolic mode.

Display memory word as ASCII text, using n-bit bytes.

n=5:

RADIX50

n=6:

SIXBIT

n=7 through 36:
Specifies the number of
default is 7-bit ASCII.
n=0:

bits

per

that

bytes,

(with

byte.

The

ASCIZ
(Stop ASCIZ typeout by typing any character.)

Display addresses as
radix.

Display addresses as values
relative
to
symbols
DDT displays the offsets in the current
(default).
radix. The maximum offset is controlled by the value
stored in the <ESC>2M mask, and defaults to 1000
(octal) •

absolute

values

the

current

RADIX MODES
MODE

EFFECT

Display numeric values in radix n (default=8), where n
is a decimal number greater than 1.
If n=8, DDT
displays the word as octal halfwords, otherwise DDT
displays the word as one number.

DDT V44

4-4

April 1986

DISPLAYING AND MODIFYING MEMORY
4.2

DISPLAYING EXPRESSIONS

DDT has three commands you can use to display expressions in different
modes.
They are:
(semicolon)
(equal sign)
(underscore)
The syntax of these commands is:
{expr}c
where expr is the expression to display (expr defaults to the current
quantity), and c
is one of the above commands. These commands are
useful for redisplaying the current quantity without affecting the
current display mode.
Table 4-3 lists the commands to display
expressions and their effects.
Table 4-3:

Commands to Display Expressions

COMMAND

EFFECT

expri
=
expr=

expr_

4.3

Display the current quantity in the
mode.

current

display

Display expr in the current display mode.
Display the current
current radix.

quantity

number

the

Display expr as a number in the current radix.
Display the current quantity in 1$ mode.
Display expr in 1$ mode.

DISPLAYING BYTE POINTERS

If you set the display mode to IT, DDT displays the contents of the
memory location as a byte pointer. DDT can display one-word local,
one-word global, and two-word byte pointers. DDT displays the P and S
fields, and the address as determined by the I, X, and Y fields of the
byte pointer.
In section zero, DDT displays only one-word byte pointers
global).

(local

and

For example, if the contents of the location at ADDR2 is 100702"addr,
where addr is the value of symbol LABL2, the following illustrates
one-word local byte pointer display:
addr2/

DDT V44

100702"addr

<ESC>lTi

4-5

10 7 LABL2(2)

April 1986

DISPLAYING AND MODIFYING MEMORY
The following illustrates one-word global byte pointer display,
addr is the value of symbol LABL2:
1"addr2/

610002"LABL2

<ESC>lT;

where

44&7 2"LABL2

The following illustrates two-word global byte pointer display,
addr is the value of symbol LABL2 (DDT echoes <BKSP> as ~H):

where

440740,,0
<LF>
1"addr2/
3"addr
<ESC>lT~H
1"addr2+1/
44 7 3"MAIN. <2>
1"addr2/

4.4

DISPLAYING AND DEPOSITING IN MEMORY

DDT allows you to display the contents of memory locations and deposit
a new value in the open location. In performing these functions, you
must understand the concept of the open location, the current
location, the location sequence stack, and the current quantity.
The open location is a memory location (or AC) that is "open" for
modification by the next command.
There is never more than one
location open at a time. DDT always closes the open location before
opening another.
The location counter contains the address of a word in memory that has
been referenced (implicitly or exp~icitly) by the previous command,
and that is the default point of reference for the next command. That
word is known as the current location. DDT uses the address of the
current location as the default address in most commands. The current
location is often, qut not always, the open location.
Most DDT commands change the current location to a word specified by
an address given (explicitly or by default) in the command. Commands
that do not are so indicated.
"." (period) is a command that returns
address of the current location.

(but

does

not

display)

the

When you first enter DDT, the current location is zero.
The location sequence stack is a "ring" of seventeen words, each
containing the address of a prior current location, or of a match
found during a search. The present value of the current location is
not placed in the ring.
Entries are made to and retrieved from the location sequence stack in
a last-in, first-out manner. Most commands that change the location
counter by values other than +1 and -1 cause DDT to place the address
of the current location (before the change) on the location sequence
stack. Addresses of matching locations found during searches are also
placed on the location sequence stack. When DDT enters a new value in
the next word on the stack, the new value becomes the current location
stack entry. This is similar to PUSHing entries on a stack. When the
current location stack entry is the last location on the location
sequence stack, DDT enters a new value on the stack by "wrapping
around" to the beginning of the stack and overwriting the value in the
first location on the stack. The first location on the stack then
contains the current location stack entry.

DDT V44

4-6

April 1986

DISPLAYING AND MODIFYING MEMORY
Certain DDT commands change the address of the current location to the
current location stack entry, and then change the current location
stack entry to the previous entry. This is similar to POPping entries
off a stack, and allows y~u to "return" to locations that have
previously been the current location. When the first location on the
location sequence stack contains the current location stack entry and
DDT changes the address of the current location to the current
location stack entry, DDT "wraps around" to the end of the stack, and
the value contained in the last word o·f the stack becomes the current
location stack entry (whether or not the stack was previously "full").
The current quantity is a value that is the most recent of:
o

the last 36-bit quantity that DDT displayed (an expression or
the contents of a memory location)

the last expression that you entered
command that deposits to memory

argument

This value is also known as the last value typed. <ESC>Q is a command
that returns (but does not display) the current quantity. DDT issues
an implicit <ESC>Q to return this value for use as the default
argument for some commands.
You can give the current quantity as an argument
entering the command <ESC>Q as the argument.
The command <ESC><ESC>Q returns the current quantity
and left halves swapped.

command

with

the

right

This manual uses the term $Q to refer to the value that is returned by
the command <ESC>Q, and the term $$Q to refer to the value that is
returned by the command <ESC><ESC>Q.
Some commands calculate the address of the location to be opened from
an expression given or defaulted in the command. Other commands use
the address of the current location or entries on the location
sequence stack.
The general syntax of these commands is:
{expr}{<ESC>}c
where expr is any legal DDT expression, and c is the command.
NOTE
See Values in DDT Expressions in Chapter 3 for a
discussion of long text strings as values in DDT
expressions.

4-7

DISPLAYING AND MODIFYING MEMORY
Table 4-4 summarizes the commands and their
descriptions of the commands follow the table.
Table 4-4:

effects.

Complete

DDT Commands to Display Memory

COMMAND

DISPLAY
CONTENTS

MODE
OF
DISPLAY

OPEN
THE
LOCATION

CHANGE
CURRENT
LOCATION

DEPOSIT
EXPR

Yes

Current

Yes

Yes(l)

[

Yes

Numeric

Yes

Yes(l)

]

Yes

Symbolic

Yes

Yes(l)

Suppress

Yes

Yes(l)

Yes(2)

Current

Yes

Yes(l)

<TAB>

Yes(2)

Current

Yes

Yes(l)

<RET>

Restore

Yes(l)

<LF>

Yes(2)

Current

Yes

Yes(.+l)

Yes(l)

<BKSP>
or '"

Yes(2)

Current

Yes

Yes ( • -1)

Yes (1)

(1 )

If you enter expr.

(2)

If not suppressed by 1 •

4.4.1

Commands That Use the Current Location

The commands <RET>, <LF>, and <BKSP> use the address of the current
location to determine the next address of the current location.
These commands do not make entries to the location sequence stack.
{expr}<RET> does the following:
o

deposits expr (if given)

in the open location

closes the open location

resets the current typeout mode
mode

does not change the address of the current location

4-8

the

prevailing

typeout

April 1986

DISPLAYING AND MODIFYING MEMORY
{expr}<LF> does the following:
o

deposits expr (if given)

closes the open location

increments the location counter

opens the current location

displays the open
suppressed by 1)

{expr}<BKSP>

and

in the open location

location

(unless

display

has

been

{expr}A do the following:

deposit expr (if given)

close the open location

decrement the location counter

open the current location

display the open location (unless display has been suppressed
by 1)

4.4.2

in the open location

Commands That Use the Location Sequence Stack

The commands <ESC><RET>, <ESC><LF>, and <ESC><BKSP> use the current
location stack entry to determine the next address of the current
location.
Repetitions of these commands refer to successively earlier entries on
the stack, until you again address the most recent entry.
These commands do not make entries to the. location sequence stack.
{expr}<ESC><RET> does the following:
o

deposits expr (if given)

in the open location

closes the open location

changes the value contained in the location
current location stack entry

opens the current location

starts a new line and displays the address and
the open location in the current display mode

causes the previous entry on the location sequence
become the current location stack entry

counter

the

contents

stack

NOTE
If display is suppressed as a result of using the
command,
the command {expr}<ESC><RET> restores the
current display mode, which can be either a
temporary
or prevailing display mode.

4-9

April 1986

DISPLAYING AND MODIFYING MEMORY
{expr}<ESC><LF> does the following:
o

deposits expr (if given) in the open location

closes the open location

changes the value contained in the location
current location stack entry

increments the location counter

opens the current location

starts a new line
location

displays the contents of the open
has been suppressed by 1)

causes the previous entry on the location sequence
become the current location stack entry

{expr}<ESC><BKSP>

4.4.3

and

displays

the

counter

address

location

(unless

the

open

display
stack

the

{expr}<ESC>A do the following:

deposit expr (if given) in the open location

close the open location

change the value contained in the
current location stack entry

decrement the location counter

open the current location

display the address of the open location

display the contents of the open location (unless display has
been suppressed by!)

cause the previous entry on the location
become the current location stack entry

location

counter

sequence

stack

Commands That Use an Address Within the Command

The commands:
/

[
]

\
<TAB>

(slash)
(left square bracket)
(right square bracket)
(exclamation point)
(backslash)

use an expression given
default) to determine
open location.

in the command (either explicitly or by
the addresses of the current location and the

4-10

April 1986

DISPLAYING AND MODIFYING MEMORY
The complete syntax of these commands is:
{expr}{<ESC>{<ESC>}}c
where expr may be an address, ".", a symbol, or any expression that is
legal in DDT, and c is the command.
When you use the commands /, [, ], 1, \, and <TAB>:
o

If you omit expr
>

DDT uses the current quantity as a default.

<TAB> enters the address of the current location on the
location sequence stack and changes the current location
to the address determined from the current quantity.

If you enter fixpr, DDT enters the address of the
location on t e location sequence stack (except \).

DDT treats expr (whether given or defaulted) as if it were in
instruction
format
and performs the effective address
calculation as follows:
>
>

current

If you omit <ESC>, DDT does not perform indexing or
indirection.
,
If you include one <ESC>, DDT treats expr as an IFIW
(instruction format indirect word), and uses the I and Y
fields of expr to perform indexing and indirection when
appropriate.

If you use <ESC><ESC>, DDT utilizes EFIWs (extended
format indirect words), as appropriate,. when performing
effective address calculations, and can thereby calculate
30-bit addresses.

In section zero, when
treated as one <ESC>.

you

include

<ESC><ESC>,

These commands always do the following:
o

close the open location

open the location at the address indicated by expr

change the current
commands except 1)

The following is a list that
effects of each command.
COMMAND

quantity
gives

to
a

the

complete

value

displayed

description

(all
the

EFFECTS

/
o

closes the open location

opens the location at the address calculated from the current
quantity

displays the contents of the open
display mode

sets the current quantity to the value displayed
4-11

location

the

current

DISPLAYING AND MODIFYING MEMORY
expr/
o

closes the open location

opens the location at the address calculated from expr

enters the address of the current location
sequence stack

the

location

changes the current location to the location at
calculated from expr

the

address

displays the contents of the open
display mode

the

current

sets the current quantity to the value displayed

closes the open location

opens the location at the address calculated from the current
quantity

displays the contents of the open location in numeric mode in
the current radix

sets the current quantity to the value displayed

closes the open location

opens the location at the address calculated from expr

enters the address of the current location
sequence stack

the

location

changes the current location to the location at
calculated from expr

the

address

displays the contents of the open location in numeric mode in
the current radix

sets the current display mode to numeric mode in the
radix

sets the current quantity to the value displayed

closes the open location

opens the location at the address calculated from the current
quantity

displays the contents of the open location in symbolic mode

sets the current display mode to symbolic mode

sets the current quantity to the value displayed

location

expr[

4-12

current

DISPLAYING AND MODIFYING MEMORY
expr]
o

closes the open location

opens the location at the address calculated from expr

enters the address of the current location
sequence stack

the

location

changes "the current location to the location at
calculated from expr

the

address

displays the contents of the open location in symbolic mode

sets the current display mode to symbolic mode

sets the current quantity to the value displayed

closes the open location

opens the location at the address calculated from the current
quantity

does not display the contents of the open location

suppresses display of the open location by the \, <TAB>,
<LF>, and <BKSP> commands (any other display command restores
the current display mode)

does not change the current quantity

closes the open location

opens the location at the address calculated from expr

enters the address of the current location
sequence stack

the

location

changes the current location to the location at
calculated from expr

the

address

does not display the contents of the open location

suppresses display of the open location by the \, <TAB>,
<LF>, and <BKSP> commands (any other display command restores
the current display mode)

does not change the current quantity

closes the open location

opens the location at the address calculated from the current
quantity

displays the contents of the open location in the current
display mode (unless display has been suppressed by 1)

sets the current quantity to the value displayed

expr!

4-13

DISPLAYING AND MODIFYING MEMORY
expr\
o

deposits expr in the open location

closes the open location

opens the location at the address calculated from expr

does not change the address of the current location (and does
not enter the address of the current location on the location
sequence stack)

displays the contents of the open location in the current
display mode (unless display has been suppressed by 1)

sets the current quantity to the value displayed

closes the open location

opens the location at the address calculated from the current
quantity

enters the address of the current location
sequence stack

changes the current location to the location at
calculated from the current quantity

the

starts a new line and displays the address
location (which is also the current location)

displays the contents of the open location in the current
display mode (unless display has been suppressed by 1)

sets the current quantity to the value displayed

<TAB>

on· the

location
address
the

open

expr<TAB>
o

deposits expr in the open location

closes the open location

opens the location at the address calculated from expr

enters the address of the current location
sequence stack

the

location

changes the current location to the location at
calculated from expr

the

address

starts a new line and displays the address
location (which is also the current location)

displays the contents of the open location in the current
display mode (unless display has been suppressed by 1)

sets the current quantity to the value displayed

4-14

the

open

DISPLAYING AND MODIFYING MEMORY
You can treat e~pr as an IFIW (instruction format indirect word), and
use any indexIng and indirection specified by expr to compute the
effective address of the location to be opened. Use the command form:
{expr}<ESC>c
where c is

I, [, ], 1, \, or <TAB>.

For example, assume the
display commands:
COMMAND

DISPLAY

LABL11
LABL1+11
SYM21
21
@LABL1(2)/
@LABL1(2)<ESC>1

SYM1
SYM2
SYM3
1
SYM1
SYM3

following

conditions

indicated

the

EXPLANATION
Display contents of LABL1.
Display contents of LABL1+1.
Display contents of SYM2.
Display contents of AC 2.
DDT uses Y field only.
<ESC> causes indexing and indirection.

Note that DDT does not start a new line unless you enter <TAB>, <RET>,
<LF> or <BKSP>, or until the display wraps around the end of the line.
DDT also displays three spaces (or a tab, depending on the TTY control
mask)
before and after its output.
Thus, an actual DDT terminal
display might be the following (user input is lowercase;
<LF> and
<TAB> do not appear on the screen, but are shown to indicate where you
pressed the corresponding keys):

21
1
1ab111
SYM1
<LF>
LABL1+11
SYM2
<TAB>
SYM21
SYM3
sym41
MOVE 1,@LABL1(2)
SYM21
SYM3

You can treat expr as an EFIW (extended format indirect word) and use
any indexing and indirection specified by expr to compute the (global)
effective address of the location to be opened. Use the command form:
{expr}<ESC><ESC>c
where c is

4.5

I, [, ], 1, \, or <TAB>.

DISPLAYING ASCIZ STRINGS

You can display memory as an ASCIZ string.

The command

addr<ESC>0T
where addr defaults to the open location (if there is one, otherwise
addr defaults to the current location), displays memory, beginning
with addr, as an ASCIZ string. The display stops when DDT finds a
zero byte, or when you type in any character, which DDT displays, but
otherwise ignores. The current location remains unchanged.

DDT V44

4-15

April 1986

DISPLAYING AND MODIFYING MEMORY
4.6

ZEROING MEMORY

To deposit the same value in each of a string of memory words
for initializing memory to zero), enter:

(useful

addrl<addr2>{expr}<ESC>Z
where expr is any legal DDT expression, addrl is the first word to
receIve expr, and addr2 is the last. Follow addrl with a left angle
bracket «) and addr2 with a right angle bracket (». Both addrl and
addr2 are required. If you omit expr, it defaults to zero. Prior to
execution, DDT enters the address of the current location on the
location sequence stack and closes the open location. When DDT has
completed execution of the command, the current location is the word
at addr2 + 1. There is no open location. This command restores the
prevailing display mode.
If you enter:
?

while DDT is executing the <ESC>Z command, DDT displays:
Depositing:

addr/

value

where addr is the location where DDT will make the next
value is the contents of addr before the deposit.

deposit,

and

If you enter any other character, DDT stops executing the <ESC>Z
command, and waits for your next command. The character that you
enter to terminate the <ESC>Z command is otherwise ignored.

4.7

AUTOMATIC WRITE-ENABLE

If you attempt to change a word that is write-protected, DDT removes
the protection, makes the change, and then reinvokes the protection.
To prevent DDT from changing write-protected memory, enter:
<ESC><ESC>{0}W
If you attempt to modify write-protected memory
write-enable is turned off, DDT returns the message:

while

automatic

?NOT WRITABLE
To allow DDT to change write-protected memory, enter:
<ESC>{0}W
This is the default condition.
The zero in the above commands is optional and has no
operation of the commands.

4-16

effect

the

April 1986

DISPLAYING AND MODIFYING MEMORY
4.8

AUTOMATIC PAGE CREATION

If you attempt to deposit a value in a word within a nonexistent page,
DDT sounds your terminal buzzer or bell and displays a question mark
(?) •

To allow DDT to create a page when
within a nonexistent page, enter:

you

attempt

deposit

word

<ESC>lW
If DDT tries to create the page and fails, DDT displays:
?CAN'T CREATE PAGE
To prevent DDT from creating a page when
value within a nonexistent page, enter:

you

attempt

deposit

<ESC><ESC>lW
This is the default condition.

4.9

DISPLAYING PAGE ACCESSIBILITY INFORMATION

You can get information about the access requirements of the pages and
sections
in the program you are debugging,
using the $L and $$L
commands. The complete format for this command is:
{{argl<}arg2}{<ESC>}<ESC>L
where argl and arg2 are sections numbers.
Using one <ESC> causes DDT
to display access information about the section and about individual
pages.
Using <ESC> twice causes DDT to display access information
only about the section(s).
If you include both argl and arg2, DDT
displays the information for all sections that your program and DDT
are using, in the range argl to arg2, inclusive.
If you include only
arg2, DDT displays access information for that section only.
If you
omit both arguments, DDT displays access information for all sections
that your program and DDT are using.
The page and section accessibility bits and their meanings are:
Read
Write
AA

Sharable
Hiseg
Zero
Spying
Cannot page
Paged out
Locked
Not cached

DDT V44

Page
Page
Page
Page
Page
Page
Page
Page
Page
Page
Page

can be read.
can be written.
access is allowed.
can be shared.
is part of high segment.
is allocated but zero.
is spying on someone.
cannot be paged out.
has been paged out.
is locked in core.
is not cached.

4-17

April 1986

DISPLAYING AND MODIFYING MEMORY
For example, the command <ESC>L might produce the following display:
Section 0
000
001-030
577
600-656

Read,
Read,
Read,
Read,

Write, AA, Cannot page
Write, AA
Write, AA
AA, Sharable, Hiseg

Section 1 indirect to
Read,
000
Read,
001-030
577
Read,
Read,
600-656

section 0
Write, AA, Cannot page
Write, AA
Write, AA
AA, Sharable, Hiseg

Section 3
000-777

Read, Write, AA

Section 4
000-354

Read, Write, AA

And the command
following:

<ESC><ESC>L

might

product

display

the

Section 0
Section 1 indirect to section 0
Section 3
Section 4

4. H~

WATCHING A MEMORY LOCATION

If you wish to have DDT monitor or "watch" a memory location while
your program is running,
and display the location whenever its
contents change, enter:
addr<ESC>V
where addr is the address of the location to be watched, and defaults
to the current location. When you enter the command, DDT starts a new
line and displays:
addr/

value

where addr is the address of the location being watched, and value is
the contents of the location.
This command also restores the
prevailing display mode.
DDT checks addr every "jiffy" (about 20 milliseconds), and displays
the address--and contents of addr whenever those contents change.
(Executive mode EDDT watches addr continuously.)
If you enter a question mark (1) while DDT is watching, DDT displays:
Watching: addr/

value

where addr is the address of the location being watched, and value
the contents of addr.

To terminate the watch, enter any other character.
DDT stops
monitoring the word, starts a new display line, echoes the character
you enter, starts another line, and waits for more input.
The
character that you enter to terminate the watch is otherwise ignored.

DDT V44

4-18

April 1986

DISPLAYING AND MODIFYING MEMORY
Because any input character terminates the watch, you cannot continue
execution and watch your own user program. The <ESC>V command is
useful to watch activity in a separate process (such as the running
monitor or other job, for which you must be using EDDT or FILDDT).
The page that contains the word you wish to watch must be mapped into
your own process (the one that contains DDT and your program).

4.11

TTY CONTROL MASK

You can control certain aspects of DDT's display by setting DDT's TTY
control mask. The command <ESC>lM returns a value that is the address
of the DDT location that contains this mask. Table 4-5 summarizes the
features controlled by the bits in the TTY control mask.
Table 4-5:

TTY Control Mask

BIT

VALUE

Display the commands (and results) from the
executed by the <ESC>Y command (defau1 t) •

Do not display the commands (or resu1 ts)
file executed by the <ESC>Y command.

When interrupting
program
execution
at
a
breakpoint, display the address and contents of
the breakpoint (default) •

When interrupting
execution
program
breakpoint, display only the address
breakpoint.

Display 3 spaces when spacing DDT output (1) •

Display DDT output fields at tab stops (I) •

The terminal doesinot have a tab mechanism (2) •

The terminal has a tab mechanism (2) •

Echo deleted characters (3) •

Backspace over deleted characters (3) •

EXPLANATION
file

from the

at
a
of the

(1) If bit 17 is reset (default) , DDT displays 3 spaces between
output fields (such as between the address of a location and the
contents of the location), and at the end of display lines.
If
bit 17 is set, DDT lines up the output fields in columns
beginning at tab stops (see bit 34).
Figure 4-1 illustrates the two different modes.
(2) If bit 34 is set, DDT displays a
tab character
«CTRL/I»
between fields.
If bit 34 is reset, DDT displays enough spaces
to start the field at the next tab stop. When starting up, DDT
checks
terminal can handle TAB characters
whether
your
«CTRL/I», and sets this bit accordingly.

(3) When starting up, DDT checks whether your terminal can
backspace to delete characters, and sets this bit accordingly.
4-19

April 1986

DISPLAYING AND MODIFYING MEMORY
To change the settings of the TTY control mask, use the command:
expr<ESC>lM
where expr evaluates to the required bit pattern.
You can also open the location addressed by <ESC)lM with one of the
DDT display commands, and deposit an expression that contains the new
bit settings.
Figure 4-1 is an illustration of the effects of bit 17 in the TTY
control mask.
The code being examined is the first few lines of
X.MAC, listed in Figure 2-1. The example is not a complete debugging
session; only enough is shown to illustrate the effects of bit 17 of
the TTY control mask. The numbers at the left of the DDT display
lines are to assist you in following the commentary that follows the
display. User input is in lowercase.
Figure 4-1:

DDT Session Showing Columnar Output
SCREEN DISPLAY

1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.

DDT
start/
MOVE P,PWORD
x$:
.$b
$g
$lB»START/
MOVE P,PWORD
$x
P/
-10"STACK
PWORD/
-10"STACK
START+l/
MOVEI IDX,TABLEI
$x
IDX/
TABLEI
TABLEI
$lm/
2
1,,2
start$g
$lB»START/
MOVE P,PWORD
$x
P/
-10"STACK
PWORD/ -10"STACK
START+l/
MOVEI IDX,TABLEI
$x
IDX/
TABLEI TABLEI
COMMENTARY
Line 1:
o

DDT is loaded and waiting for a command.

Line 2:
o

Enter start/ to examine location start.

Enter x<ESC>:

Enter .<ESC>b to set breakpoint at location START.

Enter <ESC>g to begin execution.

to open the symbol table for module X.

Line 3:
o

DDT displays breakpoint information.

Enter <ESC>x to execute the next instruction.

Line 4:
o

DDT displays results of executing the instruction.

4-20

DISPLAYING AND MODIFYING MEMORY
Line 5:
o

DDT displays the next instruction.

Enter <ESC)x to execute the instruction.

Line 6:
o

DDT displays the results of executing the instruction.

Enter <ESC)lm/ to display and open the TTY control mask.

DDT displays the mask.

Enter 1,,2<RET) to set bits 17 and 34.

Bit 34 is set.

Line 7:
o

Enter start<ESC)g to restart the program.

Line 8:
o

DDT displays the breakpoint information.

Enter <ESC)x to execute the instruction.

Line 9:
o

DDT displays the results of executing the instruction.

Line 10:
o

DDT displays the next instruction.

Enter <ESC)x to execute the next instruction.

Line 11:
o

DDT displays the results of executing the instruction.

4-21

CHAPTER 5
CONTROLLING PROGRAM EXECUTION

5.1

BEGINNING EXECUTION

To begin execution of your program, enter:
<ESC>G
Your program will run, beginning at its start address.
If you have
not set any breakpoints, your program runs to completion, or until it
makes a fatal error. At TOPS-10 command level, you can then use the
DDT command to reenter DDT and examine your program.
You can start or continue program execution at any
command:

address

with

the

addr<ESC>G

5.2

USING BREAKPOINTS

A breakpoint is a program location that has been altered such that if
your program PC reaches the address of the breakpoint, your program
transfers control to DDT.
When you set a breakpoint with DDT, DDT stores the address of the
breakpoint in an internal table. When you command DDT to begin or
continue program execution, DDT stores the instructions from all
breakpoints in the table, and replaces them with JSRs into a DDT entry
table.
While program execution is suspended at a breakpoint, you can examine
and modify memory, remove breakpoints, insert new breakpoints, execute
individual instructions, and continue program execution.
During this time, the command "<ESC>." returns the value that is the
address
of the next instruction to be executed.
The command
"<ESC><ESC>." returns a value that is the previous value returned by
"<ESC>.".
When you first receive control at the breakpoint, "<ESC>."
returns the address of the breakpoint and "<ESC><ESC>." returns zero.
Before you start execution with <ESC>G, "<ESC>." and "<ESC><ESC>." are
illegal commands (if you try to execute them, DDT sounds the terminal
buzzer or bell and displays a question mark).
NOTE
This manual uses the term "$." to represent the value
returned by the command "<ESC>.", and the term "$$."
to represent the value returned by the
command
"<ESC><ESC>.".
5-1

CONTROLLING PROGRAM EXECUTION
You can set up to 12 breakpoints at a time (this is a DDT assembly
parameter)
in your program. These breakpoints are numbered 1 through
12.
There 1S also one breakpoint
(the unsolicited breakpoint,
numbered zero) that can be used by your MACRO program to "call" DDT.
Each breakpoint has several internal DDT locations associated with it,
which contain information to control DDT action with respect to the
breakpoint. You can examine and modify these DDT locations with the
same DDT commands that you use to examine and modify locations in your
user program.
<ESC)nB is a command that returns the value that is the
address of the first DDT word associated with breakpoint n. The
symbol $nB is used here to represent that address.
Table 5-1 contains a list of the breakpoint locations of
the user, and their contents.
Table 5-1:

interest

Breakpoint Locations of Interest

LOCATION

CONTENTS

$nB

Address of breakpoint n.

$nB+l

Instruction for conditional breakpoint n.

$nB+2

Proceed count for conditional breakpoint n.

$nB+3

Address of a location to be opened and displayed when
the breakpoint is reached.

$nB+4

Address of an ASCIZ DDT command string to be executed
when the breakpoint is reached.

When your user-program PC reaches a breakpoint, your program
the JSR into DDT. When this occurs, DDT does the following:

executes

saves your user-program context

replaces the JSR instructions at
original program instructions

displays the breakpoint number, breakpoint address, and the
contents of the breakpoint (depending on bit 16 of the TTY
control mask)

sets "$." to the breakpoint address

sets "$$." to zero

enters the address of the current location (set before you
started the program or proceeded from a breakpoint) on the
location sequence stack

changes the current location to the breakpoint

waits for you to give a DDT command

5-2

all

breakpoints

with

the

CONTROLLING PROGRAM EXECUTION
When you command DDT to restart or
does the following:

continue

program

execution,

DDT

saves the program instructions from all breakpoints

replaces the program instructions at all breakpoints with JSR
instructions to DDT

if you have not executed the instruction at the breakpoint
with <ESC>X, DDT simulates execution of the instruction at
the breakpoint

restores your user-program context

DDT performs a JRSTF (if in section zero,
to the next instruction to be executed

5.2.1

otherwise

XJRSTF)

Setting Breakpoints

To set ~ breakpoint, enter:
addr<ESC>{n}B
where addr is the address where you want to suspend execution (addr
can be ".", the command that returns the address of the current
location), and n is the number of the breakpoint (and defaults to the
lowest unused breakpoint number).
If you do not specify n, it defaults to the lowest available (unset)
breakpoint.
If you have already set twelve breakpoints, DDT displays
A?" and sounds the terminal buzzer or bell.
If you specify n, it must be greater than zero and less than 13.
DDT
restores the original contents of any (previously set) breakpoint
designated as breakpoint n before setting new breakpoint n.
You cannot set more than one breakpoint at the same address.
DDT
simply sets the same breakpoint again, even if you explicitly specify
a breakpoint number the second time.
You cannot set a breakpoint at AC zero.
Assume the following conditions:
o

location LABLI+3 contains the instruction MOVE I,LABL2

breakpoint 2 is set at LABLl+3

If your program reaches LABLl+3 it executes the JSR to
does the following:

DDT,

and

DDT

saves your user-program context

restores the original program instructions to the breakpoints

sets "$." to LABLl+3

sets "$$." to zero

enters the address of the current location
sequence stack

5-3

the

location

CONTROLLING PROGRAM EXECUTION
o

changes the current location to LABLl+3 (the breakpoint)

opens location LABLI+3

displays:

$2B»LABLI+3/

MOVE 1,LABL2

To set ~ breakpoint and have DDT display .~ additional
your program reaches the breakpoint, enter:

location

when

addrl<addr2<ESC>{n}B
where addrl is the location to be displayed, and addr2 is the location
of the breakpoint. Follow addrl with a left angle bracket

«).

Assume the following conditions:
o

location LABLI+3 contains the instruction MOVE 1,LABL2

location LABL3 contains value SYMBLI

breakpoint 2 was set by the command:
LABL3<LABLI+3<ESC>B

If your program reaches LABLI+3 it executes the JSR to
does the following:

DDT,

and

DDT

saves your user-program context

restores the original program instructions to the breakpoints

sets "$." to LABLl+3

sets "$$." to zero

enters the address of the current location
sequence stack

changes the current location to LABLI+3 (the breakpoint)

enters the address of the current location
on the location sequence stack

changes the current location to LABL3

opens location LABL3

displays:

$2B»LABLI+3/

MOVE 1,LABL2

the

location

(the

breakpoint)

LABL3/

SYMBLI

Note that, because DDT placed the breakpoint address on the location
sequence stack, you can enter <ESC><RET> to change the current
location back to the breakpoint.
When invoked at a breakpoint, DDT can also execute a string of DDT
commands that is stored as an ASCIZ string. To invoke this function,
enter:
{addrl<}addr2>addr3<ESC>{n}B
where addrl is an optional location to be displayed, addr2 is the
address of the ASCIZ string containing the DDT commands, and addr3 is
the address of the breakpoint.
Follow addrl with a left angle bracket
«) and addr2 with a right angle bracket (».

5-4

CONTROLLING PROGRAM EXECUTION
This command is legal only if feature-test FTYANK was turned
DDT was assembled.

when

If your program reaches addr3 it executes the JSR to DDT, and DDT does
the following:
o

saves your user-program qontext

restores the original program instructions to the breakpoints

sets "$." to addr3

sets "$$." to zero

enters the address of the current location
sequence stack

changes the current location to addr3 (the breakpoint)

displays the breakpoint number

displays the address and contents of the location at addr3

if you give addrl< in the command, DDT does the following:

the

enters addr3 on the location sequence stack

changes the current location to addrl

opens the location at addrl

displays the contents of the location at addrl

location

executes the DDT commands stored as an ASCIZ string at addr2

If you give addrl< in the command, DDT places the breakpoint address
on the locatIon sequence stack, and you can enter <ESC><RET> to change
the current location back to the breakpoint.
To display the address of any breakpoint, enter:
<ESC>nB/
where n is the address of the breakpoint. DDT displays the address of
breakpoint n, and you can use the examine commands to open and display
the instruction at breakpoint n. If breakpoint n is not set, DDT
displays zero.
To remove breakpoint n, enter:
0<ESC>nB
To remove all breakpoints, enter:
<ESC>B

5-5

CONTROLLING PROGRAM EXECUTION
5.2.2

Proceeding from Breakpoints

After your program has reached
execution at "$." by entering:

breakpoint,

you

can

continue

<ESC>P
DDT saves the program instructions from all breakpoints, replaces the
program instructions with JSRs to DDT, restores your user-program
context, and if you have not executed any program instructions with
the <ESC>X command, simulates execution of the instruction at the
breakpoint. DDT then executes a JRSTF (in section zero, otherwise DDT
executes an XJRSTF) to the next instruction to be executed.
You can cause the program to start execution at a different location
with the {addr}<ESC>G command, where addr defaults to the program's
start address.
Once your program has reached a breakpoint and DDT has interrupted
execution, you can cause DDT to continue execution but NOT stop at
that breakpoint until your program has reached that breakpoint a
specified number of times. To do this, enter:
expr<ESC>P
where expr is the proceed count. DDT places expr at location $nB+2,
where n is the number of the breakpoint at which your program has
stopped. DDT resumes execution of your program.
Each time your
program reaches breakpoint n, DDT decrements the proceed count stored
at $nB+2. Your program continues execution until:
o

it reaches a different breakpoint

it terminates normally

it commits a fatal error

the proceed count reaches zero

Each breakpoint has an associated automatic proceed flag.
If this
flag is set and the program reaches the breakpoint, DDT decrements the
proceed count at $nB+2 (where n is the number of the breakpoint) and
displays the breakpoint information if the proceed count is less than
one. DDT then automatically continues program execution.
The <ESC>P command resets (clears) the automatic proceed
flag
associated with the breakpoint at which DDT has suspended program
execution.
To set ~ breakpoint and set the
enter:

associated

automatic

proceed

flag,

{addrl<}addr2<ESC><ESC>{n}B
where addr2 is the address of the breakpoint and may be ".", addrl is
an (optional) additional location to be displayed, and n is optional
and defaults to the lowest unused breakpoint.

5-6

CONTROLLING PROGRAM EXECUTION
Each time your program reaches
associated proceed count, and
displays:
$nB»addr2/

breakpoint n, DDT
if the result is

decrements the
less than one,

instr

where n is the breakpoint number, addr2 is the address
breakpoint, and instr is the contents of the word at addr2.

the

If you entered addrl< when you gave the command, DDT displays:
$nB»addr2/

instr

addrl/

contents

where n is the breakpoint number, addr2 is the address of the
breakpoint, instr is the contents of the word at addr2, addrl is the
additional location to be displayed, and contents is the contents of
the word at addrl.
DDT then automatically continues program execution until:
o

your program reaches a different breakpoint

your program terminates normally

your program commits a fatal error

you enter any character while your program

at breakpoint n

You can interrupt the automatic proceed function if you enter a
character while your program is at breakpoint n. DDT then resets the
automatic proceed flag and suspends program execution
at
the
breakpoint.
DDT echoes the character that you entered, which is
otherwise ignored.
To have DDT execute a DDT command stored as an ASCIZ string
interrupt the automatic proceed cycle, enter:

when

you

{addrl<}addr2>addr3<ESC><ESC>{n}B
where addrl is an optional location to be displayed, addr2 is the
address of the ASCIZ string containing the DDT commands, and addr3 is
the address of the breakpoint. Follow addrl with a left angle bracket
«) and addr2 with a right angle bracket (».
If your program reaches breakpoint n, DDT displays the requested
information
and automatically continues program execution.
DDT
executes the ASCIZ DDT command string stored at addr2 only when you
interrupt the automatic proceed cycle by entering any character.
If feature-test FTYANK was not turned on when DDT was
does not execute the command string stored at addr2.

assembled,

To proceed from ~ breakpoint and set the associated automatic
flag, give the command:

DDT

proceed

{expr}<ESC><ESC>P
where expr is the proceed count.
$nB+2.

DDT

5-7

stores

the

proceed

count

CONTROLLING PROGRAM EXECUTION
5.2.3

Conditional Breakpoints

To cause DDT to interrupt program execution at a breakpoint only if a
specific condition is satisfied, you must store a single test
instruction or a call to a test routine in DDT's breakpoint table.
You can use a test routine in your program, or one that you enter in
DDT's patching area. See Chapter 8 (Inserting Patches with DDT)
for
more
information about the patching area.
To enter the test
instruction (or the call to the test routine), open the DDT location
addressed by the command <ESC)nB+l by entering:
<ESC)nB+l/
where n is the number of the breakpoint. You must enter n, or DDT
interprets the command as <ESC)B, and removes all breakpoints.
Deposit the test instruction or the call to the test subroutine.
If
your program reaches breakpoint n, DDT executes the instruction at
$nB+l. DDT then proceeds as follows:
o

If the instruction does not cause a program counter skip, DDT
decrements the proceed count at $nB+2.
If the result is zero
or less, DDT interrupts execution at breakpoint n.

If a program counter skip of 1
execution at breakpoint n.

If the conditional instruction is a call to a subroutine that
returns by skipping over two or more instructions, DDT does
not interrupt program execution.

does

occur,

DDT

interrupts

If DDT interrupts execution because the test instruction resulted in a
program counter skip, DDT displays only one angle bracket after the
breakpoint identification, as:
$3B)LABL1/

5.2.4

MOVE 1,LABL2

The "Unsolicited" Breakpoint

You can cause your MACRO program to "call"
following instruction in your program:

DDT

inserting

the

JSR $0BPTf#
The two pound-signs (#f) appended
declare the symbol as EXTERNAL.

$0BPT

your

MACRO

NOTE
"$" represents the dollar sign character, which is
part of the symbol, and is not the DDT echo of the
ESCAPE key.

5-8

program

CONTROLLING PROGRAM EXECUTION
You must load DDT.REL with your program or you will get a
LINK error
(?LNKUGS undefined global symbol)
when you load your program.
Load
DDT.REL with your program as follows (your input is in lowercase;
the
last line indicates that DDT is loaded and ready to accept your
commands):
.r link
*/debug filnam/go
DDT
where filnam is the name of your MACRO-10 program.
You can start your
program running with the <ESC>G command.
If your program executes the
JSR instruction, DDT interrupts program execution and displays:
$0B»addr+l/

instr

where addr+l is the first location after the
and instr is the contents of that location.

JSR $0BPT

The following sequence of instructions provides another
your MACRO program call DDT:
CALDDT: SKIPN
JRST
JSR
POPJ

instruction,
way

have

.JBBPT
[OUTSTR ASCIZ\%DDT not loaded\
POPJ P,]
@.JBBPT

If DDT is loaded in memory (as indicated by a nonzero value in JOBDAT
location
.JBBPT), you can interrupt your program and transfer control
to DDT by entering:
<CTRL/D>
You must have first used the TOPS-10 command SET DDT BREAKPOINT ON
(see the TOPS-10 Commands Reference Manual).
The monitor interrupts
your program and transfers control to DDT, which displays:
$0B»CALDDT+3/

POPJ P,

You can use the sequence of TOPS-10 commands shown in the following
terminal display to get DDT loaded into memory with your program (the
commands you enter are in lowercase):
.get filnam
.ddt
DDT
<ESC>g
If you did not load and save DDT.REL with your program, you
VMDDT instead of DDT.

5.3

will

get

followed

EXECUTING EXPLICIT INSTRUCTIONS

To execute a specific instruction, enter the instruction
<ESC>X:
instr<ESC>X
For example:
MOVE 1,@LABLI(3)<ESC>X
5-9

CONTROLLING PROGRAM EXECUTION
After executing the instruction, DDT starts a new line and displays:
0

if in-line execution of instr would result in
skipping no instructions.

<SKIP>

if in-line execution of instr would result in
skipping 1 instruction.

if in-line execution of instr would result in
skipping 2 instructions.

if in-line execution of instr would result in
skipping 3 instructions.
NOTE

"In-line execution" means execution of the instruction
as part of normal program flow.
The execution of
instructions with this command has no effect on your
user-program PC.
This command restores the prevailing display mode.

5.4

SINGLE-STEPPING INSTRUCTIONS

After your program has transferred control to DDT from
you can execute program instructions one at a time.
"single-stepping."

a breakpoint,
This is called

"<ESC>." is a command that returns the address of the next instruction
to be executed.
To execute the instruction whose
enter:

address

returned

"<ESC>.",

<ESC>X
For example, breakpoint 3 is set at LABLl+3.
If your
reaches LABLl+3, control passes to DDT, which displays:
$3B»LABLl+3/

program

ADD 1,LABL2(2)

Examining the environment, you learn the following:
o

AC 1 contains 1

AC 2 contains 3

LABLl+4 contains MOVEM 1,@LABL2(3)

LABL2+3 contains SYM3

as shown by the following terminal display (DDT does not display
or <ESC»:
$3B»LABLl+3/
ADD 1,LABL2(2)
<ESC>\
SYM3
LABLl+4/
MOVEM 1,@LABL2(3)
1/
1
<LF>
2/
3

5-10

<LF>

CONTROLLING PROGRAM EXECUTION
If you now enter the command <ESC>X, DDT does the following:
o

changes "$$." to LABLl+3

executes the instruction at LABLl+3

changes "$." to LABLl+4

changes the current location to LABLl+4

opens LABLl+4

displays:
1/
SYM3+1
LABL2+3/
SYM3
LABLl+4/
MOVEM 1,@LABL2(3)

If single-stepping an instruction results in a value of ($ • minus $$. )
not equal to 1, DDT also begins a new line and displays:
0

<SKIP>

if ($ • minus $$. )

if ($. minus $$. )

if ($ • minus $$. )

<JUMP>

if ($ • minus $$. ) is greater than 4 or less than 1

before displaying the address and contents of the next instruction to
be executed."
For example,
the following shows a typical terminal
display where you enter <ESC>X to single-step the first instruction at
a breakpoint (DDT echoes <ESC> as $):
$4B»LABLl+5/
3/
1
<SKIP>
LABLl+7/

5.5

AOSN 3

<ESC>x

MOVEM 1,LABL2

EXECUTING SUBROUTINES AND RANGES OF INSTRUCTIONS

To execute a series of n instructions beginning with the
whose address is returned by the command "<ESC>.", enter:

instruction

n<ESC>X
where n is the number of instructions to execute.
DDT then does the following for each instruction:
o

starts a new display line

executes the instruction

displays the address of any register
referenced by the execution of the
after
contents of those locations
instruction

changes the current location to the next
executed

5-11

or memory location
instruction, and the
execution
of
the
instruction

CONTROLLING PROGRAM EXECUTION
o

opens the current location

displays the address and contents of the next instruction
be executed

changes "$." to the address of the
executed

changes "$S." to the address of the instruction just executed

instruction

To suppress typeout of all but the last instruction executed, use
command:

the

n<ESC><ESC>X
where n is the number of instructions to execute.
To continue program execution until the PC (program counter) enters
range of instructions, enter:

{addrl<}{addr2>}<ESC><ESC>X
where addr1 is the lower end of the range, and addr2 is the upper end.
Addr1 defaults to 1 + "S." and addr2 defaults to addr1 + 3. Follow
addr1 with a left angle bracket «) and addr2 with a right angle
bracket (».
This command also indicates skips and jumps.
This command is useful for executing
quickly and without typeout.

loop

subroutine

call

For example, breakpoint 3 is at location LABLI.
<ESC><ESC>X

S3B»LABLI/
PUSHJ 17,SUBRTN
<SKIP>
ADD 1,2
LABLI+2/

;Enter <ESC><ESC>X
iSUBRTN returns + 2

If you enter a question mark (?) while DDT is executing an <ESC><ESC>X
command, DDT displays:
Executing: addr/

instr

where addr is the address of the next instruction to be executed,
instr is the instruction.

and

To terminate the execution of the series of instructions, enter
character other-than? (question mark) • -nOT does the following:

any

echoes the character

displays <SKIP>,
appropriate

starts a new display line

changes the current location
instruction to be executed

displays the address and contents of the current location

opens the current location

waits for your next command

<SKIP

2>,

5-12

<SKIP

3>,

address

the

<JUMP>,

the

CONTROLLING PROGRAM EXECUTION
5.5.1

Single-Stepping "Dangerous" Instructions

DDT classifies the following as "dangerous" instructions:
o

instructions that can modify memory

instructions that can cause an arithmetic trap

instructions that can cause a stack overflow

a monitor call or I/O instruction

Before single-stepping one of these instructions, DDT saves and
replaces the original
instructions at the breakpoints with JSRs to
DDT, and restores the full user-program context
(including
interrupt
system and terminal characteristics) before executing the instruction.
After executing the instruction, DDT replaces the JSRs at the
breakpoints with the original program instructions, and saves the full
user-program context.
DDT does not check whether the instruction actually results in one of
these conditions, only whether the opcode is in the class of
instructions that can cause these effects. This can make executing
subroutines and ranges of instructions under DDT control extremely
time-consuming.
To execute a subroutine or series of instructions without checking for
dangerous instructions, use the command:
{addrl<}{addr2>}<ESC><ESC>lX
where addrl is the lower end of the range, and addr2 is the upper end.
Addrl defaults to 1 + "$." and addr2 defaults to 3 + addrl.
Follow
addr1 with a left angle bracket «), and addr2 with a
right angle
bracket
(». This command executes much faster than <ESC><ESC>X, but
if the execution of an instruction causes a software interrupt, the
error and trap handling mechanism may not function correctly.
In
addition, program instructions that change or rely on terminal or job
characteristics that are also used by DDT can cause unpredictab~e
results.

5.6

USER-PROGRAM CONTEXT

When DDT interrupts your program's execution at a breakpoint, and
after
it has executed a dangerous instruction during an <ESC>X or
<ESC><ESC>X command, it saves the user-program context.
The command
<ESC>nI,
where 0<=n<=10 (octal), returns the address of the word that
contains the information for "function" n. You can use this address
to display and modify these values.
Most of these values are useful
only in executive mode.
DDT displays the address of the word
containing the information for function n as:
$I+n
where 1<=n<=10 (octal).

If n

0, DDT displays only $I.

5-13

CONTROLLING PROGRAM EXECUTION
Table 5-2 lists the functions.
Table 5-2:

User-Program Context Values

FUNCTION

VALUE

Executive mode CONI PI.

Executive mode PI channels turned off.

Executive mode CONI APR.

User PC flags.

User PC address.

EPT page address.

UPT page address.

CST base virtual address.

SPT base virtual address.

DDT restores the user-program context whenever you execute <ESC>G,
<ESC>P, and when you execute <ESC>X, or <ESC><ESC>X of dangerous
instructions.
Functions 5 through 10 (octal) affect DDT's interpretation of your
program's virtual address space. You can alter DDT's interpretation
of your program's virtual address space with the physical and virtual
addressing
«ESC>nU)
commands described in Chapter 11 (Physical and
Virtual Addressing Commands). However, any alterations that you make
do not become part of your user-program context, and do not affect
TOPS-10's interpretation of your program's virtual address space.
DDT also saves and restores the user-program ACs as part of the
user-program context.
DDT stores the contents of the ACs in an
internal "register" block. Any references you make to addresses 0-17
refer to the relative locations in DDT's internal register block.
These actions are totally transparent to you.

5-14

CHAPTER 6
SEARCHING FOR DATA PATTERNS IN DDT

With DDT you can search for memory locations that contain a specific
value, and conversely, for words that do not contain a specific value.
You can also set a mask to indicate to DDT that only specified bits
are to be considered when performing the search. In addition, you can
search for words that reference a specific address. You can specify a
range within which to perform the search, or default the range to all
of your program's address space. In either case, DDT compares the
contents of each location within the range with the specified value.
To search for words that match a specific value, enter:
{addrl<}{addr2>}expr<ESC>W
where expr is the value for which DDT is to search, and addrl and
addr2 delimit the range in which the search is to be conducted.
Follow addrl with a left angle bracket «) and addr2 with a right
angle bracket (».
Addrl defaults to zero and addr2 defaults to
777777 in the current section. Expr can be any legal DDT expression.
DDT does the following:
o

compares each location (after ANDing it with the search mask)
within the search range with the 36-bit value resulting from
evaluating expr

starts the search by comparing the
expr

addrl

with

stops the search after comparing the contents of
expr

addr2

with

displays (on a new line) the address
location that matches expr

enters the address of each matching location on the
sequence stack

sets the current location to addr2

displays a blank line to indicate the search is over

restores the prevailing display mode

contents

and

contents

NOTE
If DDT finds more matching locations than there are
words on the location sequence stack, the earlier
entries are overwritten.

6-1

each

location

SEARCHING FOR DATA PATTERNS IN DDT
NOTE
When you use the DDT search functions while running
FILDDT, addr2 defaults to 777777 (in the current
section) unless:
o

the target is the running monitor or other running
job and you are using physical addressing

the target is an .EXE file
normal virtual addressing

the target is a disk structure or data file

and

you

are

using

In these cases, addr2 defaults to the last word of the
target.
See Chapter 9 (FILDDT), and Chapter 11
(Physical and Virtual Addressing Commands), for more
information.
To search for words that do NOT match a specified value, enter:
{addrl<}{addr2>}expr<ESC>N
where expr is the value which is not to be matched, and addrl and
addr2 delimit the range within which DDT is to search. Follow addrl
with a left angle bracket «) and addr2 with a right angle bracket
(».
Addrl defaults to zero and addr2 defaults to 777777 in the
current section. (If you are using FILDDT, see the note following the
description of the <ESC>W search command.) Expr is any legal DDT
expression.
DDT functions as for the <ESC>W command, except:
o

DDT searches for and displays the address and contents of any
word within the address range that does NOT match the 36-bit
value resulting from evaluating expr.

DDT enters the locations
location sequence stack.

non-matching

words

the

To search for references to an address, enter:
{addrl<}{addr2>}expr<ESC>E
where addrl and addr2 delimit the range of the search, and expr
contains the address for which DDT is to search. Follow addrl with a
left angle bracket «) and addr2 with a right angle bracket (».
Addrl defaults to zero and addr2 defaults to 777777 in the current
section. Expr is any legal DDT expression.
DDT performs an IFIW effective address calculation on the expression
contained in each word within the range, and uses the 18-bit result to
determine whether there is a match.
Thus, if bits 14-17 (the X field of an instruction) or bit 13 (the I
field of an instruction) are nonzero, indexing or indirection may
result in DDT finding different search results at different times.
DDT does not check whether the expression is actually
before performing the effective address calculation.

6-2

instruction

SEARCHING FOR DATA PATTERNS IN DDT
If you enter a question mark (?) while DDT is performing
above searches, DDT displays:

the

where addr is the address of the location that will next compare,
value ~he contents of addr.

and

Searching: addr/

any

value

To abort the search, enter any character other than question mark (?).
DDT stops-searching, and waits for more input.
The character that you
enter to terminate the search is otherwise ignored.
Each of the above search
mode.

commands

restores

the

prevailing

display

<ESC>M is a command that addresses a DDT location that contains a
search mask used to prevent specified bits in the memory word from
being considered during the search. This mask is used only by <ESC>W
and <ESC>N, not by <ESC>E.
DDT logically ANDs the search mask with
the memory word before making the comparison, but does not change the
memory word.
If DDT finds a match, it displays the entire word.
DDT sets the search mask to 777777,,777777 (compare all
default.

bits)

To set the search mask, enter:
expr<ESC>M
where expr evaluates to the required bit pattern.
For example, to search for all of
(user input is in lowercase):
<ESC><ESC>5t
37777,,777777<ESC>m
main.<ESC>5"<ESC>w

4112/
4775/

4 MAIN.

o MAIN.

the

RADIX50

references

MAIN.

;Set typeout mode to RADIX50.
;Ignore the left 4 bits.
;Enter RADIX50 symbol, start search.
;DDT displays match found.
;DDT displays match found.
;Search over, DDT displays blank line.

You can also examine and modify the search mask with the examine and
deposit commands described
in Chapter 4 (Displaying and Modifying
Memory) •

6-3

CHAPTER 7
MANIPULATING SYMBOLS IN DDT

7.1

OPENING AND CLOSING SYMBOL TABLES

Each separate program module has its own symbol table.
When
displaying a value symbolically, if more than one symbol is defined
with that value, DDT displays the first global symbol found.
When
searching for a symbol, DDT searches the "open" symbol table first.
For display purposes, DDT treats local symbols found
in the open
symbol table as global symbols. DDT appends a pound-sign (#) to local
symbol names that it finds in a symbol table that is not open.
For
example:
SYMBLl#
where SYMBL1 is a local symbol that DDT found in a symbol
is not open.

table

that

If you enter an expression that contains a symbol that is defined in
more than one of your program modules, DDT uses the value of the
symbol that is contained in the open symbol table.
If the symbol
is
not defined
in the open symbol table, or if there is no open module
and there is not a global definition of the symbol, DDT displays:

M
To open the symbol table of a program module, enter:
name<ESC):
where name is the name of the program module as specified by the TITLE
pseudo-op in your MACRO-10 program (or the equivalent mechanism in a
higher-level language program). DDT closes any currently open symbol
table and opens the symbol table associated with module name.
To close the open symbol table, enter:
<ESC):

7-1

MANIPULATING SYMBOLS IN DDT
7.2

DEFINING SYMBOLS

To redefine a symbol or to create a new symbol in the
table, enter:

current

symbol

expr<symbol:
where

is any legal DDT expression, and symbol is the symbol name.

To define symbol as the
command:

address

the

open

location,

enter

the

symbol:
If there is no open location, DDT uses the address of the last
location that was open. DDT defines symbol as a global symbol.
If
you previously used symbol as an undefined symbol, DDT inserts the
correct value in all the places you referenced symbol, and removes
symbol from the undefined symbol table.

7.3

SUPPRESSING SYMBOL TYPEOUT

To prevent a symbol from being displayed, enter:
symbol<ESC>K
where symbol is the symbol to be suppressed. DDT still accepts symbol
as input, but no longer displays symbol as output.
To suppress the last symbol that DDT displayed (in an address, in the
contents of a memory word, or in the evaluation of an expression),
enter:
<ESC>D
DDT suppresses the last symbol displayed, and then redisplays the
current quantity. DDT does not display its usual three spaces between
the command and the displayed value.
In the following example, assume that symbol SIZE is
User typein is lowercase
«LF> does not appear
screen).

defined as 3.
on the terminal

start/
JFCL ~
<LF>
LOOP/
AOS 1
<LF>
LOOP+l/
MOVE 2,1
<ESC>dMOVE 2,1
<LF>
START+3/
MULl 2,SIZE
<ESC>dMULI 2,3
To reactivate ~ symbol for typeout, redefine the symbol.
to reactivate the display of symbol SIZE, above, enter:

For example,

size<size:
Note that SIZE is now defined as a
previously a local symbol.

7-2

global

symbol,

even

was

MANIPULATING SYMBOLS IN DDT
7.4

KILLING SYMBOLS

To remove a symbol from the symbol table, enter:
symbol<ESC><ESC>K
DDT removes symbol from the symbol
symbol or accepts symbol as input.

7.5

table,

and

longer

have

not

displays

CREATING UNDEFINED SYMBOLS

It is sometimes convenient to use symbols that
defined. To create an undefined symbol, enter:

yet

been

symbolf
where symbol is the undefined symbol name. DDT enters symbol
in the
undefined symbol table. When you later define the symbol, DDT enters
it into the defined symbol table, removes it from the undefined symbol
table, and enters the correct value in all locations where you
referenced the symbol.
You can use undefined symbols only as parts of expressions that you
are depositing to memory.
Undefined symbols can be either fullword or
right-halfword values; they cannot be used as the A or X fields of an
instruction, or as the left-halfword of an expression.

7.6

FINDING WHERE A SYMBOL IS DEFINED

To determine the modules in which a symbol is defined, enter:
symbol?
where symbol is the name of the symbol. DDT displays the name of each
program module in which symbol is defined.
If the symbol is a global
symbol, DDT displays a "G", as:
sym?
MAIN.

DDT does not display G following a local symbol found
in the open
symbol table.
When DDT has searched the entire symbol table, it
displays a blank line.

7.7

LISTING UNDEFINED SYMBOLS

To get a list of all currently undefined symbols, enter:

?
DDT displays a list containing each undefined symbol.

7-3

MANIPULATING SYMBOLS IN DDT
7.8

LISTING SYMBOLS

To get a list of all symbols starting with a certain character or
of characters, type:

set

sym<ESC>?
where sym is the set of characters that all the symbols start with.
DDT lists all symbols starting with sym, the modules where they are
defined, and the values that symbols are defined as.
For example, typing
starting with TECD:

the

following

command

will

list

all

symbols

TECO<ESC>?
TECD
TECD01
TEC002
TECD03

DDT V44

TECO
TECD
TECD
TECD

600030
600040
600047
600055

7-4

April 1986

CHAPTER 8
INSERTING PATCHES WITH DDT

To replace the instruction at the open location with a series of
instructions and test the new instructions without reassembling your
program, you can use the DDT patch function.
DDT deposits
(in a
patching
area)
the
replaced
instruction, the new series of
instructions, and one dr more JUMPA instructions back to the main line
of your program. DDT also deposits (in the location that contains the
replaced instruction) a JUMPA instruction to the first word of the
patch.
To insert ~ patch that will be executed before the instruction at
open location, enter:

the

{expr}<ESC><
where expr is the start of the patching location, and defaults first
to PAT •• , then to PATCH.
EDDT defaults to PAT (an area created during
the monitor build), PAT •• , and PATCH, in that order. If you do not
enter expr, and DDT finds none of the default symbols, DDT uses the
value contained in JOBDAT location .JBFF as the address to begin the
patch.
If expr is a symbol (or the default), DDT updates the symbol
table when you terminate the patch, so that the symbol identifies the
first word after the patch that you just terminated.
If there is no open location when you initiate the patch, DDT displays
"?n and sounds the terminal buzzer or bell.

NOTE
If expr is an AC address, or resolves to a value less
than 0,,140, DDT displays n?n and sounds the terminal
buzzer or bell.
When you issue a command to start a patch, DDT saves the
the open location, closes the open location, changes
location to the first word in the patching area, and opens
DDT also displays the address and contents of the first
patching area. For example:
<ESC><
PAT •• /

address of
the current
that word.
word of the

You can now enter the patch, using deposit instructions (the expr<LF>
format is probably most useful).
DDT updates the current and open
locations according to the rules for the command that you use.

8-1

INSERTING PATCHES WITH DDT
To terminate the patch, enter:
{expr}<ESC>{n}>
where expr is the last word of the patch you are entering, and n
is
the number of returns possible from execution of the patch. The
default for n is 2, allowing for a return to 1 + the address of the
instruction being replaced, and for a "skip return" to 2 + the address
of the instruction being replaced.
instruction being
When you terminate the patch, DDT deposits the
the current location,
replaced
into the first
location following
unless:
o

display is not suppressed by

the current location is zero

the current location is closed

AND
AND
OR

you omitted expr

in which case DDT deposits the instruction being
replaced
into the
current location.
This prevents the patch from containing unintended
null words.
DDT deposits n JUMPA instructions in the locations immediately
following
the one in which it deposited the original program
instruction.
The first JUMPA instruction has 1 in its A field,
and
jumps to 1 + the address of the replaced instruction, the second JUMPA
instruction has 2 in its A field and jumps to 2 + the address of the
replaced
instruction,
and so on.
The AC numbers are used for
identification purposes only.
Any JUMPA instruction beyond the
sixteenth contains 17 in its A field.
DDT then changes the current location to the location that was open
when you initiated the patch, deposits in the current location a JUMPA
instruction to the first word of the patch that you entered, and
displays the address,
original contents,
and new contents of the
current location. The current location is "open", and can be modified
by your next command.
If you default expr, or enter a symbol in the {expr}<ESC>< command,
when you terminate the patch, DDT redefines the symbol that identifies
the start of the patch.
If DDT used the value contained
in JOBDAT
location
.JBFF as the address of the patching area, DDT changes the
values contained in .JBFF and the left half of JOBDAT location .JBSA.
In all cases,
the new value is the address of the memory location
after the last word of the patch.
By default, there are 100 (octal) words in the patching area.
DDT
does not check whether your patch overflows the patching area.
You
can control the size of the patching area with the /PATCHSIZE switch
in LINK.
NOTE
DDT allows you to use other DDT commands while you are
in the process of entering a patch. DDT does not
check whether the current and open locations are
in
the patching area, or whether you are ent~ring p~tch
instructions in sequence.
When you terminate the
patch, DDT deposits the instruction being replaced in
the current location regardless of whether the current
location is in the patching area.

8-2

INSERTING PATCHES WITH DDT
To insert ~ patch that will be executed after the instruction
open location, enter:

the

{expr}<ESC><ESC><
where expr is the address of the patching location (PAT..
is the
default).
The results are the same as inserting the patch before the
instruction as above, except:
o

When you open the patch DDT deposits the replaced instruction
in the first word of the patch.

When you terminate the patch, DDT deposits the first JUMPA
instruction (rather than the instruction being replaced) in
the first location following the current location unless:
>

display is not suppressed by

the current location is zero

the current location is closed

AND
AND
OR

you omitted expr

in which case DDT deposits the first JUMPA instruction in the
current
location.
This is to prevent the patch from
containing unintended null words.
NOTE
If expr is an AC address, or resolves to a value less
than 0,,140, DDT displays "?" and sounds the terminal
buzzer or bell.
Figure 8-1 illustrates the patching function.
The program being
patched is X.MAC
(see Figure 2-1).
The patch inserts a SKIPN
instruction that is to be executed after the instruction at START+4.
Figure 8-1:

Annotated Patching Session

DDT OUTPUT
START+41

USER INPUT

As a result of your last
command, DDT displays the
contents of START+4.

MOVE 2(IDX)

<ESC><ESC><
PAT • • 1

EXPLANATION

Enter <ESC><ESC>< to start
the patch.
DDT displays the address
and contents of the first word
word of the patch area, and
deposits the instruction from
START+4 in the first word of
the patch.

MOVE 2(IDX)

DDT displays the address
and contents of the next word
of the patch area.

PAT • • +11

pat •• =

8-3

Check the address of PAT •• "
(the first word of the patch
area) •

INSERTING PATCHES WITH DDT
Figure 8-1: Annotated Patching Session (Cont.)
USER INPUT

DDT OUTPUT
14432

EXPLANATION
DDT displays the current
address of "PAT •• ".

skipn 1,0<ESC>2>

Enter the new instruction,
and terminate the patch with
a normal return and one skip
return by entering <ESC>2>.

PAT •• +2/

JUMPA 1,START+S

DDT displays the next word
of the patch area, then
deposits a JUMPA instruction
to 1 + the address of the
replaced instruction.

PAT •• +3/

JUMPA 2,START+6

DDT displays the address
and contents of the next word
of the patch area, then
deposits a JUMPA instruction
to 2 + the address of the
replaced instruction.

START+4/

MOVE 2 (lOX)

JUMPA STACK+10
DDT displays the address
and original contents of the
replaced instruction, then
deposits and displays a
JUMPA instruction to the
first word of the patch.
START+4 is the current
location, and is "open".
pat •• =

14436

Check the address of the
patch area.
DDT updated "PAT •• ".

Figure 8-2 shows the terminal display as it actually appears when
insert the patch described above.
Your input is in lowercase.
Figure 8-2:

Terminal Display of Patching After an Instruction

START+4/
MOVE 2{IDX}
$$<
MOVE 2{IDX}
PAT •• /
0
PAT •• +1/
o pat •• =14432 skipn 1,O$2>
PAT •• +2/
o JUMPA 1,START+5
PAT •• +3/
o JUMPA 2,START+6
START+4/
MOVE 2(IDX)
JUMPA STACK+10
pat •• =14436

8-4

you

INSERTING PATCHES WITH DDT
Figure 8-3 shows the terminal display when inserting the same patch
before the instruction at START+4. You enter the instruction in the
form expr<LF> (user input is lowercase). Note the use of the patch
termination command without expr and without n.
Figure 8-3:

Terminal Display of Patching Before an Instruction

START+4/
MOVE 2 (lOX)
$<
0
skipn 1,0
.=14432
PAT •• /
PAT •• +1/
0
$>
PAT •• +1/
MOVE 2(IOX)
0
PAT •• +2/
JUMPA 1,START+5
0
JUMPA 2,START+6
PAT •• +3/
0
JUMPA STACK+10
START+4/
MOVE 2 (lOX)

pat •• =14436

To abort the patch you ~ entering, enter:
<ESC>0<
DDT displays 3 spaces (or a tab, depending on the TTY control mask)
and changes the current location to the location that was open when
you initiated the patch. The symbol that denotes the start of the
patching area is unchanged. Any deposits that you made as part of the
patch remain in the patching area. This allows you to restart the
same patch, or to write over the patch with a new one.

8-5

CHAPTER 9
FILDDT

9.1

INTRODUCTION

FILDDT is a utility used to examine and change disk files and physical
disk blocks. You can also use FILDDT to examine monitor crash dumps,
and to examine and change the running monitor or running jobs.
With
FILDDT, you can look at .EXE files as if they had been loaded with the
monitor GET command, or as if they were binary data files.
In selecting a disk file, the .monitor, or a running job, with FILDDT,
you are really establishing the virtual address space that FILDDT
accesses. When discussing the contents of that virtual address space,
where the contents can be any of the above objects, this chapter uses
the term target.
Once you have accessed a target you can examine and modify it with the
DDT
examine and modify commands, and then save it with your
modifications. You can use all of DDT's commands for examining and
modifying memory, but you cannot use any commands that cause the
execution of program instructions, such as <ESC>X, <FSC>G, and so on.
If you attempt to execute a program instruction, DDT sounds the
terminal buzzer or bell.

9.2

USING FILDDT

There are two command levels in FILDDT. This document refers to these
two levels as FILDDT command level and DDT command level.
FILDDT command level accepts FILDDT commands to control session
parameters and to select the target.
When at this level, FILDDT
displays the prompt:
File:
Once you access a target, FILDDT enters DDT command level.
level, use DDT commands to examine and modify the target.

9-1

this

FILDDT
The syntax to use at FILDDT command level is:
dev:file.ext[path]/switch/switch
where dev:file.ext[path] is the TOPS-l~ file specification, and switch
is a FILDDT command. The commands are described below. With a FILDDT
command you can:
o

request HELP on FILDDT

specify the target to be examined

establish certain parameters about the operations
can perform (enable patching, for example)

enter DDT command level

that

you

A FILDDT command can have more than one of the above effects.
At

TOPS-l~

command level, start FILDDT by entering:

R FILDDT
FILDDT enters FILDDT command level and prompts:
File:

9.2.1

FILDDT Commands

There are two classes of FILDDT-level commands; those that select the
target that FILDDT is to access and those that establish what function
FILDDT is to perform for the target (enable patching, extract symbols,
and treat an .EXE file as data).
The following are the targets (virtual address spaces) that FILDDT can
access, and the commands that select them:
o

disk files

/F (default)

disk structures

the running monitor

running jobs

To examine a running job or the running monitor, you must have PEEK or
Spy privileges.
The following are the functions you can select for FILDDT
on the target and the commands that select them:
o

load the file (used with IS)

treat file as pure binary data

enable patching

load symbol table only from file

To patch the running monitor or a running
privileges.

job,

9-2

you

must

perform

have

POKE

FILDDT
To get HELP, enter:

IH
FILDDT displays a very brief description of the
redisplays the File:
prompt.

9.2.2

FILDDT

commands

and

Symbols

To enhance performance, FILDDT uses a symbol table which it builds in
its own address space,
rather than one which exists in the target
address space.
FILDDT automatically extracts symbols from the first
.EXE file it
loads during a session to build its internal symbol table. Once
FILDDT has an internal symbol table, it ignores any symbols in
subsequently loaded .EXE files unless you use the IS command.

9.2.3

Establishing Formats and Parameters

IF
Use the IF command in conjunction with the IS command, to load
the same file from which FILDDT copies the symbol table, as:
file-spec/S/F

ID
By default, FILDDT loads .EXE files in virtual memory as if they
were to be executed. When you give the ID command you can look
at an .EXE file as if it were a data file.
FILDDT then loads the
entire file
(including the
.EXE directory blocks) as a binary
file, starting at virtual location zero.

IP
The IP command enables patching (lets you modify) the target.
you do not enter IP, you can only examine the target.

IS
The IS command tells FILDDT to copy the symbol table from the
file you named in the command. FILDDT then again prompts you
with File:

9.2.4

Selecting the Target

To select a disk file, you need only name the file.
This
default, and requires no explicit command switch. Enter:

the

file-spec<RET>
FILDDT loads the file.
If FILDDT does not already have an internal
symbol table and file-spec names an
.EXE file, FILDDT builds an
internal symbol by default. FILDDT then enters DDT command level.

9-3

FILDDT
/J
To examine a running job, enter:
number/J
where number is the job number.
You must have PEEK or Spy
privileges to examine a running job, and POKE privileges to
modify the monitor or a running job.
/M

To examine the running monitor, enter the /M command with no file
specification, as:
/M

You must have PEEK or Spy privileges to examine the running
monitor, and POKE privileges to modify the running monitor.
/U

To examine a disk structure, use the /U command:
disk-name/U
where disk-name is the logical name of the disk structure.
If
you use the logical name of a multi-disk structure, you can
examine and patch the entire logical disk. If you use a physical
disk name, you are restricted to that physical disk.

9.2.5

Exiting FILDDT

When you are through examining and
modified file by entering:

modifying

the

target,

save

the

have

made,

and

<CTRL/E>
FILDDT closes the file, saving any changes that
again prompts you for a file name.

you

Any symbol table that you have loaded (explicitly or by default)
remains loaded until you specify another with the /S command.
If you have modified symbols, FILDDT also modifies the symbol table of
the disk file, if one of the following occurred:
o

FILDDT automatically loaded the symbol table.

you loaded the symbol table and entered DDT command level
entering:

file-spec/S/F
FILDDT sometimes runs out of memory when you use the <CTRL/E> command
to save files without exiting FILDDT. If FILDDT runs out of memory
while loading a file, it displays the message:
? Not enough memory for file pages

9-4

FILDDT
If FILDDT runs out of space while building a symbol table, it displays
the message:
? Not enough memory for symbols

To reclaim all of your available memory, exit FILDDT with the <CTRL/Z>
command, and then restart FILDDT with the TOPS-10 command R FILDDT.
Note that this technique restores standard
virtual
addressing
conditions, as if you had used the <ESC>U command. See Chapter 11
(Physical and Virtual Addressing Commands) for more information about
virtual addressing conditions.
To close the file, save all modifications (as
and exit from FILDDT, enter:

with

<CTRL/E>,

above)

<CTRL/Z>
If you exit FILDDT by entering <CTRL/C>, changes that you make to a
disk file can still be in FILDDT's output buffer; if so, they will NOT
be saved. However, modifications to the monitor and running jobs take
effect as you enter them.
When you exit FILDDT with <CTRL/Z>, you can save FILDDT with its
internal symbol table.
This saves time if you often use FILDDT to
debug a specific target (such as the monitor) that has a very large
symbol table.
Start FILDDT, load the symbol table, then exit with <CTRL/Z>. Use the
TOPS-10 SAVE command to create a copy of FILDDT to be used with that
specific file.

9-5

CHAPTER

EDDT

EDOT is used to debug the monitor. You can run EOOT in executive mode
to debug the running monitor, or in user mode to examine and patch the
monitor .EXE file.

l~.l

EXECUTIVE MOOE

When you use EOOT in executive mode, it appears as if you were running
the monitor as a user job with OOT merged in.
You can set
breakpoints~ examine and modify memory,
and perform all other OOT
functions.
When at a breakpoint, timesharing is suspended, and you
have total control of the system.
You can run EOOT is executive mode only from the CTY.
To obtain
faster
response than from a printing terminal, you can redirect the
CTY (only on a KL-l~) to a OH-11 line that is connected to a video
terminal (see the TOPS-10/TOPS-2~ RSX-2~F System Reference Manual).
To use BOOT in executive mode, you must invoke it when booting the
monitor.
EOOT is built and loaded with the monitor, but if you do not
invoke it when booting the system, it is discarded to save space.
Invoke EOOT by using the /E switch when giving BOOT the name of the
monitor file:
BOOT>file-spec/E
where file-spec is the name of the monitor file that BOOT is to load.
After receiving the EOOT prompt, enter:
OEBUG<ESC>G
This tells EOOT to start the monitor in debugging mode, in which EOOT
remains in memory. The monitor goes through a minimal start-up dialog
and then begins timesharing in "DEBUG" mode.
Once timesharing has begun, enter EOOT by typing <CTRL/O> on the CTY.
The monitor traps <CTRL/O>, and calls an internal subroutine that
executes a JSR to DOT location $~BPT (dollar sign, zero, BPT). This
causes EOOT to suspend execution at the unsolicited breakpoint, and to
display:
$~B»addr/

instr

where addr is the monitor location following the JSR
instr rs-the instruction at addr.

l~-l

instruction

and

EDDT .
Timesharing is suspended and you can perform any DDT functions.
If the system is hung (and EDDT has been kept in memory), you
able to enter EDDT through the PARSER. On the CTY, type:
<CTRL/\>

may

(control backslash)

When you receive the following prompt:
PAR>
enter:
HALT
to freeze the machine state.
enter:

The

parser

again

prompts

PAR>.

Now

EXAMINE KL
to type out the machine state at the time of the HALT.
prompt, enter the command:

At the

parser

JUMP 401
to enter EDDT. The monitor is frozen in its state at the time of
HALT. The start address of EDDT is 401.

the

The dialog on the CTY after you enter <CTRL/\> might appear as follows
(your input is in lowercase):
PAR>halt
PAR>examine kl
PC/ 1450
VMA/ 405452
PI ACTIVE: ON, PION: 000, PI HOLD: 020, PI GEN: 000
NO KL PC FLAGS ARE SET
PAR>jump 401
EDDT
You can now use DDT commands to debug the monitor.
NOTE
The <ESC>Y command in executive mode EDDT
the console paper tape reader.

10.2

reads

from

USER MODE

You can use EDDT in user mode, to examine and patch the monitor .EXE
file,
and then use the TOPS-10 SAVE command to save (and rename, as
appropriate) the new version of the file. You can then boot and test
the patched version later, during stand-alone time.
Invoke user-mode EDDT by first using the TOPS-10 GET command:
GET filnam
where filnam is the name of the monitor
TOPS-10 DDT command. EDDT prompts:
DDT
10-2

.EXE

file.

Then

use

the

EDDT
EDDT does not prompt EDDT because you are in user mode rather than
executive mode.
YoU--Can now use DDT commands to set breakpoints,
examine, and patch the monitor .EXE file. When you exit EDDT, you can
use the TOPS-10 SAVE command to save the .EXE file.
If you left
breakpoints set when you exited, they are still active when you boot
the monitor using the saved .EXE file.

10-3

CHAPTER 11
PHYSICAL AND VIRTUAL ADDRESSING COMMANDS

All TOPS-10 DDTs (including FILDDT) can do their own page mapping.
The commands described in this chapter allow you to set parameters to
govern the interpretation of the address space which you
are
examining.
You can control the mapping of the address space you are
examining by choosing to use or bypass the user process table (UPT) or
the executive process table (EPT). You can choose which special pages
table (SPT) to use, and which hardware register block to use.
Other
commands allow you to emulate either KI-paging or KL-paging, control
address relocation, and set memory protection limits.
In each of the
following commands, the argument (page, addr, n) defaults to zero.
NOTE
The DDT commands <ESC>G, <ESC>P, and <ESC>X have side
effects that affect your control over physical and
virtual addressing.
In addition to their normal
functions, these commands also do the following:

COMMAND

restore normal virtual addressing as if <ESC>U had
been given «ESC>X does NOT do this)

set the FAKEAC flag (as if <ESC>U had been given)

clear the relocation factor (as
been given)

reset the address-protection address
(377777,,777777)

restore the active hardware register block to the
one in use before any <ESC>4U command was given

0<ESC>8U
to

had

infinity

EXPLANATION

<ESC>U
This command enables memory mapping by standard TOPS-10 virtual
addressing. When you give this command, DDT restores the virtual
addressing conditions
that
were
in
effect
before
any
{<ESC>}<ESC>nU
(where 0<=n<=2)
commands were given, and sets
DDT's FAKEAC flag,
thereby forcing DDT to interpret memory
addresses 0-17 as DDT's own internal "registers", in which the
user's registers were saved.

11-1

PHYSICAL AND VIRTUAL ADDRESSING COMMANDS
<ESC><ESC>U
This command enables DDT to use actual physical addresses when
accessing memory, and clears DDT's FAKEAC flag, causing DDT to
interpret memory addresses 0-17 as the hardware registers 0-17.
This command is meaningful only when using EDDT in executive
mode, or when using FILDDT to look at the running monitor.
Although DDT accepts <ESC><ESC>U at other times, this command
then produces the same effect as <ESC>U.
The general syntax of the following virtual addressing commands is:
arg<ESC>nU
where n is the function number of the command, and ~ is dependent on
the function (see the function descriptions below).
Functions 0, 1, and 2 enable you to control memory mapping by
selecting the executive process table (EPT), user process table (UPT),
or the section map through which mapping occurs.
Setting a mapping
condition with anyone of these functions (0, 1, and 2) also has the
effect of clearing the effects of any prior use of one of these
functions (0, 1, and 2).
You can also specify the offset into the special pages table
with functions 0, 1, and 2 by using the following command:

(SPT)

arg<ESC><ESC>nU
where arg is the SPT offset, and 0<=n<=2.
KL-paging is in effect.

This form is legal only

NOTE
All forms of <ESC>B and <ESC>X are illegal if you have
used the page mapping functions (0, 1, or 2) and have
not restored standard mapping with the <ESC>U command.
COMMAND

EXPLANATION

page<ESC>0U
This command causes memory mapping to occur through the executive
process table (EPT) that is located at physical page ~.
offset<ESC><ESC>eU
This command produces the same effect as page<ESC>eU
except that offset is an offset (in words) into the SPT.

(above),

pagel<page2<ESC>eU
This command is an exception to the general syntax, and is legal
only under KI-paging.
You can select both the user page table
(UPT) and the executive page table (EPT) with this command, where
pagel is the page number of the UPT, and page2 is the page number
of the EPT. Follow pagel with a left angle bracket

«).

page<ESC>lU
This command causes memory mapping to occur through the
process table (UPT) that is located at physical page~.
this command, you can bypass the EPT.
11-2

user
With

PHYSICAL AND VIRTUAL ADDRESSING COMMANDS
offset<ESC><ESC>lU
This command produces the same effect as page<ESC>lU
except that offset is an offset (in words) into the SPT.

(above),

page<ESC>2U
This command causes mapping to occur through the section map at
physical page ~. This command is legal only if KL-paging is
in effect.
offset<ESC><ESC>2U
This command produces the same effect as page<ESC>2U
(above),
except that offset is an offset (in words) into the SPT. This
command is legal only if KL-paging is in effect.
n<ESC>3U
This command determines whether DDT interprets references to
memory locations 0-17 as references to hardware registers, or to
DDT's own internal "registers"
(which normally contain the
user-program ACs) , by setting or resetting DDT's FAKEAC flag.
If n=0, reset FAKEAC flag (use the hardware regist~rs 0-17).
If n is nonzero, set FAKEAC flag (use DDT's internal registers
0-17).
If you enter a nonzero value for n, DDT stores the value -1.
n<ESC>4U
This command tells DDT to copy hardware register block n
(0<=n<=7)
to its own internal register block, set the FAKEAC
flag, and use hardware register block n as its own registers.
If
the FAKEAC flag
is set when you give this command, DDT first
restores the contents of its internal register block to the
hardware register block from which they were copied. This
command is legal in executive mode EDDT only.
Note that the
microcode uses register block 7, and any attempt to use this
block produces an almost immediate system crash.
addr<ESC>5U
This command copies the 20 (octal) word block located at addr
DDT's internal "registers" and sets the FAKEAC flag.

addr<ESC>6U
This command sets the special pages table (SPT) to addr.
addr<ESC>7U
This command sets the core status table address (CST) to addr.
addr<ESC>8U
This command sets the address relocation factor
adds addr to all user addresses that you enter.

addr.

DDT

addresses

above

addr

addr<ESC>9U
This command read-and-write-protects
(before adding relocation factor).
11-3

all

PHYSICAL AND VIRTUAL ADDRESSING COMMANDS
n<ESC>10U
This command controls whether KI paging is enabled or cleared.
If n is nonzero, KI paging is enabled.
If n=0, KI paging is cleared.
If you enter a nonzero value for n, DDT stores the value -1.
This command is illegal in executive mode EDDT.
n<ESC>llU
This command controls whether KL paging is enabled or cleared.
If n is nonzero, KL paging is enabled.
If n=0, KL paging is cleared.
If you enter a nonzero value for n, DDT stores the value -1.
This command is illegal in executive mode EDDT.
22<ESC>U
23<ESC>U
These commands specify the type of CPU on which the program is
being debugged.
22<ESC>U refers to a KL processor.
23<ESC>U
refers to a KS processor.
For DDT, this command is meaningless, because DDT uses the
current CPU type.
However, these commands may be useful for
FILDDT.
You can interrogate DDT to determine the last virtual addressing
command that was given for a specific function.
The command:
<ESC>nU
where 0<=n<=11, returns the address of a DDT location that contains
the argument that was given if the command for that function was used,
and returns the default value-i~hat functIon was-not used. ---If--yQu
entered a nonzero argument to a command that requires zero or nonzero
values (or if the default is nonzero), this location contains -1. You
can use DDT commands to examine this location.
The command:
<ESC><ESC>nU
where 0<=n<=2, returns the address of a DDT location that contains
information that indicates which function you used, and whether you
set a page address or an offset. You can use DDT commands to examine
this location.
This command is illegal for all functions where n>2.
If you did not enter any commands affecting functions 0-2 since the
last <ESC>U command, the right half of this DDT location word contains
zero. Otherwise, the right half contains n+l, where n is the number
of the command function you used.
If you set a page address (with
arg<ESC>nU), bit 1 of this word is reset. If you set an offset
(with
arg<ESC><ESC>nU), bit 1 of the word is set.

DDT V44

11-4

April 1986

CHAPTER 12
EXTENDED ADDRESSING

You can load your program with LINK so that the program
extended sections (sections other than Section 0).

resides

If you are debugging a program with extended sections
(also called
non-zero sections, or NZS), DDT is automatically loaded into Section
0, started at location 700000. To access non-zero sections, you must
issue the <ESC>4M command to enable intersection (global) breakpoints.
After you use the <ESC>4M command, you can
set
intersection
breakpoints and execute instructions that cross section boundaries.
(Refer to Section 12.2 for more information about intersection
breakpoints.)
You can load a normal, Section 0 program into a non-zero section (NZS)
using one of the following monitor commands:
.RUN prog/USE:n
.GET prog/USE:n
where n is the section number in which to load the program.
These
commands are documented in the TOPS-10 Operating System Commands
Manual.
If the program does not already have DDT loaded, then a DDT command
will merge SYS:VMDDT with your program, starting at address 700000 (in
Section 0).
In this case, DDT will be able to examine and deposit to
locations
in
the program, but you cannot set breakpoints or
single-step the program. You can merge VMDDT into a NZS section using
the monitor command:
.MERGE SYS:VMDDT/USE:n
A subsequent DDT command will then start DDT in section ann. When you
merge DDT into the same section that you specified in the GET/RUN
command, you can immediately set breakpoints and single-step the
program.

DDT V44

12-1

April 1986

EXTENDED ADDRESSING
When DDT is first started in Section 0,
if
it
detects
an
extended-section symbol table pointer, it will attempt to map itself
into an extended section so that it can access the symbol table.
For
example, the monitor works this way. DDT is load~d into Section 0
along with the rest of the monitor's low and high segments, and the
symbol table is placed in Section 2.
The section chosen is the
entry-vector section, if any; otherwise, the section that contains the
symbol table is used, or Section 1. If DDT can find a section to use,
DDT displays the following message:
[DDT - Section 0 mapped into section n for NZS symbol table access]
where n is the section number that is actually used. If DDT is unable
to find a section where it can be mapped, it displays the following
message and continues running:
[DDT - Can't access NZS symbol table(s) from Section 0]
When your program is running in extended sections, DDT searches for
the symbol table first in the entry vector section, if any; otherwise
it searches JOBDAT (locations .JBSYM, .JBUSY, and .JBHSM)
in Section
~.

Although TOPS-l0 does not support Program Data Vectors (PDVs), you can
set up your own PDV, and use the $SM command to specify the address of
a PDV to use for the symbol table vector(s).

12.1

BREAKPOINTS

If DDT is running in a non-zero section, breakpoints can be set in any
section.

12.1.1

The Breakpoint Block

To set breakpoints in a section other than the section containing DDT,
DDT requires an area of storage in the section containing the
breakpoint. This storage area, also known as the "breakpoint block,"
is required for saving global addresses for transferring control
between your program and DDT, and for executing single-stepped
instructions that refer to memory locations outside their section.
Each section in your program's memory space that contains a breakpoint
must have one breakpoint block, located at the same relative local
address within the section, of 100 octal words in length.
(If two or
more sections of the program are mapped together, the breakpoint
blocks must also be mapped together.)
Each breakpoint block is contiguous within the section.
Breakpoint
blocks cannot be extended across section boundaries, and do not wrap
around the end of the section to the beginning of the section.
Your program can refer to locations in the breakpoint block; remember,
however, that DDT can overwrite this information.

DDT V44

12-2

April 1986

EXTENDED ADDRESSING
12.1.2

Enabling and Disabling Intersection Breakpoints

The section-relative (18-bit)
address of the breakpoint block is
stored in an internal DDT location. The command <ESC>4M returns the
address of that location. The symbol $4M refers to the DDT location
at the address returned by <ESC>4M.
Intersection breakpoints are
enabled when $4M contains the locations of the breakpoint block.
To specify the address of the breakpoint block, use the following
command:

DDT

n<ESC>4M
where n is the address of the breakpoint block, and can be any valid
DDT expression {from 20 to 777700}. DDT uses only the right half of
n, and changes only the right half of the DDT location at $4M.
To display the location of the breakpoint block, use the following DDT
command:
<ESC>4M/
Therefore,
When this location contains 0, breakpoints are disabled.
you can use the following command to disable intersection breakpoints:
0<ESC>4M
While intersection breakpoints are disabled, you cannot set
a
breakpoint in a section external to DDT, and any breakpoints already
set in such a section are lost when you begin program execution with
<ESC>P or <ESC>G.
For each breakpoint that is lost, DDT displays the
following message:

% CAN'T INSERT $nB - IN NON-DDT SECTION
where n is the breakpoint number.
While intersection breakpoints are disabled, DDT cannot
<ESC>X command under the following circumstances:

execute

the

When you try to execute the instr<ESC>X command, and
default section is not the section that contains DDT.

the

When you try to single-step a dangerous instruction and
user program PC is not in the section that contains DDT.

the

In these cases, when you try to use <ESC>X, DDT rings
bell or buzzer and sets its error message text to:

the

terminal

Intersection reference and no $4M global breakpoint/execute block

DDT V44

12-3

April 1986

EXTENDED ADDRESSING
12.2

DISPLAYING SYMBOLS IN NON-ZERO SECTIONS

DDT normally uses right-halfword values when searching symbol tables
for symbols to display.
However, code linked in a non-zero section
has symbols defined with the section number in the 1eft-ha1fword. DDT
uses a
3~-bit
value when searching for a symbol in the following
circumstances:
o

when displaying the address of a location

when displaying the contents of a location as an address

when displaying the Y field of an instruction

When displaying an address, DDT searches for a symbol defined with the
3~-bit
value of the address.
If such a symbol is not found, DDT
displays the address in ha1fword format.
When displaying the Y field of an instruction, DDT
symbol defined with a 30-bit value consisting of:

searches

for

the section number of the address of the word being displayed

the section-relative address contained in the Y field of
instruction

the

If DDT does not find a symbol defined with that 30-bit value, it looks
for a symbol defined with the l8-bit value contained in the Y field of
the instruction.
Assume a program with the following conditions:
Symbol LABL1 is defined as ~,,300
Symbol LABL2 is defined as 3,,300
Location 1,,300 contains 3,,300
Location 1,,301 contains 2,,300
Location 3,,400 contains 200040,~300
(MOVE contents of location 300 to AC 1)
When displaying the contents of location 1,,300, DDT displays:
1"LABLl/

LABL2

When displaying the contents of location 1,,301, DDT displays:
1"LABL1+1/

2"LABLl

When displaying the contents of location 3,,400, DDT displays:
LABL2+100/

12.3

MOVE 1,LABL2

DEFAULT SECTION NUMBERS

To reduce th~ need to type in the section number as part of the
address when you specify a location, DDT uses a default section number
when you do not specify one. DDT has two section defaulting options:
o

Permanent default section

Floating default section

DDT V44

12-4

April 1986

EXTENDED ADDRESSING
The command (ESC>6M returns the address of an internal DDT location
that contains section default information. The symbol $6M refers to
the DDT location at the address returned by the command (ESC>6M.
When DDT is in Section 0, the default
regardless of the contents of $6M.

12.3.1

section

number

always

Permanent Default Section

If the value contained in $6M is positive
(Bit 0 is reset), the
permanent default section option is in effect. DDT then takes the
left half of $6M as the section number of any address that you type in
without a section number.
Set the permanent default section by typing the following DDT command:
n,,0(ESC>6M
where n is the section number, and can be any legal DDT expression.

12.3.2

Floating Default Section

If the value contained in $6M is negative (Bit
is set), the floating
default section option is in effect. This is the default option (at
startup, DDT initializes $6M to -1). DDT selects the floating default
section as follows:
o

If you enter DDT from its normal start address, DDT sets
default section to one of the following:

the

the section that contains the program
there is an entry vector)

(if

Section

entry

vector

If you enter DDT from a breakpoint, DDT sets the
section to the section that contains the breakpoint.

default

If you open a local address between 20 and 777777, DDT sets
the default section to the section that contains the open
address.

If you type in an address that contains a section number
(including a symbol that is defined with a section number),
DDT sets the default section to the one in the address you
typed in.

If you exit DDT with (CTRL/C> or (CTRL/Z>, and then reenter DDT, the
current location does not change.
If you give a command that takes
the current location as its default address argument, DDT sets the
floating default section to the section of the current location.

DDT V44

12-5

April 1986

EXTENDED ADDRESSING
In the following example, the DDT screen display is on the left, and
explanatory comments are on the right.
The entry vector is in section
1. Symbol START is not defined with a section number. User typein is
in lowercase.
Screen Display

User Input

Explanation

3"place/

Examine location 3"PLACE.
DDT displays the contents.

LABLI

Type in <LF> to
next location.

<LF>
3"PLACE+1/

@ddt

<CTRL/C>.
location

The
is

Reenter DDT.

DDT

DDT is loaded and ready for
your command.
The floating
default section is 1, because
the entry vector is in section
1.
<LF>

Type in <LF> to
next location.

examine

the

DDT displays the address and
contents of the next location.
DDT doesn't use the floating
default section, because your
<LF> command defaults addr to
the current location, and uses
its section number (3).

LABL1+4

start/

Examine location START.
DDT
uses
the
floating default
section number because symbol
START
is
defined with no
section number.

JFCL 0

DDT displays the contents.
<LF>

DDT V44

Exit
with
current
3"PLACE+l.

TOPS-20 prompts you.

1"START+l/

the

DDT
displays
the
next
location.
The
floating
default section = 3.

LABLl+2

3"START+2/

examine

Type in <LF> to
next location.

MOVE 1,LABLl

12-6

examine

the

DDT displays the address
contents of the location.

and

April 1986

EXTENDED ADDRESSING
12.4

EXECUTING SINGLE INSTRUCTIONS

Instructions that are executed by means of the command:
instr<ESC>X
where instr is the instruction for DDT to execute, are executed within
the current default section.
If that section is not the one that
contains DDT, DDT uses the breakpoint block in that section to execute
instr.
If the floating default section option is in effect, and you
are unsure of the current default section, use the addr/ command to
open a location in the section in which you wish DDT to execute instr.
This sets the default section to the section specified by addr.
Instructions that are executed by means of the command:
instr<ESC><ESC>nX
where instr is the instruction for DDT to execute, are executed within
the section specified by n.
If you type this command without
specifying the section number, DDT uses its current section.
If DDT is to execute the instruction in a section other than
that contains DDT, intersection breakpoints must be enabled.

the

one

If you try to execute instr outside DDT's section while intersection
breakpoints are disabled, DDT sounds the terminal buzzer or bell,
displays "?", and sets its error string to:
Intersection reference and no $4M global breakpoint/execute block

12.5

ENTERING PATCHES IN EXTENDED SECTIONS

You cannot type in a patch if a patching area does not exist in the
section that contains the word to be replaced.
To ensure that there
is a patching area for each section that contains user-program code,
do one of the following:
o

Reserve the same part of each section for patches, and define
the patch symbol as 0"addr, where addr is the local address
of the patching area.

Use only one patching area, and map it into all the sections
that contain user-program code.
Define the patch symbol as
0"addr, where addr is the local address of the patching
area.

Define a different symbol for each section's patching area,
and use the symbol appropriate to the section being patched.

If the left half of expr is 0, DDT defaults the section to the section
that contains the open location.
If the left half of expr is a value
that is not the section that contains the open locations, DDT displays
the following message:
?CAN'T PATCH ACROSS SECTIONS

DDT V44

12-7

April 1986

APPENDIX A
ERROR MESSAGES

DDT and FILDDT display error messages to indicate the results of your
commands.
DDT sometimes (and FILDDT usually) displays these messages
on the screen, and at other times displays only a question mark. When
only a question mark is displayed, a location internal to DDT usually
points to a text string that is the error message.
To display the
error message, enter the command:
<ESC>?
Following is a list of DDT messages together with explanations of what
the messages indicate.
? ABOVE PROTECTION REGISTER LIMIT

The address of the location you tried to display or modify is
above the protection register limit, which is set by n<ESC>9U.

? ACTUAL REFERENCE FAILED
A memory reference failed unexpectedly (the page
readable, but the reference failed anyway).

exists

and

? ADDRESS GREATER THAN 777777

An address to be mapped through a section table has a nonzero
section number.
This can occur only if you specified a section
table with the n<ESC>{<ESC>}2U command.
? ADDRESS BEYOND END OF PHYSICAL MEM

You attempted to examine a physical memory location beyond the
end of physical memory. This error occurs only if you have used
the <ESC><ESC>U command to enable physical addressing_

? BAD FORMAT FOR .EXE FILE
You specified a file that appears to have an .EXE directory, but
the directory is badly formatted or DDT cannot read it because of
some other reason.
?

BAD $4M VALUE
You used the n<ESC>4M command where 777700<n<20.

DDT V44

A-I

April 1986

ERROR MESSAGES
? BAD POINTER ENCOUNTERED

DDT does not recognize the type code contained in a page map
pointer.
This can occur only if you are trying to do your own
virtual address mapping, and used the expr<ESC>{<ESC>}nU command,
where 0<=n<=2.

? CAN'T BE WRITE ENABLED
Even though you have automatic write-enable turned on, DDT is
unable to write-enable a page that exists and is write-protected.
? CAN'T CREATE PAGE

DDT attempted to create a page and failed, or else is
attempt to create the page (see the <ESC>lW command).

unable

? CAN'T DEPOSIT INTO SYMBOL TABLE BECAUSE •••••

You tried to define or kill a symbol, but DDT was unable to
modify the symbol table. Look up the second part of the error
message in this appendix.
? CAN'T DEPOSIT INTO SYMBOL TABLE BECAUSE DEPOSIT FAILED

You tried to define or kill a symbol, but DDT was unable to
modify the symbol table, and cannot identify the specific reason.

% CAN'T INSERT $nB BECAUSE •••••
DDT is not able to access the location where you inserted your
breakpoint.
Look up the second part of the error message in this
appendix. This occurs before DDT tries to execute <ESC>G,
<ESC>P, <ESC>X, or <ESC><ESC>X.

% CAN'T INSERT $nB BECAUSE BREAKPOINT IS IN DIFFERENT SECTION
DDT is not able to access the location where you inserted your
breakpoint because inter-section breakpoints are not enabled
«ESC>4M contains zero). This error occurs before DDT tries to
execute <ESC>G,
<ESC>P, <ESC>X, or <ESC><ESC>X.
To enable
inter-section breakpoints, deposit the breakpoint block address
in the location addressed by the command <ESC>4M.
% CAN'T INSERT $nB BECAUSE MEM REF FAILED
DDT is not able to access the location where you inserted your
breakpoint. DDT is not able to identify the reason. This occurs
before DDT tries to execute <ESC>G,
<ESC>P,
<ESC>X,
or
<ESC><ESC>X.
% CAN'T REMOVE $nB BECAUSE •••••
DDT is not able to access the location where you inserted your
breakpoint.
Look up the second part of the error message in this
appendix. This error occurs when your program enters DDT from a
breakpoint.
DDT V44

A-2

April 1986

ERROR MESSAGES
%CAN'T REMOVE $nB BECAUSE BREAKPOINT IS IN DIFFERENT SECTION
DDT is not able to access the location where you inserted your
breakpoint, because
inter-section breakpoints are not enabled
«ESC>4M contains zero).
This error occurs when your program
enters
DDT
from
a
breakpoint.
To enable
inter-section
breakpoints, deposit the breakpoint block address in the location
addressed by the command <ESC>4M.
% CAN'T REMOVE $nB BECAUSE MEM REF FAILED
DDT is not able to access the location where you inserted your
breakpoint.
DDT is not able to identify the reason.
This error
occurs when your program enters DDT from a breakpoint.
%CAN'T SET BREAKPOINT, $4M NOT SET
You attempted to set a breakpoint in a section other than the one
containing DDT while inter-section breakpoints were not enabled.
? Device must be a disk unit or a file structure
The device that you specified to the /U command is not a disk.

? Explicit structure required with /U
You used the /U command without specifying a device.

? FAILURE ON SWITCHING ADDRESS SPACE
EDDT (Executive mode EDDT only) encountered an error while trying
to access the virtual
address space where monitor symbols are
kept.
? FILOP.

failure (n)

for input file

The FILOP.
call to open the specified file or unit
error code n.

failed

with

command

where

?Garbage at end-of-command
FILDDT encountered extra text at a place
there should have been only <RET>.

the

Intersection reference and no $4M global breakpoint/execute block
Inter-section breakpoints are not enabled, and:
o

you tried to execute the command instr<ESC>X but the
section is not the section that contains DDT, or

you tried to single-step a dangerous
instruction but
user-program PC is not in the section that contains DDT.

DDT V44

A-3

default
the

April 1986

ERROR MESSAGES
? I/O error

An I/O error occurred when FILDDT attempted to read or
the file or unit.

write

? I/O error reading command file

DDT encountered an I/O error when reading the command
you specified to the <ESC>Y command.

file

that

? Illegal job number

You entered an illegal job number with the /J command.
? Illegal switch "c" specified

You entered a command other than /D, /F, /H, /J, /M, /P,

/u.

IS,

? Incorrect symbol table pointer

FILDDT is unable to read the symbol table specified by the symbol
table pointer in the file.
? Input device must be a disk

The device you specified is not a disk.
? Insufficient memory to read EXE file directory

FILDDT does not have enough free memory to read in the
section of the .EXE file that you specified.