Soul of CP-M

SOUL OF CP/M ®
(How to Use the Hidden Power of Your

C P/M ® System)
by
Mitchell W aite and Robert Lafore
Howard W. Sams & Co.

A Division of Macmillan, Inc.
4300 West 62nd Street, Indianapolis, IN 46268 USA
© 1983 by the W aite Group, Inc.
F IR S T E D IT IO N
T H IR D P R IN T IN G - 1986
All rights reserved. N o part of this book shall be repro

duced, stored in a retrieval system, or transmitted by any
means, electronic, mechanical, photocopying, recording, or
otherwise, without written permission from the publisher.
N o patent liability is assumed with respect to the use of
the information contained herein. While every precaution
has been taken in the preparation of this book, the pub
lisher assumes no responsibility for errors or omissions.
Neither is any liability assumed for damages resulting
from the use of the information contained herein.
International Standard Book Number: 0-672-22030-X

Library of Congress Catalog Card Number: 83-61059
Edited by: Frank N. Speights

Illustrated by: Kevin Caddell
Printed in the United States o f America.

Preface
* Have you ever wanted to know how the CP/M ® operating system really
works?
* Would you like to use C P /M ’s hidden power in your own BASIC or
assembly language programs?
* Are you a BASIC programmer who would like to learn assembly lan
guage, but have been told that it’s too complicated?
* Do you need to modify C P /M to work with a particular printer or some
other I/O device?
* Do you want to write programs that will work with any version of
CP/M ?
If the answer to any of these questions is yes, then this book, with its
unique approach to teaching both C P /M systems calls and 8080 assembly
language programming, is for you. Starting with simple three- and four-line
programs, we ease you into the “ soul” of C P/M : the universal system calls
that make C P /M the world’s most popular microcomputer operating system.
Gradually and easily, you’ll learn how to write programs to control all your
I/O devices, including the disk system, and, also, perform a variety of other
functions.
Remember, you don’t need to know how to program in assembly language
to understand this book! We’ll teach you all the 8080 assembly language that
you will need to know and, since you’ll be learning the system calls at the
same time, your programs will be able to perform powerful functions from
the very beginning.
C P /M is the registered trademark of Digital Research, Inc., Pacific Grove, CA

Soul of C P /M ®
You’ll also learn how to use these powerful system calls in your BASIC
programs, how C P /M manages disk files, and how to modify C P /M ’s
“ BIOS” (Basic In p u t/O utput System) to work with different I/O devices, so
that you can customize C P /M for a particular printer or other device.
All in all, if you want to do more with your C P /M system than simply run
applications programs, then this book is for you!
M it c h e l l W a it e
and R o ber t La f o r e
Acknowledgments
The authors would like to thank Mark Berger, Phil Chapnick, and Scott
Kamins for their many helpful comments, criticisms, and suggestions. Their
pioneering journey on the road followed by this book has resulted in remov
ing many obstacles from the path of future readers.
Dedication by Robert Lafore

This book is dedicated to my parents.
Contents
In t r o d u c t i o n ............................................................ 11
Soul of C P /M -W h o Is This Book F or—W hat This Book Will
Teach Y ou-8080, 8080A, 8085, Z-80: W hat’s the D ifference?-
What You Need To Know To Get the Most Out of This Book—
How This Book Is Organized—How To Enjoy This Book
CHAPTER 1
T h e B ig P i c t u r e : H ow C P /M I s O r g a n iz e d ................................................... 17
W hat Is an Operating System, Anyway?—W hat’s So G reat About
C P /M ?-T h e Parts of C P /M —8080 Architecture—D D T-The
Programmer’s X Ray and Probe—Back Down to Earth
CHAPTER 2
ONE T o e IN t h e W a t e r : Console System C a lls ....................................... 31
Console O utput System Call—Get Console Status—Barber-Pole
Display Program -Console Input—Executing Programs From
C P /M —System Rest-A Warm Boot—So Long, Chapter 2, It’s Been
Good To Know You
CHAPTER 3
G e t t in g in D e e p e r : Advanced Console System Calls .......................... 71
Print S tring-R ead Console Buffer—Echo Program -N am e Display
Program—Direct Console I /O -L is t O utput to P rinter-R eader
In p u t-P u n ch O u tp u t-G et I/O B yte-Set I/O B yte-Goodbye,
Nondisk System Calls
CHAPTER 4
U s i n g t h e A s s e m b l e r ................................................................................................... 107
W hat’s an Assembler Do, Anyway?—W hat ASM Does—The
“DECIBIN ” R outine-Reads Decimal From K eyboard-D E C IH E X
Program-Converts Decimal to Hex, on Screen—BIN IHEX-Binary
to Decimal Conversion Routine—Using C P /M ’s Submit U tility—
G raduation Time
CHAPTER 5
D is k S y s t e m C a l l s ............................................................................................................137
Records, Files, Tracks, Sectors, Allocation Units, Extents, and
Goodness Knows W hat Else—Talking to BDOS—Open File—The
Problem W ith Where the DM A Is Located—Read Sequential Sys
tem Call—Set DM A Address—TYPE2 Program -Im itates the
“TYPE” Comm and—LINES Program -Prints N um ber of Lines in
Text File—Life on the Fast Track
CHAPTER 6
W r i t i n g t o t h e D i s k ......................................................................................................169
Writing a Sequential Record—Make File—Write Sequential Rec
o rd-C lose File System Call—Program to Write a Sequential Rec
ord—STORE Program-Stores Text in F ile-D elete File System
Call—Random R ecords-R ead Random System C all-W rite R an
dom System Call—RA ND Y M O D -Program to Modify a Random
Record—Compute File Size System C all-S et Random Record Sys
tem C all-O u t of Ink
CHAPTER 7
S o u l S e a r c h i n g : Wildcards and the Disk D ir e c to r y ...............................201
How C P /M Stores Files on the Disk—Search For First System
Call—W ildcards—Search For Next System Call—Erased Files—Sav
ing an Erased File—The Bit M ap-W O R D S Program-Counts
Words in Files and Uses Wildcards
CHAPTER 8
T e a m w o r k : Using System Calls From B A S IC ............................................243
Where Do We Put the A-L Program in Memory?—How To G et the
A-L Program Where We W ant It To G o—How Do We Transfer
Control Between BASIC and the A-L R outine?-H ow Do We Pass
Arguments Between BASIC and the A-L R outine?-B IN IH E X 2-
A-L Routine Called From B A SIC -O ther Ways To Put the A-L
Routine Into M em ory-H EX IB IN 2-Passing Arguments to BASIC
From an A-L R outine-O perating on Strings With an A-L Rou
tine-B ack to Basics
CHAPTER 9
T h e I n n e r m o s t S o u l o f C P/M : H ow To Modify C P /M for
Different P eripherals............................................................................................ 279
Why You’re Reading This C hap ter-W h at Is the BIOS Anyway?—
Learning Your Way Around the B IO S-T he Complete BIOS List
ing—How to Modify Your Printer Driver—Installing the New
Driver Into Your B lO S-Inserting the New Driver Into the C P /M
System -A Shortcut-M odifying BIOS for Different Control Char-
acters-T he Sky’s the Limit
A PPENDIX A
H e x a d e c im a l N o t a t i o n ............................................................................................... 323
Why Use Hexadecimal N otation?—Binary N otation—Decimal
N otation—Hexadecimal N otation—Converting Hex to D ecim al-
Converting Decimal to Hex
A PPENDIX B
U t il it y P r o g r a m s ............................................................................................. 331
H E X D U M P-M icro Space In v ad ers-H E X ID E C -F IL E D U M P
APPENDIX C
S u m m a r y o f 8080 I n s t r u c t i o n s ................................................................... 345
8080 Architecture—8080 Instructions—Assembler Directives
APPENDIX D
T a b l e s ..................................: ............................................................................. 359
ASCII Character Set With Hexadecimal Equivalents—Hexadeci-
mal-to-Decimal Conversion—Multiples of IK (1024), in Decimal
and Hexadecimal—Decimal, Hex, and Binary Conversion
APPENDIX E
S u m m a r y o f B D O S S y s t e m C a l l s (F o r C P /M 2.2) 365
A PPEND IX F
S u m m a r y o f D D T C o m m a n d s ......................................................................369
Loading D D T —“A” for Assemble—“ D ” for Dump M emory—“ F ”
for Fill—“G ” for G O —“ H ” for Hexadecimal Arithmetic—“ I” Com-
m a n d -“ L” for L is t- “M” for M o v e -“ R ” for R e a d - “ S” for Set
M em o ry -“T” for T ra c e -“U ” for U n tra c e -“X” for Examine Reg
isters
APPEND IX G
S u m m a r ie s o f P r o g r a m s U s e d a n d L o c a t io n s o f I n s t r u c t io n
D escription s ....................................................................................................................... 379
Programs U sed-D escriptions of Instructions
In d e x 383
Introduction
SOUL OF CP/M®
What do we mean by the “Soul” of C P/M ? One of C P /M ’s most pleasant

features is its ease of use. The loading of applications programs, the use of
such C P /M functions as DIR, STAT, and PIP, and the use of higher-level
languages such as BASIC or FORTRAN, are all simple and straightforward
11
Soul of C P /M ®
in the C P /M environment. In fact, this efficient facade is all that many users
will ever know about C P/M . And yet, below this smooth and easy-going sur
face, C P /M has a whole different level; a powerful inner structure that is
easily used if you know how, which can control your com puter’s input and
output devices, including the disk drives, with a precision and a versatility
that is impossible to obtain from a higher-level language. We call this deeper
and more powerful level the “ Soul” of C P /M and, in this book, you will learn
all about it.
WHO IS THIS BOOK FOR?
This book is aimed primarily at BASIC or other high-level language pro

grammers who are working with a C P /M system and need to do more than
they can with their higher-level language. If you need to write custom I/O
routines, handle disk records in a way not accessible to your high-level lan
guage, or use an assembly language routine to add more power or speed to
your programs, this book will teach you how to do it.
This book is also aimed at the assembly language programmer who is
either not familiar with 8080 assembly language, or who needs to know more
about how to program in the C P /M environment.
WHAT THIS BOOK WILL TEACH YOU
First, this book teaches how to use C P /M ’s built-in system calls. These
system calls are the key to programming in a C P /M system, since they allow
your program to communicate with a wide variety of I/O devices, using a
universal format that works on any C P /M system. Once you’ve learned how
to use these calls, you are freed of the restraints imposed by BASIC or what
ever other high-level language you are using. You can directly access the
video screen, the keyboard, the disk system, and other I/O devices, so that
they respond the way you want them to, not the way the designers of your
particular language decided they should.
Second, you will learn all about the C P /M disk system. You will learn how
it is organized, and how you can take control of it for use in your own pro
grams.
Third, you will learn how to “customize” C P /M to work with different I/O
devices. Since there is no universally accepted format for the communication
12
Introduction
between I/O devices and computers, it is almost always necessary to write a

special program called a “driver” in order to make your computer work with
a new I/O device. C P /M ’s solid, well-organized, I/O system makes this easy,
and we teach you how to do it.
Fourth, and this is thrown in as a sort of fringe benefit, you will learn 8080
assembly language. (If you already know it, that’s fine too. We’ve placed all
the descriptive text about assembly language in distinctive boxes, which are
easy to skip over if you wish.) As you learn assembly language, you will also
be learning the use of the C P /M programs DDT, LOAD, and ASM.
8080, 8080A, 8085, Z-80: WHAT’S THE DIFFERENCE?
A “chip” is the tiny slice of silicon which contains the thousands of transis
tors that make up a microprocessor. The exact design of this chip determines
the “instruction set” of the computer; that is, it determines what commands
you have to give it to make it work. Different chips are given different names.
One of the most famous is the “ 8080” chip manufactured by Intel Corpora
tion. After this chip had been in production for a time, Intel improved it by
coming out with a faster version called the 8080A. Later, Intel added the
8085 chip, which is very similar to the 8080 and 8080A, except for some
improvements in the way that it handles interrupts.
Throughout this book, when we refer to the “8080” microprocessor chip,
we are also referring to the 8080A and the 8085. The differences are relatively
minor and, in any case, only apply to the interrupt system which we will not
be concerned with.
Also, this family of chips is “upward compatible.” This means that any
program written for an earlier chip (the 8080, say) will run on any later chips
(the 8080A and the 8085). Thus, even if we used the interrupt system, by
programming for the 8080, we ensure that our programs will run not only on
the 8080 but, also, on the 8080A and the 8085 as well.
The Z-80 is a chip manufactured by Zilog. Although it is also upward
compatible with the 8080, it has a considerably enlarged instruction set.
Generally speaking, programs written for the 8080 will run on the Z-80 as
well, although there are exceptions.
What it comes down to is this. The programs that you learn to write for the
8080 microprocessor will also run on the 8080A, the 8085, and (usually) on
the Z-80. So, no m atter which of these chips is used in your C P /M system,
this book will tell you what you need to know to write working programs.
13
Soul of C P /M ®
WHAT YOU NEED TO KNOW TO GET THE MOST OUT OF

THIS BOOK
Before you start this book, you should have some minimal experience with
a C P /M system, including the use of DIR, PIP, and STAT. (If you need to
learn C P /M from the ground up, consult C P / M Primer, by Stephen M urtha
and Mitchell Waite, and C P / M Bible, by Mitchell Waite and John
Angermeyer.) You should also have at least a nodding acquaintance with a
text-editor of some sort, either the ED program that comes with C P /M or
another of the many popular text-editors, such as WordStar®.
Also, of course, you need access to a C P /M system, with the programs
ASM, DDT, LOAD, and your word-processing program.
This book will not teach you all of the bells and whistles of 8080 assembly
language programming. Since our emphasis is on C P/M , we will teach you
only enough assembly language to handle the examples in the book.
Although this is actually a fairly large chunk of assembly language, if you
want to go on and write your own complex applications programs, you
should read a good 8080 assembly language primer, such as 8080A-8085
Assembly Language Programming, by Lance A. Leventhal.
You should probably also have some experience with some programming
language, such as BASIC, FORTRAN, or Pascal, before you start this book,
so that you are familiar with fundamental programming concepts.
HOW THIS BOOK IS ORGANIZED

Chapter 1 is an introduction to C P /M ’s organization. You’ll learn why
C P /M can run on many different computers and why many different pro
grams can run on C P/M . The way C P /M fits into memory will also be
explained. Also, we’ll talk a little about how 8080 assembly language works,
and how D D T can be used to write simple programs.
In Chapter 2, we’ll start by writing some very short routines to access the
simplest of the systems calls, starting with outputting a single character to the
video screen. At the end of the chapter, we’ll write an actual program which
can be executed directly from C P /M , like any other program. Every step of
everything you need to do will be explained in detail, so that no m atter how
new all this is to you, you can’t go wrong!
WordStar is the registered trademark of MicroPro™ International Corp., San Rafael, CA

94901
Introduction
Chapter 3 will advance further into the realm of system calls and you’ll
learn how to handle strings of text, both for input from the keyboard and
output to the screen. Throughout Chapters 2 and 3, you’ll also be learning
the rudiments of assembly language, using D D T as a fast and easy way to try
out the small programs needed for the examples.
In Chapter 4, we’ll introduce you to ASM, the C P /M assembler, which
simplifies the writing of larger assembly language programs. You’ll also write
and operate a useful program —one which translates hexadecimal numbers
(the kind the computer uses) to decimal numbers (the kind humans use) and
makes use of the system calls you’ve been learning. (In case you’re not famil
iar with the hexadecimal numbering system, it’s described in detail in Appen
dix A.)
Chapters 5 and 6 cover the disk system. You’ll learn about the fundamen
tal building blocks of disk storage: records and files, and how to manage
them. You’ll also write a variety of programs making use of the disk system
calls. These programs will be used to write files and retrieve them from the
disk in both sequential and random format, and there will even be a program
to count the number of lines and pages in a file. As a bonus, we’ll delve into
the mysterious world of C P /M file directories and you’ll learn how to “res
cue” a file which has been mistakenly erased!
C hapter 7 covers a larger program in detail. This is “W ORDS”, which
counts the number of words in a text file. This program will make use of
“wildcards” (the use of * and ? in a program name to represent unknown
characters). It will also introduce the idea of “stack management,” so that
you can avoid a variety of pitfalls in your programming.
Chapter 8 deals with how to use system calls and assembly language from
BASIC. You’ll learn how to “call” assembly language routines from BASIC,
how to pass numbers back and forth between BASIC and your assembly
language routine, and where to put all these routines in memory. As exam
ples, we’ll use routines that allow you to use hexadecimal numbers in BASIC
and allow you to convert BASIC string variables from lowercase to uppercase
letters. Although BASIC is used as the example language here, many of the
techniques described are applicable to other high-level languages as well.
In Chapter 9, we explain how to go about modifying your C P /M to use
different I/O devices. A specific example—writing a driver for a particular
printer—will be described in detail.
Finally, a number of appendices are given that cover hexadecimal notation
and provide summaries of all C P /M system calls, 8080 instructions, and
D D T commands. They also include some useful and entertaining programs
which make use of the material covered in the book.
15
Soul of C P /M ®
HOW TO ENJOY THIS BOOK

This book starts out easily and teaches you more and more as it goes along.
For this reason, don’t try to understand it by starting in the middle some
where (unless you’re already a hot 8080 and C P /M programmer). Start at the
beginning, take it easy, and before you know it, you’ll be doing things with
your computer that you never dreamed were possible!
16
CHAPTER 1
The Big Picture

How C P / M Is Organized
In this chapter, we’re going to talk, in very general terms, about C P /M

itself—how it does what it does and why it’s such a popular operating system.
Then, we’ll present a few fundamental facts about how the 8080 microproces
sor works to prepare you for the introduction to 8080 instructions in the next
r
Soul of C P /M ®
chapter. And, finally, we’ll briefly discuss DDT, a program that lets you write
short assembly language programs quickly and easily.
The idea of this chapter is to provide you with a sort of aerial view of the
terrain we’re going to cover. D on’t worry about specific details yet. W hat
we’re interested in here is concepts: what an operating system is, how it does
what it does, how the computer itself operates, and why we need a program
like DDT. In the next chapter, we’ll get down to specific examples and, then,
the broad outlines described in this chapter will become clearer.
WHAT IS AN OPERATING SYSTEM, ANYWAY?

If you are using a small microcomputer with only a cassette system to store
your programs, you probably don’t even need an operating system. Generally
speaking, a language like BASIC is built into these small computers, and by
using BASIC’s CSAVE AND CLOAD commands or their equivalent, you
can save and load programs from cassettes in much the same way that you
would record and play back a musical selection on a tape recorder.
However, when you add a disk system to your computer, things get a little
more complicated. Now you can have dozens or even hundreds of programs
sitting on a diskette, and you need a way to load a particular one, or list what
they all are, or delete one, or rename it. Operating systems were originally
devised to handle these kinds of housekeeping chores, and that is all many
operating systems do. C P/M , however, goes beyond these simple tasks.
WHAT’S SO GREAT ABOUT CP/M?

C P /M is by far the most popular operating system ever devised for
microcomputers. Why is this? One of the main reasons can be summed up in
a single word: transportability. “Transportability” means that something can
be moved somewhere else and still work in the same way. C P /M has two
kinds of transportability, both of which contribute to its popularity.
Program Transportability
An analogy may make clearer what we mean by “program transportabil

ity.” Imagine an international chain of hotels, scattered across the globe in
the major cities of the world. In order that the typical American traveler will
feel at home in all of these hotels, they are all constructed and operated so as
18
The Big Picture
to be as similar to one another as possible. Thus, the furnishings, the interior

decorations, and the food are the same in any city.
For example, if you’re staying at one of these hotels in Hong Kong and
you order a chicken sandwich, you get a chicken sandwich that is identical,
as far as you can tell, to the one you would get if you ordered it in San
Francisco, or M adrid, or Bangkok. Of course, even though the sandwich is
the same, the way that it is made may vary a great deal from one city to the
next. In San Francisco, the hotel employees get their chicken from a restau
rant supply house. In M adrid, they get it from a man who drives up to the
hotel with a truck full of chickens. And, in some cities, the hotel employees
have to run out into the street and catch a chicken to make the sandwich.
We can think of these hotels as having two levels: the guest’s level, where a
chicken sandwich is always the same, and the hotel employee’s level, where
the making of the sandwich may be very different, depending on the location
of the hotel.
A program running on a C P /M system is like a guest staying at one of our
hotels. The program “thinks” that it is operating in the same environment,
even though it may be runnning one day on one computer and the next day
on a very different computer. It’s the job of the operating system, as it is the
job of the hotel employees, to make the program “feel at home” (that is,
operate correctly), wherever it is. One way that C P /M does this is through
the use of “system calls.”
System Calls
The “system call” is the connection between a program operating in a

C P /M environment and the I/O devices that the program wants to use. It is
analogous to the hotel guest picking up his phone and calling room service.
The system call is essentially a CALL instruction to a subroutine in the
input/output section of the operating system. (CALL means “execute sub
routine” and is similar to a GOSUB in BASIC.) Since these CALLs are all
made in exactly the same way, no m atter what machine a program happens
to be operating on, the program thinks it is operating in the same environ
ment and will work on many different computers. This is what we mean by
program transportability.
System calls do such things as printing a single character on the screen,
reading a character from the keyboard, and reading and writing records
to disks. In fact, system calls can handle all the input and output in the
C P /M system. Since these calls must be made using instructions in 8080
assembly language, they are usually used in assembly language programs,
19
Soul of C P /M ®
but they can also be used from BASIC or other higher-level language p ro
grams if you know how. (We’ll cover the use of system calls from BASIC
in C hapter 8.)
Machine Transportability
The subroutine that a particular program calls will be different, depend

ing on the actual physical characteristics of the I/O device the program
wants to use, ju st as the hotel employees and their particular m ethod of
obtaining a chicken will be different in different cities. This brings us to the
second kind of transportability that makes C P /M so versatile: machine
transportability.
The only part of the C P /M operating system that actually interracts with
physical in p ut/output devices is called the BIOS, for “ Basic Input/O utput
System.” It consists of a number of short separate subroutines, each of which
performs an input or output operation on a specific device. These subrou
tines are easy to modify if a particular piece of I/O equipment (such as a
printer or video display) is changed. Thus, it is easy to reconfigure C P /M to
make it work with different equipment and on different computers. We’ll talk
more about the BIOS later.
The diagram shown in Fig. 1-1 illustrates symbolically the relationship of
C P /M to its programs and to its operating environment.
User’s Program Interchangeable with

other user’s programs.
System System calls are always

calls. the same.
/ ... / / / This part ot CP/M is always

BDOS the same.
Y ■This part of CP/M changes
/
BIOS
/ to match particular I/O
devices.
Interchangeable
with many
different ■Interchangeable with many
computers. I/O Devices different brands of
(tape, keyboard, etc.) I/O devices.
Fig. 1-1. How CP/M is organized.
20
The Big Picture
C P /M ’s Golden Rule
The preceding ideas can be summarized in what is sometimes called

C P /M ’s Golden Rule: “A call to BDOS on one machine is a call to BDOS on
all machines.” Or, using our hotel analogy, “A chicken sandwich in one city
is a chicken sandwich in all cities.” (We’ll explain what “ BDOS” means in
the next section.)
THE PARTS OF CP/M
The C P /M operating system is divided into several parts, each of which

occupies a different area of memory. In this section, we’ll briefly review these
different parts, what they do, and where they’re located in memory. The dia
gram in Fig. 1-2 shows the various parts of the software of a C P /M system,
and where they fit in the computer’s memory.
First, let’s talk about the TPA, or transient program area. This is the part
of memory where the user’s program goes. This program could be a language
interpreter, like BASIC, or it could be an assembly language program written
by a user, or it could be one of the utility programs that are part of the C P /M
system, like PIP or STAT.
On most C P /M machines, the TPA starts at location 100H, meaning 100
in hexadecimal notation, which is 256 in decimal. (If you don’t know any-
MEMORY ORGANIZATION— 64K SYSTEM
(Addresses may be different
in different systems)
Top of memory / /
FFFF hex
BIOS
/ F200 hex FDOS
BDOS
/ E400 hex
CCP
/ DC00 hex
llllllllllllll
TPA User’s
program
/ 0100 hex
Zero page
/
0000 hex
Fig. 1-2. The parts of CP/M.
21
So l o f C P /M 5
thing about the hexadecimal numbering system, now is the time to become
familiar with it by reading Appendix A.) The size of the TPA is dependent on
how much memory your machine has. In a 64K system (the maximum for
most systems running C P/M ), the TPA will be about 56,000 (decimal) bytes
long. (It will probably be a day or two until you are writing programs that
large!)
The next part of the C P /M system is called the CCP, for Console Com
mand Processor. This does just what the name says. It deals with commands
typed in by the user from the console keyboard. Thus, every time you see the
“A > ” prompt, it is the CCP that printed it and the CCP is waiting for you to
type something in on the keyboard. When you do type something in, the CCP
will either deal with your command itself, if it is a “resident com mand” like
D IR or TYPE, or it will call another program if it is a “transient command”
like STAT or PIP. The CCP might start at around DC00 hex, in a 64K sys
tem, and will occupy about 2000 (decimal) bytes.
Although the CCP must listen to your commands that are typed at the
keyboard, read and write files to the disk system, and send messages to the
screen, it doesn’t carry out these actual in p u t/o u tp u t operations itself. For
that, it must call on the next part of the C P /M operating system, the BDOS.
The BDOS, for “ Basic Disk Operating System,” is located ju st above the
CCP in memory. BDOS handles all requests for input and output made by
your program. This includes the reading and writing of information from and
to disks, the maintaining of a directory of disk files, and the allocation of the
space that these files occupy on the disk.
BDOS also acts as a sort of intermediary for system calls that you make to
nondisk devices such as the keyboard and the video console. Sometimes
BDOS does not do very much with these calls itself, but merely passes them
along to the BIOS portion of C P /M (which we’ll describe next). Other times,
it needs to do considerable work to prepare data for the BIOS. For instance,
if you tell BDOS to print a string of characters on the video screen (the “Print
String” system call), BDOS will break the string up into individual characters
before sending it on to the BIOS, since the BIOS driver routine only deals
with one character at a time.
Like the CCP, BDOS is entirely independent of the particular computer or
disk-system it is being run on, so it does not have to be changed when it is
moved to a different system.
Finally, we come to the part of C P /M which actually communicates with
the outside world: the BIOS (for Basic Inp u t/O u tp u t System). The BIOS, as
we’ve mentioned before, contains the subroutines that actually communicate
with I/O devices like the disk drives and the console and the printer. It is
22
The Big Picture
these subroutines which must be modified when the hardware is changed in a

particular system. BIOS reaches all the way to the top of memory: F F F F
(hex), or 65535 (decimal), in a 64K system.
Since the BIOS is the only part of the C P /M system that communicates
with the physical devices in the outside world, it’s the only part that has to be
changed if the devices are changed. The systems calls, by which a program
communicates with BDOS, are always the same, no m atter how BIOS must
be rewritten to accommodate some strange new printer or disk drive.
BDOS and BIOS together are sometimes called “FDOS.” This stands for
“ Full Disk Operating System.” When you do a “cold boot” —by hitting the
reset switch on your computer, for example—both the CCP and FDOS are
loaded into the computer’s memory from the disk. When you do a “warm
boot” —by hitting the control-c key—only the CCP is loaded in.
These various parts of C P /M can also be thought of as being arranged in
layers, like an onion (Fig. 1-3). On the outside is the user, who communicates
with the CCP. Or, there is the user’s program. Either the CCP or the user’s
program communicates with the BDOS. BDOS, in turn, communicates with
BIOS. And the BIOS, finally, communicates with the actual I/O devices, like
the disk drives and the console.
There is another section of memory which, although small, is very impor
tant in the operation of the C P/M . This is the so-called “page zero”, or those
addresses from 0 to FF (hex) that are located just below the start of the TPA.
The C P /M uses this area mainly for passing information of various kinds
back and forth between the C P /M system and the user’s program. For
instance, locations 6 and 7 contain the lowest address used by the CCP. This
lets a program figure out ju st how much room it has for itself in memory.
■Direct connection
to I/O devices.
Fig. 1-3. CP/M is like an onion.
23
Soul of C P /M ®
(For example, BASIC can look at these locations and determine how large a
user program it can accept). We’ll cover other uses of page zero as we explore
the workings of the disk system.
8080 ARCHITECTURE
In this section, we’re going to describe a few fundamentals about how com
puters work on the assembly language level. (If you’re already familiar with
assembly language, you can skip to the next section.)
For a programmer, a computer can be thought of as consisting of two
parts: the memory and the CPU. The CPU, or Central Processing Unit, con
tains a number of registers. We’ll talk about memory first and, then, describe
what registers are and what they do.
Memory
As you already know, a com puter’s memory consists of a large number of

things called “bytes” (65,536 of them in a 64K system). On the kind of com
puters that we will be talking about (those that run standard C P/M ), each of
these bytes consists of 8 bits, where each bit is represented by either a binary
digit 1 or 0. All computer programs, and much of the data they operate on,
are stored in memory; that is, they occupy a number of these memory loca
tions. You can think of these memory locations as little boxes, each with an
“address” ( a number between 0 and F F F F hex) to identify it, that are capa
ble of holding one 8-bit byte.
Fig. 1-4 shows how a section of memory might look if the word “CAT”
was stored in it in ASCII characters. This section of memory may look
“upside down” to you, with the low numbers above the high numbers. U nfor
tunately, there are two more or less standard ways of showing memory. Big
blocks of memory are shown with the high numbers on top, as in the diagram
of BIOS, TPA, etc., that is given in Fig. 1-2. But when small sections of mem
ory are shown, the small numbers are at the top because that’s the way they
appear on program listings (the same as do the line numbers in a BASIC
program).
W hat do the numbers 43, 41, and 54, stored in the memory locations,
mean? If you look at the table of ASCII values given in the Appendix D,
you’ll see that 43 hex is the ASCII value for “C,” 41 is the value for “A,” and
24
The Big Picture
(M emory co n tin u e s on down to 0000 hex)
I
/ / 2000 hex
/ 2001 hex
43
/
Memory 2002 hex
locatio ns 41
/ 2003 hex
54
/ 2004 hex
/
Addresses of
— memory
locations.
(M emory co n tin u e s up to FFFF hex.)
F ig.1-4. Memory.
54 is the value for “T.” The ASCII code is simply the way that the computer
stores characters. (It stands for “American Standard Code for Information
Interchange.”) Since the computer must always think in terms of numbers, it
translates all characters (letters, punctuation, etc.) into two-digit hex num
bers.
Numbers that aren’t ASCII characters can also be stored in memory. One
byte (one memory location) can hold a number between 0 and 255 decimal (0
to FF hexadecimal). Two bytes (two memory locations) used together can
hold numbers from 0 to 65535 decimal (0 to F F F F hex.)
One of the im portant differences between assembly language (we’ll abbre
viate it A-L from now on) and a high-level language, such as BASIC, is that
when you program in the higher-level language, you don’t need to know
exactly where in memory a particular program or variable is stored. The lan
guage processing program (such as the BASIC interpreter) takes care of
deciding where to put the program and its variables. In A-L, on the other
hand, the programmer must decide himself where to put everything—this
instruction will go in this memory location, that variable will go in that mem
ory location, and so on. For this reason, all the addresses (which is the same
as saying memory locations) are numbered, starting at 0 and going up to
F F F F (hex).
25
Soul of C P /M ®
The program, which consists of a list of instructions, each of which is rep

resented by one or more two-digit hexadecimal numbers, goes in specific
memory locations just as numbers and ASCII characters do. The instructions
in the 8080 instruction set will occupy either one, two, or three memory loca
tions, depending on what instruction it is.
The drawing in Fig. 1-5 shows three instructions stored in memory.
They’re part of a program, but you can’t see the rest of the program because
we’re only looking at a very small section of memory. The instructions are
MOV E,A, CALL 5, and POP D. D on’t worry if they don’t mean anything to
you at this point; we’ll be describing some actual instructions in detail in the
next chapter. There are two things to notice here. First, each instruction is
represented by one or more hex numbers (MOV E,A is represented by the
number 5F, CALL 5 by the three numbers CD, 05, 00, and POP D by the
number D l). Second, these numbers occupy specific places in memory; MOV
E,A occupies location 018E, and so on. MOV E,A and POP D each occupy
one memory location, while CALL 5 occupies three locations.
Registers
There is another place a program can store data; it is in special hardware

devices called “registers.” A register is something like a memory location, but
it is part of the microprocessor “chip,” and can therefore be operated on
(Memory continues down to 0000 hex.)
D1
/
/
0192 hex
0191 hex
r
POP D
instructions
CD
/
0190 hex CALL 5
Memory
05
locations /
018F hex
00
/ MOV E.A
018E hex
5F
/
Addresses1
of memory
locations.
(Memory continues up to FFFF hex.)
Fig. 1-5. Three instructions stored in memory.
26
The Big Picture
faster than a memory location, which is on a separate memory chip located

some distance from the microprocessor. A register also usually has some spe
cial attributes that memory locations don’t have.
A microprocessor “chip,” such as an 8080, consists mainly of registers and
the instruction-decoding circuits that let the chip know what we want to do
when we execute a specific instruction.
You can think of registers as the work areas where data are processed.
D ata are stored in the memory, and the instructions for handling the d ata—
the program —are also stored in the memory. We execute the instructions in
the program one after the other, like items on a list. Suppose we want, for
example, to add together two numbers that are stored in memory. Our pro
gram will contain an instruction that will take the first number out of mem
ory and will put it in one of the registers. The next instruction will take the
second number from memory and add it to the contents of the register. The
third instruction in our program might cause the result of the addition to be
put back into yet another memory location or, perhaps, it might send it to an
output device like the video screen. The point is that the addition operation
was carried out in a register, not in memory.
In the 8080 chip, there are 7 main registers for handling data. (There are a
few others, but we’ll ignore them for the moment.) These 7 registers are called
the A, B, C, D, E, H, and L registers.
Of these, the most im portant is the A-register. The “A” stands for “accu
mulator.” In the early days of computing, many computers had only one
register. This was used to hold the results of all arithmetic calculations, in the
same way that your pocket calculator keeps its arithmetic results in a single
register (whose contents you can see in the little window). Since this register
“accumulates” the results of previous arithmetic calculations, it was called
the accumulator. The A-register in the 8080 still handles all of the 8-bit arith
metic (that is, numbers up to F F hex or 255 decimal), such as addition and
subtraction, as well as logical ANDs, ORs, shifts, and the like.
Bytes of data can be moved from the A-register to memory and back, and
also between the A-register and the other 8-bit registers.
The other registers, B, C, D, E, H, and L, can function as temporary stor
age places for 8-bit (one byte) quantities. They can also be used in a different
way—as register pairs to hold 16-bit (two-byte) data quantities. When used in
this way, the B and C registers are placed together to form the BC register,
the D and E registers are placed together to form the DE register, and the H
and L registers are placed together to form the HL register. The 16-bit data,
which are numbers from 0 up to F F F F hex (65535 decimal), can be trans
ferred between these register pairs, or between specific register pairs and
27
Soul of C P /M ®
pairs of memory locations. The diagram given in Fig. 1-6 shows the principle
8080 registers.
D on’t worry if all this talk about registers seems a bit obscure at this point.
In the next chapter, we’ll introduce you to some specific operations with reg
isters and their uses will become clearer. For a more complete picture of the
registers, look in Appendix C for a “Summary of 8080 Instructions.”
To summarize, the principal parts of the 8080 microprocessor are seven
registers and a large number (up to 65536) of memory locations. This is
shown in Fig. 1-7.
f= ^ = Q
Fig. 1-6. The p rin cip a l 8080 registers.
8 bits wide ► 8 bits wide

--------------- 16 bits wide -----------------
Continues
down to 0000.
Registers
A
/
B c Memory
D E
H L
Continues up to FFFF.
Fig. 1-7. The prin cip a l parts o f the 8080 m icroprocessor.
28
The Big Picture
DDT—THE PROGRAMMER’S X RAY AND PROBE

All right, you say. I’ve got this computer sitting on my desk, and you tell
me there are things called registers inside it. And, something called memory.
Well, I can’t see them and I can’t touch them. How am I supposed to do
anything with them? How can I find out how they work?
Good questions. What we need are a set of tools. We need the program
mer’s equivalent of an x-ray machine and of some long probes, so we can
examine the registers and the memory and also manipulate them; so we can
change their contents. Fortunately, the kind folks at Digital Research (the
makers of C P/M ) have provided just such a set of tools; it’s a program called
DDT. (They also make a similar program called SID. You can use that too,
if you like, but our discussion is geared to DDT.)
DDT (for “ Dynamic Debugging Program”) is one of the “ transient com
mands” (programs not built into C P /M but provided with it as a separate
program). This program was devised to make it easier to work with the com
puter on a very fundamental level. DDT is able to examine and modify the
contents of both particular memory locations and of the various registers in
the 8080.
For example, if you are using D D T and you type “dlOO”, D D T will print
out the contents of all the memory locations from 100 (hex) to IF F (hex) (or
256 locations). You can change the contents of a memory location by typing,
say, “ s i00” to alter the contents of location 100. And, you can examine and
modify the contents of registers; typing “xa” will permit you to examine and
modify the contents of the A-register.
DDT has another im portant ability—one which we will make use of exten
sively in this book. That is, you can type in a program in symbolic assembly
language and D D T will assemble the symbolic instructions into a program
which can be executed directly.
Here’s why we need this ability to handle symbolic programs. The instruc
tions for the 8080, like those for all computers, take the form of lots of binary
numbers when they are in the machine. (Of course, these aren’t abstract
binary numbers, but groups of transistors being set to either the “on” or
“off” states. For our purposes, it amounts to the same thing.) Again, read
Appendix A on hexadecimal notation if you are not familiar with binary
numbers or their relationship to hexadecimal numbers.
As an example, the instruction to subtract the contents of the C-register
from the contents of the A-register is the binary number 10010001. Now
binary numbers are hard to read and to remember, so we usually write the
instruction in its hexadecimal form of 91. (See the table of binary to hex-
29
Soul of C P /M ®
adecimal conversions in Appendix A.) However, even this is hard to remem

ber. W hat the “ symbolic assembler” function of D D T lets us do is write this
number as “ sub c” . It’s much easier to see that this means “subtract the con
tents of the C-register from the contents of the A-register” than it does when
you look at the number “91.”
It wouldn’t hurt at this point to look over the D D T commands in Appen
dix F, or even the section on D D T in the C P /M documentation provided
with your computer, ju st to get a rough idea of everything that D D T is capa
ble of. D on’t worry if you don’t understand every detail; we’ll explain how it
all works as we go along.
Instruction stored
as a binary number Hexadecimal Symbolic
in the computer’s memory. representation representation
of the instruction. of the instruction.
10010001 91 SUB C
Fig. 1-8. N um ber conversion.
BACK DOWN TO EARTH

Now that you’ve gotten a fast aerial overview of the various major aspects
of the terrain, it’s time to land and take a close-up look at a specific area.
We’ll do this in the next chapter, on Console System Calls. If you feel you’re
not quite sure of what’s happening and where all these concepts are leading,
read on. The specific examples that we’ll cover next should help to pull every
thing together.
30
CHAPTER 2
One Toe in the W a te r

Console System Calls
In this chapter, you’re going to begin your journey into the mysterious and
exciting world of C P /M system calls. System calls, as we mentioned in the
last chapter, are links between your program and BDOS, C P /M ’s Basic Disk
Operating System. BDOS examines your system call and then uses one of the
Soul of C P /M ®
routines in BIOS (the Basic Input/O utput section of C P/M ) to communicate

with a specific device, such as the video screen, keyboard, or disk drive.
Understanding how to use these calls is the key to programming in the C P /M
environment, since by using the calls, you can create programs that are effi
cient to write and are easily transportable from one computer to another.
There is a complete list of system calls in Appendix E. You might want to
glance over these calls at this point, just to get an idea of the kinds of things
they do.
Our first programs will be very short, and will introduce the simplest of
system calls at the same time that you’re learning just enough assembly lan
guage to use the call. For simplicity and ease of operation, we’ll use D D T to
create the examples. By the end of the chapter, you’ll be well on your way to
understanding both system calls and 8080 assembly language.
We’ll introduce each system call with a box containing the im portant facts
about how to use it. D on’t worry if you don’t understand what we mean by
“ REG C = 2”, and so on, in the following explanation box; we’ll get to that
soon.
CONSOLE OUTPUT SYSTEM CALL
CONSOLE OUTPUT FUNCTION 2 (dec) = 2 (hex)
Enter with: REG C = 2

REG E = ASCII character to be displayed
The first system call that we’ll learn is a simple one called “Console O ut
put.” This call is nothing more than a way to send a single character from
your program to the C P /M display screen. It’s like a one-character-at-a-time
version of the PR IN T statement in BASIC. We’ll describe how the call is
used, then write a program that makes use of the call, and, finally, show you
how to type the program into the computer’s memory and execute it using
DDT.
In order to execute this system call, your assembly language program must
do three things:
1. Put the number 2 in the C-register.

2. Put the ASCII character you want to print in the E-register.
3. Execute a CALL instruction to memory location 5.
32
One Toe in the W ater
T hat’s all there is to it! If you do these three things, a character will be
printed on the screen. You don’t need to understand anything about the
actual instructions that C P /M uses to send the character to a particular
kind of terminal or crt screen, since the routine in BIOS takes care of that
for you.
Briefly, here’s what each step does. First, the num ber “ 2” is the number
of the system call in hex. C P /M uses the C-register as the “ mail-box” for a
program to tell C P /M what systems call it wants to use. Second, the ASCII
code for any character can be looked up in Appendix D found at the back
of this book. In this system call, C P /M gets the ASCII value of the charac
ter that is to be displayed from the E-register. And, finally, all system calls,
no m atter what they are, use a CALL to location 5 in order to enter BDOS,
where the BIOS and BDOS routines will do whatever input or output func
tion has been requested; in this case, printing a character on the screen.
Your First Program
All right, you ask, how do I actually go about writing down these steps in a
form that the computer can understand? Let’s look at a program that does
just what we want:
mvi c,2
mvi e,48
call 5
Well, it’s short enough, but what does it all mean? Easy. The first instruc
tion puts the number 2 in the C-register. The second instruction puts the
number 48 in the E-register. And the third instruction causes the program to
“call” or jum p to the entry point of BDOS, which is at memory location
0005.
All the numbers used in programs in this chapter are in hexadecimal, so
the 2, the 48, and the 5 are all hexadecimal numbers. (The 2 and 5 are the
same as their decimal equivalents, but the 48 is equal to 72 decimal.)
Statement “Fields”
Each of the three lines in the preceding program is called a “statement.” As

you can see, each of these statements consists of two parts separated by a
space. These parts are called “fields.”
33
Soul of C P /M ®
The first field shown is the “operation” field. The instruction, or what
you’re going to do goes in this field; “mvi” and “call” are instructions. (To
confuse the issue, the word “instruction” is also used to refer to the entire
statement.)
Following the space (which could be several spaces, or a tab) comes the
“operand” field. This field contains the thing you're going to do it to. Thus, in
the first line, “mvi” is the instruction or operand. It operates on the operand
field, which contains “c,2”, and causes the number 2 to be placed in the C-
register. In the third line, CALL is the instruction, and it operates on the
operand 5, causing the program to jum p to location 5. Later, we’ll learn
about other fields in the instruction line, but for the time being these two will
keep us busy.
Something to notice here is that the order in which things are written in the
operand field may seem backwards. In the example, “MVI C,2”, it’s the 2
that is placed into the C-register, not the other way around. It’s like the state
ment “ LET C = 2” in BASIC, where the variable C is given the value 2.
The MVI Instruction
“MVI” is an instruction that means “move immediate.” The word “imme

diate” means that the data to be moved immediately follows the instruction in
memory. (Later, we’ll look at instructions that can take a constant from other
places in memory and put it in a register.)
As we mentioned before, the memory locations in these drawings start at
the top and go downward. This may seem strange at first, but you’ll get used
to it.
The number to be moved using MVI can be any 1-byte num ber—that is,
any number from 0 to F F hex (0 to 255 decimal). Also, the register that the
number is moved to can be any of the seven main registers: A, B, C, D, E, H,
or L. In the diagram of Fig. 2-1, the number is moved to the C-register. The
second time that the MVI instruction is used in our example program, the
number 48 is moved to the E-register.
The use of a constant as part o f an instruction can be confusing. Some com
puters require that constants be stored in a different part of memory from the
program. However, in the “immediate” instructions used in the 8080 micro
processor, constants actually become a closely connected part of some
instructions, such as MVI. Notice how the instruction occupies two bytes of
memory. The first byte, at location 100, is the code that tells what the instruc
tion is going to be: 0E. This means the instruction is going to transfer a
constant into the C-register; in other words, it’s the code for the “MVI C”
34
One Toe in the Water
Before MVI C,2 is executed:
Section of memory where

the program is located
/ 1 / 00FF
/ 0100 This is where

C-register
0E
/ 0101
the MVI C,2
instruction
is in memory.
z : 02
/ 0102
/
Memory
address.
After MVI C,2 is executed:
/ / j
00FF
/
0100
0E MOV C,2
C-register /
0101
02
( °2 0 " /
0102
The number
2 is moved /
from memory
to the C-register.
Fig. 2-1. The MVI in stru ctio n .
part of the instruction. This number will vary, depending on which of the
seven registers the constant is to be placed in. The constant itself is given in
the second byte of the instruction, at location 101; it’s the hexadecimal
number 02.
We’re not going to be too concerned with the exact hexadecimal codes for
the instructions we learn, but it’s im portant to understand the relationship of
the codes to the symbolic instructions that we’ll be typing in using DDT.
We’ll type in a symbolic instruction, like “mvi c,2”, and D D T will take care
of the dirty work of figuring out the corresponding hexadecimal code and
35
Soul of CP/M®
placing it in memory. We’ll talk more about this process later, when we show
you how to type in the program.
Examples:
mvi c,2
mvi h,ff
mvi e,20
So the instruction “mvi c,2” means “take the number 2 and put it in the C
register.” This 2 in the C-register tells BDOS that we want to execute Func
tion 2, which is Console Out.
The number 48 (hex) is the ASCII value of the letter “ H ” (you can check
this in the table of ASCII values in Appendix D). So the instruction “mvi
e,48” means “take the ASCII value of ‘IT and put it in the E register.” Note
that not all hex values represent printable characters. If you put a 0 in the E
register, for example, nothing would happen when you tried to print it,
because 0 is the ASCII code for a “null,” which is a nonprintable character.
Also, remember that this number must be the hex representation of the char
acter and not the decimal representation.
The CALL Instruction
CALL means “execute” or “call” a subroutine. It’s equivalent to a GOSUB

in BASIC. When this instruction is executed, the program jum ps to the mem
ory address in the operand field of the instruction. Also, the instruction
stores the “return address” so that it can get back to the proper place in the
calling program when the subroutine is completed. The place that the pro
gram wants to return to in the p ro g ram -th e return address—is simply the
location following the CALL instruction. The place where the CALL instruc
tion saves the return address is called the “ stack.” We’ll learn more about the
stack later. For now, think of it as a handy place for the program to save an
address until it’s needed again.
Fig. 2-2 is a diagram of how CALL operates. In this case, when the call
instruction is executed, program control will go to location O2C0, and loca
tion 107 will be stored on the stack. W hen the subroutine, which starts at
location 02C0, is completed, program control will resume at location 107.
(This is done using the RET instruction, which we’ll cover later in this
chapter.)
36
/ /
0103
/
0104 00
/
The return • CALL 02C0
address, 107, 0105 CO
will be placed /
on the stack instruction
0106 02 is executed,
A the program
/ / \ will go to
location 02C0.
/
The “Stack”
02BF
02C0
02C1
Fig. 2-2. O peration of the C ALL in stru ctio n .
Examples:
call 5
call 100
call bfOO
So, in our little program, the “call 5” means “execute the subroutine at
memory location 5 hex” and 5 hex turns out to be the entry point for all
system calls. W hat really happens is that locations 5, 6, and 7 contain a jum p
instruction to the actual BDOS entry point in high memory. We’ll talk more
about that later in the book. But for now, all you need to know is that in
order to do a system call, you execute a CALL 5 instruction.
So there it is, your first C P /M system call, a simple 3-instruction program,
written in assembly language. But, how do we get it to do what it’s supposed
to do—put a character on the screen? In other words, how do we put the
program into the com puter’s memory and execute it?
We could actually write the program in “official” assembly language, using
the ASM assembler program that comes with C P/M , and, then, execute it as
a COM file (the same way systems programs are executed). But if we did
that, we would have to add other instructions to the program to make it work
37
Soul of CP/M®
and we also would have to use several different programs to convert it to an

executable routine. Why go to all that trouble? Instead, we simply take
advantage of DDT, which has a built-in mini-assembler, and which can exe
cute its own programs with no trouble at all. (For longer programs involving
lots of jum ps and subroutines, this D D T approach will begin to hold us back
and we’ll graduate to using ASM, but for the moment, D D T is just what the
doctor ordered.)
Just for fun, let’s make the program slightly more complicated before we
type it in with DDT. Instead of a single letter, we’ll send the word “H I” to
the console screen. Here’s the program to do that:
mvi c ,2 Put 2 in the C-register for Console Out.

mvi e ,4 8 48 hex is ASCII “H”.
c a ll 5 Jump-to-subroutine (BDOS) at location 5.
mvi c ,2 Put 2 in C-register for Console Out.
mvi e ,4 9 49 hex is ASCII “I”.
c a ll 5 Jump-to-subroutine (BDOS) at location 5.
rs t 7 Return to DDT.
This program is very much like the last one, except that we print two letters
instead of one. In other words, we use the Console Out system call twice,
once with “ H ” and once with “I.”
Something to note here is that we have to restore the “2” in the C-register
(as well as putting the new character in the E-register) before we can “call 5”
the second time. This is because the system call itself trashes the contents of
the C-register. (“Trash” is a programmer’s word meaning to change some
thing, usually with disastrous results.)
Also, we’ve added comments to each line, to make the program clearer
(although you can’t actually type in such comments in DDT). And, there is a
final addition to the program —the “rst 7” instruction at the end.
The RST Instruction
This instruction was actually designed to be used with the interrupt system
of the 8080 chip. Since this book does not cover the interrupt system, we
won’t say anything further about RST, except to note that, since D D T uses
the interrupt system, this instruction must be used to terminate programs
when they are being executed under DDT. When used in DDT, RST returns
control from the program to the D D T monitor. It’s a little like the STOP or
END instruction in BASIC. W ithout the rst 7, the computer would just keep
38
on executing all the instructions in memory that happened to follow the end
of the program.
Example:
rst 7
Typing in the Program Using D D T
The first step in writing our program is to load and get into DDT. (Notice
that our typed input will be in lowercase letters, while C P /M ’s output is in
uppercase letters. D on’t worry about this. C P /M is good at translating the
lowercase input to uppercase.) After you load D D T by typing “d d t” follow
ing the “A > ” prompt, D D T will print a “sign-on” message and then print a
dash (“-”) and will wait for your command. (The dash is the D D T
prom pt character.)
A>ddt Call up DDT.

DDT VERS 2 .2 DD T sign-on message.
- DD T’s prompt character.
You can now type “alOO”, which means “ start assemblying a program at
location 100 (hex).” D D T will respond to this command by printing 100,
which is the location where the next instruction will go in memory. Each time
that we type in an instruction and hit the carriage return, D D T will reply
with the next available memory location. Here’s how our program will look
when typed in using DDT:
A>ddt
DDT VERS 2 .2
-a 1 0 0 --------------- Assemble code at 100 hex. (Type each instruction, followed by a
0100 mvi c ,2 return.)
0102 mvi e ,4 8
0104 c a l l 5
0107 mvi c ,2
0109 mvi e ,4 9
01 OB c a l l 5
010E r s t 7
01 OF ----------------- Press return to end assembly.
'[ t______ You type the program in this column.
------------------------------------------- DD T types these addresses.
39
Soul of CP/M®
We began at 100 hex because that’s the standard beginning address for all
C P /M programs and that is where the SAVE utility looks for code to save.
(We’ll talk about that later.) Notice how different instructions take up differ
ent amounts of memory: mvi takes two bytes, call takes 3, and rst only needs
1. When we’ve typed the last instruction, we type a carriage return instead of
another instruction to let D D T know that we’re done.
Let’s make sure the code is set up right by using the “1” (lowercase “L”) list
command. The “1” command prints out or “lists” a program in the same
format that we typed it in.
(This is a lowercase “L”.)
(This is the number 100.)
-1100 List the code to see that it’s all right.

0100 MVI C,02
0102 MVI E,48
0104 CALL 0005
0107 MVI C,02
0109 MVI E,49
010B CALL 0005
010E RST 07
Looks great. If you made any errors in entering your code, use the “A”
(assemble) command again to reenter the correct code. For example, if you
mistakenly typed CALL 6 at line 104, you would change it by typing: “a 104”
(return). The address 0104 would appear. Then, you would simply type “call
5” , hit return twice, and you’re finished:
-1100
0100 MVI C,02
0102 MVI E,48
0104 CALL 0006 W oops-typed the wrong thing.
0107 MVI C,02
0109 MVI E,49
010B CALL 0005
010E RST 07
-a104 Start at the offending instruction. Type the right thing,

0104 ca L I 5 another carriage return, and it’s fixed!
0107
40
Now that our little program is entered into the com puter’s memory, it’s
time to actually execute it, using DDT. We use the “go do it” command “g”,
followed by the address where our program starts (100 hex).
-g100 Run the program at address 100 hex.
H I *0 1 0E Program prints HI and the last address preceded by a
Wow! It actually printed what it was supposed to! The asterisk tells us that
the program is finished, and the 010E tells us that the last instruction to be
executed was a “rst 7” at location 010E. The HI, of course, stands for “High
ly Ingenious.”
To reward yourself for successfully writing and executing your first C P /M
program, why not take the rest of the day off? Or, at least treat yourself to a
beer!
Saving the Program
Now that you’ve written the program, you will want to be able to save it
onto disk so that you can use it later. Here’s how to do it:
1. Type “gO” to take you out of D D T and back into C P/M .

2. Following the “A > ” prompt, type “save 1 test.ddt”.
(This is the number “zero,” not the letter “Oh”.)
-gO Leave DDT.

A> Get the A > prompt back.
A>save 1 t e s t . d d t Save the program.
Since 0 is where the computer automatically goes to do a warm boot, typ

ing “gO” from D D T takes you back to C P/M . (It actually loads the CCP
back into memory and executes it. You could also have typed a control-c,
which has the same effect.) “ SAVE” is a “resident command” that autom ati
cally writes to the disk the program that is occupying the TPA, starting at 100
hex. It saves the program using the name that you type in; in this case,
“test.ddt”. The “ 1” tells SAVE how many 256-byte “pages” of memory we
want to save; in this case, just one page, since our program is less than 256
bytes long.
41
Soul of CP/M®
If you want to reload the program, you can do it at the same time that
you’re loading D D T :
A>ddt t e s t . d d t
Then, to execute the program, type:
-g100
Don’t try to execute the program directly from C P /M by typing

A > test.d d t. For one thing, only files with an extension of “COM ” can be
executed this way and, for another, the fact that the program ends with “rst
7” (instead of “ret”) will cause problems if you do change the extension to
COM and try to execute it. This is because RST takes you to an address that
D D T is able to deal with but which C P /M is not expecting at all. Later, we’ll
learn how to execute programs directly from C P/M .
Using the “Control-S” Feature
There is more you should know about the way C P /M handles the Console
Output function. As we mentioned earlier, BDOS does not simply pass the
request for output along to the in p ut/output routine in BIOS—it does some
interpretation of its own. This gives it the opportunity to add some useful
features to the input/output routines that can be used by any program run
ning in the C P /M environment.
For example, when you use the Console O utput system call, BDOS checks
to see if you’ve typed a “control-s” , which has the effect of starting and stop
ping the scrolling of material displayed on the screen. (Control-s is the char
acter generated when you hold down the “control” or “alt” key, and type “ s” .
You’ve probably used it in such C P /M utilities as “TYPE” .) So if you press
control-s as the program is running, C P /M will freeze your output on the
screen—that is, stop runn in g -u n til you press another control-s.
Want to see control-s work on our sample program? Unfortunately, the
program prints “H I” and returns to D DT so fast that you don’t have time to
type anything. The solution to this is to replace the “return to D D T ” instruc
tion—“rst 7” —with a jum p to the beginning of the program, so that we have
an endless loop printing the word HI. Then, you can try the control-s and
verify that it freezes the program, and restarts it as well.
42
The JM P Instruction
A JM P instruction is just like a GOTO in BASIC. When the program exe

cutes it, control goes to the address specified in the operand field of the
instruction. Of course, in assembly language, the address is an actual memory
location, not a line number as in BASIC. JM P differs from a CALL instruc
tion in that no return address is stored; the program doesn’t remember where
you were before you executed the jump.
/ y
0110 C3
/
JM P 0100 —
0111 D2 causes the
/ program to
jump to 1D2
0112 01
/
llllllllllllllllllll
Fig. 2-3. The JMP in stru ctio n . llllllllllllllllllll
/ /
01D1
/
01D2
/
01 D3
/
01D4
/
Examples:
jm p 100
jm p bfOO
Which Half Comes First?
You may have noticed something a little strange if you’ve been examining
the diagrams of the programs carefully. Whenever there’s an address in a
program listing or diagram, it seems to be backwards. An address consists of
two bytes. For instance, 01D2 is stored in the com puter’s memory as the two
bytes 01 and D2. However, the makers of the 8080 (and the 8085, Z-80, and
so forth), for reasons best known to themselves, chose to put the least-signifi
cant byte first, followed by the most-significant byte. That is, if you have the
43
Soul of CP/M®
instruction “JM P 01D2” in a program, the JM P will come first (represented

by the number C3), then the D2, and then the 01. This makes listings and
diagrams confusing to read, until you get used to the procedure. Of course,
you can simply ignore the hexadecimal values that the “a” function of DDT
puts in memory and ju st look at the symbolic instructions.
To check the control-s feature, type the following:
A>ddt t e s t . d d t Bring up DD T and our previous program.

DDT VER 2 .2
NEXT PC
0200 0100
-L100 List the code to see that it’s all right.
0100 MVI C,02
0102 MVI E,48
0104 CALL 0005
0107 MVI C,02
0109 MVI E,49
010B CALL 0005
010E RST 7
Notice the NEXT and PC headings that D D T prints when you load a pro
gram. NEXT means the next memory location after the one loaded in. Since
we SAVEd one 256-byte page when we saved our program, 256 decimal bytes
(which is 100 hex bytes) are loaded in along with DDT. This fills memory
locations from 100 to IFF, so the next available one is 200 hex. PC means
Program Counter. This is D D T ’s way of keeping track of where it is in a
program, and it is always at 100 when a program is first loaded.
We want to change the last instruction in the program, RST 7, to a JM P
100. So we type:
~a 1Oe Change the rst 7 to a JMP 100.

010E JMP 100
0 1 1 0 -«------------------------------------ Carriage return.
-gO Now return to the CCP.
A>save 1 t e s t l . d d t Save the program as TEST1.
44
A>ddt t e s t l . d d t Go back to DDT.
- g 1 00 Execute the program.
e tc .
A huge amount of H is are sent to the screen, quickly filling it up. The pro
gram will continue to send H is until the control-s key is pressed; at which
point, the display will freeze. Pressing another control-s will allow it to restart.
But how do you stop the entire program, so you can get back to D D T or
C P/M ? Unfortunately, you’re in big trouble in this regard. The only way to
regain control of the computer is to hit the reset button. That will cause a
“cold boot,” and you’ll be back in C P/M . The moral of this is to avoid writ
ing assembly language programs with loops that never terminate. In BASIC
you can always hit the Break key but, in assembly language, you need to
write an escape route into your program. In the next section, we’ll show you
how to modify your program so that it can be interrupted from the keyboard.
So, you’re now an expert on the C P /M function call “Console O utput.”
The nice thing about this is, as we mentioned earlier, that what you’ve
learned is applicable to any machine running C P/M , whether it has an 8080
chip, an 8085, a Z-80, or whatever. It’s also applicable to any sort of display
terminal, whether it’s from TeleVideo, IBM, Amdek, or any of the dozens of
other manufacturers.
There are many other nondisk C P /M system calls, some of which are more
powerful than this one, and some of which are pretty mundane. U nderstand
ing them all will help you discover how C P /M works and how to write pro
grams that make use of C P /M ’s full capabilities.
The next C P /M function call that we will study is a simple but im portant
one that is used by almost all of the C P /M utilities.
GET CONSOLE STATUS
GET CONSOLE STATUS FUNCTION 11 (dec), 0B (hex)
Enter with: REG C = 0B

On return: REG A = 0 if no key pressed
REG A = non-0 if key is pressed
45
Soul of CP/M®
Get Console Status (sometimes called Interrogate Console Ready) is used

mainly for signaling to your program that the user has pressed a key. It
doesn’t tell what character was typed, only that some key was pressed. W hat
good is that? Well, remember the last program example of sending continu
ous H is to the screen? We had to press the reset button on the com puter to
stop the display. The program was locked into a tight loop, continuously
using the “Console O ut” routine, and there was no way we could stop it.
Let’s fix this problem. We’ll change our program so that every time we
print “ H I” on the screen, we also use “G et Console Status” to check if the
user has pressed a key. If he has, we’ll have the program end itself and return
to DDT.
First, bring in the old testl.ddt program with DDT:
A>ddt t e s t l . d d t
NEXT PC
0200 0100
- L1 0 0 List the code to see if it’s all right.
0100 MVI C,02
0102 MVI E,48
0104 CALL 0005
0107 MVI C,02
46
0109 MVI E,49

01 OB CALL 0005
01OE JMP 0100
Looks fine—an endless loop that prints HI on the screen forever, or at least
until RESET is pressed causing a cold boot of C P/M . N ot the most elegant
way to end the program.
Change your code as follows:
-a10e
01 0E mvi c , b Put 0B hex in C register.
0110 call 5 Call BDOS.
0113 ora a O R A with itself—to set zero flag.
0114 j Z 100 Go do HI again if no key pressed.
0117 rs t 7 Back to D D T if key is pressed.
0118
Now list the whole thing:
-L100
0100 MVI C,02
0102 MVI E,48
0104 CALL 0005
0107 MVI C,02
0109 MVI E,49
010B CALL 0005
010E MVI C,0B
0110 CALL 0005
0113 ORA A
0114 JZ 0100
0117 RST 7
0118
You can save this program as “ test2.ddt” and then bring it back into mem
ory with D D T in the usual way:
-go
A>save 1 t e s t 2 . d d t
A>ddt t e s t 2 . d d t
47
Sou! of CP/M®
W hat do these new instructions do? Let’s explain. W hat’s basically

changed here is that, in line 10E, we don’t simply ju m p back and repeat
the loop. Instead, we put OB hex in C-register to set up the G et Console
Status system call. Then, we do a call to BDOS with CALL 5. This will
make C P /M go and check the keyboard to see if a key has been pressed.
This system call is a little different from the last one, in that our p ro
gram is trying to fin d out something from C P /M (namely whether a key
was pressed) rather than trying to tell C P /M something. Thus, we d o n ’t
need to put anything in the E-register before we do our “ call 5.” But we
do w ant to know what C P /M has to tell us, so after the “ call 5” is exe
cuted, we want to find out if the A-register contains a 0 (which would
mean that no key was pressed) or if it contains something else (which
would mean that a key was pressed). To do this, we need to use something
called the “ zero flag.”
The Zero Flag
We’ve already mentioned that arithmetic and logical operations involving

8-bit quantities are always carried out in the A-register. Often, after perform
ing such an operation, our program needs to know what the results of the
operation were. For instance, if we do an addition, we might like to know if
the result is zero. The 8080 does this through what’s called the “zero flag,”
which is simply a switch in the CPU that is set to “ 1” whenever the results of
an arithmetic or logical operation are zero, and set to “0” when they’re not.
(This might seem backwards, setting the flag to 0 when the result is nonzero,
but remember, it’s called the “zero flag.” It gets set, meaning “ set to 1,” when
the result is 0.)
Once this “zero flag” switch is set, it can be used to affect the results of
other instructions, such as jum ps, in much the same way that a BASIC state
ment, such as “IF A = 0 THEN GOTO 1000”, is used.
When we use the “Get Console Status” system call, the A-register comes
back with an 8-bit quantity in it, and we want to find out if it’s zero or not.
The way to do this is to test the zero flag, but (remember this!) the zero fla g is
not set until we perform an arithmetic operation. So we need to do some arith
metic on the A-register which will set the zero flag if the A-register is zero. An
old programming trick here is to OR the A-register with itself.
48
The “ORA” Instruction
“O R ” means to take the bits in the A-register and OR them with the corre
sponding bits in some other register. This is illustrated in Fig. 2-4. Either the
B, C, D, E, H, or L register will work fine. As you no doubt recall from
BASIC:
0 ORed with 0 is 0
0 ORed w ith 1 is 1
1 ORed with 0 is 1
1 ORed with 1 is 1
A-register Some other register
01001100 00001111
01001100
00001111 Contents of
A-register ORed
01001111
with contents of
another register.
A-register
Result is placed back in A-register.

01001111
Fig. 2-4. The ORA in stru ctio n .
Examples:
ora b
ora h
In our particular program , in stead o f ORing the A -register w ith so m e other

register (B or C, or w hatever), w e OR it w ith itself. A n d , as y o u can see from
the ab o v e d efin itio n , if w e OR an yth in g w ith itself, all w e ’ll get b ack is itself
again! W h ile this m ay so u n d lik e an exercise in fu tility, it’s im p ortan t b eca u se
w h en w e perform an OR op era tion , the zero fla g is set. T h at’s the o n ly reason
for the O R A in struction : to set the zero flag.
Following the “ora a” instruction, we know that the zero flag is set ( = 1) if
the A-register came back from the “Get Console Status” system call set to
zero, and cleared (= 0) if the A-register came back with some nonzero quanti
ty. How does our program make use of this information? The “jum p-on-
49
Soul of CP/M®
zero” (jz) instruction takes care of it nicely by doing just what its name
implies.
The JZ Instruction
This instruction is a special case of a regular jum p (JMP) instruction. If the

zero flag is set, this instruction will act like a jum p and go to the address
given in the operand field of the instruction. However, if the zero flag is not
set, nothing at all will happen. N o jum p will occur and the program will just
go on to the instruction following the JZ ju st as if the JZ hadn’t even been
there. The 8080 instruction “JZ 100” is very similar in function to the BASIC
statement of “ IF Z = 1 THEN GOTO 100”.
This instruction, and similar ones that we’ll learn later, give our program
the opportunity to branch or head in different directions, depending on
something that’s happened in the program.
/
0100
/
0101
0102
/
Goes back to 100
iiiiiiiiiiiiiiini it zero flag set.
iiiiiiiiiiiiiiiiii Fig. 2-5. The JZ in stru ctio n .
/
0114 C3
/ JZ 1 0 0 -
0115 00
Goes on to 0117
0116 01 if zero flag
/ not set.
0117
/
Examples:
jz 100
jz bfOO
In our case, if the A-register returns with zero, it means no key was pressed,
so the zero flag will be set to 1, the jz 100 instruction will cause program con
trol to go back to 100, and the program will continue to print “H I” on the
50
screen. However, if a key is pressed, the A-register will return with nonzero,
the zero flag will be cleared (set to 0), and when we execute the jz 100 instruc
tion, we won’t jum p at all but, instead, will go to the last instruction in the
program (the “rst 7” instruction) which will return us to DDT.
So, does all this actually work?
-g 1 00 Execute th e p ro gram .
H I H I H I H I H I H IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH IH I
H IH IH IH IH IH I H....etc.
Watch the “ H i’s” fill up the screen.

Try pressing control-s. The display should freeze. Press control-s again to
unfreeze the display.
Now for the big test. Try pressing any key—for instance, the “z” . The pro
gram should come back to DDT, like this:
___ H IH IH IH IH IH IH IH IH * (0 1 1 7 )
-z
------------------------- *-----------------------N
We pressed a key here and the program stopped.
Here we are, back in DDT! Lo and behold, our modified program works
too! It’s not perfect, because the letter we pressed gets passed along to DDT.
T hat’s the “z” you see printed out following the D D T prompt. If we type a
carriage return, D D T will think the “z” is input and will output a question
mark when it can’t understand it. Aside from this minor glitch, the program
is certainly very successful in getting us out of the endless loop.
Congratulations are again in order. You have just created your third
C P /M program and learned a new system call! At this rate, you’ll be writing
programs for mass consumption within days!
BARBER-POLE DISPLAY PROGRAM

Here’s a somewhat longer exercise that demonstrates the “Console O utput”
and “Get Console Status” functions while showing how to program a loop
with a changing variable in 8080 code. The goal of the exercise is to write a
program that will display the entire ASCII set on the console, over and over
51
Soul of CP/M®
again. We’ll use “Console O utput” to send the characters to the screen and the
“Get Console Status” to end the program if a key is pressed. (W ARNING: Do
not turn on your printer while running this program as it does not send a
carriage return/linefeed to the screen, and it will, therefore, cause the printer
to go to the right edge of the paper and just sit there, typing over and over on
the same spot.) This program uses several new and interesting instructions and
it introduces you to that useful but mysterious device, the “stack.”
Again, get into D D T and enter this program with the A (assemble) com
mand:
-a100
0100 mvi e ,2 0 Set up E-register for first ASCII character.
0102 mvi c ,2 Ready for output.
0104 push d Save the DE register-pair (save E).
0105 c a ll 5 Send character to the screen.
0108 pop d Get the DE pair back (E is restored).
0109 in r e Bump E by + 1 .
010A mov a ,e Put the E-register in the A-register.
010B cpi 7f Is it the 127th character?
010D jn z 102 If result not zero, then no, so loop.
0110 mvi c , b Check console status.
0112 c a ll 5 Call BDOS.
0115 o ra a Set zero flag based on contents of A.
0116 j z 100 If a = 0, then no key pressed, so loop.
0119 rs t 7 Return to DDT.
You can save the program as “barber” by exiting D D T and typing:
A>save 1 b a r b e r . d d t
The program can be executed in the usual way by loading it along with D D T :
A>ddt b a r b e r . d d t
And, typing:
-g100
But, before you do that, take a minute to understand just what’s going on.
There are a lot of new instructions in the program that you need to learn.
(Too late, right? You already ran it. That’s all right, we admire impetuous
programmers.)
52
Fig. 2-6 gives a flowchart of the program’s operation. You can refer to the
flowchart as you read about the new instructions the program uses.
A flowchart is simply a pictorial representation of the operation of a pro
gram. Sometimes, certain conventions are followed in flowcharting. For
instance, actions which result in the program making a choice between two
different routes are placed in diamond-shaped boxes. Rectangular boxes
show actions which don’t result in a choice; there’s only one way out of a
rectangle. Circles show places where the program enters or leaves the chart.
Fig. 2-6. Flowchart of the Barber-Pole Display program.

53
Soul of CP/M®
The Stack
The first unfamiliar instruction in the program is the “push d” at location

104. In order to understand this instruction and the one at location 108, “pop
d ” , you need to know about a strange, wonderful, and, occasionally, infuriat
ing thing called the stack.
We showed you earlier how the stack can be used as a convenient place to
store the return address when we call a subroutine. But the stack can store
more than one thing. It can be thought of as, well, a stack. A stack of dishes,
for example. When you’ve washed a dish, you put it on the top of the stack for
storage. If you need a dish, you take it off the top of the stack. (This kind of
stack is called LIFO, for “last in, first out.”) There is a stack in the memory of
your C P/M computer and it works in the same way except, of course, that it
doesn’t store dishes, it stores the contents o f register pairs. The contents of a
register pair is two bytes long (which is 16 bits, or four hexadecimal digits).
There are two main instructions for manipulating the stack: PUSH (which
puts something on the stack), and POP (which takes it off). The operation of
these instructions is shown in the diagrams of Figs. 2-7 and 2-8. Notice that
PUSH
Fig. 2-7. Using the PUSH to manipulate the stack.
54
POP
A register pair.
7 Top of the stack.
1020
./
9E03 FCOO
The number 9E03 is 0200

removed from the top /
of the stack with a
POP instruction. 40 E0
POP
A register pair Top of the stack.

FC00
/
1020 0200
/
Then, the 1020 is removed. 40E0
POP
A register pair. Top of the stack.

0200
FC00 40 EO
¥
Finally, we can take off the FC00.
Fig. 2-8. U sing the POP to m anipulate the stack.
each box in the diagrams stands for two memory locations, since each is hold
ing a two-byte quantity.
We can’t take a number out of the middle of the stack. If we want the
number FC00, for example, we must first remove the 9E03, then the 1020,
and finally the FC00. This is illustrated in Fig. 2-8.
Remember how, in the last chapter, we mentioned that the B and C regis
ters, the D and E registers, and the H and L registers could be put together to
form the BC, DE, and HL register-pairs? It’s the contents of these 16-bit
register-pairs that are stored on our stack. Sometimes these 16-bit quantities
are simply numbers that we want to save, other times they are addresses.
W hat does the stack consist of? It’s ju st a series of memory locations,
somewhere in your computer’s memory. Often the program you’re using,
55
Soul of CP/M®
such as DDT, or C P /M itself, takes care of figuring out what memory loca
tions are to be used for the stack, and we’ll assume that’s true for the time
being. Later, we’ll find that this can sometimes be a dangerous assumption,
and we’ll figure out ways to deal with the stack more directly.
How does the CPU know where in memory to put whatever is supposed to
go on the top of the stack? Well, there’s actually another register, which we
haven’t mentioned yet, called the “stack pointer,” which keeps track of where
the top of the stack is. For the moment, we won’t need to know too much
about this register since the common instructions for putting things on the
stack and taking them off—PUSH and POP—handle the stack pointer auto
matically.
Something strange to notice about the stack is that it grows downward in
memory. T hat is, if the “ top” of the stack happens to be at location 1000
hex and you add something to the stack, it will go into locations F F F and
FFE, ju st below 1000. The next thing you put on the stack will go in loca
tions F F D and FFC, and so on. Likewise, if the top of the stack is at 1000
and you take off the first item, it will come from locations 1000 and 1001.
The next item will come from locations 1002 and 1003, and so on. There’s a
reason for this seemingly backwards behavior, and we’ll discuss it later in
the book.
The PU SH Instruction
To store the contents of a register-pair on the stack, we use the PUSH

instruction. It has the format:
push x
where the x can stand for either “b”, “d”, or “h” . In this case, “b ” stands for
the BC-register, “d” stands for the DE-register, and “h” stands for the HL-
register. When this instruction is executed, the 16-bit (two bytes, four hex
digits) contents of the register-pair x are copied into the vacant memory loca
tion at the top of the stack.
This is the memory location pointed to by the stack pointer register. Once
the quantity is written into this location, PUSH takes care of changing the
stack pointer register so that it points to the new top of the stack -th e next
available place where a quantity can go.
Examples:
Before the PUSH Instruction:
Stack pointer points here.

/ /
A register pair. Top of the stack.
OFFD 90
/
98DE OFFE 77
/
OFFF OE
/
1000 D9
/
The Stack.
After the PUSH Instruction:
Stack pointer.
/
OFFB 98 Top of memory.
PUSH
/
OFFC DE
/
OFFD 90
/
A register pair.
OFFE 77
/
98DE OFFF 0E
/
1000 D9
/
The Stack.
Fig. 2-9. The PUSH in stru ctio n .
The PO P Instruction
POP is simply the opposite of PUSH. It takes things o ff the stack, from where
PUSH put them on the stack. The 16-bit quantity removed from the stack is
written into the register-pair specified in the operand field of the instruction:
pop x
where x can be either “b ”, “d”, or “h” and stands for the BC, DE, or HL
registers.
POP takes care of incrementing the stack pointer so that it points to the
next free memory location.
57
Soul of CP/M®
Before the POP Instruction:
Stack pointer.
/ — /]
0FFB 98 Top of memory
/
0FFC DE
,
OFFD 90
A register pair. /
OFFE 77
/
OFFF OE
1000 D9
/
The Stack
After the POP Instruction:
Stack pointer
points here.
Top of the stack.

OFFD 90
A register pair.
OFFE 77
Z I=
98 DE OFFF OE
1000 D9
The Stack
Fig. 2-10. The POP in stru ctio n .
Examples:
pop d
pop h
In our “barber-pole” program, we need to save the E-register each time

that we call the “Console O utput” routine. Why? Because we’re going to use
the E-register to hold the ASCII value of the character that we want to print.
58
And, every time we call the Console Out routine, we want to increase the
ASCII value of the contents of the E-register by one, so as to print the next
character. Unfortunately, however, the Console Out routine trashes
(destroys) the contents of the E-register when it is called. To prevent this
unfortunate occurrence, we save the E-register on the stack with a “push d”
instruction before calling “Console O utput,” and restore it afterwards with a
“pop d.” Notice that, even though it’s the E-register we want to save, we use
“d” in the PUSH and POP instructions, because it is the first letter in the
register-pair “DE.” The instruction saves both the “ D ” and “E” registers but,
in our case, the “ D ” register is ju st along for the ride.
We mentioned that we wanted to increment the ASCII value in the E-
register each time that we call the Console Out routine, so that we will print
all the ASCII characters in order. How do we go about incrementing (adding
1 to the contents) a register?
The INR Instruction
This instruction is simply a way to add the quantitiy 1 to the contents of a

register (see Fig. 2-11). It works on any of the registers A, B, C, D, E, H, and
L. (It doesn’t work on register-pairs—there’s another instruction for that,
which we’ll get to later.)
This instruction adds 1 to whatever is in the register. If the number in the
register is FF, adding 1 will change it to 00, and the zero flag will be set. (This
instruction will also set other flags, which we’ll discuss later.)
Register Before INR Instruction:
Fig. 2-11. The INR in stru ctio n .
Register After INR Instruction:
Examples:
inr e
inr a
inr h
59
Soul of CP/M®
The MOV Instruction
You’ve already learned that the MVI instruction will take a fixed 8-bit
number from memory (from the location immediately following the instruction)
and put it in a register. The MOV instruction, on the other hand, takes the 8-bit
contents of a register and puts it in another register. MOV can be used to MOVe
data from any 8-bit register to any other 8-bit register. The format is:
mov x , y
where the contents of register “y” is moved into register “x.” (As we men-
tioned before, this may seem backwards, or at least a little arbitrary, but
you’ll get used to it. Think of the data as going from right to left in the
instruction. All the 8080 instructions do things from right to left in this way.)
In the diagram of Fig. 2-12, the contents of the B-register are copied into
the E-register by the MOV instruction. The contents of the B-register are not
changed.
This instruction does not cause any flags to be set. Thus, if you MOV zero
into a register, the zero flag will not be set.
Before the MOV Instruction:
B-register E-register
A A
82
)
Fig. 2-12. The MOV in stru ctio n .
After the MOV Instruction:
B-register E-register
/ A
82 82
MOV E,B
)
Examples:
mov e,a
mov h,l
mov d,b
We mentioned earlier that not all hex numbers are printable as ASCII
codes. In fact, the printable ASCII codes run from 20 (hex), which is a space,
to 7F (hex), which is the rubout. Sending numbers greater or less than these
to your console device or printer is likely to cause strange and unpredictable
60
results. Thus, we want to start our program by sending 20 (hex) to the con
sole, and when we’ve sent 21, 22, and so on up to 7F, we want to start over
again with 20. The first instruction in the program, “mvi e,20”, starts us off
with 20, but how will we know when we get to 7F?
The CPI Instruction
The answer is the CPI instruction, which stands for “Compare Immedi
ate.” CPI performs a comparison between the number in the A-register and
the number in memory immediately following the CPI instruction. The result
of the comparison is used to set the various flags, including the zero flag.
How do we know what flags will be set? The idea here is to think of this
instruction as a sort of “phantom ” subtraction of a fixed 8-bit quantity from
the A-register. Why isn’t it a “real” subtraction? Because the quantity in the
A-register is not actually changed; nothing is subtracted from it. However,
the zero flag (and the various other flags that we will learn about later) act as
if the subtraction had been carried out.
This is easy to understand in the case of the zero flag: i f the two numbers
are equal, the zero fla g is set. Why? Because when you subtract a number from
the same number, the result is zero.
the program is located.
In this case, they are not the same,

so the zero flag is not set.
Fig. 2-13. The CPI in stru ctio n .
Examples:
cpi 7f
cpi 2
61
Soul of CP/M®
In our case, the “cpi 7f” instruction compares the contents of the A-regis
ter with 7F hex. The first time through the loop, the A-register will contain
20, because the E-register contains 20. So the result of the subtraction will
NOT be zero. The next time, the A-register will contain 21, because the E-
register contains 21, because we incremented it with the IN R instruction. The
next time it will contain 22, and so on, until we’ve counted up to 7F. When
the A-register is 7F, the results of the comparison will be 0, and the zero flag
will be set. W hat use will we make of the zero flag?
The JN Z (jump-on-not-zero) Instruction
As you can guess, this instruction is similar to the JZ instruction that

you’ve already encountered, except that it jum ps if the zero flag is NOT set.
Otherwise, it goes on to the next instruction in the program.
/ /
0100
/
0101
/
0102
/
lllllllllllllllllllll
lllllllllllllllllllll
/
Goes back to 0100
0114 C2 if zero flag is NOT set.
i
JNZ 100 —
0115 00
/
Goes on to 0117
0116 01
if zero flag is set.
/
0117
/
Fig. 2-14. The JNZ in stru ctio n .
Examples:
jnz 100
jnz bfOO
In the case of our barber-pole program, the CPI instruction will result in
the zero flag not being set until all the ASCII characters from 20 to 7F have
62
been printed. So each time the JN Z instruction will take us back to the sec
ond instruction in the program —at location 102. When we’ve printed all the
ASCII characters, the program will go on to location 110, where it will per
form the “Get Console Status” system call to see if any key of the keyboard
has been pressed. If not, it will start the program over. If so, it will return to
DDT, as in the example shown in our previous program.
Running the Program
When you run the program, you should get something like this display:
-g 1 00
! " # $ % & $ ! ( ) * + ' - . / 0 1 234567890:;<=>?ABCDEFGHIJKLOMNOPQRSTUVWXYZC

\ ] A_ 'a b c d e fg h i j klmn o p q rs tu v w x y z { I }~ ! "#$% & ! ( ) * + ’- . / 0 1 234567890
: ;<=>?ABCDEFGHIJKL0MN0PQRSTUVWXYZC\] A_ 'a bcd e fg h i j klmn o p q rs tu v w
x y z { ! } ~ ! 1#$% &$!( ) * + ’- . / 0 1 2 3 4 5 6 7 8 9 0 :;< =>?ABCDEFGHIJKLOMNOPQRSTUVW
XYZC I ]A _ 'a b c d e fg h i j klmn o p q r s tu v w x y z { I }~ !"#$% &$I < ) * + ’- . / 0 1 23456
7 8 9 0 : ;<=>?ABCDEFGHIJKLOMNOPQRSTUVWXYZC\]A_'abcdefghijklmn o pq rs
tu v w x y z { ! .....[etc. until you press any key]
This is a good program to keep in your wallet and memorize for when
you’re at a party or at a new friend’s house and you want to impress them
with your knowledge of C P /M and 8080 code.
CONSOLE INPUT
CONSOLE INPUT FUNCTION 1 (dec) = 1 (hex)

On return: REG A = ASCII character from keyboard
Console Input is perhaps the most-often used C P /M function call. Its pur
pose is to get a character from the keyboard into your program. Console
Input is used by almost all programs that run under C P /M which request
user input from the keyboard. For example, all text editors for C P /M use the
Soul of CP/M®
console input function to get an ASCII value from the keyboard. It works
much like the G ET statement in BASIC. When Console Input is called, it
reads the next console character into the A-register of the 8080. It will “echo”
your character to the screen as well. It will not echo control characters but
will react to many of them. If no key is pressed, the function will hang, wait
ing until a key is pressed, and, thus, suspending execution if a character is not
ready.
There are some special features of the Console Input function that you
should be aware of. Most im portant is the way it responds to C P /M control
characters. It does not respond to a warm boot (control-c), or to the printer
stop/start toggle (control-p). This makes complete sense, as you often
D O N ’T want the user to be able to warm-boot the system or turn on the
printer from inside your program. When you DO wish the user to have such
control, you can use another C P /M console function called “Read Console
Buffer.” This call, which we will describe shortly, is the one that comes with a
complete set of editing commands, and is used by many of the C P /M utili
ties. You’ll hear more about “Read Console Buffer” later.
Beep Program
Let’s do a simple exercise program with the Console Input system call.
This program will cause C P /M to echo everything typed in at the keyboard
onto the screen, accompanied with a little beep that is provided by your con
sole’s “beep” or “bell” sound.
Bring up D D T and enter this short program.
- a 1 00
0100 mvi c ,2 Set up for console output.
0102 mvi e ,7 a s c i i 7 = bell.
0104 c a ll 5
0107 mvi c,1 Set up for console input.
0109 c a ll 5
010C jmp 100 Loop forever getting key and echoing it.
Save it with:
-gO
A>save 1 t e s t 3 . d d t
Now, run it by typing:

64
A>ddt t e s t 3 . d d t
and
-g100
Try it out. Each time you press a key, the console beeps and the character
is printed on the screen. Neat. But if you try to press control-c to reboot,
nothing happens. G reat Scott, we’re caught in a deadly endless loop . .. ;
we’ll have to press reset to escape. But first, while you have your program
running, try a few of these keys and verify what happens on your system. All
should cause a beep.
AC Nothing happens and nothing gets displayed.

AP Same as above.
AJ Causes a line feed to occur.
AM Causes a carriage return to occur.
AS Nothing happens (or seems to happen).
AG Nothing happens.
AH Backspaces the cursor.
W hat this tells us is that the Console Input function does not respond to all
the normal C P /M control-key conventions. If you wanted it to respond, for
instance, to the control-c key, you would have to write a special part of your
program yourself, to do just that.
Also, you can see that our program has a “bug”in it, in that the only way
we can turn it off is to do a cold boot by resetting the system.This, again, is
less than elegant. Can you think of a way out of this problem? Could you
rewrite the program so that it looks for the control-c and causes the program
to end if it sees one? Yes, Watson, and here’s how to do it!
Take our old code:

0102 mvi e ,7 ASCII 7 - bell.
0104 c a l l 5
0109 c a l l 5
010C jmp-1-90 (Replaced with cpi 3.)
Enter this new code:

65
Soul of CP/M®
-a10C
010C c p i 3 Check if A = 3.
010E jn z 100 If not, repeat loop.
0111 r s t 7 Yes, it was a 3, so end.
You can save the program as “ test4.ddt”.

W hat do these new instructions do? The ASCII code for a control-c is 3
(hex), so we now check each character typed in to see if it has a value of 3,
using the cpi instruction as in the previous example. If it does, we go back to
D D T with the “rst 7” instruction. Otherwise, we keep looping.
Run the program from D D T with glOO and see if you can stop the pro
gram by pressing a control-c.
As an exercise, you could try modifying this program by having the cap
tured character do something other than end the program. Perhaps it could
cause a warm boot when a control-c is typed. The next function call (system
reset) explains how that is done. But first, we need to learn how to execute
programs directly from C P/M .
EXECUTING PROGRAMS FROM CP/M
So far we have executed all our programs from D D T by typing glOO. This
is fine for short exercises, but many times we want to be able to execute a
program directly from C P /M without calling up D D T at all, simply by typ
ing the name of the program following the C P /M prom pt A > .
In theory, this is simple. We write the program in DDT, then SAVE it as a
COM file, and, then, execute it directly from C P/M . However, in practice,
there’s a problem, and it’s this: if our program contains a “rst 7” instruction,
and we attempt to execute it directly from C P/M , we’ll probably “crash the
system” (cause error messages followed by a cold boot), because C P /M does
not respond to “rst 7” the same way that D D T does, “rst 7” can be used only
to return to DDT. To return to C P/M , we use another instruction—“ret” .
The RET Instruction
RET is usually used in connection with the CALL instruction. CALL takes
you from your main program to a subroutine, and RET takes you back again.
Remember how, in the CALL instruction, the address immediately following
the CALL was placed on the stack? Well, the RET instruction takes this
66
address off the stack and transfers control back to this address in the main
program.
The CALL instruction

MAIN PROGRAM transfers control to SUBROUTINE
the subroutine.
program.
Fig. 2-15. The RET in stru ctio n .
Example:
ret
RET is ordinarily used to return us to the calling program from a subrou

tine. Now, the way C P /M is set up, applications programs—that is, programs
we want to execute directly from C P /M —are treated as subroutines by the
C P /M operating system. This makes it easy to leave a program and go back
to C P/M . All we have to do is execute a RET instruction and, presto, we’re
back in the monitor with the A > prompt.
However, if we attem pt to execute a program directly in C P /M that doesn’t
use RET to return to the monitor, then we can be in big trouble. Specifically,
if we attem pt to execute a program in C P /M that ends with RST 7, disaster
will probably result.
So, before we can use any of the programs we’ve written so far in a direct
C P /M mode, we need to go through them and change any “rst 7” instruc
tions we find to “ret” instructions. Let’s do that on the last example, which
67
Soul of CP/M®
beeped when we typed in characters, but which went back to D D T when we

typed a control-c. Simply change the last instruction in the program, rst 7, to
ret. Here’s the resulting code:

0102 mvi e ,7 ASCII 7 = bell.
0104 cal L 5
0109 c a ll 5
010C cpi 3 Check if A-register = 3.
010E jn z 100 If not, repeat loop.
0111 re t Yes, it was a 3, so end.
Go back to C P /M and save this program as a .COM file by typing:
A>save 1 te s t4 .c o m
Now you can execute the program directly from C P/M , simply by typing its
name:
A > te s t4
Type in some stuff. Listen to the beeps. W hat happens when you type a
control-c? You’re back in C P /M again! This is just how programs are exe
cuted in the big leagues.
SYSTEM RESET-A WARM BOOT
SYSTEM RESET FUNCTION 0 (dec) = 0 (hex)
The System Reset system call is used for causing a warm boot from your
program. The warm boot, as you recall, causes the CCP part of the C P /M
operating system to be reloaded. Also, several locations in FDOS (BDOS
plus BIOS) are reset to their initial values.
The reason that you need to know how to do a warm boot is simple. Some
times you will need as much memory space in the TPA as you can get. As you
know, BIOS, BDOS, and CCP take up room in the top of RAM. It turns out
68
that you can remove the entire CCP from RAM and still use all of the system
calls, provided you don’t wipe out FDOS. When you want to return to
CP/M , you do a “System Reset” and the CCP will be reloaded and FDOS
reinitialized. System reset works just as if you pressed control-c from the
keyboard. You’ll hear the disk click as the CCP is read off the disk into
memory.
Here’s a little program that will cause a warm boot (system reset). But,
look out! You can’t test it from D D T because it will wipe itself out in the
process of resetting the system, thus, resulting in error messages and trouble!
-a100
0100 mvi c , 0 Set up for system reset.
0102 c a l l 5 Call BDOS.
0105 r e t Return to CP/M .
-gO
Enter the program from DDT, exit D D T with a gO (which also causes a
warm boot and replaces D D T with the CCP), and do a:
A>save 1 te s t5 .c o m
Now, you can execute the program directly from C P/M :
A > te s t5 Test the program.

A> Hear disk click, new prompt.
Now you know how to make your program go back and reinitialize C P /M
whenever you want. That means that you can run programs that use the
memory space usually occupied by the CCP and can be assured that you can
reinitialize the system later.
SO LONG, CHAPTER 2, IT S BEEN GOOD TO KNOW YOU
By this time, you know more about C P /M and 8080 programming than
you ever expected to. You’ve learned the Console Out, Get Console Status,
Console Input, and System Reset systems calls. And, you’ve learned a whole
batch of 8080 instructions: MVI, CALL, RST, JMP, ORA, JZ, PUSH, POP,
INR, MOV, CPI, JNZ, and RET.
69
Soul of CP/M®
That’s enough 8080 instructions to write some pretty complicated code.

And, since you now know how to do input and output to your video screen
and keyboard, there’s really no limit to the programs you can write. However,
there are other, more powerful, systems calls that will give you greater flexi
bility and will simplify your programming. We’ll cover them in the next
chapter, so hang onto your hats!
70
CHAPTER 3
Getting in Deeper
Advanced Console System Calls
In this chapter, we’ll look at some console in p u t/o u tp u t system calls that
operate on whole groups of characters, rather than on one character at a time
as did the system calls in the last chapter. Then, we’ll introduce you to an
unusual display program which will act as a review of what you’ve learned so
71
Soul of CP/M®
far. We’ll describe “Direct Console I/O ,” which lets you interact much more
directly with the screen and the keyboard than have our previous system
calls. Finally, to wrap up our study of nondisk system calls, we’ll cover a
number of functions which deal with nonstandard I/O equipment.
PRINT STRING
PRINT STRING FUNCTION 9 (dec) = 9 (hex)
Enter with: REG C = 9 hex

REGs DE = starting address of string
Comments: String must end in a “ $” (24 hex)
Here’s the way to send complete words or even sentences to the screen
from inside C P/M . In the programming world, as you know, a series of char
acters like a word or a sentence is called a “ string” (it’s just a collection of
strung-out characters). In C P/M , a string may goeth and a string may
cometh, meaning that we can send strings to the screen and we can accept
strings from the keyboard. The Print String function is for making your
string goeth to the console display screen. It’s an advanced version of the
Console Out system call in the the last chapter, which only sent one character
to the screen at a time. Print String is sort of like the PR IN T statement in
BASIC, except it is a bit more indirect to use, as you will see.
Print String expects that you have stored the string you want to send to the
screen in a continuous area of memory as a sequence of ASCII bytes. (We’ll
show you how to do this presently.) You must end the string with hex 24, the
ASCII value for the “$” symbol. Then, to print the string, you put the
address where the string starts in the DE register-pair, put a 9 in your C REG
and do a BONSAI TO BDOS (a very excited call 5).
Of course, manually typing in and looking up the ASCII equivalents for all
of the characters in the message that you want to display can certainly be a
tedious process. Be patient! In the next chapter, we are going to show you
how to use ASM, the C P /M assembler, to simplify this process. When using
an assembler (as opposed to a miniassembler like that in DDT), you can
simply enter the letters for the string into the source listing directly from the
keyboard. So take heart, we’ll eventually learn to do Print String the easy
way. In the meantime, using D D T will be a bit tedious, but it will give us a
better idea of what’s really going on.
72
Getting in Deeper
Typing in a M essage With DD T
First use the D D T Set command “s” to put the hex values for the letters
“A B C D E” into memory starting at location 010A hex. The set command
first displays the current contents of the memory location that you are
about to type in to. In this case, these numbers are of no interest to us. Each
time you type a two-digit (one byte) value and hit the carriage return, your
number is stored in the memory location shown, overwriting the old value.
■ These are the old values.
You type numbers in this column.

-s10a I
010A 53 41 D D T displays 010A 53 and you typed 41 (hit return after every value
010B 49 42 you type in).
010C 47 43
010D 48 44
010E 54 45
01 Of 20 24 ■This is the $ to end the string.
0110 28 m • Type a period to end the Set command.
Now you can check that you have entered the string correctly, using the D
command:
-d 1 0 a ,1 0 f
010A 41 42 43 44 45 24 ABCDES
As you can see, the numbers are just as we entered them, with the ASCII
letters that they represent shown in the right-hand display column. Now we
are ready to enter the program that will actually print the string:
- a 1 00
0100 mvi C,9 Set up for Print String.
0102 t x i d ,1 0 a We start our string at 10A hex.
0105 c a ll 5 Our famous BDOS call.
0108 rs t 7 Return to DDT.
Save it as test5.ddt.
73
Soul of CP/M®
The LXI Instruction
As you recall from the last chapter, the mvi instruction took a one-byte
constant and placed it into the register indicated in the instruction. LXI is
similar, except that it puts a two-byte constant into the indicated register-
pair. This two-byte constant is stored in the program in the two bytes imme
diately following the lxi instruction in memory.
As in the MVI instruction, the “ I” in LXI means that the constant to be
stored immediately follows the instruction in memory (as shown in the dia
gram of Fig. 3-1). The “X” means that the instruction operates on a register
Before LXI D.010A is executed:
Section of memory
containing program.
0100
DE register 0101
0102
11
0103
0A
0104
01
After LXI D.010A is excuted:
/ 0100
0101
DE register
/ 0102
z : 11
010A
k 10103 LXI D.010A
0A
r 0104
The constant in the instruction 01
is moved into the DE register when /
the instruction is executed.
1/
Fig. 3-1. The LXI instruction.
74
Getting in Deeper
pair and not on a single 8-bit register. These are both conventions which
make it slightly easier to remember the mnemonics (abbreviations) for the
instructions.
Don’t forget when using LXI that you need to type in four hexadecimal
digits, not two as with MVI.
Examples
lxi d,1234
lxi h,01ff
lxi b,bf00
Now try executing the “ test5.ddt” program:
-g100
ABCDE*01 08 Worked perfectly! ABCDE got printed.
There is almostno limit to the size of the string you can print. To see this,
use the “fill” command in D D T to put a large number of the same ASCII
letter after the ABCDE string. To use “fill,” type f, followed by the address
where you want to start filling, the address where you want to stop filling,
and the constant you want to fill in. For instance,
-fl Of,400,41
will fill memory from lOf to 400 with ASCII “A’s” . Don’t forget to put the 24
hex at the end o f the string, using the “s” function.
-s401
401 FD 24 This is the ASCII for
402 DO . Period used to terminate “s”.
Now try your program on this new string. The screen will simply fill with
the letter “A ” continually until it reaches the end. D O N ’T TU R N ON
YOUR PRINTER. There are no carriage returns at the end of every 80th
character of the string, so the printhead may go to the right side of the car
riage and bang itself to death there.
75
Soul of CP/M®
READ CONSOLE BUFFER
READ CONSOLE BUFFER FUNCTION 10 (dec) = OA (hex)
Enter with: REG C = OA hex

REG DE = Buffer address
DE + 0 = Maximum number of characters
On return: DE + 1 = Number of characters typed

DE + 2, etc. = Typed characters in buffer
Comments: Max length string = 255 characters

Responds to all CP/M line editing commands
Read Console Buffer is one of C P /M ’s most useful functions. Its purpose

is to accept a string of characters typed in at the console device (usually the
keyboard) and put them in a “buffer” area in memory so your program can
use them. Read Console Buffer is similar to the Console Input function we
covered earlier in that it accepts information typed at the keyboard. How
ever, the similarity stops there, for the read buffer function allows the user to
type a complete string of up to 255 characters. It’s also a little more compli
cated to set up than Console Input. We’ll explain how to do it, and what
“DE + 1” and similar notations mean, in a minute.
C P /M ’s Built-in Editing Commands
One feature that makes Read Console Buffer especially useful is that it
responds to the set of C P /M control-character commands and, thus, per
mits editing while you’re typing in the string. Perhaps the most important
of these commands is control-c. If this is typed at the beginning of the
string, C P /M does a warm boot. Thus, by using Read Console Buffer, you
allow your program user the opportunity to reboot the program during
input. This may be desirable or not, depending on the type of program
being used. Read Console Buffer offers a host of other useful line editing
features. The commands available to the lucky user of this function are
(press CONTROL with all these letters):
H backspaces one character position.

X backspaces to the beginning of the line and erases all characters
(start over, erase).
76
Getting in Deeper
U moves cursor down to beginning of next line and IGNORES previ

ous typed line (start over, still view old line).
R retypes the current line after the new line. Useful when you over
used the DEL key and can’t figure out what the line means.
E causes “physical end of line,” meaning the cursor returns to the left
margin, one line down.
J is a line-feed character, and terminates input line (as if a carriage
return was typed).
M is a carriage return, terminates input line.
DEL removes and echos the last character typed. A n old-fashioned way
to remove characters, left over from the old days of hardcopy-only
teletypewriter machines.
C does a warm boot.
We don’t want to go too far off on a tangent at this point by getting too
involved in these editing features. You can practice them on the string that
we will be using in the next exercise. For now, here is a short way to remem
ber the most im portant commands:
H H ard left one space, no Hurt.

X X out the whole line, start over.
U yUck, start over next line.
R Retype line, down one line.
E End this line, go down a line.
You can copy this out and stick it up near your computer, or on the fore
head of a passing co-worker.
How to Set Up Read Console Buffer
The Read Console Buffer system call “reads” a line of edited console input
into a buffer addressed by the contents of register-pair DE. You must set up
the buffer address in the DE-register before making the call. The LXI
instruction is used to do this, ju st as in the Print String function. In addition,
you must set up a number in the beginning of the buffer which represents the
maximum number of characters you want to accept. If you put a hex 20, for
example, in the buffer, then as soon as the user types more than 32 characters
(decimal), the function will terminate. We call this “ending by OVER
FLOW .” The user can also terminate the string by typing a RETU RN (or a
control-J or -M).
77
Soul of CP/M®
DE+O +1 +2 +3 +4 ... + n-1 + n
/ / / / / / / / ,/|
mx nc c1 c2 c3 ??
? ? |/
\ ' T his is the number of characters typed.
-
--T his is the maximum characters allowed.
Fig. 3-2. Buffer address in the DE register.
The buffer that we set up looks like the diagram in Fig. 3-2.
This is what it means. “DE + O” is simply shorthand for the address sent to
the function in the DE-register. DE + 1 is the next address after this, and so
on. Thus, if you put 400 in the DE-register when you call this function,
D E + 1 will be at 401, DE + 2 will be at 402, and so on up to DE + n, which
will depend on the length of your message.
The “mx” indicates the maximum number of characters that the function
will allow to be typed into the buffer, a number from 1 to FF hex (1 to 255
decimal).Your program must put this value in the first position in the buffer.
The “nc” is the number of characters actually typed by the user and this is set
by FDOS when the function returns to your program. This number is useful
for determining how long the input string actually is. It is found at D E + 1.
Following “nc” are the actual characters read from the keyboard. If the
number of characters actually typed by the user is less than the number set
by mx (nc < mx), then the remaining positions in the buffer are whatever
they were before the function was called and have no meaning. These are
marked as ?? in Fig. 3-2.
Note that some control characters typed into the print buffer will get
stored in their proper ASCII codes. Tabs, for example, appear as 09 hex. A
control-c in the middle of a line will appear as a 03 hex.
Our Read Console Buffer example is really quite simple. Let’s assume that
we’re going to start our buffer at 200 hex. Type the following in D D T :
- a 1 00
0100 mvi a , 20 Set max characters to 32 (dec)
0102 s ta 200 and put in first buffer position.
0105 mvi c ,a Set up REG C for Read Console Buffer.
0107 Lxi d ,2 0 0 Load DE with location of buffer start.
010A c a l l 5 Finally, call BDOS.
010D r s t 7 Back to DDT.
78
G etting in Deeper
You can store this program as “ testó.ddt” .

As you can see, there’s a new instruction listed: STA. Let’s see what it’s all
about.
The STA Instruction
This instruction will take the 8-bit value in the A-register and store it any
place in memory. Where this value will be stored is determined by the
address in the operand field of the instruction. For instance:
sta 2000
will take the 8-bit value in the A-register, which might be anything from 00 to
FF, and store it in memory location 2000.
In DDT, this address is represented by a four-digit hexadecimal number.
In the next chapter, when you learn how to use the assembler, you will find
that this address can also be represented by a name.
Notice the difference between this instruction and others that we’ve
learned about earlier. For instance, MOV B,A takes an 8-bit value from the
A-register and stores it, not in memory as STA does, but in a register: the B-
register. An instruction like MVI A,7F is different from STA in two ways.
First, it’s loading an 8-bit value from memory into the A-register, not storing
it from the A-register into memory as STA does. Second, MVI A,7F refers to
a constant at a place in memory immediately following the MVI instruction,
while STA refers to a location in memory that can be located far away from
the STA instruction itself. For this reason, STA uses an address in the oper
and field, while MVI uses the actual 8-bit value.
Examples
sta 2010
sta 0100
sta bfOO
Our example program first puts a 20 (hex) into the A-register and stores
it at the beginning of our buffer at 200 (hex). This is “mx,” the maximum
number of characters. The program then calls Read Console Buffer, using
the address 200 as the start of the buffer. It then waits for you to type
something in.
79
Soul of CP/M®
Before STA 2011 is executed:
/ 0100
Section of memory
containing program.
/ 0101
A-register
/ 0102
63 IP
/ 0103 STA 2011
/ 0104
/
/
1111111111111
1111111111111
/ / Section of memory
where constant
will be stored.
2011
/ 2012
/
After STA 2011 is executed:
0100
Section of memory
containing program.
A-register 0101
0102
0103 STA 2011
0104
2010 Section of memory

where constant
is now stored.
2011
2012
Fig. 3-3. The STA instruction.
80
Getting in Deeper
-g 1 00 »-------- Start the program.

Now i s the t i m e . - . -----------Type this in.
* 0 1 OD -*---------- This will actually overwrite the first part of the input.
There is a small glitch in that the “ *010D”, which D D T prints when the
program is over, overwrites part of the line that we typed in. This would be
easy to fix, as we’ll see in the next example, but for the time being we’ll live
with it.
Now you can dump (display) the buffer at 200 (hex) to see if what you
were supposed to put there has actually arrived.
-d 2 0 0 ,2 1 f
0200 20 10 4E 6F 77 20 69 73 20 74 68 65 20 74 69 6D .Now i s th e tim

0210 65 2E CD 05 00 F5 79 CD 8F 06 F1 C9 FE 20 C8 FE e .....y .............
There it is! The 20 at location 200 is the maximum number of characters

“mx,” which you put there with the STA instruction. The 10 in location 201
is the actual number of characters typed in (10 hex is 16 decimal). The rest of
the buffer from 212 on is still filled with whatever ju n k was in it before.
Let’s see what happens if we type in more characters than are specified by
“mx.”
-g 1 00
Now i s th e tim e f o r a l l good men ------- Type this in, keep typing.
* 0 1 0D I------- — At this point, the function took
~ over and returned us to DDT.
Dump the buffer again and there’s our input, safely stored away. This time
the number of characters that were actually typed in is the same as the maxi
mum “mx.”
-d 2 0 0 ,2 2 f
0200 2020 4E 6F 77 20 69 73 20 74 68 65 20 74 696D Now i s th e t im

0210 6520 66 6F 72 20 61 6C 6C 20 67 6F 6F 64 20 6D e f o r a l l good m
0220 656E FE 2C C8 FE OD C8 FE 7F CA 24 05 C9 0E 0D e n . , ............... $ ____
There it is again, just as you typed it. Later we’ll see how a program can
make use of this function to accomplish all sorts of useful and exciting things.
81
Soul of CP/M®
ECHO PROGRAM
Let’s put together the two string-handling system calls that you’ve just
learn ed -P rin t String and Read Console Buffer—into a single short program.
-a100
0100 mvi a , 20 Put max characters at start of buffer.
0102 s ta 1 fe
0105 mvi c,0 a Call Read Console Buffer.
0107 Lxi d , 1 f e
010A ca L L 5
010D mvi c ,2 Use Console Out to print linefeed.
01 OF mvi e,0 a
0111 c a ll 5
0114 mvi c ,9 Print String.
0116 l x i d ,2 0 0
0119 c a ll 5
01 1 c rs t 7 Back to DDT.
011D
You can save this as “ test7.ddt” .

This program will accept the input that you type, store it in a buffer, and
then print it out on the screen, echoing what you typed in. There are several
things to notice. First, we had to add a section to the program to print a
linefeed. This keeps the Print String function from printing right over the
string that you typed in. To do this, we use the Console O utput function to
print a OA ASCII character, which is the linefeed.
The next thing to notice is that we tell the Read Console Buffer and the
Print String functions different addresses for the start of the buffer. Read
Console Buffer is told to start at 1FE, while Print String is told to start at
200. This is because Read Console Buffer needs two extra bytes at the start of
the buffer to enter the maximum number of characters “mx” and the number
of characters actually typed “nc.” These will go in 1FE and IFF, respectively,
so that the actual typed characters will start at 200.
Try typing in some input. But, BE CAREFUL! Since Print String requires
that the string it prints be terminated with a dollar-sign character, you must
type a “$ ” at the end o f your string. Otherwise, as we noted earlier, Print String
won’t know when to stop, and may end up printing a lot of weird characters
that will do strange things to your terminal. For this reason, you must also
make sure you don’t type any more than 32 decimal (20 hex) characters. If
82
Getting in Deeper
you do, Read Console Buffer will terminate itself before you have time to
type the dollar-sign character.
Don’t forget the $.

-g100
Now i s the tim e .S You type this.

Now i s the t im e . * 0 1 lC Program types this.
NAME DISPLAY PROGRAM

The next program also makes use of the Read Console Buffer and Print
String functions. It’s a little more ambitious—which is to say longer and more
com plicated-and is really included just to give you something a little frivo
lous and amusing to play with. So don’t worry if every nuance of the pro
gram’s operation isn’t clear to you. However, in addition to Print String and
Read Console Buffer, it also makes use of the Console O utput and Get Con
sole Status system calls and it uses most of the 8080 instructions we’ve cov
ered so far. So it can serve as a review of what you’ve learned up to this point.
It also introduces the loop-within-a-loop, a concept that is good to get used
to, as we’ll be seeing it again later.
W hat exactly does the program do? Well, that’s a little hard to explain.
You start off by typing your name and the program then uses your name to
make some rather surprising patterns on the video screen. One picture, they
say, is worth a thousand words, so why not type in the program (very care
fully) and see what happens?
-a100
0100 mvi a ,20 Put max characters at start o f buffer.
0102 sta o lf e
0105 mvi c,0a Set up to get input string,
0107 lx i d ,1 fe store it at lfe.
010A c a ll 5 Call “ Read Console Buffer.”
0100 mvi b,30 Set initial B-register value to 30
010F push b and save on stack.
0110 pop b Get B from stack,
0111 in r b increment it,
0112 mov c,b store it in C,
0113 mov a,b and in A,
0114 push b and put it back on stack.
0115 cpi 50 Is the B-register = 50 yet?
83
Soul of CP/M®
0117 jz 10D Yes, so go reset it.

011A mvi c,2 Set up to print a space,
<\J
o
011C mvi (20 hex is a space),
<D
011 E cal L 5 call “ Console Output.”
0121 pop b Get BC, to decrement C.
0122 dcr c Decrement C,
0123 push b save BC.
0124 jnz 115 If C-register not 0, go print space.
0127 mvi c,9 Print the string;
0129 lx i d,200 starts 2 bytes past Ife.
012C ca LI 5 Call “ Print String.”
012F mvi c,b Keyboard character typed?
0131 ca 1 1 5 Call “ Get Console Status.”
0134 ora a Is A-register still = 0?
0135 jz 110 Yes, so do another line.
0138 rst 7 Back to DDT.
You can save this program as “nam edisp.ddt” . Be careful while typing in
the code. One disadvantage of using the microassembler in DDT is that if
you make a mistake in your input, sometimes it’s not easy to go back and
change it. This is because different instructions have different lengths, and if
you put a two-byte instruction in a place where you meant to put a three-byte
instruction, and then you want to go back and try to change it to the 3-byter,
it won’t fit. Using the assembler will eliminate this problem, as we will see in
the next chapter.
Here’s how this program works. When you first start it, you type in your
name. As in the last example, BE CAREFUL! You must terminate your name
with a dollar-sign character!
-g 1 00 « Start the program.
A Lf red E . NewmanS -«--------- Type your name (press return).
-«----------- Watch what happens!
Unfortunately, we can’t reproduce in this book a picture showing the

motion that the program displays. However, we can describe how the pro
gram works. After you’ve typed in your name, the program prints a string of
spaces, then your name, then a string of spaces (which is one space longer
than the first string of spaces), then your name, then a string of spaces which
is two spaces longer than the first one, then your name, and so on. The result
84
Getting in Deeper
is a pattern of shifting parabolas which seems far too complicated to have

come from such a simple program.
The constants in the program, 30 hex and 50 hex, are set up to work on an
80-column screen. If your screen is a different size, the program may not
produce the desired results. Try changing the 30 in line 10D and the 50 in line
115 to different values. Experiment a little.
Two registers are used to hold the variables that the program needs to
remember what it’s doing. The B-register holds the number of spaces to be
printed on the current line. This number starts at 30 hex and goes up to 50
hex. (These values were determined by trial and error.) The C-register counts
how many of these spaces have already been printed. That is, if the number
in the B-register is 40, then the C-register will start off at 40 and count down
ward to 0, printing a space each time. When all these spaces have been
printed, the program will go back, increment B by one, and start over print
ing the new number of spaces.
There’s one new instruction used in this program; it’s called DCR.
The DCR Instruction
This instruction is the opposite of the IN R instruction that you learned

about earlier. Where INR incremented (added 1 to) the one-byte register
specified in the instruction, DCR decrements (subtracts 1 from) the register.
Any 8-bit register (A, B, C, D, E, H, or L) may be used in the operand field.
Note that this instruction also sets the appropriate flags. That is, if decre
menting the register causes it to become 0, the zero flag will be set; otherwise,
it will be cleared. (Some other flags may be set as well.)
Before DCR C Is Executed:
C-register
y /
99
/
Fig. 3-4. The DCR instru ctio n .

After DCR C Is Executed:
C-register
/ /
98
/
85
Soul of CP/M®
Examples:
dcr b
dcr h
Fig. 3-5 is a flowchart that details the operation of the program. The memory
locations where the different parts of the code occur are shown on the side.
By studying the flowchart along with the program listing, you should begin
to understand how the program works. The heart of the program is the print-
G et input string
(100 to 107)
and store in buffer.
T
Set B-register = 30. (10D)
t
Increm ent B-register. (10F to 111)
Transfer B-register
(112)
to C-register.
< ^ J s B-register = 5 0 ? ^ > ---------------- (115)
( 1 1 A to 122)
(124)
(127 to 12C)
(12F to 135)
(138)
(E xit to D D ^
Fig. 3-5. Flowchart for the DCR instruction.
86
Getting in Deeper
ing of a string of spaces, in lines 11A to 124. Register C is set at the beginning
of this section to the number of spaces to be printed and is decremented each
time until it is zero. Then, the user’s name is printed and the program checks
to see if a keyboard character was typed to halt the program. After this, the
program returns to 10D to increment the B-register, which started off with 30
and will end at 50. The B-register holds the value that is given to the C-
register in line 112 so that the correct number of spaces will be printed each
time through.
Again, don’t worry if every detail isn’t crystal clear. The point really is just
to understand how a number of systems calls can work together in a single
program.
DIRECT CONSOLE I/O
DIRECT CONSOLE I/O FUNCTION 6 (dec) = 6 (hex)

REG E = FF hex on input
REG E = ASCII character on output
On return: REG A = ASCII character, or 00 (no character) on input.
Comments: A dual-purpose function call, for input and output.

No echo, bypasses all CP/M line-editing commands.
Direct Console I/O provides the serious programmer with a means of get
ting characters from the keyboard and displaying characters on the screen
without echo and without the previously described built-in control-character
functions, which it does not acknowledge. This is useful in those special cir
cumstances where you want to do something nonstandard with the user’s
input or the screen output. For instance, you might be writing a word-
processing program, and you might want to use control-c to cause the cursor
to move to another part of the document, rather than causing a warm boot as
it normally does. Or, you might want to define a special function for control-
s, instead of having it halt the display.
The use of Direct Console I/O lets you define control characters as you
wish and, thus, gives you a great deal of flexibility and control over your
input and output. However, you sacrifice all the capabilities that C P /M
87
Soul of CP/M®
offers for free, such as, freeze the display, warm boot, retype line, backspace,
printer on/off, etc. If you want these functions in Direct Console I/O , you
must build them into your program yourself.
Since using the control characters in a nonstandard way can lead to confu
sion if you’re not careful, the makers of C P /M (Digital Research, Inc.) rec
ommend that you not use Direct Console I/O . Of course, many programmers
use it anyway.
Direct Console I/O is unusual in another way. It’s actually two functions,
accessed with the same system call.
On input, put ff (hex) into the E-register. The function will immediately
return with a 0 in the A-register, and will continue to return 0 until some
thing is typed on the keyboard. Then, it will return the ASCII value of the
character typed, but nothing will appear on the screen. This function is
unlike both the Console Input and Read Console Buffer system calls in that
it does not wait until the user types something before it returns to the calling
program. (In this way, it’s like the INKEY$ function in some versions of
BASIC.) Thus, you must continually check to see if the A-register is zero, and
do the call again if it is.
On output, put the ASCII character you want to send to the screen into the
E-register. The function will print it, without checking to see if it is a control
character.
88
Getting in Deeper
A Short Example
Here’s a very short D D T program demonstrating how the calls are made to
both the input and output functions of Direct Console I/O . All this program
does is echo on the screen whatever is typed on the keyboard.
-a100
0100 mvi c ,6 Get keyboard character;
0102 mvi e ,ff ff indicates input.
0104 ca LI 5
0107 o ra a Is A-register = 0?
0108 jz 100 Yes, go try again.
010B mvi c ,6 Got character, so print it;
010D mov e ,a put it in E-register.
010E ca L L 5
0111 jmp 100 Go wait for next character.
Save the program as “test8.ddt” and then try it out. Notice how none of
the editing control keys has any effect. Also, the backspace doesn’t work.
And, most inconvenient of all, there is no way to stop the program since
control-c is inoperative. If you needed to use Direct Console I/O , you’d have
to build all these features into your program.
Password Program
Have you ever used an automated bank teller that required you to type in
an account number? Or a time-sharing computer that requested a password
before giving you access to the system? In both these cases, what you type in
is often not echoed to the screen. This is a security precaution. It keeps any
one who happens to look over your shoulder from learning your number or
password. Our next example is a short program that shows how the Direct
Console I/O system call might be used to implement such a function.
Type in the following program and save it as “test9.ddt:”
-a100
0100 Lxi h,200 Put buffer address in HL;
0103 push h save it on stack.
0104 mvi c ,6 Set up Direct Console I/O;
0106 mvi e ,ff specify “input.”
0108 ca L L 5
010B ora a Anything typed yet?
010C jz 0104 N ot yet.
Soul of CP/M®
01 OF pop h Yes. Restore address in HL.

0110 mov m,a Store character in buffer.
0111 i nx h Increment address.
0112 cpi 24 Was character a “$”?
0114 jn z 0103 No, go get next character.
0117 mvi c ,9 Yes. Print string in buffer;
0119 Lxi d ,2 0 0 set buffer address.
one ca L L 5
011 F rs t 7 Back to DDT.
This program lets you type in a string of characters, without echoing them
to the keyboard, just as a real “password” program would do. To terminate
the input string, you type a dollar sign ($). Then, to ensure that everything is
working the way we expect, the program prints out the complete phrase. (It
wouldn’t do this, of course, in a real password application.)
The Phantom “M ” Register
You may have noticed something new going on in this program. It is the
letter “m” in the “mov m ,a” instruction at location 0110. W hat is this? We’ve
never mentioned an “ M” register before. Well, as it turns out, there isn’t any
such register. “ M” is nothing more than a handy abbreviation for the memory
address pointed to by the HL-register. This usage is possible because the
designers of the 8080 gave the HL register the useful ability to indirectly
address a memory location. That is, other 8-bit instructions, such as MVI and
MOV, can “pretend” there is an “M ” register, but what they really do (when
we write an “m” following the instruction) is to first look at HL to get the
address it holds and then operate on the memory location pointed to by that
address, as if the memory location were a register. This is a useful concept
when we want to store a series of data items in sequential memory locations,
as we do here with the characters that are read in using the Direct Console
I/O routine. This is illustrated by the diagram shown in Fig. 3-6.
Here’s how it works. We start off by putting the address of the first mem
ory location where we want to store our series of characters—in the HL regis
ter. In this case, we put 200 into HL (line 100). Now that we’ve done this, we
know that every time we refer to the “M ” register, we’re really referring to
memory location 200 (until we change the contents of HL). So—the first time
it is executed, anyway—the “mov m,a” instruction in line 110 has the effect of
taking the character in the A-register and putting it in location 200. But we
don’t want to put all the characters in location 200—we want the second char-
90
Getting in Deeper
Before MOV M,A Is Executed:
HL-register
z: / 010D Section of memory

0203 containing program.
A-register 010E
010F
0110 -M O V M,A
77
A 0111
1
/

where constant will
be stored.
0203
0204
After MOV M,A Is Executed:
HL-register
( .............-
0203
A/ 010D Section of memory
containing program.
A-register 010E
010F
0110 ■ -M O V M,A
0111
llllllllllllllllll
llllllllllllllllll

where constant is
0203 now stored.
0204
Fig. 3-6. The phantom “ M” register.
91
Soul of CP/M®
acter to go in 201, the third in 202, and so on. We accomplish this by simply
incrementing the HL register-pair each time we put something in it. That
way, the next time we refer to “m ” in an instruction, we’ll really be talking
about location 201, or 202, or however far we’ve gotten.
The INX Instruction
INX increments a register pair in the same way that IN R incremented a

single 8-bit register. This means that it adds 1 to the 16-bit number in the
register pair. If you started with a register-pair equal to zero and just kept
incrementing, it would count all the way up to F F F F hex (65535 decimal)
before starting over again at zero.
The register pairs are HL, BC, and DE. INX works on all of them. A simi
lar instruction, DCX, decrements these register-pairs. An im portant and fre
quently annoying difference between these 16-bit increment and decrement
instructions, and the 8-bit instructions IN R and DCR, is that the 16-bit
instructions don’t set the zero fla g when the count gets to zero. T hat’s not a
problem in this program example, but it will be later on.
Before INX B Is Executed:
BC-register
/ —
BFFF
Fig. 3-7. The INX instruction.

After INX B Is Executed:
BC-register
( — ■cooo 7/ \
Examples:
inx b
inx h
Our program, after setting an initial value of 200 in HL and saving HL on

the stack, calls the Direct Console I/O routine to get the first character from
the keyboard. (HL had to be saved on the stack because this routine, natu
rally, trashes it.) We cycle around the loop from 104 to 10C, waiting tor a
nonzero value in the A-register to indicate that a character was typed. Once
we get the character in A, we do several things: we get HL back from the
92
G etting in Deeper
stack (line 10F), we store the character in the buffer (line 110), and we incre
ment the HL-register (line 111) so it will point to the next sequential location
in the buffer when we next call it.
To find out if the user has finished his message, we then check, with the
“cpi 24” instruction, to see if the character typed was a dollar sign. If not, we
jum p up to 103, save HL again, and wait for a new character. If it was a
dollar sign, we go on and print the contents of the buffer, starting at location
200, using our old friend the Print String system call. Since we required that
the message be terminated with a dollar sign on input, we know that there
will be one at the end of the buffer to end the message for Print String.
Finally, we return to DDT.
LIST OUTPUT TO PRINTER
LIST OUTPUT (PRINTER) FUNCTION 5 (dec) = 5 (hex)

REG E = ASCII character
Comments: Similar to Console Output, except character is sent to LIST

device.
This system call lets you send a character to the LIST device, which is
usually the printer, in the same way that Console O utput lets you send a
character to the console screen. Of course, there are some differences in the
way the printer operates, as compared with a video screen, that must be
taken into account.
First, the usual situation is that a printer will absorb a certain number of
characters, such as one line, without doing anything; at least, anything you can
see. The characters sent are stored in an internal buffer in the printer, until
either (1) the printer’s line length is exceeded, or (2) a carriage return or other
terminating character is sent. At this point, the printer will print the entire line
of characters. So, if your program wants to ensure that what it has sent is what
gets printed out, it must send a carriage return as the last character.
Some printers automatically supply a linefeed when they receive a car-
riage-return character, others don’t. If yours doesn’t, then you need to send
one following the linefeed, to keep the printer from overprinting the previous
line.
93
Soul of CP/M®
Second, keep in mind that some characters look different on the screen
than they do on the printer. Control characters, for example, may appear as
characters preceded by a caret (A) on the screen but, instead, cause strange
nonprinting actions to the printer, such as changing the printing pitch.
Program to Type to the Printer
This program will accept a line of input from the keyboard using the Read
Console Buffer system call and then will output the string to the printer using
List Output.
-a100
0100 mvi a , 50 Get input string. Max line length
0102 sta 01 f e into buffer.
0105 mvi c,a Read Console Buffer.
0107 Lxi d,1fe Buffer address.
010A ca L L 5
010D Lxi h , 200 Set up HL and B. HL is buffer address.
0110 Lda 01 f f Number of characters typed.
0113 mov b , a Goes in B.
0114 mvi c,5 Send character to printer.
0116 mov e,m Get character from buffer.
0117 i nx h Increment pointer.
0118 push h save H.
0119 push b save B.
011A ca L L 5 Do it!
0 1 1D pop b restore B.
011 E pop h restore H.
011 F dcr b Check if done. Decrement count.
0120 jn z 114 Not done. Go print next character.
0123 mvi c,5 Done. Print linefeed.
0125 mvi e,a
0127 ca L L 5
012A mvi c , 5 Print carriage return.
012C mvi e , d
012E ca L L 5
You can save this program as “ testlO.ddt” . A flowchart of the program is

given in Fig. 3-8.
The program uses two different registers to keep track of two different
things. The HL register-pair (16 bits) holds the address in the buffer of the
94
G etting in Deeper
Fig. 3-8. Flowchart for outputting data to the printer.
character currently being p rocessed-that is, it’s a “pointer” to the current

character in the buffer. The B-register (8 bits) holds the number of characters
remaining to be printed in the buffer.
We’ll put the actual typed characters into the buffer starting at memory
address 200 hex. As is usual when using Read Console Buffer, the first location
in the buffer (lfe hex) holds the maximum character count, which we set at 50
hex (80 decimal) to avoid getting more than one line of characters. The second
address of the buffer (Iff hex) will be filled in with the number of characters
actually typed and this quantity is put in the B-register, which then uses it as the
count when sending the characters to the printer. The typed input will be stored
95
Soul of CP/M®
in the buffer starting at 200 hex, so this is the address we put in the HL register-
pair, which is the pointer to the current character.
The program loops between 114 and 120, getting a character from the
buffer (line 116), incrementing the pointer to the next character (line 117),
sending the character (line 11A, set up in line 114), and decrementing the
count (line Ilf) to see if all the characters have been sent.
The LDA Instruction
LDA is the opposite of the STA instruction that we described earlier in

this chapter. It loads the A-register with an 8-bit value taken from the mem
ory address specified in the operand field of the instruction. This is illustrated
in Fig. 3-9.
Managing the Stack
Notice in the preceding printer program how we need to save both the HL
and the B registers on the stack to keep them from being destroyed by the
Read Console Buffer, which we call in line 11 A. The im portant thing to
notice here is that the order in which we save the registers is the opposite o f the
order in which we restore them. This is because the stack is “last in first out,”
so that the number we put on first will be “pushed down” into the second
position from the top when we put the next number on.
It’s easy to get confused when using the stack and pop things off into the
wrong registers. This is a relatively simple example, but when the stack is
used extensively in a program, it’s im portant to pay close attention to its use.
Program bugs involving the stack can cause more bizarre results than usual,
and they always seem to be particularly hard to track down.
READER INPUT
READER INPUT FUNCTION 3 (dec) = 3 (hex)
On return: REG A = ASCII character
Comments: Same as Console Input, except uses tape reader.
96
Getting in Deeper
Before LDA 2011 is Executed:
/ / 0100
Section of memory
A-register
A 0101
containing program.
A 0102
3A
/
0103 LDA 2011
11
/ 0104
20
/
A
///////////////////
///////////////////
/ 2010 Section of memory
where constant
/ 2011
is stored.
FE
/ 2012
J
After LDA 2011 is Executed:

containing program.
0101
A-register
0102
0103 LDA 2011
0104
iiiiiiiiiiiiin iii
iiiiiiiiiiiiiiini
Section of memory
2010 where constant
is stored.
2011
2012
Fig. 3-9. The LDA instruction.
97
Soul of CP/M®
This system call, and the one following, apply to devices that are no longer
found in a typical C P/M system: a paper-tape reader and a paper-tape punch.
In the old days of computing, paper tape was an important medium for storing
programs and data. Paper tape came in long rolls that were about an inch wide,
and each character was punched into the tape as a group of 7 hole-positions.
Each position in the 7-hole group could be either punched (indicating a 1) or
not punched (indicating a 0). Many tape readers and, of course, all tape-punch
devices, were mechanical and, therefore, not too reliable or fast. The introduc
tion of magnetic storage media, such as magnetic tapes and floppy disks, caused
such a dramatic change in the reliability and pleasure of using mini- and
microcomputers that it probably can’t be appreciated by anyone who has not
struggled endlessly with fiendishly tangled rolls of paper tape.
In any case, should you be unfortunate enough to be using a paper-tape
device, this system call will operate on the paper-tape reader in exactly the
same way that the Console Input operates on the console device.
PUNCH OUTPUT
PUNCH OUTPUT FUNCTION 4 (hex) = 4 (dec)

REG E = ASCII character
Comments: Same as Console Output, except uses tape punch.
As discussed previously under Reader Input, this function is usually used

for a paper-tape punch device, which are no longer found in most C P /M
systems. However, should you have occasion to use it, Punch O utput func
tions exactly the same as the Console O utput system call.
GET I/O BYTE
GET I/O BYTE FUNCTION 7 (hex) = 7 (dec)
On return: REG A = I/O Byte Value
98
Getting in Deeper
Logical and Physical I/O Devices
This system call, and the following one (Set I/O Byte), are not often used
in the operation of a typical C P /M system. However, they can be very useful
when nonstandard devices, such as a modem, are attached to the system.
W hat these calls do is make possible the assignment of different physical I/O
devices to the logical devices that the program thinks it is talking to.
What do we mean by “logical” and “physical” devices? “ Physical” simply
means the actual device itself, such as the keyboard, video screen, or printer.
Now it’s a strange and amazing fact that in CP/ M, a systems call to, say, the
keyboard (such as Console Output) doesn’t necessarily have to go to the key
board. By setting a group of four software switches, you can actually cause
the character that you sent to the keyboard (with a Console O utput call) to
end up at the printer, or you can cause what you sent to the printer to end up
on the console device. The actual device that receives the character is called
the “physical” device, whereas, the device that the program thinks it is send
ing the character to is called the “logical” device.
All this is explained in general books on C P /M (such as CP/ M® Bible, by
John Angermeyer and Mitchell Waite) in the description of the STAT func
tion. STAT can be used to do all the things the GET I/O Byte and Set I/O
Byte system calls do, but they must be done by the user from the keyboard.
W hat Get I/O BYTE and Set I/O BYTE do is let your program change the
device assignments without human intervention.
bit 7 bit 6 bit 5 bit 4 bit 3 bit 2 b it 1 bit 0
LIST PUNCH READER CONSOLE
Fig. 3-10. Breakdown of the I/O Byte.

The I/O Byte
The byte referred to as the “I/O Byte” in these system calls has a memory
location in a typical C P /M system of 0003 hex. The byte is broken up into
four fields, each of which represents a logical I/O device. It is arranged as
illustrated in Fig. 3-10.
Each of the four logical devices is assigned two bits: the console gets bits 0
and 1, the list device gets bits 6 and 7, and so on. Each of these 2-bit fields
can represent four numbers (00 = 0, 01 = 1, 10 = 2, 11 = 3). Each of the result
ing four numbers is assigned to a physical device, according to the following
list:
99
Soul of CP/M®
CONSOLE FIELD (bits 0,1)

0—Printer device (TTY:)
1 -C rt device (CRT:)
2-B atch mode: READER is CONSOLE input, LIST is CO N
SOLE output (BAT:)
3—User-defined device (UC1:)
READER FIELD (bits 2,3)

0—Teletypewriter device (TTY:)
1-H igh-speed reader device (RD R:)
2—User-defined reader device No. 1 (UR1:)
3-U ser-defined reader device No. 2 (UR2:)
PUNCH FIELD (bits 4,5)

1—High-speed punch (PU N :)
2—User-defined punch No. 1 (UP1:)
3—User-defined punch No. 2 (UP2:)
LIST FIELD (bits 6,7)

1—Crt device (CRT:)
2—Line printer device (LPT:)
3—User-defined list device (UL1:)
The 3-letter mnemonics following each device are those used in the STAT
function. N ote that many of the devices listed are no longer used in a typical
C P /M system. Usually the CONSOLE is assigned to the “console printer
device” which C P /M thinks of as the teletypewriter (TTY). Although your
console uses a crt (cathode-ray tube), this device name (CRT:) is not usually
used for the console.
How does all this look on a typical system? Bring up D DT and type -d0,f.
This will cause the contents of the first 16 bytes of memory to be displayed.
Look at the byte in location 3. It will typically have a value like 94 (hex).
Let’s decode this to see what’s happening. Write down 94 in binary, like this:
10010100
Then, divide it into groups of two bits:

100
Getting in Deeper
10 ,01 ,01,00
The first two bits, 10, show that the LIST function has been assigned to the
line-printer device, as can be seen using the preceding list. The next two bits,
01, show that the PUNCH device has been assigned to the high-speed punch.
The next two bits, 01, show that the READER device has been assigned to
the high-speed reader, and the last two bits, 00, show that the CONSOLE
device has been assigned to the console printer device.
That’s how a human being can read the IOBYTE. How about a computer
program? T hat’s where the Get I/O Byte system call comes in. Try typing
this program in using DDT:
-a100
0100 mvi c,7 Call Get I/O Byte.
0102 ca ll 5
0105 mvi b,4 Set count of 4 in B-register.
0107 r Lc Rotate A-register.
0108 r Lc 2 bits left.
0109 mov c,a Save result in C-register.
010A ani 3 Mask off all but lower 2 bits.
010C adi 30 Add ASCII value of 0.
010E mov e ,a Store result in E-register for printing.
01 OF push b Save BC register.
0110 mvi c,2 Call Console Out.
0112 ca L I 5
0115 pop b Get BC back.
0116 mov a,c Put number back in A-register.
0117 dcr b Done 4 digits yet?
0118 jnz 107 No.
011B rst 7 Yes, back to DDT.
Save the program as “ test 11 .ddt”. W hat it does is

tents of the IOBYTE. The first two instructions are the Get I/O Byte system
call, which returns with the IOBYTE in the A-register. The problem then is
how to take each of the four 2-bit numbers and display them separately on
the screen as ASCII characters. We do this by rotating the contents of the A-
register 2 bits to the left, printing the two bits that are now on the right-hand
end of the IOBYTE (converting them to ASCII first), then rotating the con
tents again and printing again; doing this four times. To do all this, we need
to introduce three new instructions.
101
Soul of CP/M®
The RLC (Rotate Left) Instruction
There are 8 bits in the A-register. Think of them as being 8 chairs placed in
a line. Two kinds of people can sit in the chairs: zeros and ones. The chairs
are numbered from 7 on the left down to 0 on the right. When the RLC
instruction is executed, everyone stands up and moves over to the chair on
his left. The person on the leftmost chair (number 7) has no chair to his left,
so he runs all the way around to the right and sits on the rightmost chair
(number 0). This is what “rotate” means in computer instructions; the bits
rotate around the A-register.
Before E xecuting RLC:
carry flag 5 4 3 2 1 0
1 0 0 0 1 0 1
z
A\
\J VJ’VJ \J \jU’vJ
(The arrow s show where the b its w ill go.)
A fte r E xecuting RLC:
carry flag
/ 7i / / / / / / / A
0 0 0 1 0 1 1 1
> >
Fig. 3-11. The RLC instruction.
Another detail, although we won’t be concerned with it in this example, is

that the value of the bit in position 7 is not only copied into position 0, but
also into a special 1-byte register called the “carry flag.” This can be useful in
many circumstances, such as when you want to rotate 16-bit numbers. Later,
there will be an example of that.
The ANI Instruction
T his instruction m ea n s “AND Im m ed ia te.” Im m ed iate m ean s that the value

to b e ANDed w ith the A -register is part o f the in stru ction (rather than b ein g
stored so m ep la ce else in m em ory). T he lo g ica l AND op eration is som ew h at
like OR, excep t that w h en you AND tw o num bers together, both b its in the
co rresp on d in g lo c a tio n s in the op eran d s m u st b e set in order for the result to
b e set, as the fo llo w in g listin g show s:
102
Getting in Deeper
0 A ND 0 = 0
0 A ND 1 = 0
1 A ND 0 = 0
1 A ND 1 = 1
The following is an example of two 8-bit numbers being ANDed together:
0 1 1 0 10 0 1
10 1 1 0 0 10
0 0 10 0 0 0 0
One useful application of the A NI instruction is to “mask off” unwanted

bits in a particular byte. How does this work? When we AND a bit with 0, it
doesn’t matter whether that bit was 1 or 0, the result is always 0. So, if we
want to get rid of some bits in a particular quantity, we AND them with 0. In
the diagram of Fig. 3-12, we’ve ANDed 66 with OF. This has the effect of
masking off, or setting to zero, the left four bits of the 66.
Fig 3-12. The ANI instruction.
103
Soul of CP/M®
In our program, we want to get rid of all the bits in the A-register except
the two on the right (positions 1 and 0). So we “AND Immediate” a 3, which
is the number with the two rightmost bits set: 00000011. All the bits in the A-
register that match up with a 0 will be set to 0, and all the bits that match up
with a 1 will be preserved—that is, set to 1 if they are a 1 already, and cleared
to 0 if they are a 0.
The ADI (Add Immediate) Instruction
This instruction is similar to the preceding ANI instruction, except that the
contents of the A-register are added to the number following the instruction.
This is a simple arithmetic addition of two hexadecimal numbers. If there is a
carry (that is, if the the resulting sum is greater than FF hex, 255 decimal),
the carry flag is set. The other flags are also set. In particular, if the result of
the addition is zero, the zero flag will be set; otherwise, it will be cleared.
00FF
0100
ADD 15
0101
0102
Memory
address.
Fig. 3-13. The ADI instruction.
Examples:
adi 30
adi 7f
104
Getting in Deeper
In the preceding program example, we want a 2-bit value of 0 (00) to print

out as an ASCII “0,” a 2-bit value of 1 (01) to print out as an ASCII “ 1,” and
so on. However, the ASCII code for “0” is 30 hex ( not 0), “ 1” is 31 hex, 2 is
32 hex, and 3 is 33 hex; so we need to add 30 hex to each of our little 2-bit
numbers before printing them out. The A DI instruction does it nicely.
The program uses the B-register to hold the count of how many 2-bit num
bers remain to be printed. This starts at 4 (set in line 105) and counts down
to 0, at which point the program returns to D DT (lines 117 to 11B). The C-
register is used to keep all eight bits of the IOBYTE (rotated either two, four,
six, or eight times) as the program progresses. Since the B and C registers can
both be saved on the stack with the “push b” instruction (line 10F), we can
save both the count and the current rotated state of the I/O byte at the same
time, and, similarly, can restore them with a “pop b” in line 115. We need to
save them because the Console Out system call that we use to print out the 2-
bit numbers destroys both the B and C registers when it’s called.
Try running the program. It should give you the same value for the
IOBYTE that you found by using the “d” function in DDT.
SET I/O BYTE
SET I/O BYTE FUNCTION 8 (dec) = 8 (hex)

REG E = new I/O byte
This is a straightforward system call whose purpose is to set the IOBYTE

described in the last section to a new value. In fact, unless you have some
unusual I/O devices on your C P /M system, there’s not really too much you
can do that’s interesting by changing the values of the IOBYTE. Here’s a
little experiment you can do, however, to see if everything is working as
advertised.
Write the following program in DDT:
-a100
0100 mvi c , 8 Set I/O Byte system call.
0102 mvi e , 1 4 New IOBYTE makes LIST the Console.
0104 c a ll 5
105
Soul of CP/M®
This program simply changes the IOBYTE from the 94 (hex) that we found
in the last section to 14 (hex). W hat does this do? Hex 94 is 10010100, while
hex 14 is 00010100. Thus, we changed the leftmost two bits from 10 to 00,
which (looking back at the diagram of the IOBYTE and the list of device
assignments in the last section) means that we’ve changed the destination
device of the LIST device from the lineprinter to the “console printer device”
(TTY:). How do we know that’s what’s happened? Read on!
Turn on the printer with a control-p. Now type something. It doesn’t m at
ter what it is, it will get printed twice on the screen! Why is that? It gets sent
once because the screen is simply echoing the keyboard as it normally does.
It gets printed the second time because we’ve turned on the printer echo with
a control-p, but the characters which would normally go to the printer have
been re-routed to the console device because we put a 0 in the LIST field of
the IOBYTE, instead of a 2.
GOODBYE, NONDISK SYSTEM CALLS

We’ve now covered all 12 of the nondisk system calls. You’ve learned a lot
about how C P /M works, and even more about how to program in 8080
assembly language.
This might be a good time to review what you’ve learned so far. Go back
and look at the various example programs. Experiment a little with them,
changing a line here and a line there, to see what happens. You should feel
comfortable assemblying and running short programs with DDT, and you
should understand the operation of the 8080 instructions covered so far.
In the next chapter, we’re going to explain how the C P /M assembler ASM
works. Using ASM will save a lot of time, trouble, and agony, as compared
with typing long programs in directly using DDT. It has a lot of other great
features too, and you may find it almost too luxurious—but we figured that
you deserved a break.
106
CHAPTER 4
Using the Assembler

Until now, you’ve been writing programs using the built-in miniassembler
in DDT. This is fine for short routines, but its disadvantages begin to be
apparent on longer programs. The most obvious problem is that once the
program is written you can’t go back and insert a new instruction in the
middle. This is because each instruction is converted into machine code, and
the appropriate memory space is assigned to it as you type it in.
107
Soul of CP/M®
A true assembler such as ASM, on the other hand, doesn’t convert any of
the instructions into machine language until the entire program has been
typed in. This makes modifications to the program much easier and also per
mits the use of various other wonderful features, such as symbolic labels to
refer to memory addresses rather than hex numbers.
In this chapter, we’ll explain how an assembler works, show you how to
use the C P /M assembler ASM, and cover the use of the LOAD program,
which converts the output of ASM into a form that can be executed directly
from C P/M . We’ll start off by assemblying “TEST1” (one of the first pro
grams from Chapter 2) and then move along to a routine (“ D ECIBIN ”) that
accepts decimal numbers from the keyboard and converts them into binary
for the computer to read. This routine makes up part of our next program,
“DECIHEX,” which is used to convert decimal numbers typed in at the key
board into hex numbers on the screen. DECIHEX is a useful utility program,
as well as providing a testing ground for the use of the assembler. Finally
we’ll describe how to simplify the assemblying process through the use of the
C P /M utility, SUBMIT.
WHAT’S AN ASSEMBLER DO, ANYWAY?
The purpose of an assembler is to take instructions that are written in a

form which is more or less understandable to a human and convert them into
the binary numbers that a computer can read. When you typed “ mvi c,2” in
the DDT microassembler, for instance, D D T automatically converted this
into the two bytes OE, 02. The OE is the code for the “mvi c” part of the
instruction, and the 02 byte is the number that you want to put in register C.
Similarly, a “call 5” instruction is converted into three bytes: CD, 05, 00. The
CD is the code for “call,” and the 05, 00 is the address 0005. (As we men
tioned earlier, in 8080 machine language, the low-order or least-significant
byte precedes the high-order or most-significant byte.) You might not even
have been aware that these numbers were being generated when you used
D D T’s microassembler if you didn’t look into the TPA (where the program
was stored, at 100 hex), using the “d” command.
Let’s try that now. Bring up D D T and a simple program such as test 1.ddt:
-ddt t e s t l. d d t
Then list it to see how it looks in symbolic form:

Using the Assembler
-1 1 0 0
0100 MVI C,02
0102 MVI E,48
0104 CALL 0005
0107 MVI C,02
0109 MVI E,49
01 OB CALL 0005
01OE JMP 0100
Now, dump the contents of the memory locations occupied by the pro
gram, using “d” :
- d 1 0 0 , 1 10
— mvi c,2”
------- “mvi c,2”
I------“mvi e,48” | ----- “call 5
j—.“call 5”
0100 0E 02 "1E 48' 'CD 05 00 '0E 02' 1E 49 CD 05 00 C3 00 01

0110 01 V
(from next lin e)------1
Notice how the mvi instructions have different codes depending on what
register they’re addressing: 0E for the C-register and IE for the E-register. In
general, instructions that include an 8-bit byte (like the 02 in “mvi c,2”) are
two-bytes long, and those that include a 16-bit address, like the “call” and
“jm p ” instructions, are three-bytes long.
The hexadecimal numbers revealed by the “d” function are representations
of the binary numbers that the computer actually operates on when it is exe
cuting a program. The microassembler in D D T has taken symbolic instruc
tions, such as “mvi c,2” , and converted them into these binary numbers
(which DDT translates into hexadecimal, so we can read them more easily).
This is essentially what all assemblers do, but true assemblers do it much
more elegantly than the D D T microassembler.
WHAT ASM DOES

In DDT, you typed symbolic instructions using the “a” function, and
D D T assembled them one at a time as you typed them in. In ASM, the pro-
109
Soul of CP/M®
cess is quite different and is somewhat more involved. You first type your
symbolic input into a text file, using a word-processing program, ju st as if
you were writing a letter. This text file, which is called an ASM file (and must
have a file extention of ASM), is then stored on the disk, like any other text
file. You then call up the assembler program ASM, which performs the actual
assembly process: that is, figuring out what binary numbers should stand for
each symbolic instruction. ASM generates two files: (1) the HEX file, which
consists of the binary numbers, but in a special format which is not yet
directly executable, and (2) the PRN (for “print”) file, which is the same as
the original ASM file, but with the hexadecimal addresses and instructions
included alongside the original symbolic instructions so that you can see how
they all fit together.
Finally, the LOAD program is used on the HEX file to generate a COM
file, which can be executed directly by C P/M .
Alternatively, the HEX file can be executed, inspected, and modified
directly from DDT. This is useful if the program has a bug in it (a topic we’ll
discuss later), or if access to the 8080 registers is necessary while the program
is being used, as is the case in the “ D ECIBIN ” routine that will be described
later in this chapter.
The diagram in Fig. 4-1 shows the relationship of these files and programs.
Using the Word Processor
As we indicated in the introduction, we assume that your system includes

a word processor or text-editor program. ED is included as a basic part of
all C P /M systems, and most people who use C P /M also run one of the
popular word-processing programs, such as W ordStar, Spellbinder, Select,
or Magic W and. (For a complete description and comparison of these and
other word-processing programs, see Word Processing Primer by Mitchell
Waite and Julie Area.) Since there are so many different word-processing
programs, we will not attem pt here to describe how they work. We will
simply assume that you have one running on your system and that you
know how to use it.
Our first project will be to use ASM to assemble the program that we
have just investigated using DDT. To begin assembling the program, use
your word processor to open a file which has a file extension of ASM and
the file name TEST1. (Some word processors have a special “ nondocu
m ent” mode for writing program listings: it suppresses page breaks and
word wrap-around. If your word processor has such a feature, now is the
time to turn it on.)
110
Using the Assembler
ASM File
Symbolic Instructions
mvi c,2
mvi e,48
call 5
etc.
ASM Program
PRN File HEX File

Instructions with Hex numbers in special format.
hex equivalents.
0100 0E02 mvi c,2

0102 1E48 mvi e,48
0107 CD0500 call 5
LOAD Program DDT Program
COM File
Binary numbers,
directly executable.
Fig. 4-1. Assemblying using ASM.
Format Differences Between D D T and ASM
There are several differences in the way that you type in programs using
DDT and the way you type them using ASM.
1. Programs in ASM must start with an O RG (for “O RiG in”) directive to

tell ASM where the program is to go in memory. (D D T assumed that
the program would go at 100 hex.) We’ll explain more about “direc
tives” later in the chapter. Since the LOAD program (we’ll get to that
later too) requires programs to begin at 100 hex, the O RG directive
111
Soul of CP/M®
must be followed by lOOh, as shown in the first line of the following

program.
2. ASM assumes that numbers are in decimal unless it is told otherwise.
Thus, hex numbers must be followed by an “h.” (D D T assumed num
bers were in hex.)
3. The fields of the instruction are separated from each other by tabs.
(D D T used spaces.) Also, there is a new field to the left of the opera
tion field for labels.
4. Hexadecimal numbers which start with a letter must be preceded by a
zero (0), or ASM will think they are symbolic names rather than num
bers. This is very easy to forget, so remember it! D on’t write ffh, write
Offh.
Let’s try typing in a program, keeping these rules in mind:
org 100h
mvi c,2
mvi e ,48h
ca L L 5
mvi c,2
mvi e,49h
ca L L 5
jmp start
That’s not so different from the D D T version, is it? We’ve started off with
the ORG statement, and we’ve put an “h” after all the hex numbers (except
those that are the same in both hex and decimal, like 2 and 5). You’ve proba
bly noticed one other difference: the word “ start” that precedes the first mvi
c,2 instruction and, also, follows the jm p instruction. W hat’s this all about?
Symbolic Labels
One of the really nice things about using an assembler is that it relieves you
of the responsibility of figuring out what memory address a particular
instruction or data item occupies. In DDT, it was necessary, when we wrote
the jm p instruction at the end of the program, to look up at the place at the
beginning of the program where we wanted to jum p to, and then write that
same number following the “jm p ” ; in this case, “jm p 100.” Of course, that’s
not a problem in this particular example, but in longer programs, especially
those where you want to jum p down (that is to an instruction you haven’t yet
112
Using the Assembler
written), the use of symbolic labels is invaluable. Also, as you will see in the
next few programs, the labels given to subroutines can visually help to break
the program into separate and more understandable sections.
You can use a label to refer to any particular address. A label can be any
group of letters and numbers, but it must start with a letter, and it should not
be longer than 8 characters or it will cause formatting problems when you try
to type it in, and when ASM generates the PRN file. (Although, actually,
ASM can accept up to 16 characters.) This label is placed in the “label field”
in the program: that is, the first column of the listing. The instruction itself
(as we learned earlier) then goes in the next column, which is called the
“operation field.” The third column is called the “operand field” since it con
tains the thing that the instruction is going to operate on- th e operand. This
operand can contain either register names and constants, as is the case with
the mvi instructions, or it can be a symbolic label, as in the case of the jm p
instruction. There is another column, the “comment” field, which we’ll
explore later. The fields are separated from each other either by tabs or by
any number of spaces, but using the tab key makes for neater listings.
I tabel I operation I operand I comment

I I I I
Idecibin llx i lh ,0 l ; s e t HL t o ze ro
In using symbolic labels, writing “jm p start” is equivalent to writing “jm p

100,” providing that we have already defined “start” as representing the
address 100 by putting it in the label field at the appropriate place.
Assemblying the Program
Once you’ve written the program and checked it over for errors, save it on
your disk using the appropriate command from your word-processor pro
gram. D on’t forget that it must have an ASM file extension. If it doesn’t, the
ASM program won’t function correctly.
Now, return to C P /M and call up ASM, followed by the name of the pro
gram you want to assemble. But don’t type any file extension following the
name o f your program. Just type the program name and a carriage return—
don’t even type a period. This is because ASM interprets the letters, which
appear in the place usually occupied by the file extension, in an entirely dif
ferent way. For the time being, we won’t worry about this, so leave the letters
out.
113
Soul of CP/M®
A>asm t e s t l Assumes “testl.asm” exists.

CP/M ASSEMBLER- VER 2 . 0 Sign-on message.
0111 Address following program.
000H USE FACTOR %of symbol table used.
END OF ASSEMBLY
ASM introduces itself with a sign-on message that gives its version
number, and then proceeds to assemble the program. When it is done, it
prints the address following the last address used in the program; 0111 in this
case. The “USE FACTOR” has to do with the am ount of space used by
symbolic labels. There is only a certain am ount of space for storing these
labels in ASM; if you use too many labels, you’re in trouble. The USE FAC
TOR tells you the percentage of available space used in your program. The
programs used in this book seldom have a USE FACTOR of more than 3%.
In the present case, with only one label in the program (“ start”), the USE
FACTOR doesn’t even get up to 1%.
If you have made any errors in typing your program, ASM will print them
out during the assembly process. The error messages are single letters incor
porated into the offending program line and can be rather obscure; usually, a
glance at the line will show you where you went wrong.
Finally ASM tells you END O F ASSEMBLY, and returns you to C P/M .
If you now use “dir”, you will see that two new files have been generated:
TEST1.HEX and TEST1.PRN. To see what ASM has been up to, display the
PRN file:
A>type t e s t l . p r n
0100 org 100h

0100 0E02 start mvi c,2
0102 1E48 mvi e,48h
0104 CD0500 ca L L 5
0107 0E02 mvi c,2
0109 1E49 mvi e, 49 h
010B CD0500 ca ll 5
010E C30001 jmp start
You’ve got to admit that’s pretty slick. Everything is all neatly printed out,
you can see at a glance what hex values go with what symbolic instructions,
and the program has even figured out that “jm p start” means “jm p 100.”
About the only inconvenience is having to remember to reverse the order of
114
Using the Assembler
the address bytes; thus, at line 104, the CD0500 means “call 0005,” not “call
0500.”
Using the LOAD Program
You can’t actually execute (run) the HEX file from C P/M : it’s not in quite
the right format. You’ll need to put the program into the correct format for
execution, using the LOAD program. To do this, simply type “load” followed
by the name of the program, againwithout a file extension. LOAD assumes
that it will be operating on a file with an extension of HEX, so typing the
extension can cause trouble. LOAD also assumes it will be operating on a
program that starts at 100 hex, so don’t forget the “org lOOh” directive at the
start of your program.
A>load t e s t l Assumes testl.hex exists.

FIRST ADDRESS 0100 M ust start at 100 hex.
LAST ADDRESS 0110
BYTES READ 0011
RECORDS WRITTEN 01 Number of 128-byte records.
The messages generated by LOAD are largely self-explanatory. When

LOAD returns you to C P/M , use D IR to see what’s happened. You’ll find a
new file has been created: “TEST1.COM” . This file can be directly executed
from C P/M , so type:
A> t e s t l (N o extension necessary for COM files)
The program will start and the screen will fill up with the word “H I”, just
as it did under DDT. Another pat on the back is in order. You’ve just assem
bled and executed your first program using ASM. You are now a real
programmer! All that stands between you and fame and fortune is a little
more practice, some of which we’re about to give you.
Source Code and Object Code
Some nomenclature might be in order here. The ASM file that you type in
is often called the “source file.” The COM file that you actually execute is
called the “object file.” Individual lines of the source file are called “source
code,” and individual lines of the object file are called “object code.” These
terms won’t make you a better programmer, but they’ll make you sound like a
115
Soul of CP/M®
real pro if you drop them into your conversation from time to time. (As in,
“A head crash trashed my object file, so I had to reassemble.”)
THE “DECIBIN” ROUTINE—READS DECIMAL FROM

KEYBOARD
The routine that we’re about to describe takes a decimal number that you
type in at the keyboard and converts it into binary form, but leaves it in the
HL-register where other routines (which we will write later) can have access
to it. In order to verify that the correct binary number has indeed turned up
in the HL-register at the end of the program, we’re going to execute the pro
gram in DDT. This will give us a chance to use the “x” function of DDT,
which permits us to examine the contents of any of the 8080 registers.
Decimal to Binary Conversion
Before we describe how our DECIBIN routine works, you should make
sure that you understand the distinction between binary and hexadecimal
numbers. If necessary, read Appendix A. Essentially, binary is the way that
the computer stores numbers, while hexadecimal is a convenient way for
human beings to talk about binary numbers. A computer program can take
the binary numbers stored in the computer and print them out on the screen
in hexadecimal notation. (It could also print them out in binary notation, but
that wouldn’t be so easy for a human to read.)
Frequently, when we talk about numbers in the computer, the distinction
between binary and hexadecimal becomes a little fuzzy. The number in the
computer is in binary, but when we print it out so that we can see it, as we
might do with DDT, we’ll look at it as a hexadecimal number. It’s really
always a binary number, but when it reveals itself to us on our computer
screen, we see it as hexadecimal.
The DECIBIN routine that we’re about to discuss reads in a decimal
number from the keyboard and changes it to a binary number and stores it in
the HL-register. At least, it’s a binary number when it’s safely in the com
puter. If we wanted to see what the number was, we would print out the
contents of the HL-register using DDT, and the number will appear in hex
adecimal form.
The program uses a different strategy to convert from decimal to binary
than a human might. (For a human approach to decimal-to-binary conver
sion, see Appendix A on Hexadecimal Notation.) Here’s how the program
116
Using the Assembler
does it. It uses the HL-register to store the binary number. At the beginning
of the program, it sets HL to 0. Then, each time the user types in a decimal
digit, the program performs the following steps:
1. It converts the new digit from decimal to binary.

2. It multiplies the old number in HL by 10 (decimal).
3. It adds the new digit to the old value in HL.
Thus, if the user types “432,” the program first sees the 4, and converts it
to binary (which we’ll refer to as 4 hex). The old value in HL was 0, so when
it multiplies this by 10 it’s still 0. Then, when it adds the new digit, the result
is 4 hex. Next, the user types the 3. The program converts this to 3 hex,
multiplies the old 4 hex by 10 decimal (which makes it 28 hex), and adds the
3; thus, obtaining 2B hex. If the user at this point typed a return, signaling
that he was finished typing in the number, the correct binary translation of
43 decimal would be in the HL-register: 2B hex. However, the user now types
a 2, little realizing how hard he’s making the program work.
The program converts the 2 to 2 hex and, then, proceeds to multiply the
old 2B hex by 10 decimal, which makes it 1AE hex. (2B hex is 43 decimal,
times 10 is 430 decimal, which is 1AE hex.) Adding the 2to 1AEmakes it
1B0 hex, and that’s what remains in the HL-register if the user now types a
return. Whew! All that trouble just to go from decimal to hex notation.
H ex number in
HL-register
H L
0 0 0 0
--------------- User types “4” , program multiplies 0 by 10
0 0 0 0
- ------------and adds the 4.
0 0 0 4
---------------- User types “3”, program multiplies 4 by 10
0 0 2 8
-------------- and adds the 3.
0 0 2 B
-------------- User types “2”,program multiplies 2B by 10
0 1 A E
-*------------- and adds the 2.
0 1 B 0
-------------User types “return”, 1B0 hex is 432decimal.
Soul of CP/M®
Why do it this way, rather than dividing by 4096, then by 256, and then by
16, as shown in Appendix A? Because it’s easier for the computer to multiply
by 10 than it is to divide by all those other numbers. Next question: how does
the computer multiply by 10 when there are no multiplication instructions in
the 8080? Well, the computer can easily double a number simply by adding it
to itself.
Can you figure out how to multiply a quantity by 10 simply by using the
doubling operation? Here’s how the program does it. It takes the original
number in HL and copies it into the DE-register. Then it adds HL to itself,
which doubles the number. If, for example, we started with 1, we now have 2.
The result is in the HL-register. It adds HL to HL once more, which again
doubles the number giving us a 4 in HL, with a 1 still left in the DE-register.
It adds DE to HL which gives a 5, and, finally, it adds HL to HL again which
doubles the result, giving us 10. Clever, no?
Decibin Routine Listing
Listing 4-1 shows the DECIBIN routine. We have used the PRN file so
that it will be easy to refer to the particular program lines by their memory
addresses.
You’ll notice that the program is liberally sprinkled with comments. This is
made possible by the semicolon (;). Anything following a semicolon is a com
ment and is ignored by ASM (in the sense that it won’t try to turn it into
binary instructions). The semicolon can occur any place in a program line,
but the usual place to put it is at the beginning of a line (when you want the
entire line to be a comment) or at the beginning of the comment field (the
one on the right). It’s always a good idea when you write a program to use
even more comments than may seem necessary, since a program listing is
never as clear when you look at it some time after you’ve written it as it is
when you’re writing it. And, in assembly language, there is no penalty for
comments, as there is in interpreted languages such as BASIC (where com
ments occupy memory space when the program is running and, also, slow
down execution speed). In assembly language, the comments exist only in the
ASM and PRN files—they disappear completely when the program is ren
dered down into binary in the HEX and COM files.
Something else to notice about the listing is that we have added an “end”
statement to the end of the program. Although the ASM assembler does not
require this statement, many other assemblers do and it is good practice to
include it. The “end” statement has another use in ASM and that is to specify
where a program will start; that is, what instruction will be executed first.
118
Using the Assembler
Listing 4-1. The DECIBIN Subroutine

***************************************************
DECI BIN-reads d e c i m a l number f rom k e y b o a r d ,
converts to b in a ry in H L -re g is te r
0100 org 100h
c a l l i n g p r o g r a m - t o c a l l r o u t i n e and r e t u r n t o DDT
0100 CD0401 ca 11 d e c i b i n ; c a 11 r o u t i ne
0103 FF rst 7 ; b a c k t o DDT
f
; d e c ib in subroutine
/
0104 210000 d e c i b i n l x i h,0 ; s e t h i to 0
0107 E5 newdig push h ; s a v e h i (Con I n p u t uses i t )
0108 0E01 mvi c,1 ;g e t character
01OA CD0500 ca 11 5
01 OD E1 pop h ; r e s t o r e hi
01OE D630 sui 30h ; c o n v e r t f ro m ASCII t o b i n a r y
0110 F8 rm ; r e t u r n i f i t was < 0
0111 FEOA cpi 10d ;is i t >9 ?
0113 FO rp ; i f so, r e t u r n
W
; m u l t i p l y contents of h i by 10 ( d e c ) , t hen add new d i g i t
F
0114 E5 push h ; p u t h i i n de
0115 D1 pop d
0116 29 dad h ; a dd h i t o h i ( d o u b l e i t )
0117 29 dad h ; d o u b l e i t agai n
0118 19 dad d ; a dd de ( o r i g i n a l number) t o h i
0119 29 dad h ;double r e s u lt
011A 16 mvi d,0 ;zero in d
011B 5F mov e , a ;new d i g i t i n e
011C 19 dad d ; a dd d i g i t t o number
; r e s u l t i s now i n h i
/
01 1D C30701 jmp newdig ;go look f o r next d i g i t
0120 end
119
Soul of CP/M®
(Note that this is not the same as the first instruction in the program, nor
where the program starts in memory.)
If, for example, the last statement in your program is
end 100h
then, the first instruction to be executed will be at 100 hex. (This information
is included by ASM in the HEX file.) This is useful if you have a program
that you want to start executing in the middle. Only HEX files will be given
an arbitrary address this way; COM files are assumed to start at 100 hex.
Subroutines
We have used the “call” instruction many times before when executing a
system call to BDOS (“call 5”). As we pointed out, “call” is like a “GOSUB”
in BASIC. It can be used to call any sort of subroutine, not just BDOS. A
subroutine is simply a section of code that performs some function, that has a
beginning (which is the address one uses to “call” the subroutine), and which
ends with a “ret” instruction (which returns control to the calling program).
If you’re hazy on what CALL does, you might want to review the description
of it at the beginning of Chapter 2.
In our DECIBIN routine, note that lines 100 and 103 are actually the
“program.” All these lines do is call the DECIBIN subroutine (which starts
at 104) and, then, return to D D T with a “rst 7” instruction. Why make
DECIBIN a subroutine? Because later, we’re going to use DECIBIN in a
larger program where it will need to operate along with other subroutines
and, also, because we can simplify the coding of the program if we can use
instructions such as RM and RP, instead of RST 7.
The RM and RP Instructions, and the Sign Flag
The RM instruction means “return on minus,” while RP means “return on

plus.” They are both very much like the RET instruction, except that they
will only cause the return to the calling program if certain conditions are met.
These conditions have to do with the state of something called the “sign
flag.” You’ve already learned about the zero flag, which is set if the result of
an arithmetic operation or a comparison turns out to be zero. The sign flag is
similar, but it is set to “m ” for minus or “p” for plus depending on the result
of an arithmetic operation. Thus, if you subtract 5 from 3, the sign flag will
be set to minus, but if you subtract 5 from 10, it will be set to plus.
120
Using the Assembler
The RP instruction will cause a return (the same as a ret instruction) if the
result of a preceding arithmetic operation has set the sign flag to plus. If the
sign flag is minus and this instruction is executed, control will simply con
tinue on to the next instruction after the RP. The RM instruction will cause a
return if the sign flag is minus; if it is plus, control will go on to the following
instruction.
The RP instruction functions in the same way, except that it causes a
return to the calling program if the sign flag is set to plus.
Examples:
rm
rp
The SUI Instruction
This instruction is similar to the A DI instruction covered before, except

that the number included in the instruction is subtracted from the contents of
The CALL instruction

transfers control to
the subroutine.
MAIN PROGRAM SUBROUTINE
0200
0100
/ /
0201
0101
0202
0102 CD
CALL 200 —
/ 0203
0103 00
0204
0104 02
0205
0105
0206
0106 RM F8
0207
0107
The RM instruction transfers control back to the main program,

jf the sign flag is set to minus. If the sign flag is not set to
minus, control goes on to the next instruction, at 207.
Fig. 4-2. The RM instruction.
121
Soul of CP/M®
the A-register, rather than being added. Thus, “sui 2” means “subtract 2 from
the contents of the A-register.” This instruction, like other 8-bit arithmetic
instructions, sets the zero flag and, also, the sign flag.
Examples:
sui 30
sui I f
In the DECIBIN routine, the first half of the program, from locations 104
to 113, is concerned with figuring out if the character that the user has typed
in is a decimal digit or not. If it is, it’s converted to binary. If n o t-th a t is, if
the user types any character other than a decimal digit—the subroutine is
terminated and control returns to line 103 and, thus, back to DDT.
Let’s look at this in detail. The lxi h,0 instruction clears the HL register,
which we need to do at the beginning of the program to get ready to add the
digits to it. Then we save HL with a “pop h” instruction, since the Console In
system call, as we’ve learned before, trashes all the registers and we need to
remember the contents of HL. We call the Console In routine in lines 108
and 10A to get the character from the keyboard and, then, we restore HL in
10D.
Fig. 4-3. The SUI instruction.

122
Using the Assembler
Now comes the interesting part. We have the character in the A-register. Is
it a decimal digit? To find out, and at the same time to convert it from ASCII
to binary, we subtract 30 hex in line 10E. (Recall that 30 hex = “0” in
ASCII, 31 hex = “ 1,” and so on up to 39 hex = “9.”) If, when we subtract 30
hex, the result is negative, then we know that the character typed in must
have had an ASCII value less than 30 and, therefore, it could not have been a
decimal digit. If the result is positive, then it may be a decimal number, pro
vided it isn’t too big. Since we’ve changed it to a binary number, we now
need to see if it is greater than 9, so we do a “cpi lOd” which performs a
“phantom ” subtraction of 10 decimal from the contents of the A-register,
and sets the flags accordingly. If the result is positive (or 0, which is consid
ered to be positive by the sign flag), then it must have been greater than 9,
and is therefore not a decimal digit. The “rp” instruction will, therefore,
cause a return to 103 and back to DDT.
The DAD Instruction
The DAD instruction adds the contents of a register-pair to the contents of

the HL-register.
Fig. 4-4. Flowchart of DECIBIN subroutine.
123
Soul of CP/M®
There are not nearly so many arithmetic instructions for 16-bit quantities
in the 8080 as there are for 8-bit quantities. In fact, except for incrementing
and decrementing, which are rather limited arithmetic operations, DAD is
the only one! It was probably included in the 8080 instruction set to provide
a way to calculate addresses but it is, of course, useful for other 16-bit quanti
ties as well. Any of the 16-bit register-pairs—BC, DE, or H L —can be added to
the contents of the HL register-pair. The result is always left in HL.
As in other register-pair instructions, only the first letter of the register-
pair name is used in the operand field. Thus, “dad d” means “add the con
tents of the DE register-pair to the contents of H L” ; “dad h” means “add the
contents of HL to itself.”
Note that DAD does not set either the zero fla g or the sign flag. It does,
however, set the carry flag.
Examples:
dad d
dad b
dad h
The second part of the subroutine, from 114 to 11C, is concerned with
multiplying the contents of the HL-register by 10 and then (line 11C) adding
the new digit obtained in the first part of the program. As described earlier,
the multiplication by 10 is accomplished by adding the contents HL to itself
Before DAD B is executed:
HL- register B-register
z :
02F1
BC03
f a
BC 03
0 2 F 1
B E F4 Result goes back into HL.
After DAD B is executed:
HL- register B-register
z :
BEF4 02F1
Fig. 4-5. The DAD instruction.
124
Using the Assembler
twice (lines 116 and 117), then (in line 118) adding the original number
(stored for that purpose in the DE-register in lines 114 and 115), and, finally,
adding HL to itself again in line 119.
Notice, in lines 114 and 115, how easy it is to copy the 16-bit number from
HL into DE. We simply do a PUSH H to write the number from HL into the
stack and, then, a POP D to read it back into the DE-register. As long as we
make sure to follow a PUSH with a POP, the stack is left unchanged.
The new digit is then added to the result in HL by placing it in the DE
register-pair and adding DE to H L in line 11C. Notice how the D-register is
first cleared and then the new digit is transferred from the A-register to the
E-register (lines 11A and 11B), since it takes two 8-bit transfers to fill up a
16-bit register. After this, we go back to get another character with the “jm p
newdig” in line 11D.
Assembling and Executing the DECIBIN Routine
Type the program using your word-processing program, assign it the name
“decibin.asm”, and then assemble it with ASM. Look at the resulting PRN
file. It should look ju st like the one just shown. If ASM tells you there are
errors, then you’ve probably made a typo somewhere. Fix it up until you
have an error-free assembly.
Since we need to look at the HL register-pair after we execute this routine
to see if it has done its job, we’ll run the program using DDT. D D T (unlike
C P/M ) can load HEX files directly, so we’ll use the HEX file version of our
program. When you start the program, it will just sit there waiting for you to
type a decimal number. When you’ve finished typing the number and hit
return, it will return to D D T and print the asterisk and the ending address.
When it does this, D D T will overprint your original number, but that’s all
right; the program has already read it.
Now you want to examine the contents of the HL-register, so you type “x”
for eXamine, followed by “h” for the HL-register, and return. D D T will print
out the contents of HL, and then wait for you to type a number to enter into
HL; but that’s not necessary here, so hit return to get back to DDT.
A>ddt d e c i b i n . h e x
-g100 Start the program.
4096 Type decimal number (then return).
*0103 (Actually prints over above line.)
-x h Type this to look at HL.
H=1000 D D T prints out contents (in hex).
125
Soul of CP/M®
Since 1000 hex is the equivalent of 4096 decimal, you know the program is
working correctly. You can try it with other decimal numbers.
-g 1 00
10 Decimal number.
*0103
-xh
H=000A Hex equivalent.
-g100
32767 Decimal number.
*103
-xh
H=7FFF Hex equivalent.
And so forth. Notice that you can’t input a number greater than 65535,
because that’s the largest number that can be represented by 16 bits (four hex
digits).
DECIHEX PROGRAM-CONVERTS DECIMAL TO HEX, ON

SCREEN
Hold on to your hats. For the first time, we’re going to write a program
that is actually useful! By adding a routine which prints a hex number on the
screen to the DECIBIN routine already described, we’re going to create a
program that will convert a decimal number that you type in, to a hex
number, right before your very eyes! The program will be a COM file so you
can run it directly from C P/M , thus amazing your friends and teaching you
the hexadecimal numbering system at the same time. Fig. 4-6 shows how the
routines fit together.
BINIHEX—BINARY TO DECIMAL CONVERSION ROUTINE
Let’s talk about the new subroutine we’re going to add, which prints a
binary number out on the screen. We’ll call it BINIHEX. It turns out that it’s
surprisingly difficult to convert a four-digit hex number (really a 16-bit
binary number) into four individual ASCII digits. This is because two of the
digits are in one register (H) and two are in another (L), and two are on the
126
Using the Assembler
left side of their respective registers while two are on the right. We’ll make the
project somewhat simpler by always printing four digits, even if they are
leading zeros. Fig. 4-7 shows how it will look.
Digit 1, the most-significant digit, will be printed first, and so on, down to
digit 4. To print the digits on the left-hand sides of the registers (1 and 3), we
will have to shift them over to the right-hand side of the A-register so that
they can have 30 (hex) added to them to make them into an ASCII code.
(The digits on the right-hand sides, 2 and 4, don’t need to be shifted.)
Another problem is that the hex digits, A to F, need to be converted to
ASCII in a slightly different way than the digits 0 to 9. This is because the
letters A, B, C, etc., don’t immediately follow the numbers 7, 8, 9 in the
ASCII coding system. (An unfortunate situation that results from the fact
DECIHEX Program
DECIBIN Routine
Converts decimal
from keyboard
to binary in HL.
BINIHEX Routine
Converts binary in
HL to hexadecimal
on screen.
^ R etu rn to C P /M ^
Fig. 4-6. The DECIHEX program .
H-register L-register
digit 1 digit 2 digit 3 digit 4

Bit positions 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
Fig. 4-7. BINIHEX subroutine.
127
Soul of CP/M®
that ASCII was invented before hexadecimal notation became popular.) List
ing 4-2 shows the BINIHEX subroutine.
Listing 4-2. The BINIHEX Subroutine

; b i n i h e x - s u b r o u t i n e t o p r i n t b i n a r y number i n
: h i o u t on s c re e n i n hex
/
0128 7C b i n i hex mov a , h ;p u t h in a ( f i r s t d i g i t )
0129 CD3901 c a l L p r i nt1 ; p r i n t L e f t - h a n d d i g i t
012C 7C mov a ,h ; p u t h i n a (se co nd d i g i t )
012D CD3D01 ca 11 p r i n t2 ; p r i n t r i g h t - h a n d d i g i t
0130 7D mov a , I ;p u t L in a ( t h i r d d i g i t )
0131 CD3901 ca L L p r i nt1 ; p r i n t L e f t - h a n d d i g i t
0134 7D mov a , L ;p u t L in a (f o u r th d i g i t )
0135 CD3D01 ca 11 p r i n t2 ; p r i n t r i g h t - h a n d d i g i t
0138 C9 ret ; e x i t b i n i hex
r
; c o n v e r t t o ASCII and p r i n t
w
0139 07070707 p r i nt1 r l c ! r L c ! r l ( :! rLc ;move h i g h 4 b i t s t o
013D E60F p rin t2 ani Of h ; g e t r i d of high 4 b i t s
013F C630 adi 30h ; ch an ge hex t o ASCII
0141 FE3A cpi 3ah ; i f more t ha n 9
0143 FA4801 jm n o t b i g ; ( i t 1s n o t )
0146 C607 adi 7h ; t he n add b i a s (10=A, e t c )
0148 CD4C01 notbig ca I L p cha r ;p rin t d ig it
014B C9 ret
f
; s u b r o u t i n e t o p r i n t c h a r i n a - r e g o u t on s cr ee n
r
014C E5 pchar push h ; s a v e hL ( c o n o u t uses i t )
014D 5F mov e , a ; p r i n t hex d i g i t
014E 0E02 mvi c,2
0150 CD0500 ca ll 5
0153 E1 pop h ; g e t hL back
0154 C9 ret
/■
0155 end
Notice first, that this is a subroutine, not an executable program. That’s

why the memory locations don’t start at 100. W hat we’ve done is simply
128
Using the Assembler
showing this subroutine by itself for clarity, even though it forms part of a
larger program (as you can see by looking ahead a few pages).
BINIHEX consists of three parts. PCHAR is a subroutine whose only
function is to print a character on the screen. It is entered with the character
in the A-register, and before it calls the Console Out routine (lines 14E and
150), it saves the HL-register because this is where the 16-bit binary number
that we’re going to print out is stored.
PR IN T 1 and PRINT2 are two different entry points for the subroutine
that prints out, in ASCII, the 4-bit hexadecimal digit that is in the A-register
when the routine is entered. If you want to print the hex digit on the left side
of the A-register, you call PRINT1; if you want to print the hex digit on the
right, you call PRINT2. This is because entering at PR IN T 1 causes four
additional instructions to be executed. The instructions are written in a some
what unusual way.
The Exclamation Point (!)
If you want to write a number of instructions on the same line, rather than
on separate lines as we have done so far, all you need to do is separate the
instructions by exclamation points. This is useful when a group of similar
instructions that perform the same task can be grouped together. In this case,
we need to rotate the A-register 4 bits to the left so that the leftmost 4 bits
will end up on the right. Since each RLC instruction rotates the contents of
the A-register 1 bit, we’ll do four instructions to move it the required 4 bits,
and we’ll separate the instructions with exclamation points for clarity. (Of
course, we could also have written each RLC instruction on a separate line—
the assembled binary program would have been ju st the same.)
So, whether the A-register must be rotated or not, when we get to line 13D
we know that the hex digit we want to print is on the right side of the A-
register. Our next step is to “mask off” the upper 4 bits, which are meaning
less. We do this with the “ani Ofh” instruction. The number “Of hex” is
00001111 in binary, so when we A N D it with our 8-bit number, only the
rightmost 4 bits will be left. Then, we add 30 (hex), to change the digit from
binary into ASCII (since 30 hex is the ASCII code for 0).
Now we have to figure out if the resulting 4-bit ASCII digit is in the range
from 0 to 9 or in the range from A to F. To determine this, we do a “compare
immediate” with 3ah, since 3a (hex) is the ASCII code for 10. If the result is
minus, we know that the number is less than 10 (decimal), so we jum p over
129
Soul of CP/M®
the next instruction and go to “notbig.” On the other hand, if the result is
plus, we know that our ASCII digit is more than 9, so it must be in the range
from A (hex) to F (hex). If you look at the table of ASCII values in Appendix
D, you’ll see that “A” is 41 hex, while “ 9” is 39 hex. If “A ” immediately
followed “9” in the ASCII table, it would be at 3A hex, so there are seven
characters between where “A” actually is in the ASCII table and where it
should be. To make up for this difference we need to add an extra “7” to any
ASCII character representing the hex numbers from A to F. We do this in
line 146. Finally, in line 148, we call the PCHAR subroutine, already
described, to print the ASCII digit on the screen.
Now, we can look at the main part of the BINIHEX routine, from line 128
to line 138. These lines are responsible for making sure that the four digits
that get printed come from the right place. The first two lines print the left
side of the H-register. This is done by putting the H-register into the A-regis-
ter and then calling PR IN T 1 which, as we have seen, prints the left-hand
digit (4 bits) of whatever is in the A-register. The next two lines print the
right side of the H-register. Finally, the last four lines repeat the process with
the L-register, and then returns to the main program.
The Complete DECIHEX Program
Now we can put together the DECIBIN and BINIHEX routines into a
complete program. The combined DECIHEX program is given in Listing
4-3.
Listing 4-3. The DECIHEX Program

• ***************************************************
; DE CI HE X- c on v er ts d e c i m a l i n p u t f rom keyboard
; t o hex on s c r e en
0001 = conin equ 1h

0002 = c ono ut equ 2h
0005 = bdos equ 5h
000A = If equ Oah
0100 org 100h
; ma i n p r o g r a m - l i n k s s u b r o u t i n e s t o g e t h e r
130
Using the Assembler
0100 CD0C01 c a ll d ecibin ; g e t d e c im a l, c o nve rt to b in a r y

0103 3E0A mvi a ,If ; p r i n t line fee d
0105 CD4C01 c a ll p cha r
0108 CD2801 c a ll binihex ; c o n v e r t b i n a r y t o hex and p r i n t
010B C9 ret
/
; d e c i b i n - r e a d s d e c i m a l number f rom k e y b o a r d ,
; converts to b in a ry
010C 210000 d e c i b i n Lxi h,0 ; s e t h i to 0

01 OF E5 newdig push h ; s a v e h i ( c o n i n uses i t )
0110 0E01 mvi c,conin ;g e t character
0112 CD0500 c a ll bdos
0115 E1 pop h ; r e s t o r e hI
0116 D630 su i 30h ; c o n v e r t f rom ASCII t o b i n a r y
0118 F8 rm ; r e t u r n i f i t was < 0
0119 FEOA cpi 10d ;is i t > 9 ?
011B FO rp ; i f so, r e t u r n
; m u l t i p l y c o n t e n t s o f h i by 10 ( d e c ) , t he n add new d i g i t
011C E5 push h ; p u t h i i n de
011 D D1 pop d
011E 29 dad h ; ad d h i t o h i ( d o u b l e i t )
0 11 F 29 dad h ;d o u b le i t again
0120 19 dad d ; ad d de ( o r i g i n a l number) t o h i
0121 29 dad h ;double r e s u lt
0122 50 mov d,0 ;zero in d
0123 5F mov e ,a ;new d i g i t i n e
0124 19 dad d ; ad d d i g i t t o number
r e s u l t i s now i n h i
0125 C30F01 jmp newdig ;go look f o r next d i g i t
b i n i h ex- p ro gr a m t o p r i n t b i n a r y number i n h i
o u t on s c re e n i n hex
0128 7C b i n i h e x mov a , h ;p u t h in a ( f i r s t d ig i t )
0129 CD3901 c a llp rin tl ; p r in t le ft-h a n d d i g i t
012C 7C mov a , h ; p u t h i n a ( second d i g i t )
012D CD3D01 c a llp rin t2 ; p r in t right-hand d i g i t
131
Soul of CP/M®
0130 7D mov a , I ;put L i n a ( t h ir d d i g i t )

0131 CD3901 c a llp rin tl ; p r i n t Left-hand d i g i t
0134 7D mov a , I ;put L i n a (fo u rth d ig it )
0135 CD3D01 c a llp rin t2 ; p r in t right-hand d i g i t
/
; c o n v e r t t o ASCII and p r i n t
0139 07070707 p r i n t l rLc! rlc ! rlc ! rlc ;move h i g h 4 b i t s t o Low

013D E60F p rin t2 ani Of h ; g e t r i d o f high 4 b i t s
013F C630 adi 30h ; cha nge hex t o ASCII
0141 FE3A c pi 3ah ; i f more t ha n 9
0143 FA4801 jm notbig ; ( i t ' s not)
0146 C607 adi 7h ; t hen add b i a s ( 1 0 = A, e t c )
0148 CD4C01 notbig ca LI p cha r ;p r in t d ig i t
014B C9 ret
; s u b r o u t i n e t o p r i n t c h a r a c t e r i n a - r e g o u t on s cr ee n
f
014C E5 p c ha r push h ; s a v e h i ( c o n o u t uses i t )
014D 5F mov e,a ; p r i n t hex d i g i t
014E 0E02 mvi c,conout
0150 CD0500 c a l l bdos
0153 E1 pop h ; g e t h i back
0154 C9 ret
0155 end
The EQU Directive
You’ve already learned about O RG and END. They’re instructions to the

assembler program, rather than to the 8080 itself, like most instructions in an
assembly listing. Digital Research, who wrote ASM, refers to such entities as
“directives,” so we’ll do that too, although many other assembler writers call
them “pseudo-ops,” meaning that they aren’t quite like real 8080 op codes.
Anyway, you will by now have noticed, unless you have fallen asleep at
the wheel, that our D ECIH EX program starts off with a num ber of state
ments containing “equ” , like “ conin equ 5h” . EQU is another directive.
W hat’s it for? The idea with these statements is to make the program listing
clearer by using names for things instead of numbers. We know, for
132
Using the Assembler
instance, that to call the Console In system call, we need to do an “ mvi c ,l”
instruction. T hat’s fine, but the num ber “ 1” is not really very descriptive of
what the instruction is trying to do. It’s much clearer to be able to use an
illustrative sort of name in the instruction, like “ mvi c,conin” , which is
exactly what we do in line 110. But how will the assembler program know
what we mean when it sees “conin” used in this way? It won’t, unless we tell
it, and th at’s what the EQU directive is for. Using EQU, we can tell the
assembler that every time it sees a certain name, it is to substitute the
num ber given in the equ statement.
As another example, in line 103, we say “mvi a,If’. (These are the lower
case letters “LF,” for “Linefeed.”) W hat we’re doing here is loading the
ASCII code for a linefeed into the A-register, where this value has already
been defined in the statement “If equ Oah” at the beginning of the program.
We could have said “mvi a,Oah” in line 103, but unless we happened to
remember that 0a hex is the hex code for linefeed, we wouldn’t have known
what the instruction meant.
When to use an EQU directive and when to simply use a regular hex or
decimal number in an instruction is largely a matter of style. M any program
mers follow the convention that instructions that refer to memory locations
outside o f the program, such as the entry point to BDOS at 5 hex, must be
given a symbolic name with an EQU directive. This convention makes it eas
ier to go back and change the program if, for example, you wanted it to work
on a C P /M system where BDOS started at a location other than 5 hex. O th
erwise, EQU is used when it will make the program easier to read. By con
vention, EQU statements are all grouped at the beginning of a program
where they are easier to find.
Since we already know all about the D ECIBIN and BINIHEX subrou
tines in this program, there isn’t too much more to say about the program.
The first four lines, from 100 to 10B, link the subroutines together. First, we
call DECIBIN, to get the decimal num ber that the user will type in on the
keyboard. The num ber is placed in the HL-register where it will remain
when we return to the main program in line 103. Then, we print a linefeed,
so that when we print the hex number, it won’t print on top of the decimal
num ber that was ju st typed in. To print the linefeed, we make use of the
PCH AR subroutine that is already a part of the BINIHEX routine. We put
the ASCII code for a linefeed in the A-register and call PCHAR. To print
the hex version of the number, we then call BINIHEX, in line 108, and our
job is done!
133
Soul of CP/M®
Assembling and Using DECIHEX
Type in the entire DECIHEX program using your word-processor pro

gram and give it a file name and an extension of “decihex.asm” . Then, assem
ble it in the usual way:
A>asm d e c i h e x
CP/M ASSEMBLER - 2 . 0
0155
000 USE FACTOR
END OF ASSEMBLY
Now, since we want to run this program directly from C P /M (rather than
DDT), we’ll convert the HEX file to a COM file with the LOAD program:
A>load d e c i h e x
FIRST ADDRESS 0100
LAST ADDRESS 0154
BYTES READ 0055
RECORDS WRITTEN 01
And now, lo and behold, we can actually execute the program and see if it
works. Type the program name (no extension needed to execute a COM file),
and when the program is loaded and waiting, type any decimal number
between 0 and 65535:
A>deci hex
65535
FFFF
A>
Wow! It did it! F F F F is the hex equivalent of 65535, so we’re really in

business. Try it with other numbers and, then, file it away on a disk for the
next time when you need to do decimal-to-hex conversions. D ECIHEX is a
lot faster than thumbing through some greasy table.
USING CP/M’s SUBMIT UTILITY

You’ve probably noticed that if you do a lot of assemblying, it gets a little
tedious going through all the steps to assemble, load, and execute the pro
gram. Also, when the process is finished, you’re left with a lot of files for each
program: ASM, BAK, HEX, PRN, and COM. (You may not have a BAK file
134
Using the Assembler
if your word processor doesn’t create one.) Of these, you only need to store
the ASM and COM files, since you can generate the others from the ASM file
whenever you want to. W ouldn’t it be nice if there were a way to start with
the ASM file and end up with just the ASM and COM files without having to
go through all the steps of creating and, then, erasing the intermediate files?
The C P /M utility program SUBMIT permits us to do ju st that.
If you haven’t used SUBMIT before, here’s a brief description of how it
works. The idea is to take a string of C P /M commands (the kind you type
following the A > prompt) and put them together in a text file. Then, if you
run the SUBMIT program, these commands will be executed one after the
other.
Let’s try it out. Use your word processor to create the following file, and
give it the name “quick.sub” :
Type this in. r--------These are just comments; don’t type them in.
era $ 1 . ba k Erase the “bak” file,

asm $1 Assemble the program,
era $1.prn Erase the “pm ” file.
Load $1 Load the program,
era $1.hex Erase the “hex” file.
$1 Execute the program.
Now, let’s assume that you have the following files on your disk in drive A:
1. “quick.sub” (which you ju st made above).

2. “decihex.asm” (which you typed in on your word processor).
3. “decihex.bak” (which your word processor created).
4. “submit.com” .
Type the following:
A>submi t q u i c k d e c i h e x
My goodness, what a clicking and whirring of the disk drive there is now!
It’s hard to believe that one little phrase could cause so much activity. C P /M
is erasing the “decihex.bak” file, assemblying the “decihex.asm” file with
ASM, erasing the “decihex.prn” file, LOADing the “decihex.hex” file and
then erasing it, and, finally, it executes the “decihex.com” file.
How does all this happen? SUBMIT looks first for the file with an exten
sion of SUB whose name was typed in following SUBMIT: in this case,
135
Soul of CP/M®
QUICK. It then proceeds to “execute” the lines of this file as if they were a
program written in “C P /M language,” which, in a way, they are. When SUB
M IT sees the “era $ l.bak” statement, for example, it looks for the file name
that was typed in following the name of the submit file QUICK; in this case,
DECIHEX. Then, wherever there is a $ 1, SUBMIT will fill in the name of the
file: DECIHEX. So, the first line is translated into “era decihex.bak” . The
second line is translated into “asm decihex” , and so on. (Actually, more than
one file name can be dealt with in this way, by using $2, $3, and so on, but we
don’t need to get into that here.)
Amusing, no? And also a great time saver. You can customize this little
Q U IC K file to suit your needs. For instance, if you want to retain the BAK
file for safety’s sake, leave out “era $ l.bak” . And, if you don’t want to exe
cute the program right away, leave out the last line: “$1” .
GRADUATION TIME
You now know almost as much about 8080 assembly language as anyone.
Oh, sure, there are some more instructions in the 8080 repertoire, but the
ones you’ve already learned are used in 95% of all programming situations. In
fact, you could probably write any program you wanted to by just using only
the instructions you’ve learned so far. We’ll pick up a few more along the
way, but they won’t be too different from what you know already.
Also, you’ve learned to use the sophisticated (at least when compared with
DDT) ASM assembler to assemble your program. Now you can write pro
grams of almost unlimited length (subject to the limitations of your com
puter’s memory, of course) with the assurance that you’ll be able to turn them
into object code. So, how about a round of champagne? You’ve graduated
from 8080 school!
136
CHAPTER 5
Disk System Calls

You can do some interesting things with the system calls you’ve learned so
far, especially those that deal with the keyboard, the video screen, and the
printer. However, most serious application programs deal with data in some
form or other, and data in a C P /M system are usually stored on a disk. If
you’re writing a word-processing program, the text files are stored on the
disk. If you’re writing a spreadsheet program like Visicalc, the data you put
in the spreadsheet are stored on the disk. If you’re writing an improved
C P /M file directory program, the data you want to look at (the disk direc
tory) are stored on the disk. In short, understanding the C P /M disk system is
indispensable if you want to write programs that make use of the full capabil
ity of your C P /M system.
The C P /M disk system calls are amazingly powerful. Remember our anal
ogy in the introduction about ordering a chicken sandwich in hotels in differ
ent cities? The idea was that no m atter what city you were in, you could
always get the same chicken sandwich, even if the hotel employees, depend
ing on whether they were in Calcutta or Istanbul, had to engage in very dif
ferent practices to prepare the sandwich.
Let’s extend this analogy a little. If using the system calls for the console
(keyboard and video) is like ordering a chicken sandwich, then using them
for the disk drives is like ordering duck a l’orange with a magnum of Lafite
Rothschild ’63. When you used the console system calls, you were dealing
with single characters or character strings. W ith disk system calls, you can
handle whole records and files at a time, all without having to worry about
how C P /M and your computer actually go about reading and writing infor
mation to the disk. And, of course, your programs will read and write files on
any computer or disk system, as long as it is running C P/M .
137
Soul of CP/M®
Learning how to use these disk system calls is the purpose of this chapter.
You’ll find out about the “mailbox” system that C P /M programs use to tell
C P /M what files to read or write, and you’ll explore several short system
calls which will be all you need to have to read any file into your program. By
the end of this chapter, you’ll be able to reproduce the C P /M “type” com
mand and also write a program that counts the number of lines in a text file.
(We’ll save writing to the disk until the next chapter.)
If this sounds complicated, relax. Thanks to the transportability features of
C P/M , learning how to input and output inform ation to the disk is scarcely
more complicated than it is for the console. Well, maybe a little more compli
cated, but it’ll be fun. Trust us!
RECORDS, FILES, TRACKS, SECTORS, ALLOCATION

UNITS, EXTENTS, AND GOODNESS KNOWS WHAT ELSE
One of the truly wonderful things about C P /M is that you can write pro
grams in 8080 assembly language, which will do almost anything you want
with the disk drives, without knowing anything about most o f the terms, such as
those listed in the heading of this section. All you really need to understand
138
Disk System Calls
are records and files. We won’t talk (too much) about the other terms until
Chapter 7, when we get to such mysterious topics as the file directory and
saving erased files.
Files
From the user’s viewpoint, the fundamental unit of information on a disk

is a file. You’re already familiar with files and how they are named
(“testl.com ” and so on). A file is simply a whole lot of bytes stored on the
disk. Files in C P /M can be almost as small or as large as the person generat
ing them wants them to be. The minimum size is 256 bytes (which is 256
characters, if the file consists of text), and the maximum size is more than 8
million bytes. Now, that’s really big. Because C P /M can handle such large
files, it needs to be able to break them down into smaller sections. Why is
this? Mostly because the memory of the computer is much smaller than this
maximum file size and, also, smaller than the space on a typical 8-inch floppy
disk. The memory of a typical C P /M computer is 65,536 bytes (some of
which are used by C P /M itself). When you add the user’s program, there may
not be more than a few thousand (or even a few hundred) bytes left for stor
ing data on the disk. On the other hand, an 8-inch disk will hold from about
75,000 bytes to upwards of more than one million bytes. Clearly, if you have
a file that occupies most of a disk (or more than one disk), you can’t cram it
all into memory at the same time. So a file is broken down into smaller units
called records, only one of which is loaded into memory at any one time.
Records
The designers of C P /M had to determine what size records they wanted to

break a file into. If they made the records too large, the records would take
up too much memory when they were read in, but if they were too small, the
disk drives would have to work too hard to transfer a file into memory, since
each record requires a separate disk access. They chose a fairly small record:
128 bytes. Remember this num ber—you’ll be seeing it again. Use your
DECIHEX conversion program to find out what 128 decimal is in hex.
TALKING TO BDOS
When it is reading or writing information to the disk, the Basic Disk Oper
ating System (BDOS) uses two areas of memory to communicate with the
139
Soul of CP/M®
program calling it. These are the DMA buffer and the File Control Block
(FCB). Understanding the DMA and the FCB and how they’re used is the
key to understanding the C P /M disk system calls.
Fig. 5-1 shows where the DMA buffer and the FCB are located in memory.
They’re both in the “zero page,” the portion of memory from 0000 hex to
00FF hex.
The DM A Buffer
When you want to read a file from the disk into memory, the process goes
like this. You set aside a place in memory that is 128 bytes long. This space is
called the “ DMA buffer.” (DMA stands for “ Direct Memory Access” and is
actually a term better used with large mainframe computers that can transfer
a block of data without the intervention of the a program —but that’s another
story. The name got started and here it is.) The DMA buffer is usually
located at memory address 80 (hex), which is called the “ DMA Address,”
although you can change it to any address you want, as we will soon see.
Once the DMA buffer is set up, you read the first record of the file into
this space. When your program has done whatever it’s going to do with this
record (printing it out on the screen, doing arithmetic on data in the record,
or whatever), it then reads in the next 128-byte record, processes it, and so
o n -u n til the end of the file is reached.
The File Control Block (FCB)
How can your program tell C P /M what file to read? We need a way to
pass file names from your program to C P/M , so that BDOS can take care of
all the tedious details of looking for the file on the disk, finding the record we
want and reading it off the disk, and putting it in memory in the DMA
buffer. To pass these file names, we set up a sort of “mailbox” in memory,
lllllllllllllll
II I I I III l l l l
/
TPA
/
DMA
Buffer
/
FCB
/
/
Fig. 5-1. The memory location of the DMA buffer and the FCB.
140
Disk System Calls
which we call the FCB, for File Control Block. This is simply a section of
memory, 36 (decimal) bytes long, where we can put the file name. C P /M also
uses the FCB to store information about where the file is located and some
other things, but we don’t need to worry about that now. The FCB is usually
located at memory address 5C (hex), just below the DM A address.
The following listing shows the various sections of the file control block
(FCB). For the time being, we are only interested in the place where the file
name and extension go. (The mnemonics shown in parentheses are the desig
nations given the various bits by Digital Research.)
Byte number Location

(decimal) (hex) Contents
0 5C 0 Drive number (dr).
1 5D T
2 5E E
3 5F S
4 60 T -File name (8 bytes) (fl to f8).
5 61 1
6 62 0
7 63 0
8 64
9 65 T
10 66 X ^■File extension (3 bytes) (tl to t3).
11 67 T
12 68 00 Current extent (ex).
13 69 00 Used internally by C P /M (si).
14 6A 00 (User should set to zero) (s2).
15 6B 02 N br of records in current extent (rc).
16 6C 54
17 6D 00
18 6E 00
19 6F 00
20 70 00
21 71 00 ►
Allocation units (dO to dlO).
22 72 00
23 73 00
24 74 00
25 75 00
26 76 00
141
Soul of CP/M®
27 77 00
28 78 00
29 79 00 ►Allocation units ( d ll to dl5).
30 7A 00
31 7B 00
32 1C 01 Current record (cr).
33 7D 00
34 7E 00 ^•Random record number (rO, rl, r2).
35 7F 00
Now that you know about the DM A buffer and the FCB, we’re ready to
plunge on into our first system call.
OPEN FILE
OPEN FILE FUNCTION 15 (dec) =0F (hex)
Enter with: REG C = OF (hex)

REGs DE = FCB Address
On return: REG A = directory code.
Comments: Directory Code = 0,1,2, or 3 if file found.

Directory Code = FF (hex) if file not found.
W hat does it mean to “open” a file? Before a program can do any reading
or writing to a file, BDOS has to figure out where the file is on the disk. It is
alerted to do this with the “Open File” system call. When this call is exe
cuted, BDOS finds the addresses of the various parts of the file (they’re called
“allocation units”) and records them in the FCB for later reference. Since
there is only one FCB, there can only be one file open at any one time. (Actu
ally, there can be several FCBs operating at once, but we’re not going to get
into that now.)
Here’s a little program to open a file using this system call:
mvi C,f Put f in C-register for Open File.

Lxi d , 5 C Put address of FCBin DE-register.
call 5 Call BDOS.
rst 7 Back to DDT.
142
Disk System Calls
Type in this program using DDT, save it as “test 100.ddt”, and then exe
cute it by typing -glOO. You should hear your disk drive click and D D T will
print out the usual star and ending address:
-g100
*0108 (Click!!)
W ow—what a powerful program —it made the disk drive click! W hat’s the
click mean? You’ve told BDOS to open the file whose name is in the FCB.
W hat name is in there? We don’t really know, since we haven’t put anything
in the FCB ourselves. Maybe there’s an old file name left over from a previ
ous operation, maybe not. W hatever is in there, even if it’s a string of
blanks or zeros, BDOS will try to find a file with that name. If it finds it,
BDOS will “ open” the file by recording the numbers of its allocation units
in the FCB. If it doesn’t find the file, it will still make the disk drive click by
looking for the file in the disk directory. (We’ll talk more about the direc
tory in Chapter 7.)
It’s not hard to see what’s in the FCB. From DDT, simply type “d5c,7f” . If
there’s nothing in the FCB but zeros, you’ll get a printout like this:
- d 5 c ,7 f
005C 00 00 00 00 ___
0060 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 .............................
0070 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 .............................
The first line shows the memory locations from 5C to 5F, and the next
lines, the locations from 60 to 7F. A name would be in here somewhere if
there was one, but there isn’t.
You can make sure a file name is placed in the FCB by simply calling up
D D T with the name of another program. For instance, assuming you have
saved the “ testlOO.ddt” program described above, you can put its name in
the FCB in the following way. First, exit from D D T with a -gO. Now, to get
back into DDT, and at the same time, load the new program into the TPA at
100 hex and leave the name o f the program in the FCB, type:
A > d d t testlOO.ddt
Now look at the FCB with “d” :

143
Soul of CP/M®
-d5c,7f
005C 00 54 45 53 .TES
0060 54 31 30 30 20 44 44 54 00 00 00 00 00 00 00 00 T100 DDT.............
0070 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ............................
There’s the name of the program!The name itself starts at location 5D, is 8
bytes long, and ends at location 64. The numerical ASCII values of the char
acters are shown on the left, and the actual characters on the right. Since
“TEST 100” is only seven characters long, the last space of this 8-space field
is filled in with a blank (20 hex) at location 64. The file extension “ D D T ”
occupies locations 65 to 67 hex.
If we now run our little program with a -glOO, it will find an existing file,
namely itself, in the FCB and open it.
Can we tell whether the Open File system call has been successful in find
ing the file whose name is in the FCB? Yes, by making use of what is called
the “directory code,” which is returned in the A-register following the call.
To use this feature, we need to add a few lines to our program to print out the
number returned in the A-register.
0100 mvi c,f Put f in C-register for Open File.

0102 lxi d,5c Put address of FCB in DE-register.
0105 ca 11 5 Call BDOS.
0108 mvi c,2 Set up Console Out.
010A adi 30 Add 30 hex to A-register to get ASCII.
010C mov e,a Put result in E-register.
010D c a ll 5 Call BDOS.
Type this program in using the “a” option in DDT, save it with “A > save
testlO l.ddt”, call it back in with “A > d d t testlO l.ddt” and run it with a
“glOO”. You should get the following on the screen:
-g100
3*0110
The “3” preceding the usual asterisk and ending address is the number
printed out by our program, and is the number that was in the A-register on
completion of the Open File system call. It might also be a 0, or a 1, or a 2.
Any of these numbers mean that the file, whose name was in the FCB, was
found by the Open File system call. (Whether the number is a 0, 1, 2, or 3 is
determined by the place in the disk directory that is actually occupied by the
file nam e—a topic we’re going to avoid until the next chapter.)
144
Disk System Calls
The “i” Command in DDT
It would be more convenient if there were a way to place other file names
into the FCB directly, without having to enter them when calling up DDT.
This is the purpose of the “i” (for “Input”) command.
Suppose you have a program on your disk called TESTPROG.TXT. If
you’re already in DDT, and you want to put this name into the FCB, all you
need to do is type:
-itestprog.txt
Doesn’t that seem easy? Let’s try it out to see if it really works. First, we’ll fill
the FCB with “F F ’s” to make sure there’s nothing in it, and then we’ll use “i”
to fill in a program name. Then, we’ll check to see if it’s there.
-f5 c ,7 f,ff
-d5c,7f
005C FF FF FF F F ___
0060 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF F F ...................
- i testprog. tx t
-d5c,7f
005C 00 54 45 53 .TES
0060 54 50 52 4F 47 54 58 54 00 FF FF FF FF FF FF FFTPR0G..........
The name is there, just asit was when we called it in with DDT. Notic
also that byte 0 at location 5C and byte 12 at location 68, which are the drive
number and “current extent,” respectively, are also zeroed out by the “i”
function. A “0” drive number stands for the “default drive,” which is the one
we’re in unless otherwise specified, and the “current extent” is 0 unless we’re
reading from a file that is more than 16,384 bytes long. (More on that later.)
It is possible to do “by hand” what the “i” command does, if we translate
the letters of the file name into ASCII values and put them into the correct
locations using the “s” command in DDT; but, of course, the “i” command is
far more convenient.
You can now check to see if your Open File program can find all sorts of
different programs. Use “i” to insert the name of a program that is on the
disk, and then run your program.
145
Soul of CP/M®
- i testp r o g . tXt Existing program name.

-g100
3*0110 “3” means it was found.
The program should print out a 0, 1, 2, or 3. Now try it with a program

name that isn’t on your disk.
-i n o t a p r o g . c o m Nonexistent program.
- g 1 00
/ * 0 1 10 “/ ” means it wasn’t found.
If the file isn’t found, the A-register will contain F F when the program
returns from the Open File system call. The program should then print out a
slash (/), since this is the character with an ASCII value of 2F (30 plus FF),
which we calcuated in line 010A of the program. (FF has the value —1 in 8-
bit arithmetic, and 30 minus 1 is 2F.)
THE PROBLEM WITH WHERE THE DMA IS LOCATED

The next thing that we want to do after opening a file is to read it into
memory so that our program can examine it, print it out, send it to the
printer, or whatever. We also want to be able to do this from DDT, because
the “i” command makes it so easy to set up the FCB for a particular record.
Unfortunately, there is a small problem with using D D T at the same time that
we’re using the DMA in its normal location from 80 to F F (Fig. 5-2). The
problem is that D D T uses this area for its stack (the place where the contents
of registers go when you “push” them). These two areas can’t occupy the
same space at the same time without causing error messages. W hat to do?
There are two solutions to this problem: an easy one and a good one. We’ll
explore the easy one first.
The Easy Solution to the DMA Dilemma
The easy solution is to read only very short records into the DMA. Since
D D T ’s stack grows down from the address FF, and records are read into the
DMA buffer at 80 and moving upward toward FF, if the records are short,
we can avoid conflict. We’ll try this just because it makes for a nice easy
146
Disk System Calls
iiiiiiiiiiiiiiiiiiiiiiin ii
///z///;////;;;/////;/;/////
TPA
0100
DDT Stack
lllllllllllllllllllllll
DDT's stack and the
- DMA buffer both try
to use this space.
///////////////////////
Zero DMA Buffer
Page 0080
FCB
005C
Fig. 5-2. The c o n flic t between DMA and DDT.
program, even though it has a built-in potential for disaster if we try to read
too long a record.
The first thing to do is to create a very short record. Call up your word-
processing program and type in some characters, but make sure you don’t
type more than a line (80 decimal characters). End your line with a “return.”
Save this as a file called “short.txt” . Since this file is so short, it is a 1-record
file. (It will show up as a 2K file in the directory, but only one 128-byte
record will be used.)
Now the only thing that stands between us and writing a program to read
this record into the DMA is learning the Read Sequential system call.
READ SEQUENTIAL SYSTEM CALL
READ SEQUENTIAL RECORD FUNCTION 20 (dec) = 14 (hex)
Enter with: REG C = 1 4 (hex)

REGs DE = FCB address
On return: REG A = directory code.
Comments: Directory Code = 0 if read was successful.

Directory Code = nonzero if end-of-file.
147
Soul of CP/M®
This system call looks a good bit like the Open File call, but note that it
reads a record, where the Open File call opened a whole file. W hat does
“sequential” mean? It means that the call will start off reading the first 128-
byte record in a file, will read the second one the next time it is called, the
third one the next time, and so on, until it comes to the end of the file.
How does it know when it’s at the end of a file? In either of two possible
ways. First, it can find an “end-of-file” mark in the file. This is only possible
if the file is a text file, so that one of the characters can be set to the ASCII
character for “end-of-file,” which is a 1A hex.
Secondly (and more important), since C P /M keeps track of how many
records are in a file and stores this information in the FCB when the file is
opened, all the Read Sequential system call has to do is keep track of how
many records it has already read to know if it has read the last record. The
total number of records in a file is stored in byte 15 (decimal) of the FCB,
and the number of the next record to be read is stored in byte 32. By com par
ing these two numbers, the Read Sequential call knows when it’s finished an
entire file.
If the Read Sequential system call does find an end-of-file marker, it sets
the A-register to a nonzero value on its return. Otherwise, the A-register is set
to 0, which indicates that the read was successful.
Reading a Record
Here’s the routine to read into the DMA the record that we created earlier:
“ short.txt” . (D on’t try to read anything longer, or bad trouble and error
messages will result.) Call this program “test 102.ddt” .
-a100
0100 mvi c,f Open file.
0102 Lxi d,5c Set FCB address.
0105 c a ll 5 Call BDOS.
0108 mvi c,14 Read record.
010A lxi d , 5c Set FCB address.
010D c a ll 5 Call BDOS.
Before running this program, you need to be sure that (1) your short file
“ short.txt” is on your disk, and (2) that you have put the name of this file
into the FCB by typing “ishort.txt” from DDT. Now, run it with a “-glOO” .
W hat happens? The disk drive should click. Big deal—no better than the last
program? No. This time there’s a tangible result.
148
Disk System Calls
Use “d” to look at the DMA buffer. Assuming that your “short.txt” file
consisted of the line “Now is the time for all good men to come to the aid of
their country,” you should see the following when you dump the buffer:
-d80,ff
0080 4E 6F 77 20 69 73 20 74 68 65 20 74 69 6D 65 20 Now i s t he t i me
0090 66 6F 72 20 61 6C 6C 20 67 6F 6F 64 20 6D 65 6E f o r a l l good men
00A0 20 74 6F 20 63 6F 6D 65 20 74 6F 20 74 68 65 20 t o come t o t he
00B0 61 69 64 20 6F 66 20 74 68 65 69 72 20 63 6F 75 a i d o f t h e i r cou
00C0 6E 74 72 79 2E 0D 0A 00 00 00 00 00 00 00 00 00
00D0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00E0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 F0 00 00 00 00 00 00 00 00 C1 D6 9B D4 42 d4 44 00
j
These numbers inserted by D D T stack process.
The record ends with the codes for carriage return and linefeed: OD, OA.
The zeros after that could be any junk that happened to be in the buffer
before the record was read in, although you could guarantee they were zeros
by using “f” to fill the buffer before executing the program.
So, there’s the record, sitting safe and sound in the DMA buffer, just where
it should be. And the program to read it in is only 7 lines long! That’s even
easier than reading a record in BASIC! However, as you’re aware, we’re
restricted to very short records with this program. W hat we need now is a
way to avoid the conflict that results when the DMA buffer and the D DT
stack try to share the same space.
The Good Solution to the DM A Dilemma
Fortunately C P /M offers an easy solution to this problem; we can move

the DMA buffer using the “ Set DMA Address” system call.
SET DMA ADDRESS
SET DMA ADDRESS FUNCTION 26 (dec) = 1A (hex)
Enter with: REG C = 1A (hex)

REGs DE = New DMA address
149
Soul of CP/M®
This system call looks easy enough to use, and it is. All we need to say is:
m vi C, 1a Set up for Set DMA Address.

Lxi d,400 Move DM A address to 400.
caLL 5 Call BDOS.
We chose 400 (hex) as the new DMA address simply because it’s high
enough in memory so that we know it isn’t going to interfere with our pro-
gram at 100 hex. Actually, you can put the DM A anywhere you want, as long
as it doesn’t interfere with your program or the C P /M operating system (or
DDT, if you’re using that).
Let’s incorporate these program lines into our read record program:

0102 Lxi d,5c
0105 ca L L 5
0108 mvi c,1 a Set DMA address to 400.
010A Lxi d ,4 0 0
010D ca L L 5
0110 mvi c,14 Read record.
0112 Lxi d,5c
0115 ca L L 5
Save this program as “testl03.ddt” . Now, use it to read in the first record
of any file you want, no matter how long it is. Here’s how to do it:
1. Load the program with D D T with “A > d d t testl03.ddt”.

2. Put the file name of the program you want to look at in the FCB with
“-iprogname.ext” (fill in the name of the file you want).
3. Run the program with “-glOO”.
4. Check the DM A buffer with “-d400” to see that whatever was in the
record was read in correctly.
If you want to read the second record of a file that is longer than one
record, simply repeat Steps 3 and 4. Each time you execute the program a
new record will be read into the DM A buffer, where you can look at it with
the “-d” command. You can examine any sort of record this way, whether it
contains text, hex values, or whatever. This can be useful in investigating
what’s really going on, on the bit level, in a record on your disk.
150
Disk System Calls
For instance, some word-processing programs use the high-order bit (bit 7)
of each character to indicate that there is something special about the charac
ter. A normal space is 20 hex, but the “soft” space used in some processors to
justify text lines might be represented by AO hex, since 20 hex is 0010,0000 in
binary, and A0 hex is 1010,0000. They’re the same, except that the high bit is
turned on in A0.
Dumping a record using D D T this way immediately reveals the difference
between hard and soft spaces, and a variety of other things as well. Read
different kinds of files and look them over. You may be surprised at what you
discover.
Fancy Read Record Program
We’ve left two things out of our program: (1) the check to see if the file
we’re trying to open really exists, and (2) the check to see if the record we’ve
read is a valid record or an end-of-file. Let’s modify the program so that it
prints out the directory codes returned in the A-register twice; first when it
returns from opening the file, and second, when it returns from reading the
record. This way, we can tell if the file we are trying to read really exists, and
if we have read a valid record in the file or an end-of-file. We’ll call this
program “ testl04.ddt”.
- a 1 00
0100 mvi c,f open file
0102 Lxi d,5c
0105 ca L L 5
0108 mvi c,2 print resulting directory code
010A adi 30
010C mov e , a
010D ca L L 5
0110 mvi c,1 A set DM A to 400
0112 Lxi d,400
0115 ca L L 5
0118 mvi c,14 read record
011A Lxi d,5c
011 D ca L L 5
0120 mvi c , 2 print resulting directory code
0122 adi 30
0124 mov e , a
0125 ca L L 5
0128 rst 7 back to DDT
151
Soul of CP/M®
Let’s try out this program on the “short.txt” file that we created before.
After saving the program, reload it with DDT. Then, set up the FCB with the
“i” instruction and run the program.
- i short. tx t
- g 1 00
30*0128
I-----------------------------------------------------------------The “0” says that the record was read successfully.

--------------------------------------------------------------- The “3” (or 0, or 1, or 2) says that the file was found.
Now we can dump the contents of the DMA to see that the record is really
there:
-d400,47f
0400 4E 6F 77 20 69 73 20 74 68 65 20 74 69 6D 65 20 Now i s t he t i me
0410 66 6F 72 20 61 6C 6C 20 67 6F 6F 64 20 6D 65 6E f o r a l l good men
0420 20 74 6F 20 63 6F 6D 65 20 74 6F 20 74 68 65 20 t o come t o t he
0430 61 69 64 20 6F 66 20 74 68 65 69 72 20 63 6F 75 a i d o f t h e i r cou
0450 6E 74 72 79 2E OD0A 00 00 00 00 00 00 00 00 00 n t r y ..........................
0460 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ...................................
0470 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ...................................
But, now, if we try to read the next record of this file, we find that a direc
tory code of 1 is returned, indicating an end-of-file:
- g 1 00
31*0128
^------------------------The “ 1” indicates that the record was not sucessfully read; it was an end-of-file.
------------------------------------------------------------------------------------------- The “3” means the file was found.
Continuing to attempt to read records from the file will yield the same result:
a directory code of nonzero indicating end-of-file.
Try out this program on some more existent and some nonexistent files.
Check the contents of the DMA with the “d” command both before and after
reading a nonexistent file. They don’t change since there’s nothing in the file.
Read a file with a fairly small number of records and see how the contents of
the DMA change for each succeeding record. Watch the directory code
printout change from 0 to a nonzero value when the last record is reached.
152
Disk System Calls
Using this program with the D D T dump function, you can explore how a
variety of files are stored on the disk. You can find out what the contents of
your files really are, rather than just what your applications programs tell you
they are.
TYPE2 PROGRAM—IMITATES THE “TYPE” COMMAND

We’re now going to put together some of the things we’ve learned in order
to show how to perform a simple but useful function involving the disk sys
tem. In fact, this function is so useful that Digital Research has already incor
porated it into C P/M . It’s the “type” function, which simply prints out on
the screen the contents of a text file.
Our program will operate in almost exactly the same way as “ type,” so
we’ll call it “type2.com” . It will operate directly from C P /M as a COM file.
To use it, you type:
A > ty p e2 progname.ext
where “progname” is the name of the file you want to look at and “ext” is its
file type. Executing the program in this way has the effect of putting the
program name which follows “ type2” into the FCB, just as it did when we
called D D T and followed it with a program name. In fact, this is always true;
when you type two program names in a row following the A > prompt,
C P /M will load the first program into the TPA, and put the filename of the
second into the FCB.
Look at the listing of TYPE2 in the following pages. The program starts by
opening the file whose name is in the FCB and, then, checking to see if the
file was found. If not, it prints the message “N o such filename” and exits
back to C P/M . Assuming that the file exists, it reads the first record from the
file and checks to see if it is a valid record or an end-of-file (EOF). If it is the
EOF, the program figures its job is done and exits to C P/M . Otherwise, it
knows it has a valid record, which it prints out using the Console Out system
call in the subroutine “pchar” (for “print character”). We could have used
the Print String system call, but then we wouldn’t have been able to print
strings containing dollar signs, since these act as terminators to Print String.
Since this is a fairly long program which we don’t want to run from D D T
anyway, we’ll assemble it using ASM. The program is given in Listing 5-1.
153
Soul of CP/M®
Listing 5-1. The TYPE2 Program

; ************************************************
;TYPE2-program t o i m i t a t e CP/M " t y p e " f u n c t i o n
/
000F = openf equ Of h ; op e n f i l e
0014 = readr equ 14h ;re a d record
0009 = p rin ts equ 9h ; p r in t strin g
0002 = c onout equ 2h ;console out
005C = fcb equ 5ch ; f i le c o n t r o l b lo c k
0080 = dma equ 80h ; s t a r t o f dma b u f f e r
0005 = bdos equ 5h ; o p e r a t i n g system e n t r y
/
0100 o rg 100h
f
; op en f i Le ( name must a l r e a d y be i n f c b )
0100 0E0F mvi c,openf
0102 115C00 Lxi d , f cb
0105 CD0500 ca L L bdos
0108 3C in r a ; i f a was f f , now i t ' s 0 ,
0109 CA2701 jz nof i ; so no such f i l e name
; r e a d r e c o r d f rom f i l e
/
010C 0E14 nextr mvi c,readr
010E 115C00 lxi d , f cb
0111 CD0500 ca 11 bdos
f
; i f e n d - o f - f i l e , t hen e x i t t o CP/M
0114 B7 ora a ; i s a=0?
0115 CO rnz ; n o, so e o f , back t o CP/M
r
; d i s p l a y c o n t e n t s o f dma buffer
011 ó 218000 lxi h,dma ; s e t p o i n t e r i n hL
0119 0680 mvi b ,1 28d ; s e t c o un t i n b
011B 5E l o op mov e,m ; g e t c h ar f rom b u f f e r
011C CD3001 ca 11 p c ha r ;display i t
0 11 F 23 i nx h ; i n c r e m e n t hL
0120 05 dcr b ; d e c r e m e n t b-done?
0121 C21B01 jnz lo op ; not yet
0124 C30C01 jmp nextr ; y e s , go g e t n e x t r e c o r d
/
; n o such f i Le name: p r i n t message and e x i t
0127 0E09 nofi mvi c , p r i nts
0129 113A01 Lxi d , n f me s s
012C CD0500 ca 11 bdos
012 F C9 ret ; b a c k t o CP/M
154
Disk System Calls
;s u b ro u tin e to d i s p l a y one c h a r a c t e r on s cr ee n
0130 E5C5 p cha r push h ! push b! ;save r e g i s t e r s
0132 0E02 mvi c,conout / p r i n t character in
0134 CD0500 ca 11 bdos
0137 C1E1 pop b! pop h ! ; restore re g is te rs
0139 C9 ret
013A 4E6F207375nfmess db ’No such f i l e n a m e . $ ’

A
014C end
Most of the programming tricks used in this program you’ve seen before.
We’ve used a lot of EQU statements at the beginning of the program in an
attem pt to make the rest of the listing easier to read. A flowchart for the
TYPE2 program is given in Fig. 5-3.
In lines 108 and 109, we check for EOF by incrementing the directory code
in the A-register. If it was F F hex, indicating an EOF, incrementing it will
cause it to become zero, and our “jz ” (jump on zero) instruction will then be
activated and will cause control to go to “nofi” (for “no file”), where the “N o
such filename” message is printed out using the Print String system call.
You’ve used this system call before, but the way we type the message into the
listing, using the “db” directive, may be new to you.
The “D B ” Directive
As we pointed out earlier, it’s tedious to convert long strings of characters

into their ASCII values and then type them in by hand when a message is
called for in a listing. ASM provides a way to simplify this task with the “db”
directive, which stands for “define bytes.” This directive is used whenever
you want to put 1-byte values into your listing. These values can be repre
sented by either numbers from 0 to 255 decimal (0 to FF hex), strings of
characters (which ASM will translate into their ASCII values), or labels that
refer to 1-byte numbers. Combinations of these things may be used, sepa
rated by commas. Strings of characters must be enclosed in single quotes.
Thus, any of the following statements are valid:
max db 12d ; single number

data db 43h,41h,54h ;group of numbers
mess db ’speak to me!’ ; string of characters
mess2 db ’your name?’0D,0A ; string plus numbers
mess3 db ’your name?’cr,lf ; string plus labels
155
Soul of CP/M®
The hex values for carriage return and linefeed are OD and OA, respec
tively. Thus, mess2 and mess3 are equivalent, provided the labels “cr” and
“If” have been set to these values with EQU statements.
Fig. 5-3. Flowchart for the TYPE2 program.
156
Disk System Calls
After reading a record, TYPE2 checks for end-of-file by ORing the A-regis
ter with itself; if it’s not zero, the program returns to C P/M . To display the
contents of the DM A buffer on the screen, the program sets up a loop. The
B-register holds the count of characters in the buffer (which is 128 decimal)
and the HL-register holds the address of the particular characters in the
buffer. We can then ju st put a character in the E-register with a “mov e,m”
instruction and print it with a call to pchar. Next, we do a loop, incrementing
the HL pointer, decrementing the B-register counter, and printing the charac
ters, until the count is zero, at which time we go off to read another record.
Type the program in using your word processor, giving it a filename of
“ type2.asm” . (D on’t type the hex values on the left-hand side, of course.)
Assemble it with ASM, load it with LOAD, and you’re ready to execute it
directly from C P/M . Type “type2” followed by the name of the program that
you want printed out.
Terrific! It’s ju st like C P /M ’s “ type” command. You can even start and
stop the scrolling with control-s, just as you can with “type.” So look at you!
Now you’re writing C P /M system programs. In a few more pages, you’ll be
ready to apply for a job at Digital Research!
LINES PROGRAM—PRINTS NUMBER OF LINES IN TEXT

FILE
For our next program, and the last one in this chapter, we’ve tackled some
thing a little more ambitious. We’re going to write a program that will read
through a file and count the number of linefeeds it encounters, thus provid
ing a line count of a document or listing.
Actually, the LINES program should look more or less familiar to you,
since it consists of system calls and concepts you’ve looked at before—except
for one section. So we’re not going to go into detail on every part of the
program. We’ll talk about a few new things, and we’ll cover the BINIDEC
subroutine which converts a binary number in the HL-register into a decimal
number and prints it out on the screen. This subroutine has a cute way of
doing what it does, so we’ll describe it briefly.
The BINIDEC Subroutine
The BINIDEC subroutine occupies locations 175 to 1B2 in the LINES

program. Here, in Listing 5-2, is how it looks, separated from the rest of the
listing.
157
Soul of CP/M®
Listing 5-2. The BINIDEC Subroutine

; b i n i d e c - c o n v e r t s b i n a r y number i n h i t o
; d e c i m a l , p r i n t s r e s u l t on s c r e e n .
0175 11F0D8 b i n i d e c l x i d , - 10000 ; p r i n t number o f 1 0, 000s

0178 CD9401 ca ll subcnt
017B 1118FC lx i d , - 1 000 ; p r i n t number o f t housands
017E CD9401 ca 11 s u bc n t
0181 119CFF lx i d,-100 ; p r i n t number o f hundreds
0184 CD9401 ca 11 s u b cn t
0187 11F6FF lx i d,-10 ; p r i n t number o f t en s
018A CD9401 c a ll s u b cn t
018D 11FFFF lx i d,-1 ; p r i n t number o f ones
0190 CD9401 ca 11 s u bc n t
0193 C9 ret ; t h a t 1s a l l
r
0194 0E2F su bc n t mvi c , ’0’-1 ; c h o l d s ASCII v e r o f c oun t

0196 0C sub2 in r c ; i n c r e m e n t c oun t
0197 22B301 sh Id temp ;save h 1
019A 19 dad d ; a d d neg c o n s t f ro m de t o h i
019B FA9601 jm sub2 ; l o o p t i l r e s u l t i n h i i s neg
019E 2AB301 Ih Id temp ; g e t l a s t pos v a l u e back i n h i
01A1 79 mov a,c
01A2 CDA601 c a ll p c ha r ; p r in t d ig i t
01A5 C9 ret
; p r i n t c h a r a c t e r i n a - r e g i s t e r on s cr ee n
01A6 D5C5E5 pchar push d ! push b ! push h ;save r e g i s t e r s
01A9 5F mov e ,a ;cha ra cte r in e
01 AA 0E02 mvi c,conout
01 AC CD0500 ca 11 bdos ; c a l l c ono ut r o u t i n e
01AF E1C1D1 pop h ! pop b ! pop d ; g e t r e g i s t e r s back
01B2 C9 ret
A
01B3 0100 temp dw 0
The routine uses the following strategy to convert a binary to a decimal

number. To start with, it knows that no 16-bit binary number can be larger
than 65535 decimal (F F F F hex). The first thing it wants to do then is to find
out how many ten thousands there are in the number. There could be as
many as 6, there could be 0, or there could be some number in between. How
158
Disk System Calls
can it find this out, working only in binary? N ot so hard. It merely subtracts
10,000 decimal (2710 hex) from the number and checks to see if the result is
negative. If not, it knows that the number is larger than 10,000, so it subtracts
it again. If the result is still not negative, it knows that the number is larger
than 20,000. It keeps subtracting until the result is negative, at which point it
knows (since it’s been counting) just how many 10,000’s there are in the
number. It prints this out, since it’s the first digit of the decimal translation of
the number. Then, it restores the original number to the value it had just
before the subtraction that made it go negative; this is the number with the
10000’s digit removed.
Let’s say the number is 8000 hex, which we happen to know is 32768 deci
mal. When we subtract 2710 (hex) from B000, the result is not negative, as we
can easily see by performing the arithmetic in decimal: 32768 minus 10000.
So we do it again. We have to do it three times, so we print out 3 (which is
right) and restore the number to 0AD0 hex, which is 2768 decimal: the
number with the 10000’s digit removed.
Now we have a new num ber that we know m ust be less than 10,000, so
we can start subtracting 1,000 (one thousand) from it to see how many of
them there are. And, so on, until we’ve printed out the hundreds, tens, and
ones places. In 8080 assembly language, there isn’t a subtraction instruction
for 16-bit numbers, so we put negative numbers into the program when we
assemble it and add them with a “dad” instruction. This subtraction pro
cess is similar for each of the five values that we need to subtract, so we put
it in a subroutine that we will call each time with the value in the DE-
register.
Another part of this routine is tricky. Look at line 194. W hat we want to
do here is put the count of how many times we have had to subtract 10000 (or
1000, or 100, etc.). But, we want to be able to print this count out, so we want
it in ASCII and we want to start at —1 instead of 0, because we always
subtract the number the first tim e -th a t doesn’t count. So the clever way of
generating a —1 in ASCII is to specify ’0’ (that’s zero, not oh) in single
quotes, which gives us the ASCII code for zero, and then we subtract 1 from
it: ’0’- l .
Yes, you can write this kind of arithmetic statement in the operand field of
an instruction. ASM will carry out the arithmetic operations for you, unless
they get too complicated.
You may want to use the BIN IDEC subroutine in other programs that you
write. If so, just plug it in where it’s appropriate. All you need to remember is
to define “conout” and “bdos” at the start of your program, so it will know
where they are.
159
Soul of CP/M®
We’ve actually used this subroutine in a program which is in the appendi

ces: the HEXIDEC program which converts a hex number typed in at the
keyboard into a decimal number on the screen. This is another useful utility
program (like DECIHEX in the last chapter) if you work with hexadecimal
numbers. Once you’ve typed BIN IDEC in for the LINES program, you
might as well juggle it around with your word processor so that you can use it
in HEXIDEC too.
You’ll notice a few other unfamiliar things in LINES: two new instructions
and a new assembler directive.
The “SH LD ” Instruction
This instruction is somewhat like the STA instruction, in that it stores the
contents of a register directly into memory. However, STA stored the 8-bit
contents of the A-register, while SHLD stores the 16-bit contents of the HL-
register. Note that this means that two bytes of memory have to be set aside,
whereas only one was needed for STA. To do this, see the DW directive
described next. The place where the two bytes are to go can either be named
with a hex address, or with a symbolic name, either of which are pointers to
the first byte of the two-byte “word.”
Examples:
shld 2011
shld penny
The “LHLD” Instruction
“LH LD ” is the opposite of SHLD, as you may have guessed. It takes the
16-bit value from the referenced memory location and loads it back into the
HL-register.
Examples:
lhld 2011
lhld whistle
The “DW ” Directive
We’ve already discussed the directive DB which defined a byte or number

of bytes to be specific 8-bit values. The DW directive is similar, except that it
160
Disk System Calls
Before SHLD 2011 is executed:
/ / 0100 Section of memory

containing program.
/ 0101
HL-register
A / 0102
63 F9 22
/
0103 SHLD 2011
11
/ 0104
20
/
/
///////////////////
lllllllllllllllllll
/ 2010
Section of memory
where constant will
/ 2011
be stored.
/ 2012
/
After SHLD 2011 is executed:
Section of memory
containing program.
SHLD 2011
Section of memory
where constant is
stored.
Fig. 5-4. The SHLD instruction.
161
Soul of CP/M®
Before LHLD 2011 is executed:

containing program.
0101
HL-register
z: 0102
0103 LHLD 2011
/ 0104
20
///////////////////
lllllllllllllllllll

where constant is
2011 stored.
FF
2012
A fter LHLD 2011 is executed:

containing program.
/
0101
/ 0102
22
/
0103 LHLD 2011
/
0104
20
/
/
llllllllllllllllll
llllllllllllllllll
where constant is
stored.
FF
/
2012
01
/
Fig. 5-5. The LHLD instruction.
162
Disk System Calls
defines a word (which is two bytes) to be a specific 16-bit value. In our pro
gram, we need two locations to store 16-bit values because all the registers
are already used: “ctr” to store the number of linefeeds counted so far, and
“ temp,” in BINIDEC, to store the original number in HL before we subtract
from it each time. Both of these storage areas are reserved by using DW
directives.
Like DB, DW can define either numerical or character constants. Several
constants can be used together if they’re separated by commas.
addrs dw OffOOh
crlf dw ODOAh
abchar dw 4142h
busy dw 4142h,4344h
series dw 1000,1001,1002,1003
Fig. 5-6 gives a flowchart showing the operation of LINES. Using this
chart and the descriptions of the various sections of the program given ear
lier, you should be able to to figure out what the program is up to. The
LINES program is given in Listing 5-3.
Listing 5-3. The LINES Program
; L I N ES - pr o gr a m t o p r i n t o u t number o f Li nes i n f i Le
000 F = openf equ Of h ; op en f i Le

0014 = readr equ 14h ; r e a d seq r e c o r d
0002 = conout equ 2h ; c o n so Le o u t p u t
0005 = odos equ 5h ;BD0S e n t r y
005C = fcb equ 5ch ; f i Le c o n t r o L bLock
0080 = dma equ 80h ;DMA a dd re ss
0080 = recsi z equ 128d ; s i z e o f r e c o r d i n DMA
007F = mask equ 7fh ; k i L Ls b i t 7
001A = eof equ 1ah ;e n d - o f- fiL e character
000A = Lf equ Oah ;Linefeed character
f
0100 org 10Oh
open f i Le, i n i t i a Li z e. read r e c o r d s
163
Soul of CP/M®
Fig. 5-6. Flowchart for the LINES program.
164
Disk System Calls
0100 0E0F mvi c , o p e n f ; op en f i Le

0102 115C00 Lxi d , f cb ; ( a d d r o f f c b i n de)
0108 116501 Lxi d , n f m e s s ; p u t "no f i Le" mess i n de
01 OB 3C in r a ; ad d 1 t o a , i f i t was f f .
010C CA4D01 jz n o f i Le ; now i t ' s 0 , so no such f i L e
/
01 OF 210000 Lxi h ,0 ; s e t h L to 0
0112 225301 shld ctr ; s a v e f o r Li ne c o u n t e r
/
0115 0E14 newrec mvi c,readr ; read r e c o r d
0117 115C00 Lxi d , f cb ; i n t o dma b u f f e r
011A CD0500 ca L L bdos
011D B7 ora a ; c h e c k a t o see i f e of
011E C24401 jn z done ; n o n - 0 i s e of
; c o u n t number o f L i n e f e e d s i n r e c o r d s t o r e d i n dma
¥
0121 218000 Lxi h,dma ; p u t dma add r i n hL as p o i n t e r
0124 0680 mvi b , r e c s i z ; p u t r e c o r d s i z e i n b as c o u n t e r
r
0126 7E newch mov a,m ; g e t c h a r a c t e r f rom dma b u f f e r
0127 E67F ani mask ;mask o f f h i g h b i t
0129 23 i nx h ;increm ent p o in te r
012A 05 dc r b ;decrement c h a r a c t e r counter
012B CA1501 jz newrec ;when c o un t i s 0 , g e t new r e c o r d
012E FE1A cpi e of ; i s t h e c h a r a c t e r an e of ?
0130 CA4401 jz done ; yes
0133 FEOA c pi Lf ; i s the c h a r a c te r a Linefeed?
0135 C22601 jnz newch ; n o, g e t n e x t c h a r a c t e r
0138 E5 push h ; s a v e a d d re s s which i s i n hL
0139 2A5301 LhLd ctr ; i n c r e m e n t Line c ount
013C 23 i nx h ; ( u s i ng h L)
013D 225301 sh Ld ctr
0140 E1 pop h ; g e t a dd re ss back i n h i
0141 C32601 jmp newch ;go get next c h a r a c te r
r
; e n d - o f - f i L e , o r no f i Le , so p r i n t r e s u L t and e x i t
/■
0144 2A5301 done Lh Ld ctr ; g e t c o u n t i n hL f o r b i n i d e c
0147 CD7501 ca L L b i n i d e c ; p r i n t number o f L i nes i n dec
014A 115501 Lxi d,Lmess ; s e t up " L i n e s " message
014D 0E09 n o f i Le mvi c , p r i n t s ; p r i n t message
165
Soul of CP/M®
014F CD0500 ca 11 bdos

0152 C9 ret ; b a c k t o CP/M
0153 ctr dw 0 ; lin e fe e d counter
0155 206C696E65Imess db ’ lin e s in f i l e . $ ’

0165 4E6F20736Fnfmess db ’No s o ur c e f i l e . $ ’
f
; b i n i d e c - c o n v e r t s b i n a r y number i n h i t o
; d e c i m a l , p r i n t s r e s u l t on s c r e e n .
0175 11F0D8 binidec lx i d , - 1 0 0 0 0 ; p r i n t number o f 1 0, 000s

0178 CD9401 ca ll s u b cn t
017B 1118FC lxi d , - 1 000 ; p r i n t number o f t housands
01 7E CD9401 ca 11 s u b cn t
0181 119CFF lxi d,-100 ; p r i n t number o f hundreds
0184 CD9401 cal I subcnt
0187 11F6FF lxi d,-10 ; p r i n t number o f t en s
018A CD9401 cal I subcnt
018D 11FFFF lx i d,-1 ; p r i n t number o f ones
0190 CD9401 c a ll s ub cn t
0193 C9 ret ; t h a t 1s a i l
f
0194 0E2F s u b c n t mvi c , ’0’-1 ; c h o l d s ASCII v e r s i o n o f c oun t
0196 0C sub2 in r c ; i n c r e m e n t count
0197 22B301 shld temp ;save hi
019A 19 dad d ; ad d neg c o n s t f ro m de t o h i
019B DA9601 jc sub2 ; l o o p t i l r e s u l t i n h i i s neg
019E 2AB301 lhld temp ; g e t l a s t pos v a l u e back i n h i
01A1 79 mov a,c
01A2 CDA601 cal 1 p cha r ; p r in t d ig i t
01A5 C9 ret
; p r i n t c h a r a c t e r i n a - r e g i s t e r on s cr ee n
01A6 D5C5E5 p c ha r push d ! push b ! push h ;save r e g i s t e r s
01A9 5F mov e,a ;ch a ra cte r in e
01 AA 0E02 mvi c,conout
01 AC CD0500 ca 11 bdos ; c a l l c o no ut r o u t i n e
01AF E1C1D1 pop h ! pop b ! pop d ; g e t r e g i s t e r s back
01B2 C9 ret
f
166
Disk System Calls
01B3 0100 temp dw 1
01B5 end
Try typing in LINES, assemblying it, and running it on some of your test
files. N ot bad, eh? Now when someone asks you how many lines are in some
program that you’ve written, you can tell them exactly, in about three
seconds.
LIFE ON THE FAST TRACK

In this chapter, you’ve learned the fundamentals of how your programs
communicate with C P /M ’s disk operating system. Our examples have shown
you how to read records and files from the disk. In the next chapter, you’ll
learn how to write to the disk. With this knowledge, we’ll go on to write the
STORE program, which will enable you to enter text files onto the disk. Then
we’ll learn how to delete files and, finally, go on to master the intricate R an
dom Read and Random Write system calls.
167
CHAPTER 6
W riting to the Disk
In the last chapter, you learned how to read records from a disk file. In this
chapter, we’re going to move on to writing records and files to the disk. To
write to the disk, you’ll need to know the “Make File,” “Write Sequential
File,” and “Close File” system calls. After explaining these calls, we’ll illus
trate their uses with an example program, STORE, which is a very simple
word-processing program. We’ll show you two versions of the program, one
of which uses the “Delete File” system call.
169
Soul of CP/M®
The next area that we’ll cover is that of “random ” records. Random, in this
case, doesn’t mean that the records contain just any old random words and
numbers, it means that it’s possible to read or write to any record in a file,
without starting at the beginning of the file and without reading all the
records until you get to the one you want. Thus, “random ”is the opposite of
“sequential.” We’ll describe the “ Random Read” and “Random Write” sys
tem calls, and then use them in a program (RANDYM OD) which will permit
the modification of any record in a file.
WRITING A SEQUENTIAL RECORD
In this section, we’re going to describe the three new system calls that are
necessary for writing a sequential record: Make File, Write Sequential, and
Close File. Since these calls are all necessary to do the writing operation,
we’re going to describe each of them before we go on to give an example
program.
MAKE FILE
MAKE FILE FUNCTION 22 (dec) = 16 (hex)
Enter with: REG C = 16 (hex)

On return: REG A = Directory Code
Comments: Directory Code = 0, 1, 2, or 3 if file made successfully.

Directory Code = FF (hex) if disk directory is full.
In the last chapter, you learned that to read a record from a file, you had to
first “open” the file using the “Open File” system call. This was necessary,
first to tell the BDOS routines of C P /M what file you wanted to read the
record from (the file name passed in the FCB), and secondly, to tell BDOS to
determine where the various records of the file were so that they could be
easily accessed by subsequent Read system calls. BDOS then wrote the loca
tions of the records in the FCB in the area called “allocation units.”
170
Writing to the Disk
When we want to write a new file, theprocedure issomewhatdifferent.

Since the file does not yet exist, it cannot be “opened”but, instead, must be
(as Digital Research puts it) “made.” To do this, we use the “ Make File”
system call. This call records the new file name in the disk directory so that
BDOS knows what to do with subsequent “Write Record” system calls.
Using “Make File” assumes that the file whose name is being “made” doesn’t
already exist. If there’s any chance that it might exist, then it is the program
mer’s responsibility to delete the file before trying to “make” it. We’ll
describe the “Delete File” system call later.
The Make File call is similar in format to Open File. The returned direc
tory code is different, in that a value of F F hex (meaning “unsuccessful”) is
returned only if the directory is fu ll-a rare occurrence. Otherwise, a 0, 1,2,
or 3 is returned as in Open File.
A code fragment for using this call might be:
m vi C,16 Set up for Make File.

L xi d, 5C Set FCB address.
call 5 Call BDOS.
We’ll show how this code fragment is used when we get to the STORE pro
gram.
WRITE SEQUENTIAL RECORD
WRITE SEQUENTIAL RECORD FUNCTION 21 (dec) = 15 (hex)

Comments: Directory Code — 0 if write is successful.

Directory Code = nonzero if disk is full.
Before the “Write Sequential Record” call can be used, several conditions
must be met:
1. The nam e of the file to be w ritten m ust be in the FCB.
171
Soul of CP/M®
2. The file must have been initialized with a Make File system call. (It is
also possible to use the Write Sequential callwith an existing file that
has been initialized with an “Open File” system call.This isdescribed
later in this chapter.)
3. The record to be written must be in the 128-byte (128 hex) DMA
buffer. If the DM A buffer is not in the usual (or “default”) position at
80 hex, a Set DMA system call must have been issued to put it in the
appropriate place.
The format of the Write Sequential system call is similar to the Read
Sequential Record call. The directory code returned in the A-register is dif
ferent, in that a nonzero value indicates that the disk is full, a fairly rare
occurrence and one we won’t worry about with our small sample programs.
A typical section of code used to write a sequential record might be:
m vi C, 1 5 Set up for Write Sequential.

L xi d,5c Set FCB address.
Ca LL 5 Call BDOS.
Like the Read Sequential system call. Write Sequential writes to the first
record of the file the first time that it is called, writes to the second record the
second time it is called, and so on. (That’s why it’s called “ sequential.”) How
does BDOS “remember” what record it’s supposed to write to next when it
executes this call? To understand this, we’ll need to look somewhat more
deeply into the workings of the FCB.
The “ CR” Byte in the FCB
Look back at the diagram of the File Control Block in the last chapter
(Fig. 5-1). The “cr” byte is number 32 in the FCB, and is located at memory
location 7C (if the FCB is in its usual place). The purpose of this byte is to
keep track of what record is currently being written to (or read) by a sequen
tial write (or read) operation. Thus, when you execute a call to the Sequential
Write system call, the record in the DMA buffer will be written to the record
number that is in this cr byte. After either a write or a read operation, the
number in cr is incremented so that the next record will be written to the next
record in order.
This byte is typically set to zero by the user at the same time that the file is
opened (or “made”), so that the first record will be written into record 0, the
second into record 1, and so on.
172
Writing to the Disk
Those of you who have caught on to the hexadecimal numbering system

will now be wondering what happens if a file has more than 256 records,
since that’s all that can be described in a single byte. The answer is that when
the cr byte “overflows” (that is, goes from 127 to 128 decimal, which is from
7F to 80 hex), then a new “extent” is automatically opened. Why doesn’t this
overflow take place at 255 records, instead of 127? The reason for this action
has to do with allocation units, sectors, and the way records are stored on the
disk, a topic which we’ll cover later.
Extents
The next question is, “W hat’s an extentl” An extent is 128 records. Extents
are necessary because of the way C P /M keeps track of where the various
records of a file are stored on the disk. In general, a programmer doesn’t need
to know too much about this process, since C P /M takes care of it more or
less automatically. Again, we’ll postpone further discussion of these topics
until the next chapter, where we’ll talk about the disk directory.
For the time being, just keep in mind that the cr byte in the FCB is incre
mented each time a record is read or written sequentially, until the value in cr
reaches 127 decimal. At this point, a new extent is opened. This means that
the value in cr is reset to 0 and another byte in the FCB is incremented. This
is the “ex” or “current extent” byte, which is number 12 and is located at
address 68 hex. This byte, too, is normally set to zero when a file is first made
or opened for sequential operations.
CLOSE FILE SYSTEM CALL
CLOSE FILE FUNCTION 16 (dec) = 10 (hex)

Comments: Directory Code = 0,1,2,3 if file closed successfully.

Directory Code = FF (hex) if file name not in directory.
173
Soul of CP/M®
After you have opened or “made” a file and started writing to it with Write
Sequential system calls, C P /M ’s BDOS takes care of deciding where on the
disk each record is going to be written. This information, which constitutes a
map of the disk showing where the various records of a file are stored, is kept
in memory as long as the file is “open” ; that is, currently being written to. If,
after writing a bunch of records, you ju st turned off your computer and
walked away, this “mapping” information would be lost forever and, then,
when you powered up again and tried to read the file from the disk, C P/M
wouldn’t know where to find it. It’s the purpose of the Close File call to make
sure this doesn’t happen.
When the Close File call is executed, C P /M takes the mapping informa
tion, which is stored temporarily in memory, and writes it onto the disk in a
region called the “disk directory.” When you next try to read this file, BDOS
will look for the file name in the directory on the disk and will write the
information it finds there back into memory. This is done by the Open File
system call.
The moral of all this is that after you have finished writing records to a file,
you had better close it, or you will never be able to read it back in. You don’t
have to close a file after reading it, however, because the directory has not
been changed. Thus, the directory information on the disk is still valid, even
though the directory in memory may be destroyed.
The format of the Close File call is similar to that of an Open File. Here’s a
section of code used to close a file:
m vi C,10 Set up Close File.

Lxi d, 5C Set FCB address.
caLL 5 Call BDOS.
PROGRAM TO WRITE A SEQUENTIAL RECORD
Now we’re ready to put together the three system calls that we’ve just
learned into a real program to write something to the disk. Here’s the pro
gram:
-a100
0100 mvi c, 1a Set DMA address to 400.
0102 Lxi d ,4 0 0
0105 ca L L 5
0108 mvi c,16 Make file.
174
Writing to the Disk
010A Lxi d,5c

010D ca L L 5
0110 mvi c , 15 Write file.
0112 Lxi d,5c
0115 ca L L 5
0118 mvi c,10 Close file.
011A Lxi d,5c
0 1 1D ca L L 5
Before we can execute this program from DDT, however, there are a number
of things that we need to do.
First, make sure that there is no file on your disk with the name
“newfile.txt” . Next, we need to insert the name of the file that we’re going to
be creating into the FCB. We’ll do this using the “i” operation. Thirdly, we
need to put something into the DM A buffer so that we can write it onto the
disk. This is a little cumbersome to do from DDT, but we’ll try it just to get
the feeling of what the routine is doing. For this, we’ll use the “s” operation.
Type in the program in DDT, save it as “ testl05.ddt” , and return to D D T
with the program (“A > d d t testl05.ddt”). Then, type in the following:
- i newf i L e . t x t Put name of file in FCB.
- s4 0 0 Fill stuff into DMA.

0400 08 41 1
0401 DC 42
0402 D3 43 ► ASCII values for text: “ABCDE”
0403 01 44
0404 67 45 .
0405 3A 0A Linefeed.
0406 00 0D Carriage return.
0407 53 1A End-of-file mark. Don’t forget this!
0408 9F
------------------ These are the numbers you type in.
-------------------------- This is junk that was in the buffer already.
We won’t fill in all 128 decimal bytes of the DMA, since that would take too
long using the “s” operation. (Although you could fill the whole DMA buffer
with the same character using the “f” option.)
175
Soul of CP/M®
We end our message with a carriage return and a linefeed so that when we
print out the record it won’t be overprinted by the next line. And, most
importantly, the last character of our record is an end-of-file character: 1A
hex. This is necessary to tell BDOS that the record is finished, when we go to
read it back.
Now run the program and then exit to C P /M and see if the file is in the
directory:
-g100
*0120
-gO
A>dir n e w f i l e . t x t
A: NEWFILE.TXT
So far, so good. Now, let’s see what’s really in the record, using the C P /M
built-in TYPE function. (We can’t use TYPE2 here because it isn’t sophisti
cated enough to see the end-of-file mark in the middle of the record and it
will print out all the junk in the DMA buffer following the “ABCDE”
message.)
A>type n e w f i L e . t x t
ABCDE
A>
There it is! It may not be War and Peace, but it is the very first file that
you’ve written to the disk with your own program.
There’s another way to examine the contents of newfile.txt to see if it’s
really there. Call up D D T along with newfile.txt:
A>ddt n e w f i l e . t x t
When D D T is loaded, dump the DMA buffer, which is where the first
record of a file is loaded when the file is called in with DDT:
-d 8 0,ff
0080 41 42 43 44 45 0A 0D 1A 51 01 CD 8C 00 C3 51 01 ABCDE.. . Q............Q.
^ ..........■! || | ,T —...... J I w >
First record of newfile.txt ASCII version
176
Writing to the Disk
There it is! This is a good way to examine files that have only one short
record.
Now we’re going to expand this little program into one that you can actu
ally use as a mini word processor.
STORE PROGRAM-STORES TEXT IN FILE

The program we’re about to describe accepts text typed in on the keyboard
and puts it into a file. Since we’ll assemble the program with ASM and store
it on the disk as a COM file, you can execute it directly from C P/M .
A>store n e w f i l e . t x t
T h i s i s t he Li ne t h a t you t y p e i n , t o be s t o r e d on d i s k
Type a n o t h e r Line i n t o n e x t r e c o r d .
A> k : Terminate lines with a “return”.

Typing “return” at the beginning of a line ends the program.
When the program is executed, it first finds out if the file name you typed
in following “store” exists or not. If it does, the program will read (without
printing) to the end of the file, wait for you to type something in, and then
write it at the end of the file. If the file doesn’t exist, the program opens a new
file with that name (using the Make File system call), waits for you to type
something in, and then writes it at the beginning of the file.
We have made the restriction that you can only type in one line—no more
than 80 characters—at a time. This avoids a lot of complexity about how to
handle “returns” embedded in the text. At the end of your line, you must
press “return” to tell the program that you’ve finished. It will then write the
line to the disk as a single record. If you press “return” without writing any
thing, the program will assume that you’ve finished with the entire file and
will close the file and exit to C P/M .
177
(
Soul of CP/M®
Listing 6-1. The STORE Program

• ************************************************
;s to re -P ro g ra m to s t o r e t e x t in a f i l e .
; S t o r e s one Li ne o f t e x t , t e r m i n a t e d
; by a r e t u r n , p er r e c o r d . Type r e t u r n
; to exi t .
000F = openf equ Of h ; op e n f i l e

0016 = makef equ 16h ;make f i l e
000A = reads equ Oah ;read s tr in g
0015 = w rite r equ 15h ; w r i t e s e q u e n t ia l record
0014 = readr equ 14h ;re a d s e q u e n t ia l record
0009 = p rin ts equ 9h ;p r in t strin g
0010 = closef equ 10h ;close f i l e
0002 = conout equ 2h ; c o n s o le out
0005 = bdos equ 5h ; o p e r a t i n g system
005C = fcb equ 5ch ; f i le c o n t r o l b lo ck
0080 = dma equ 80h ;dma b u f f e r
00FF = de I equ Of f h ;d e le te character
000A = If equ Oah ; lin e fee d
000D = cr equ Odh ;c a rria g e return
f
0100 org 100h

F
; t r y t o open f i l e (name must a l r e a d y be i n f c b )

0100 0E0F mvi c,openf ; op en f i l e
0102 115C00 lxi d , f cb
0108 3C in r a ; i f a was f f , now i t ' s 0
0109 C25B01 jnz a lex ; n o t 0 , so f i l e e x i s t s
F
; f i l e does n o t a I ready e x i s t , so we1 11 c r e a t e i t

010C 0E16 mvi c, ma kef
010E 115C00 lxi d , f cb
0111 CD0500 ca 11 bdos
; f i L L t h e dma b u f f e r w i t h d e l e t e marks
0114 218000 newrc lx i h,dma ; p u t dma a dd r es s i n h I
0117 0680 mvi b ,1 28d ; p u t c o un t i n b
0119 36FF lo op mvi m, d e l ; s t o r e d e l e t e i n memory
178
Writing to the Disk
011B 23 i nx h ; i n c r e m e n t hL p o i n t e r
011C 05 dcr b ; d e c r e m e n t count
011 D C21901 jnz Loop ; n o t done y e t
r
; p r i n t a Linefeed
0120 0E02 mvi c,conout
0122 1E0A mvi e , Lf
ł
;read ch aracters in to b u f f e r f rom keyboard
0127 3E50 mvi a, 80 d ; s e t c o un t t o s cr ee n w i d t h
0129 327E00 sta dma-2 ; ( s trin g buffer s ta rts 2
012C 0E0A mvi c,reads ; b y t e s b e f o r e dma
012E 117E00 Lxi d,dma-2 ; b u f f e r , t o Leave room f o r
0131 CD0500 ca L L bdos ; ma x- co unt and c o u n t )
r
; f i nd o u t i f b u f f e r i s empty-i f so, exi t
0134 3A7F00 Lda dma-1 ; g e t number o f ch ar i n p u t
0137 B7 ora a ; i s i t 0?
0138 CA5201 jz f i n i to ; yes
; i n s e r t c r and I f i n b u f f e r f o l L o w i n g t e x t
013B 5F mov e , a ; c h a r a c t e r c o un t i n de
013C 1600 mvi d,0 r
013E 218000 Lxi h,dma ;dma a dd r es s i n h L
0141 19 dad d ; ad d c o un t t o a d d r , p u t i n hL
0142 360D mvi m,cr ;s to r e ca rriage re turn
0144 23 i nx h ;increm ent p o in te r
0145 360A mvi m, Lf ; s t o r e Linefeed
; w r i t e record to d is k
0147 0 E1 5 mvi c , w r i t e r ; w r i te i t
0149 115C00 Lxi d , f cb
014C CD0500 ca L L bdos
014F C31401 jmp newr c ; g o read n e x t r e c o r d
;c lo s e f i l e before e x it in g
0152 0E10 f i n i t o mvi c,cLosef
0154 115C00 Lxi d , f c b
015A C9 ret ; b a c k t o CP/M
: f i l e a l r e a d y e x i s t s , so read t i l l EOF
179
Soul of CP/M®
015B 0E09 a Lex mvi c,p rin ts ; p r i n t message

015D 117201 Lxi d , a Lmess
0163 0E14 read2 mvi c,readr ;re a d record
0165 115C00 Lxi d , f cb
016B B7 ora a ; e n d - o f - f i L e (a n o t 0 ) ?
016C CA6301 jz read2 ; n o , so read n e x t r e c o r d
016F C31401 jmp newrc ; y e s , so go w r i t e new reco
f
0172 5465787420aLmess db ’T e x t wi LL be added t o f i L e . ’, c r , Lf

f
0190 end
Type the program in with your word processor, assemble it, and try it out,
before you read the explanation of how it works. This will give you an idea
what the program is supposed to do, which will be helpful in understanding
the following comments. Fig. 6-1 is a flowchart of the program’s operation.
We will first try to open the file. If it already exists, we jum p down to the
“alex” label at line 15B and print the following message to the user: “Text
will be added to file.” This will alert her to the fact that she’s not writing into
a new file. Then, we read the first record of the file and check to see if there’s
an EOF. If not, we read the next record and check again. If there is an EOF,
we go back to line 114, where we would have started if the file had not existed
in the first place.
Since our input lines are 80 character or less, and the records we’re writing
into are 128 characters, we’re going to have left-over space in the record. We
don’t want these extra characters to appear on the screen, or cause the printer
to do anything weird if we want to print out the file, so we want to ensure
that the rest of the buffer after our typed-in line is filled with some harmless
character. A good harmless character, and one that we can send to the printer
without causing any action at all, is the “rubout” character, which is 7F hex
(FF hex if we include the high-order bit). The section of code from 114 to
11D fills the entire DM A buffer with rubouts before any characters are typed
in by the user, thus ensuring that there will be no printable garbage following
the text.
We do a linefeed and, then, at line 127, read the characters from the key
board into the DMA buffer. Since we’re not using DDT, we can put the
DMA buffer where it’s supposed to go at 80 hex (its default address), which
we tell the program about with an EQU directive. We use the Read String
180
Writing to the Disk
system call, which requires that the maximum count of words be set two
addresses before the first character, and which fills in the number of charac
ters that are actually read in from the keyboard at the address that is one
byte before the first character.
If the buffer is empty after this call, we know the user is done and we close
the file and exit to C P/M . Otherwise, we write a carriage return and linefeed
into the buffer following the text, so that each record typed in doesn’t over
print the one before it. Then, we write the record to the disk and go back up
to “newrc” to get another record from the keyboard.
181
Soul of CP/M®
Your Own Text Editor
Now you can type in files using STORE and can read them out again using
TYPE2. As text editors go, this may not be too fancy, but it does give you the
satisfaction of having written it all yourself and, we hope, of understanding
how the programs work.
Use STORE to create a file called “sample.txt”, which contains 10 or 12
records, by typing in 10 or 12 lines one after the other (separated only by
single carriage returns). Check that the whole record is there, using TYPE2.
We’ll use this file later to experiment with the Random Read and Random
Write system calls.
DELETE FILE SYSTEM CALL
DELETE FILE FUNCTION 19 (dec) = 13 (hex)

Comments: Directory Code = 0,1,2,3 if file deleted successfully.

Directory Code = FF (hex) if filenot found.
This system call is largely self-explanatory. When executed, it modifies the

directory entry of the file so that C P /M ’s BDOS knows that it’s erased.
BDOS will then release the disk space occupied by the file so that it can be
used for other files when they are written.
Modifying the STO RE Program
Here’s an example of how this call can be used. In the STORE program,
we assumed that, if a file already existed, the user would want to add the
records that he typed in to the file. We could have made another assumption:
that he wanted to erase whatever was in the file and start over with what he
was typing in.
Let’s use the Delete File system call to modify the STORE program to do
this. Do the following:
182
Writing to the Disk
1. Make a copy of STORE using PIP. Call it “ STORE2” .
A>pi p s t o r e 2 . a s m = s t o r e . a s m
2. Add this statement to the beginning of STORE2:
d e file equ 13h ;d e le te file
3. Remove the program lines from 100 to 109 and substitute the following:
;d e le te t he f i Le
mvi c , d e f i Le
Lxi d,fcb
caLL bdos
4. Remove lines 15B through 172, including the “almess” message.
Fig. 6-2 is the flowchart for the resulting STORE2 program.

Assemble STORE2 and try running it. When you write to an existing file,
everything that was in it disappears, and only your new input is left. This
works because if the file wasn’t there to begin with, the delete will have no
effect, and if the file was there, it will be deleted. Either way, it won’t be there
when we get to the “ Make File” system call in line 10C. Now you have two
versions of the STORE program, one which will add text to a file and one
which will write over the old text.
RANDOM RECORDS
If you want to read or write a file, starting at the first record and going on
until you come to the end, then the “ Read Sequential” and “W rite Sequen
tial” system calls which we have already described are just what you need.
But suppose you want to read a record that is in the middle of a file? Or, you
want to modify a record in the middle of a file? You can do it using the
sequential read and write calls, but it’s a little difficult. W hat’s difficult about
it? Mostly the way that the record numbers are specified in the FCB.
As you recall from the last section, there is a special byte in the file control
block to indicate what record is currently being written. When 127 decimal
records have been written, this byte “overflows” and is reset to 0, and another
byte, the “current extent” byte, is automatically incremented. The use of two
separate bytes to specify what record we’re talking about makes disk access to a
183
Soul of CP/M®
Fig. 6-2. F low chart o f the STORE2 program .
particular record somewhat more awkward than it might be. For instance, if we
had a program that wanted to read the 300th record in a file, it would have to
first determine what “extent” this record was on, by dividing 300 decimal by 128
decimal. Since 300 divided by 128 is 2, with a remainder of 44, our program
would have to set the extent byte to 2 and the current record byte to 44 decimal
184
Writing to the Disk
(2C hex). This isn’t impossible, but it does complicate things, so Digital
Research (starting with release 2.0 of CP/M ) has provided a set of system calls
which use a single 16-bit value to specify the record number.
Look back at the map of the FCB in the last chapter. Bytes 33, 34, and 35
(locations 7D, 7E, 7F) constitute the “random record num ber” and are
called, respectively, rO, rl, and r2. This is shown in Fig. 6-3. The last byte, r2,
is not used in C P /M systems (although it is used by M P/M ). In C P /M sys
tems, it must always be set to zero, otherwise error messages will result. The
bytes rO and rl constitute the 16-bit record value, with the rO byte represent
ing the least-significant byte and rl the most-significant byte.
However, using random reads and writes requires one more step than sequen
tial reads and writes. The program must place the 16-bit number of the record
to be accessed into bytes rO and rl before the read or write takes place.
We’ll briefly describe the Read Random and Write Random system calls
and, then, go on to show how they’re used in the RANDYM OD program.
READ RANDOM SYSTEM CALL
READ RANDOM FUNCTION 33 (dec) = 21 (hex)

On return: REG A = Return Code
Comments: Return Code = 00 if read was successful.

Return Code = nonzero if error occurred.
When BDOS executes this call, it first looks at the record number in bytes
rO and rl to see what record the program wants to read. It then figures out
what “extent” the record is in, and the record number in the extent, and sets
7D 7E 7F
rO r1 r2
least- most-
significant significant
byte byte
always 0
16-bit record number
Fig. 6-3. The “ random record number.'
185
Soul of CP/M®
these bytes in the FCB. Then, it reads the record just as the Sequential Read
system call did.
An im portant difference between random and sequential system calls is
that the random calls do not automatically advance the record number each
time they are called. So, if you do a random read and, then, do another ran
dom read, you’ll be reading the same record twice unless your program has
incremented the random record number in rO and rl before the second read.
Also note that, since Random Read has automatically set the current
extent and current record bytes in the FCB, you could then do a Sequential
read to read the same record again, followed by subsequent records, if you
wished. This gives you the capability to plunge into the middle of a record
with random access and, then, read a number of records, starting at that
point, with sequential access.
The “Return Code” returned in the A-register following this call can actu
ally have a number of nonzero values, depending on what type of error has
occurred:
01 attempt to read unwritten data block.

04 attempt to read unopened extent.
06 attem pt to read past end of disk (byte r2 not set to zero).
Here’s a short D D T program for reading a random record:
-a100
0100 mvi c,1a Set DMA to 400.
0102 Lxi d ,4 0 0
0105 ca L L 5
010A Lxi d,5c
010D ca L L 5
0110 mvi c,21 Read random.
0112 Lxi d,5c
0115 ca L L 5
0118 mvi c,2 Print error code.
011A adi 30
011 c mov e,a
011 D ca L L 5
0120 rst 7 Return to DDT.
Save this program as “ testl06.ddt” and then bring it back into memory
with DDT. Use the “i” command to set the filename of a file that you know
186
Writing to the Disk
has a number of text records in it, such as the “sample.txt” file that we sug
gested you write in the section on the STORE program. Then, use the “s”
command to set a record number into rO rl that you know is in the file. In
other words, don’t make the record number so large that it doesn’t exist; if
“sample.txt” is 12 records long, put in a number less than that.
A>ddt t e s t 1 0 6 . d d t
- i sample, t x t A file you know has more than 3 records.

-s7d
007D 00 03 Least-significant two digits.
007E 00 00 Most-significant two digits.
007F 00 00 Always zero.
0080 00
------------ This is what you type in.

--------------------This is junk left over.
Execute the program and then look at the DMA with a “d400” to see
what’s been read in. Now, change the rO byte in 7D to some other record
number, like a 2 or a 4. If you have file that you know is longer than 256
records, you can change both rl and rO. For record number 350, for example,
you’d convert to the hex number 015E and then put 5E into rO (location 7D)
and 01 into rl (location 7E).
Read a number of records by changing the record number and see what
happens. Ordinarily, the “return code” printed out by this program will be
zero, but if you try to read a nonexistent record, you’ll get one of the codes
referred to above.
WRITE RANDOM SYSTEM CALL
WRITE RANDOM FUNCTION 22 (hex) = 34 (dec)

On return: REG A = Return Code
Comments: Return Code = 00 if write was successful.

Return Code = nonzero if error occurred.
187
Soul of CP/M®
This call is similar to the Read Random call except, of course, that the
record to be written must already be in the DM A buffer. The error codes are
the same except that there is a new error, 05, which indicates that a record
cannot be written due to directory overflow.
As with Random Read, the current record and current extent bytes are
changed to correspond to the random record number given, but none of these
numbers is incremented.
Writing to a New File
Here’s a short D D T program showing how this call can be used. This pro
gram assumes that we want to create a new record, so it uses the Make File
system call. N ote that it’s necessary to close the file after writing to it.
-a100
0100 mvi c,1 a Set DM A to 400.
0102 Lxi d,400
0105 ca L L 5
0108 mvi c , 16 Make file.
010A Lxi d,5c
010D ca L L 5
0110 mvi c,22 Write random.
0112 Lxi d , 5c
0115 ca L L 5
0118 mvi c,2 Print return code.
011A adi 30
011 c mov e,a
011 D ca L L 5
0120 mvi c,10 Close file.
0122 Lxi d , 5c
0125 ca L L 5
Save the program as “test 107.dd t” and then load it back in with DDT. Use
the “s” command to fill in the DM A buffer from 400 to 47F with whatever
ASCII characters you want. Since we’re starting a new file, we assume we’re
going to write to the first record, whose number is 0000, so use “ s” again to
fill in 0 values in rO, r l, and r2. Use the “i” command to set the name of the
new text file (you can call it newfile2.txt) into the FCB and, then, run the
program. Exit from D D T and check the dirctory to see if the new file is there.
188
Writing to the Disk
Print it out using “TYPE.” It should be the same as whatever you put in the
DMA buffer.
Writing to Existing Record
If we want to write to an existing record, we need to use the Open File

system call, instead of Make File, just as we did with sequential writes. Here’s
how we modify our program to do that:
- a 1 00
0100 mvi c , 1a Set DMA to 400.
0102 Lxi d,400
0105 ca L L 5
0108 mvi c,0f Open file.
010A Lxi d,5c
010D ca L L 5
0110 mvi c,22 Write random.
0112 Lxi d,5c
0115 ca L L 5
0118 mvi c,2 Print return code.
011A adi 30
011C mov e,a
011D ca L L 5
0120 mvi c , 10 Close file.
0122 Lxi d,5c
0125 ca L L 5
Save this as “testl08.ddt” and try it out, using the same steps as previously.
As with the Read Random system call, you must be sure that the record
number you put in rO and rl actually exists.
RANDYMOD-PROGRAM TO MODIFY A RANDOM

RECORD
The following program incorporates both the Random Read and the Ran
dom Write system calls. You call it from C P /M by specifying the name of the
file you want to modify:
A>randymod t e s t f i l e . t x t
189
Soul of CP/M®
The file name must be one which exists, or the program will print “N o such
filename,” and return to C P/M . The program now waits for you to type in
the record number, in decimal, that you wish to modify in the file. Make sure
that this record exists, because the program does no checking to make sure it
has been given a valid record.
You can use the “sample.txt” file that you created in the section on the
STORE program for this. If “sample.txt” is 12 records long, set the record
number you want to modify to a number less than that: say 3. Once the
program has read the record, it prints it out on the screen, and then asks “OK
to modify (y/n)?” If you answer anything other than “y”, the program
returns to C P/M . Otherwise, the program waits for you to type something in.
As with the STORE program, you must type in a line that is less than 80
decimal characters long and terminate the line with a “return.” Listing 6-2
shows the RANDYM OD program.
Next, in Fig. 6-4, we have the flowchart for the RANDYM OD program.
The listing for RANDYM OD should be fairly easy to follow since it con
sists mostly of routines and code fragments that have been covered before.
However, there are one or two unusual items.
We can’t put the DMA buffer at the usual place from 80 hex to FF hex
because we want to use the Read String system call to get the input from the
user. Why doesn’t this work? Because Read String uses two bytes immedi
ately preceding the actual buffer: one to store the maximum number of char
acters and the second to store the actual number of characters that are typed
in. Unfortunately, the two bytes immediately preceding 80 hex are 7E and
7F, which are the bytes used to store rl and r2 of the random record number.
We could move the FCB, or move the DMA, or use a different way to read
the characters from the keyboard, but moving the DMA seems easiest, so
that’s what we do in lines 100 to 105. We move it to a place that we label
“dm a” at the end of the program, which we specify as 128 decimal bytes
using the “ds” directive.
Notice how we do arithmetic with the symbolic labels in the address field
in lines 117 and 11C. We know that byte rO is byte number 33 decimal in the
FCB, so instead of figuring out what this address is and writing it in the
address field, we write “fcb + 33d” . The assembler takes care of determining
where “fcb” is, adding 33 to it, and translating the result into an address for
the “shld” instruction to store in rO and rl. A similar process takes place for
the “sta” instruction in line 11C.
As we explained in the section on the STORE program, it’s necessary to fill
the DMA buffer with delete marks before accepting input to it from the key
board, so that any junk remaining in the buffer between the end of the user’s
190
Writing to the Disk
Listing 6-2. The RANDYMOD Program

****************************************************
RANDYMOD-Used t o m o d i f y a r e c o r d s e l e c t e d a t random i n a
f i l e . Type f i l e n a m e f o l l o w i n g " r a n d y m o d " , and
t hen t y p e r e c o r d number when program l o a d s ) .
****************************************************
000F = openf equ Of h ; op en f i l e

0021 = randr equ 21 h ; random f i Le read
0022 = randw equ 22h ; random f i l e w r i t e
0009 = p rin ts equ 9h ;p r in t strin g
0002 = conout equ 2h ;c o n s o le out
0001 = coni n equ 1h ;c o n s o le in
000A = reads equ Oah ; read s t r i n g
0010 = closef equ 10h ; c Lose f i Le
005C = fcb equ 5ch ; f i le c o n t r o l b lo ck
0005 = bdos equ 5h ; o p e r a t i n g system e n t r y
00FF = de 1 equ Of f h ;d e le te character
000A = If equ Oah ; Linefeed
000D = cr equ Odh ;c a rria g e return
r
0100 org 100h
r
; p u t dma b u f f e r a t end o f program ( c a n ' t be a t 8
; o r c o u n t s used by " p r i n t s " w i l l
; o v e r w r i t e r1 and r 2 )
0100 0E1A mvi c, 1ah ; s e t dma a dd re ss
0102 11EB01 Lxi d,dma
0105 CD0500 c a l L bdos
/
; op en f i Le (name must a l r e a d y be i n f c b )
0108 OEOF mvi c , o p e n f
01OA 115C00 l x i d , f cb
01 OD CD0500 ca LI bdos
0110 3C in r a ; i f a was f f , now i t ' s 0 ,
0111 CA8701 jz nof i ; so no such f i Le name
r
; g e t r e c o r d number f rom k e y b o a r d , s t o r e i n f c b
0114 CD9B01 ca LI d e c i b i n ; r e a d dec number, c onver
0117 227D00 sh Ld f cb + 33d ; s t o r e i n rO, r1 o f f c b
011A 3E00 mvi a , 0 ; z e r o o u t r2 o f f c b
Soul of CP/M®
011 C 327F00 s t a f c b + 35d

0 1 1 F CD9001 ca ll p c rlf ; p r i n t carriage return
r
; r e a d random record
0122 0E21 mvi c,randr
0124 115C00 Lxi d ,fcb
0127 CD0500 ca LL bdos
; d i s p L a y c o n t e n t s o f dma b u f f e r
012A 21EB01 Lxi h,dma ; s e t p o i n t e r i n hL
01 2D 0680 mvi b ,128d ; s e t c o un t i n b
0 1 2 F 7E d Loop mov a,m ; g e t c har f rom b u f f e r
0130 CDB701 ca L L pchar ; d i spLay i t
0133 23 i nx h ; i ncrement hL
0134 05 dcr b ; d e c r e m e n t b - done?
0135 C22F01 j n z dLoop ; not yet
;make s u re u s e r wants to modify i t

0138 0E09 mvi c , p r i n t s ; p r i n t question
013A 11C401 Lxi d,qmess
013D CD0500 ca L L bdos
0140 0E01 mvi c , c o n i n ; g e t 1 - c h a r response
0142 CD0500 caLL bdos
0145 FE79 c pi 'y ' ;is i t "y" ?
0147 CO rnz ; n o, so back t o CP/M
0148 CD9001 caL L p e r L f ; y e s , c a r r y on
; f i LL t h e dma b u f f e r w i t h d e L et e marks
014B 21EB01 Lxi h,dma ; p u t dma b u f f e r a d d re s s i n h L
014E 0680 mvi b ,1 28d ; p u t c o un t i n b
0150 36FF f Loop mvi m,deL ; s t o r e d e Le te i n memory Loc i n h i
0152 23 inx h ; i n c r e m e n t hL p o i n t e r
0153 05 dcr b ; d e c r e m e n t c oun t
0154 C25001 jnz f Lo op ; n o t done y e t
/
;read characters in to b u f f e r f rom k eyboard
0157 CD9001 cal L perLf ; p r i n t Linefeed
015A 3E50 mvi a ,8 0d ; s e t max c o un t t o s c r e e n w i d t h
015C 32E901 s t a dma-2 ; ( r e a d s t r i n g b u f f e r s t a r t s two
0 1 5 F 0E0A mvi c , r e a d s ; b y t e s b e f o r e s t a r t o f dma
0161 11E901 Lxi d,dma-2 ; b u f f e r t o Leave room f o r
0164 CD0500 ca L L bdos ; ma x- co unt and c o u n t )
192
Writing to the Disk
; i n s e r t c r and Lf i n b u f f e r f oL L ow in g t e x t
0167 3AEA01 Lda dma-1 ; g e t number o f c h ar s t y p ed i n
016A 5F mov e , a ; p u t i t i n de
016B 1600 mvi d , 0 /
016D 21EB01 Lxi h,dma ;dma a d d re s s i n hL
0170 19 dad d ; ad d c o u n t t o a d d r , r e s u L t i n hL
0171 360D mvi m , cr ;s to re carriage return
0173 23 i nx h ;increment p o in te r
0174 360A mvi m, Lf ; s t o r e Linefeed
; w r i t e record to d is k
0176 0E22 mvi c , r a nd w
0178 115C00 Lxi d , f c b
017B CD0500 ca L L bdos
;cLose f i L e before e x it in g
017E0E10 mvi c,cLosef
0180 115C00 Lxi d,fcb
0183 CD0500 caLL bdos
0186 C9 ret ; b a c k t o CP/M
; n o such f i Le name: p r i n t message and e x i t

0187 0E09 nofi mvi c , p r i n t s
0189 11D901 Lxi d , n f me s s
018C CD0500 caLL bdos
018F C9 ret ; b a c k t o CP/M
;subroutine t o p r i n t c a r r i a g e r e t u r n and L i n e f e e d
0190 3E0D pcrLf mvi a,cr ; p r i n t carriage return
0192 CDB701 caLL pchar
0195 3E0A mvi a,Lf ; p r i n t Linefeed
0197 CDB701 caLL p cha r
019A C9 ret
; d e c i b i n - s u b r o u t i n e t o read dec number from

; k e y b o a r d , c o n v e r t t o b i n a r y i n HL
019B 210000 d e c i b i n Lxi h,0 ; s e t hL t o 0

019E E5 newdig push h ; s a v e h i ( c o n i n uses i t )
019F 0E01 mvi c,conin ;g e t character
01A1 CD0500 ca L L bdos
01A4 E1 pop h ; r e s t o r e hL
01A5 D630 s ui 30h / c o n v e r t f rom ASCII t o b i n a r y
193
Soul of CP/M®
01A7 D8 rc / r e t u r n i f i t was < 0

01A8 FEOA cp i 10d ;is it > 9 ?
01AA DO rnc ; i f so, r e t u r n
r
/ m u l t i p l y contents of h i by 10 ( d e c ) , t h en add new d i g i
01 AB E5 push h ; p u t h i i n de
01 AC D1 pop d
01 AD 29 dad h ; a dd h i t o h i ( d o u b l e i t )
01AE 29 dad h ; d o u b l e i t agai n
01AF 19 dad d ; a dd de ( o r i g i n a l number) t o h i
01B0 29 dad h ;double r e s u lt
01B1 50 mov d , 0 ;zero in d
01B2 5F mov e ,a ;new d i g i t i n e
01B3 19 dad d ;ad d d i g i t t o number (now i n h i )
01B4 C39E01 jmp newdi g ;go look f o r next d i g i t
r
/ s u b r o u t i n e t o p r i n t c h a r a c t e r i n a - r e g o u t on s cr ee n
01B7 E5C5D5 pchar push h! push b! push d ;save r e g i s t e r s
01 BA 5F mov e , a ; p r i n t ASCII c h a r a c t e r
01BB 0E02 mvi c , c o n o u t
01BD CD0500 c a l l bdos
01C0 D1C1E1 pop d ! pop b ! pop h ; restore re g is te rs
01C3 C9 ret
r
01C4 4F4B20746Fqmess db ’OK t o m o d i f y ( y / n ) ? $’
01D9 4E6F207375nfmess db ’No such f i l e n a m e . $ ’
f
01 EB dma ds 128d ;dma b u f f e r
W
026B end
typed-in line and the end of the buffer will not cause odd effects when it is
printed out.
The DECIBIN routine at the end of the program is the same one that you
saw before in the chapter on console system calls.
Trying O ut the Program
Try out the program using the “ sample.txt” file described in the section on
the STORE program. Use TYPE2 to examine the file, and then use
RANDYM OD to modify one of the records in the file. It’s easy to figure out
194
Writing to the Disk
Fig. 6-4. F low chart of the RANDYMOD program .
which record number you want to modify, since each line in the file corre
sponds to one record.
N ot bad, is it? Using STORE, TYPE2, and RANDYM OD you can create,
examine, and modify text records, just as if you were using a real word
processor. Well, not really quite as well, but by now you’re such a good 8080
programmer that you can probably figure out how to combine these three
195
Soul of CP/M®
programs and add the features necessary to come up with a competitor for
WordStar!
We’re going to cover two more system calls in this chapter, both of which
are concerned with what happens when we change in midstream from read
ing files sequentially to reading them randomly, and vice versa.
COMPUTE FILE SIZE SYSTEM CALL
COMPUTE FILE SIZE FUNCTION 23 (hex) = 35 (dec)

On return: Bytes rO, r1, r2 set in FCB
This is a useful little system call that makes it easy for you to get to the end
of a file. This is useful if you want to add something to the end of a file and
don’t want to waste the com puter’s time in reading all the records sequen
tially to find what the number of the last record is.
For instance, take a look back at the STORE program earlier in this chap
ter. Here, if we wanted to add a record to an existing file, we had to read (in
lines 163 to 16C) all of the records in the file until we came to the end. To see
how the Compute File Size system call works, try modifying the STORE pro
gram as follows:
1. Make a copy of STORE using PIP. Call it STORE3.
A>pi p s t o r e 3 . a s m = s t o r e . asm
2. Put this statement at the beginning of STORE3:
cfsize equ 23h ;Compute f i l e size
3. Change the “readr equ” statement to:
readr equ 21h ;Read random r e c o r d
4. Delete lines 163 to 16C, and substitute the following:

196
Writing to the Disk
mvi c,c fs iz e ;Compute f i l e size.

Lxi d ,fcb
c a ll 5
mvi c,readr ;Read random r e c o r d
Lxi d,fcb ; t o s e t c u r r e n t r e c o r d number.
caLL 5
Fig. 6-5 is a flowchart of the STORE3 program.

Instead of reading all the records until we get to the end of the file, we
execute a Compute File Size system call. This sets rO and rl to the record
number at the end of the file (r3 is set to 0). Then, in order to set the “current
record” and “current extent” bytes in the FCB, we also execute a random
read. This call uses the information in rO and rl to compute the values of the
current record and byte, which is needed for sequential system calls. If we
had wanted to do random writes to the file instead of sequential writes, this
last step would not have been necessary because the random write call has no
need for the current record and extent values.
Using the Compute File Size call will save our program a lot of time, espe
cially on long files, when compared with reading laboriously through all the
records in the file to get to the end.
SET RANDOM RECORD SYSTEM CALL
SET RANDOM RECORD FUNCTION 24 (hex) = 36 (dec)

On return: Bytes rO, r1, r2 set in FCB
This system call is similar to the Compute File Size call, except that it finds
the random record number in the middle of a record rather than at the end.
This is useful if you have been reading through a file using the Read Sequen
tial system call and, suddenly, find a record whose number you want your
197
Soul of CP/M®
Fig. 6-5. F lo w ch a rt o f the STORE3 program .
program to remember. Executing this call will put the random record number
into rO and r l, where it can be extracted and stored by your program. Or,
your program can make use of the information in rO and r l to perform a
random write operation at this point in the file.
198
Writing to the Disk
OUT OF INK
That finishes up our description of the various system calls used to write to
the disk. In the next chapter, we’re going to delve deeper into the murky
world of disk directories, allocation units, blocks, tracks, and sectors. We’ll
learn how wildcards work and how to rescue a file that has been mistakenly
erased. We’ll finish off the chapter with the W ORDS program, which counts
the words in a file, or in a whole group of files if wildcards are used in the file
name. So don’t go away—things are just getting interesting!
199
CHAPTER 7
Soul Searching
W ildcards and the Disk D irectory
This chapter describes how C P /M keeps track of what programs are on a

disk and where they are. We’ll explain the disk directory, allocation units,
extents, sectors, bit maps, and how they all fit together. We’ll also explain
how C P /M uses “wildcards” (the “?” and “ *” characters) to refer to whole
groups of files rather than single files.
Soul of CP/M®
Using these ideas, we’ll then cover the “ Search for First” and “Search for
Next” system calls, whose purpose is to provide your program with informa
tion about particular files. These calls give us the tool we need for our next
example: a procedure which permits you to restore a file that has been acci
dentally erased.
We’ll finish off this chapter with WORDS, a program that counts the
number of words in a text file. W ORDS permits the use of wildcards in its
input; that is, it will list the number of words in a whole group of files. In this
program, which is somewhat more ambitious than any we’ve looked at so far,
we’ll also introduce the idea of stack management.
In addition to teaching you about the disk system, this chapter will give
you the skills necessary to write a variety of such advanced utility programs
as a directory program that tells you how much disk space a program occu
pies, a master directory program that will read all your disks one after the
other and produce a file of all your programs, and a program that restores
erased files. You could even write a disk utility program that would enable
you to read and write to specific sectors of the disk, as is done in many “disk
debugger” programs.
HOW CP/M STORES FILES ON THE DISK
In previous chapters, we’ve mentioned, in passing, such terms as allocation

units, extents, and the disk directory. Now we’re going to find out what these
terms really mean and how they all work together to permit C P /M to store
and retrieve a particular file on the disk.
As you recall, a standard 8-inch C P /M disk has 77 tracks, each of which
contains 26 sectors. In a single-density disk, a sector is 128 bytes or the same
length as a C P /M record. (In double-density disks, a sector can hold two or
even four records, but let’s ignore this possibility for the time being. It’s the
idea of how the disk is organized that’s im portant here, not the actual num
bers.) Thus, there are 77 tracks times 26 sectors for 2002 sectors on the disk.
You have also learned that a file is simply a number of records. Each of these
records is 128 bytes long, which is the same length as a sector. Keep in mind
the difference between sectors and records. A sector is a physical location on
the disk, while a record is 128 bytes of information that you’re going to put,
temporarily, in that sector. It’s like a parking lot. There are a certain number
of spaces (sectors) in the lot, and cars (records) come and go, leaving some
spaces empty and some full.
202
Soul Searching
Things would be easy if all the records in a file were just assigned to a
group of sectors in order, so that a file with 100 records would simply occupy
(say) sectors 450 to 550—as if all cars of the same color (representing a file)
occupied one area of the parking lot. Unfortunately, things aren’t that simple
because of the way files actually get created. Fig. 7-1 gives a picture of how
two files are probably not arranged.
/// /// 111 111 111 111 111 1 1 1 + ++ + + + + + + + + + + + + + + + + ++
/ / / = file 1
+ + + = file 2
Fig. 7-1. An u nlikely a rrangem ent of tw o files.
In the real world, however, this is what might happen. Suppose that
you’re using your word-processing program to write both a personal letter
and an 8080 program on the same disk. You might work a little on the
program and, then, a little on the personal letter, and then some more on
the program. C P /M doesn’t know, in advance, how long either of these
documents is going to be (you probably don’t either), so it doesn’t try to set
aside a big group of sectors for each file. As you type in parts of the pro
gram, it assigns sectors to this file, and as you type in parts of the letter, it
assigns sectors to that file. As a consequence, the sectors for the two files
get mixed up, like red and green cars parked random ly all over the lot. The
problem then is, how is C P /M going to keep track of what sectors hold the
records for a particular file? It’s like asking the parking lot attendant to give
you a list of the locations of every green car in the lot. The diagram given in
Fig. 7-2 illustrates how the sectors of two files are random ly distributed on
a disk track.
/ /1 + ++ + ++ 111 +++ 111 111 + ++ ++ + ++ + / / / + ++ 111 111 11 / + + +
/ / / = file 1
+ + + = file 2
Fig. 7-2. The random d is trib u tio n of tw o files on a disk track.
Allocation Units
Here’s a copy of the diagram of the file control block that we discussed in
Chapter 5. (It is reproduced here for your convenience.)
203
Soul of CP/M®
Byte number Location

(decimal) (hex) Contents
0 5C 0 Drive number.
1 5D T
2 5E E
3 5F S
4 60 T ►File name (8 bytes).
5 61 1
6 62 0
7 63 0
8 64
9 65 T
10 66 X File extension (3 bytes).
11 67 T
12 68 00 Current extent.
13 69 00 Used internally by CP/M .
14 6A 00 (User should set to zero.)
15 6B 02 Num ber of records in current extent.
16 6C 54
17 6D 00
18 6E 00
19 6F 00
20 70 00
21 71 00
22 72 00
23 73 00
24 74 00 ►
Allocation units.
25 75 00
26 76 00
27 77 00
28 78 00
29 79 00
30 7A 00
31 7B 00
32 1C 01 Current record.
33 7D 00
34 7E 00 ^■Random record number.
35 7F 00
204
Soul Searching
This 36-byte file control block (FCB) is very similar to the information
that C P /M keeps in a place on the disk called the “disk directory.” At least
one such FCB-like entry is recorded in the directory for each file. It contains
all the information that C P /M needs to know about the file and where it’s
located on the disk.
Notice that bytes 16 to 31 of the FCB are occupied by something called
“allocation units.” This rather ponderous name holds the key to the way that
C P /M keeps track of where the sectors are in a file.
An allocation unit is nothing more or less than a group of 8 sectors on the
disk. The designers of C P /M decided it would be too complicated for the
operating system to try to remember the location of every single individual
record, so they grouped each eight sectors together and gave them a number,
and then made up a rule: all eight sectors in a particular allocation unit must
be occupied by records in the same file. It’s as if each block of eight parking
spaces in the lot had to be occupied by cars of the same color. This cuts down
the information the operating system needs to remember about each file and
speeds up disk access to the file, but it also means that there will (usually) be
unused sectors at the end of each file. For example, a file 10 records long will
occupy all of one allocation unit, but only two sectors of the next one, leaving
6 unused sectors which can’t be used by any other file. However, this is a
small price to pay for simplifying the disk directory entries.
In the FCB, there are sixteen bytes set aside to hold the allocation units.
Each allocation unit is represented by a single byte. This works because there
are approximately 2002 sectors, and 2002 sectors divided by 8 sectors per
allocation unit gives 250 allocation units. Thus, one byte (which can have
values from 0 to 255) can be used to specify any one of the 250 allocation
units. Some of these sectors are used by the system, leaving 242 for the user’s
programs. So the sixteen bytes in the FCB (or the directory entry) can refer
to 16 allocation units; this is 16 times 8, or 128 sectors, which can hold 128
records. (There can be more than 128 records in a file if different “extents”
are used. We’ll look at that soon.)
As we noted, the preceding description only applies if the disk system
being discussed is single density. If it is a double-density system, then,
instead of 16 one-byte numbers to refer to the allocation units, there are 8
two-byte numbers, with each one able to refer to any one of 256 times 256, or
65536, possible allocation units.
When you “open” a file, the operating system gets the information about
which allocation units the file occupies from the disk directory and writes this
information into the FCB. Let’s see how this process looks in the real world.
205
Soul of CP/M®
Examining the FCB
Get into D D T and enter the following program:
-a100
0100 mvi C,f Open file.
0102 Lxi d,5c
0105 c a ll 5
Now, since we want to see what happens to the FCB when we do various
things to it, let’s fill it with all bits (FF bytes) so we can start with a clean slate.
-f5 c,7F ,ff
Now dump the FCB area to see that it really is filled with FFs:
-d5c,7f
005C FF FF FF F F ___
0060 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF F F ....................................
0070 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF F F ....................................
Looks all right. Now put the name of a short program into the FCB with
the “i” command. We’ll use a program called “multi.txt” which is three
records long. (You can create records of any length using the STORE pro
gram, since each line typed into this program is a record).
-im u lti.tx t
Now, dump the contents of the FCB again to see what’s there. (We’ll also
provide some reference numbers so that you can see more easily what bytes
are where.)
c D E F
Drive code
Current extent
005C 00 4D 55 4C .MUL \
0060 54 49 20 20 20 54 58 5400FFFFFF FFFFFF FF T I TXT
0070 FF FF FF FF FF FF FF FFFFFFFFFF 00 FFFFF F ..................
Current record
0 2 3 4 5 6 7 8 9 A B C D E F
206
Soul Searching
The name and file extension have been filled in from bytes 5D to 67 and,
in addition, byte 5C (which is the drive code), byte 68 (which is the current
extent), and byte 7C (which is the current record) have all been set to 0. The
“i” command does this automatically, since this is what BDOS requires when
the file is opened.
Now we’ll open the file by executing our little program.
- g 1 00
*0109
And now we’ll dump the FCB again and see what’s happened:
C D E F
■Record count
■Allocation unit
d 5 c. 7f
005C 00 4D 55 4C .MUL
0060 54 49 20 20 20 54 00 T I TXT.
0070 00 00 00 00 00 00 F F .....................
0 l 2 3 4 5 7 8 9 A B C D E F
Lots of zeros, and a few other goodies. Byte 69 has become 0, and byte 6A
is 80. (BDOS uses these bytes internally: don’t worry about them.) Byte 6B
(which is the “rc” or record count byte) is 03, which is the total number of
records in the file. Interesting. Bytes 6C to 7B are the 16 bytes that hold the
allocation units and they’re all 0, except for the first one, which is 61.
Since the file is a mere 3 records long, it’s only going to use one allocation
unit, since each allocation unit can hold up to 8 records. And that’s exactly
what we see; all the allocation unit bytes are zero (meaning they’re unused)
except one. BDOS can look at this FCB (so can we) and know immediately
that the 3 records of the file “multi.txt” are located in allocation unit number
61 (hex), which is one of the 242 (decimal) or so allocation units on the disk.
So if we issued a “read record” system call, BDOS would know which sectors
to read to get this file.
Extents
We’ve found that our 16 allocation units can hold 8 times 16, or 128 records.
This is 128 times 128, or 16384 bytes, a rather large file. But what happens when
a file is longer than that? Then, instead of simply assigning more allocation units
207
Soul of CP/M®
to increase the size of the file, we have to do a more major operation called
“opening a new extent.” W hat’s this mean? Remember that the information that
we read into the FCB when we opened the file came from the disk directory. It
was, in fact, an FCB-like entry in the directory, and if you looked in the direc
tory (as we’re about to do), you would see it sitting there.
Now, when a file exceeds 128 records, what we have to do is make another
entry in the directory. We use the same filename and type, but we have the
extent number (byte 6A) set to 1 instead of 0 (or to 2, or 3, or more, if that
many extents are required). Thus, a file with 300 records would have 3
extents and, thus, 3 entries in the directory: one for the first 128 records, one
for the next 128 records, and one for the 44 remaining records.
Fig. 7-3 gives a picture of how records, allocation units, sectors, extents
and so on are related. N ote again, that if you are using a double-density disk,
these numbers will be somewhat different. In double density, a sector can
hold either 256, 512, or 1024 bytes, depending on the system. The other num
bers given in the diagram of Fig. 7-3 change accordingly. However, records
will always consist of 128 bytes regardless of the system. This means that
when you write a program, you don’t need to worry about single density,
double density, or whatever other peculiarities the system may have: you sim
ply deal with 128-byte records.
1 DISK = 77 tracks x 26 sectors/track = 2002 sectors
Fig. 7-3. The relationship of records, allocation units, sectors, etc.
208
Soul Searching
The Disk Directory
The disk directory, itself, is stored on the disk and consists of a number of
records. How many? In single density, there are 16 records, each of which can
hold 4 directory entries, for a total of 64 directory slots. In double density,
there are 32 records, each of which can hold 4 directory entries of 32 bytes,
for a total of 128 directory slots. This means that it is impossible to put more
than 64 (or 128) files on a disk, even if they are all so short that they have no
trouble with disk space.
You may be wondering where the last 4 bits went, if the FCB is 36 bytes
long and the directory entry only holds 32. W hat happens is that when a file
is opened, only 32 bytes are read from the directory to the FCB. The “cr”
(current record) byte and the 3 bytes which make up the random record
number (rO, rl, and r2), are constructed by BDOS when they are needed, and
are not a part of the permanent record of the file.
Here’s what a directory entry looks like:
Byte Number
(dec) (hex) Contents
0 00 00 Set to 00 if file is valid; set to E5 if file is erased.
1 01 T
2 02 E
3 03 S
4 04 T Filename, 8 bytes.
5 05 F
6 06 I
7 07 L
8 08 E
9 09 C
10 0A O
11
12
0B
0C
M
00
} File extension, 3 bytes.
Extent.
13 0D 00 si
14 0E 00 s2
15 OF 12 Num ber of records in this extent.
16 10 3C
17 11 3D
Allocation units (unused spaces = 0).
18 12 00
19 13 00
209
Soul of CP/M®
20 14 00
21 15 00
22 16 00
23 17 00
24 18 00
25 19 00
►Allocation units (unused spaces = 0).
26 1A 00
27 IB 00
28 1C 00
29 ID 00
30 IE 00
31 IF 00
The information given in a directory slot (a slot is the position occupied by

one directory entry) is not exactly the same as that in the FCB. For instance, the
first byte (at location 0) is no longer the drive code. It’s now called the “user
number.” On a single-user system, it can have either of two values: 00, meaning
that the file name in this slot is in use, or E5, meaning that the file has been
erased. The file name and file extension are the same as they are in the FCB
and, on single-density systems, the record count is the record count. However,
on double-density systems, the number in this position is not actually the record
count, but is related to it by an obscure algorithm which we won’t go into.
As in the FCB, bytes si and s2 are used for something mysterious, and are
undocumented by Digital Research, and must not be asked about.
Next, we’re going to discuss two systems calls that give your program the
ability to read the disk directory: “ Search For First” and “ Search For Next.”
SEARCH FOR FIRST SYSTEM CALL
SEARCH FOR FIRST FUNCTION 17 (dec) = 11 (hex)

On Return: REG A = Directory Code
Comments: Directory Code = 0, 1, 2, or 3 if file found.

210
Soul Searching
When you execute it, this system call will look at the file name in the FCB
and, then, will go and read the disk directory to see if there’s a file name there
that matches the name in the FCB. If it finds the file, itwill write the direc
tory record that contains the name into the DMA buffer. Since there are four
directory entries in each record of the directory, there will be three other
entries written into the DMA besides the one you want. In order to tell your
program which of these four entries is the right one, Search For First returns
a number in the A-register that corresponds to the position of the desired file
in the directory record:
0 means the file is the first entry in the record.

1 means the file is the second entry in the record.
2 means the file is the third entry in the record.
3 means the file is the fourth entry in the record.
This system call only looks for the first occurrence of a file in the directory.
There are two reasons why a file whose name you have placed in the FCB
may have more than one directory entry. First, it may be so large that it
occupies more than one extent. Each extent that the file occupies requires an
additional directory entry. Second, you may have used wildcards in the file
name you placed in the FCB, in which case, a number of different file names
may all fit the pattern.
WILDCARDS
As you know from using C P/M , it is possible to use the characters “?”
(meaning any character) and “ *” (meaning any group of characters) in a file
name. When you do this, any filename that matches the pattern you have set
up will be operated on. For instance, if you type:
A>dir chap????.txt
all the files having a name that starts with the four letters “chap” and that
have an extension of “txt” will be listed, such as “chapter.txt”, “chap-2.txt” ,
and so on. Similarly,
A>di r * . t x t
211
Soul of CP/M®
will list all files with a file type of “ txt” . We can use one of these two conven
tions in the Search For First system call: the “?” character. The “ *” cannot be
used, because it is the CCP that translates an “ *” into a “?”, and your pro
gram doesn’t have access to the CCP.
Let’s see how this call works. Type in the following program, using DDT:
- a 1 00
0102 Lxi d , 40 0
0105 c a ll 5
0108 mvi c,11 Search For First.
010A lxi d,5c
010D c a ll 5
0110 mvi c,02 Print out directory code.
0112 adi 30
0114 mov e,a
0115 c a ll 5
Save the program as testl09.ddt, and then go back to D D T with the pro
gram:
To make the program work, all you need to do is to put the name of the
“target” file (the one whose name you want to find in the directory) into the
FCB. This is easily done using the “i” command. Assume you’re going to
look for a file called “wsibm.com” :
- i wsi bm. com
Now run your program:
-g100
2*0118
t-------------- Position of target file in directory: 3rd.
212
Soul Searching
Your program will print out a single digit: 0, or 1, or 2, or 3, assuming that

the file you named actually exists. If there is no such file, then a “ / ” will be
printed out, since this is the ASCII value corresponding to an “ F F ” code
returned in the A-register. (FF plus 30 = 2F.)
And now, finally, we’ll get our first look at the directory itself. Use “d” to
dump the 128 bytes at location 400:
-d400,47f
0400 00 45 58 41 4D 50 20 20 20 43 4F 4D 00 00 00 01 .EXAMP COM___
0410 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
0420 00 45 58 41 4D 50 20 20 20 41 53 4D 00 00 00 01 .EXAMP ASM___
0430 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
0440 00 57 55 49 42 4D 20 20 20 43 4F 4D 00 00 00 0C . WSIBM COM___
0450 03 04 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
0460 00 42 4F 42 20 20 20 20 20 54 58 54 00 00 00 03 .BOB TXT___
0470 21 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
That looks like a lot of numbers, but as you can see from the ASCII
printout on the right, four files are listed, and the one which we originally
asked for—“wsibm.com” —is in the third position down, corresponding to the
“2” that was returned as the directory code.
Let’s take one of these directory listings and examine it more closely:
------------ User number t;ctent -Record count
Filename typ
f ..... s1 s2
0400 00 45 58 41 4D 50 20 20 20 43 4F 4D 00 00 00 01 .EXAMP COM.
0410 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
0 1 2 3 4 5 6 7 8 9 A B C D E F
Onl y one a l l o c a t i o n u n i t used: number 1.
In the lower line, from 410 to 4 IF, are the allocation units, the same as
they are in the FCB. These are either 16 one-byte values, if the disk is single
density, or 8 two-byte values, if the disk is double density.
Now we’re going to find out how to find filenames that occur more than
once in the directory.
Soul of CP/M®
SEARCH FOR NEXT SYSTEM CALL
SEARCH FOR NEXT FUNCTION 18 (dec) = 12 (hex)

On Return: REG A = Directory Code
Comments: Directory Code = 0, 1, 2, or 3 if file found.

As you can see, this system call is very similar to Search For First. The
difference is that instead of starting at the beginning of the directory as
Search For First does, this call starts looking for a file name at the place
where either Search For First or Search For Next left off looking when it was
last called. This is useful in either finding files that have more than one
extent, or when the use of wildcards has made it possible for more than one
file name to match the name given in the FCB.
Let’s write a little program to look at a number of files. Take the program
from Search For First, given earlier as “test 109.ddt”, and add new code as
shown in the following program, starting at location 119:
0100 mvi c,1 a Set DMA address to 400.

0102 Lxi d,400
0105 ca L L 5
010A Lxi d,5c
010D ca L L 5
0112 adi 30
0114 mov e,a
0115 ca L L 5
0119 mvi c,12 Search For Next
01 IB Lxi d,5c
►Add new code.
011 E ca L L 5
0121 jmp 110 Jump back to print directory. „
Save it as “test 1 lO.ddt” and, then, reenter D D T with it.

214
Soul Searching
You can use the program to search for a group of files, using wildcards.
Here’s how. First, figure out what wildcard name you want to search for.
Let’s say you want to look at the directory entry for every file that has a file
extension of ASM. Type:
- i ? ? ? ?? ?? ?. asm
That’s eight question marks, one for each character position. (As noted ear
lier, you can’t use asterisks here because BIOS doesn’t understand them; only
the CCP understands asterisks.)
Now, run the program from the beginning:
-g100
1*0118
^-----------------This “ 1” means filename found in second position.
Dump the contents of the DMA buffer:
-d400,47f
0400 00 45 58 41 4D 50 20 20 20 43 4F 4D 00 00 00 01 .EXAMP COM___
0410 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
0420 00 45 58 41 4D 50 20 20 20 41 53 4D 00 00 00 01 .EXAMP ASM___
0430 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
0440 00 57 55 49 42 4D 20 20 20 43 4F 4D 00 00 00 0C . WSIBM COM___
0450 03 04 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
0460 00 42 4F 42 20 20 20 20 20 54 58 54 00 00 00 03 .BOB TXT___
0470 21 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..............
Well, it’s our old friend, the same directory record we saw before. Since it
has an ASM file in the second position, a “ 1” is printed out when we run the
program.
When we search for the next ASM file, we want to use the Search For Next
system call, so we start our program at location 119 instead of at the begin
ning.
- g 1 19
0*0118
^-----------------The “0” means file found in first position.
D um ping the D M A buffer again shows us:
215
Soul of CP/M®
-d400,47f
0400 00 43 4F 55 4E 54 20 20 20 41 53 4D 00 00 00 01 .COUNT ASM-------
0410 1D 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ..................................
0420 00 43 4F 55 4E 54 00 00 00 43 4F 4D 00 00 00 01 .COUNT COM-------
0430 1E 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ...................................
0440 00 4D 45 4D 52 20 20 20 20 43 4F 4D 00 00 00 OC .MEMR COM------
0450 1 F 20 00 00 00 00 00 00 00 00 00 00 00 00 00 00 .....................
0460 E5 54 45 53 54 31 30 30 20 43 4F 4D 00 00 00 02 .TEST100 COM--
0470 21 00 00 00 0000 00 00 00 00 00 00 00 00 00 00 .....................
The “0” that our program printed out shows us that the file we’re looking for
is in the first position, and sure enough, there it is.
We can keep doing this, executing the Search For Next system call with a
-gl 19, and then dumping out the buffer to see what’s there, until we’ve found
every ASM file in the directory.
What good is all this? After all, you can use the regular D IR and STAT
commands in C P /M to find out the same information and much more conve
niently. That’s true, you can use D IR and STAT, but your program can’t.
Everything we’ve shown here can be done by your program; it can set up the
FCB with a program name, execute the “ Search” system calls, and then
examine the contents of the DMA buffer to read the directory entries. When
we get to the W ORDS program at the end of this chapter, we’ll show you an
example of just this process.
Scanning the Entire Directory
We’ve seen how to search the directory for all of the ASM files. If you want
to look at everything in the directory, all you need to do is type:
- i ????????. ???
This will match with every file, so when you execute the program four
times, it will (usually) find all four files in each record of the directory record
in the FCB.
. cp9
-g100
0*0118 First position.
- g 1 19
1*0118 Second position.
216
Soul Searching
—g 119
2*0118 Third position.
- g 119
3*01 18 Fourth position.
At any time, you can dump the contents of the DMA buffer to look at this
record of the directory. It will show the same page until it’s found the last of
the four entries; then, a new record will be loaded in:
-g100
0*0118 First position in next record.
When you see the 0, you know that a new record has been loaded in, so
you can dump it to look at all four new directory entries. Continuing this
process will eventually show you the entire directory and the directory entries
for every program on your disk. This program will, in fact, do something a
little special; it will show you not only existing files, but files that have been
erased.
ERASED FILES
Look back at the dump in the Disk Directory section of this chapter that
contained the file TESTIOO.COM. The first byte in the directory listing of
this file is E5, not 00 as it is for the other files. W hat does the magic number
E5 mean here? It means that the file has been erased, probably through the use
of C P /M ’s “era” command. When you erase a file this way, C P /M doesn’t
actually blot out the file on the disk; it doesn’t even blot out the information
about the file in the directory. All it does is set this one byte in the directory
entry to E5. Later, if it needs to go through the directory looking for some
thing, it ignores all the entries whose first byte is E5, since it knows they have
been erased. (E5 was apparently chosen for this purpose because it’s the
number that is placed in every byte of a newly formatted disk.) Of course, if
BDOS, at some point, needs the space on the disk formerly occupied by the
erased program, it will take it and, if it needs the space in the directory, it will
take that too, but until it needs this space, the erased file is still there.
This leads to an interesting idea. Suppose you accidentally erased a file;
would it be possible to get it back again, simply by changing the E5 back to
00? Sure would. Let’s see how to go about it.
217
Soul of CP/M®
SAVING AN ERASED FILE

The process for saving an erased file consists basically of three steps:
1. Find the erased file in the directory and record the number of records
and the allocation units it uses.
2. Set up a new FCB using the name of the erased file and the number of
records and allocation units discovered in Step 1, above.
3. Write this FCB back into the directory by performing a “Close File”
system call.
To make this process easier, we’ll add a few lines of code to the testl lO.ddt
program that we used above.

0102 Lxi d ,4 0 0
0105 ca L L 5
010A Lxi d,5c
010D ca L L 5
0112 adi 30
0114 mov e,a
0115 ca L L 5
0119 mvi c,12 Search for Next.
011B Lxi d,5c
011 E ca L L 5
0121 jmp 110 Jump back to print directory.
0124 mvi c,16 Open file
0126 Lxi d,5c
0129 ca L L 5
012C rst 7 Back to DDT.
►New code
012D mvi c,10 Close file.
012F Lxi 5,c
0132 ca L L 5
0135 rst 7 Back to DDT. _
Save this program as testl 11.ddt.

You should probably practice the “rescue” procedure on a file you don’t
like very much, just in case something goes wrong and you can’t get it back.
218
Soul Searching
Use STORE to create a 3-record file; you can call it BADFILE.TXT. Check
that it’s there, using TYPE2 (or C P /M ’s “ type” function). Now, erase it!
A>era b a d f i L e . t x t
Use “dir” to check to see that it’s really gone. Imagine your horror if this
were a good file, filled with irreplaceable data, that you had—in a moment of
inexcusable inattention—erased.
Step 1—Getting the Vital Information About the File
Actually, you already know how to perform this step. Load in testl 11.ddt
with DDT. Then, type:
- i ????????.???
to set up the FCB to look for all files and, then, repeatedly execute the pro
gram as shown in the last section. (The first part of the program works just
the same as it did before.) Every time a new record is loaded in from the
directory, dump it with “-d400,47f”, and see if BADFILE.TXT is one of the
four entries. (You can’t just put BADFILE.TXT in the FCB and search for it
because it’s been erased, and BDOS can’t “see” it anymore.) Eventually,
you’ll find the entry. Maybe it will look something like this:
-d400,47f
00 57 53 4F 56 4C 59 31 20 4F 56 52 00 00 00 18 . WS0VLY1 0VR.
29 2A 2B 00 00 00 00 00 00 00 00 00 00 00 00 00
E5 42 41 44 46 49 4C 45 20 54 58 54 00 00 00 03 .BADFILE TXT.
2C 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 48 45 58 49 44 45 43 20 41 53 4D 00 00 00 14 .HEXIDEC ASM.
1 F 20 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 4C 4F 41 44 20 20 20 20 43 4F 4D 00 00 00 0E .LOAD COM.
21 22 00 00 00 00 00 00 00 00 00 00 00 00 00 00
There’s BADFILE.TXT, ju st as we hoped it would be. The E5, at the

beginning of its line, signals disaster unless our rescue operation is successful.
Now, what we would really like to do is simply change the E5 byte back to
00, and then write this whole record of the directory back onto the disk.
Unfortunately, C P /M did not provide a system call for writing directory
records, only for reading them—so we’re going to have to work a little harder
to get the information back into the directory.
219
Soul of CP/M®
Examine the directory entry carefully. The information we need to know is

in two places. First, write down the number in location 42F, which contains
the number of records in the file (or if you have double density, a number
related to the number of records). In this case, it’s 3. Then, write down all the
numbers that appear in the second line of the entry—here, it’s the line starting
at 430. These are the numbers of the allocation units assigned to the file.
There is only one allocation unit: 2C.
Step 2—Creating a New FCB With the Old Information

First, put the name of the file into the FCB:
-ib a d fi Le.txt
Now, open the file, by executing the “open file” system call in our testl 1l.ddt
program:
-g124
* 0 1 2C
The reason for opening the file is that we’re going to close it, and you can’t
close an unopened file.
Now, put the information you found from the old directory listing into the
FCB:
- s6 a
006A 00 0 -------- -------------- -------------- This byte must be zero.
006B 00 3 -------- -------------- -------------- Number of records.
006C 00 2C -------- -------------- -------------- Allocation unit.
006D 00 . -------------- -------------- -------------- More allocation units would go here.
I------------------ These are the values we type in.

-------------------------Junk left over in the FCB
The FCB now contains all the information that we need to put in the direc
tory listing.
Step 3 —Close the File
By closing the file whose name is in the FCB, we write all the information
in the FCB into the directory on the disk. Execute the “close file” section of
the program:
220
Soul Searching
- g 1 2D
*0135
That’s it!
Is It Really Back?
Go back to C P /M and use “dir” to verify that the file has been restored. Is
it back? If so, bravo! If not, you probably made a typo somewhere. Try it
again.
Now, before you do any writes to the disk, do a warm boot (control-c).
Why do we need to do this? The answer lies in a mysterious place called the
“bit map.”
THE BIT MAP
Ask yourself this question: when BDOS starts to write a record to the disk,
how does it know which allocation units are already in use and which are
available to be written in? One way it could find out is to read the directory
and make a list of all the allocation units shown in the entries of active files
(“active” meaning not erased). Then it would know not to write to these
units. However, scanning the directory is a lengthy process involving a disk
access, and it is not something that BDOS would want to do every single time
it writes a record. So, instead of scanning the directory every time it wants to
do a write, BDOS only scans it once: when the disk is first initialized (by a
warm boot).
BDOS uses an area of high memory for something known as a “bit m ap”
(sometimes called the “ allocation vector”). On a single-density disk, this is
simply a string of 242 bits (31 bytes). Each bit represents one of the alloca
tion units on the disk. If the allocation unit is in use, then the bit is set to 1. If
it is free, the bit is set to 0. When a warm boot is performed, BDOS scans the
directory and creates a bit map based on the information it finds there. Then,
every time it needs to do a “write,” it looks at the bit map to see what alloca
tion unit is free, rather than going back and looking at the directory. As it
writes, it will set the bits that correspond to the allocation units it has written
into to a 1, to show they have been used. When you erase a file with “era,”
the bits used by the file are set back to 0, to show that the allocation units,
which they represent, are again available for use.
221
Soul of CP/M®
Here’s how the bit map might look if most of the allocation units on the
disk were in use:
11111111 11111111 11111111 11111111

11111111 11111111 11111111 11111111
11111111 11111111 11111111 11111111
11111111 11111111 11 111111 11111100
00000000 00000000 00000000 00000000
00000000 00
If we erase a file, it will free whatever allocation units the file was written
into, thus setting the corresponding bits to 0:
11 111111 1 1111111 11111111 11 111111

11000111 00110011 10001111 11111111
11111111 11111111 11111111 11111111
11111111 11111111 11111111 11111100
00000000 00000000 00000000 00000000
00000000 00
(Note that, as discussed above, the allocation units of a particular file aren’t
necessarily contiguous.)
Now it becomes clear why you need to do a warm boot after you have
rescued the erased file. Suppose you rescued the erased file and, then, without
doing a warm boot, caused BDOS to write something to the disk. It would
look in the bit map and, finding that the allocation units of the erased file
were free, it would write over them (if it needed the space). Goodbye file! To
avoid this, we simply cause the bit map to be recreated, using the new infor
mation we’ve put in the directory with our rescue process, by doing a warm
boot (or a cold one, for that matter). Our file will then be completely legiti
mate in all respects and will be safe from post-rescue disaster.
WORDS PROGRAM-COUNTS WORDS IN FILES AND

USES WILDCARDS
The program that we’re going to describe in this section is fairly lengthy,
but don’t let that bamboozle you. You don’t really need to understand every
part of the program, at least not all at once. The main point of interest is the
way that the program handles “wildcards,” that is, file names given to it
which contain question marks and asterisks.
222
Soul Searching
Here’s what the program does. You type in a file name, containing wild
cards if you wish. The program then finds all the files that match the name
you typed in, and it counts the number of words in each one. These word
counts are then printed out next to the name of each program, like this:
A>words * .asm
F ile s Words
SHOW ASM = 1135

SPACE ASM = 307
WORDS ASM = 970
STORE ASM = 297
In this example, we’ve counted the words in all the ASM files on the disk,
but you could just as easily count all the TXT files, or all the files whose
names start with “chap”, or whatever.
W ORDS can be a useful program for anyone doing serious writing, since
managers and editors always seem to ask, “Well, how many words are there
in that report, anyway?” With WORDS, it takes only a few seconds to find
the length of that 50-page short story for which the New Yorker says it is
going to pay you by the word.
How does the program count words? Essentially, by counting spaces.
However, this is not quite as simple as it sounds, since a string of spaces must
only be counted as one space, and carriage returns and linefeeds should also
be counted as spaces, since they separate words too. Also, the program
should avoid getting confused when words fall across the boundary between
one record and the next.
But before we get into the actual word-counting process, let’s look at how
the program deals with wildcards.
A Problem With the “Search” System Calls
You learned in the last section how the Search For First and Search For
Next system calls handled wildcards. If you put a file name which contains
question marks in the FCB, these calls will find the directory entries for all
the files that match the pattern. This works very well if all you’re doing is
looking at the directory entries, as we had to do to save the erased file. But
suppose you want to actually read the files that you find using this process?
Then there’s trouble. Why? Because when you “open” a file (which you must
Soul of CP/M®
do to read it), the Search For Next system call loses track of where it is in the
directory. If you use Search For Next, and then Open File, and then Search
For Next again, there will be error messages as Search For Next tries desper
ately to figure out why it has lost its place.
The solution to this problem is to do all the searching first and, when it’s
done, do all the reading. So, we first scan through the directory, looking for
filenames that match the name in the FCB. When we find them, we put the
names in an array called “ table” in our program. Once we’ve found all the
names that match, we go back, take them out of “ table” one at a time, open
the files, read them, count the words, and print out the totals.
Take a look at the program in Listing 7-1. D on’t be alarmed; it may be big.
but it’s a pussycat. We’ll take you through it section by section, until it all
makes sense.
We’ll need two flowcharts to describe the program in Listing 7-1. One will
deal with the entire W ORDS program (Fig. 7-4), and the other will cover the
major subroutine called W COUNT (Fig. 7-5), which actually counts the
words in a file. Let’s begin our detailed examination of the program (Listing
7-1) by thinking for a moment about the stack.
Stack Management
In the programs we have written so far, we have, in the interest of simplic

ity, neglected to pay proper attention to the stack. In short programs, that
has not gotten us into any serious trouble, but the longer the program is, the
more likely it is that improper stack management will cause us grief.
W hat is the stack? It’s simply the area of memory where the 8080 processor
stores things that are PUSHed onto it with a “push”instruction, and where
the return address is stored when we do a “call” to a subroutine.
How does the 8080 know where to put the stack? T hat’s easy; as far as
the 8080 is concerned, the stack is at whatever address is in the stack
pointer. The stack pointer is a 16-bit 8080 register, ju st like the HL- and
BC-registers. It’s abbreviated “sp” in assembly language. When you “push”
something onto the stack, it goes to the memory address pointed to by the
SP-register, and the SP-register is decremented two bytes so that it points to
the next lower location in memory. Thus, if the SP-register contains 400,
and you “push” a 16-bit value from some register, this value will go into
locations 400 and 3FF, and the SP-register will be decremented to 3FE.
Why does the stack pointer count down instead of up? Because lots of pro
grammers like to put their program in low memory and have it (and what-
224
Soul Searching
Listing 7-1. The WORDS Program

• ****************************************************
;WORDS-PROGRAM TO COUNT WORDS IN A FILE.
; A l l o w s wi I d c a r d s i n f i l e n a m e .
F
; Type ' ' w o r d s < f i l e n a m e . t y p > ' ' ,

; ( * and ? permi t t e d ) .

005C = f cb equ 5ch ; f i le c o n t r o l block
005C = dr equ f cb ; d r i v e code i n FCB
0068 = ext equ f c b + 12 ; c u r r e n t e x t e n t i n FCB
007C = e r f cb equ f c b + 32 ; c u r r e n t r e c o r d i n FCB
0080 = dma equ 80h ;DMA b u f f e r
0011 = s fi rst equ 11 h ;search fo r f i r s t
0012 = s n ex t equ 12 h ;search f o r next
0002 = conout equ 02h ; c o n s o l e o ut
000F = openf equ Of h ; open f i l e
0010 = c lo s e f equ 10h ;close f i l e
0014 = readf equ 14h ; s e q u e n t i a l read
0000 = wf lag equ 0 ; f l a g value f o r "w ord"
0001 = s p f lag equ 1 ; f l a g v a l u e f o r "sp ace
000D = cr equ Odh ;ca rria g e return
000A = If equ Oah ; linefeed
001A = c t r Iz equ 1ah ; c o n t r o l - z (EOF)
f
f
0100 o rg 100h
f
; s e t up l o c a l s t a c k
0100 210000 lx i h,0 ; c l e a r HL
0103 39 dad sp ;g e t c u rre n t stack p t r
0104 22E502 sh Id old sp ; save i t
0107 310703 lxi sp,stktop ; p u t i n new s t a c k p t r
f
o
; s e t number o f names i n a r r a y
+■»
o
01OA AF xra a ; p u t s 0 i n A -r eg
01 OB 32E202 st a n mcntr
r
225
Soul of CP/M®
;S CAN FOR F I LE N A M E AND PUT IN A RRA Y

r
; s e a r c h f o r f i r s t o c c u r r e n c e o f f i Lename
/■
010E 0E11 mvi c ,s fi rst ;search f o r f i r s t
0110 115C00 Lxi d , f cb
0116 B7 ora a ; c h e c k d i r e c t o r y code
0117 FEFF c pi Of f h ; i f A=255, no f i Le found
0119 CA1102 jz error ; so p r i n t message
011C CD3301 ca L L putary ; f o u n d , p u t name i n a r r a y
A
;search f o r next occurrence
/■
011 F 0E12 nmfnd mvi c,snext ;s ea rc h f o r next
0121 115C00 Lxi d , f cb
0127 B7 ora a ; c h e c k d i r e c t o r y code
0128 FEFF cp i Of f h ; i f A=255 t he n Last f i l e found
012A CA5B01 jz L a s t f i Le ; so go c o u n t words
012D CD3301 ca L L putary ; n o t L a s t , so p u t i n a r r a y
0130 C31F01 imp nmfnd ; g e t a n o t h e r f i Le
; P U T A R Y - S U B R O U T I N E TO PUT F I LE N A M E IN A R R A Y " T A B L E "
0133 0 70 7 07 070 7pu tar y r Lc ! r Lc ! r Lc ! r l c ! rLc ; A * 3 2 g i v e s 0 , 3 2, e t c .

0138 C680 adi dma ; L o c a t i o n o f DMA
( A - r e g now hoLds p o i n t e r t o f i Lename i n dma)
move f i Lename f rom DMA t o a r r a y " t a b L e " , c h ar by ch ar
013A 060C mvi b , 12 ; s e t up c o u n t i n B - r e g

013C 2A0703 LhLd pntrtab ; s e t up p t r t o tabLe
013F EB xchg ; i n D E -r e gi s t e r
0140 2600 mvi h,0 ; s e t up p t r t o DMA
0142 6F mov L,a ; Leave i n HL-reg
0143 3A5C00 Ida dr ; g e t d r i v e code
0146 77 mov m,a ; p u t d r i n new f c b
r
0147 7E repeat mov a,m ; g e t c h a r a c t e r f rom FCB
0148 23 inx h
226
Soul Searching
0149 12 stax d ;pu t i t in " ta b le "

014A 13 i nx d
014B 05 dcr b ; do ne y e t ?
014C C24701 jnz repeat
c
o
014F EB xchg ;save t a b le p o i n t e r
0150 220703 sh Ld pntrtab
; i n c r e m e n t t he "number o f names i n a r r a y " c o u n t e r

0153 3AE202 Lda n mc nt r
0156 3C i nr a
0157 32E202 sta nmcntr
015A C9 ret ; return
r
; l a s t f i l e i s f o u n d , so go c o u n t words i n each f i l e
015B11B402 la s tfile Lxi d , a r r a y m e s s ; p r i n t " F i l e s Words"

015E 0E09 mvi c,p rin ts
MOV E A F I L E NA ME I N T 0 FCB
move f i l e n a m e s f rom a r r a y " t a b l e " i n t o FCB

/
0163 210903 movnm Lxi h ,ta b le ;put table p oin te r
0166 220703 sh Ld pntrtab ; in "pntrtab"
0169 215C00 movnm2 Lxi h , f cb ;put FCB p o i n t e r
016C EB xchg ; in DE
016D 2A0703 Lh Ld pntrtab ;put t a b l e p t r i n HL
0170 060C mvi b,12 ;set c o un t
/
0172 7E spin mov a,m ; g e t c h ar f rom " t a b l e
0173 23 i nx h
0174 12 stax d ; p u t i t i n FCB
0175 13 inx d
0176 05 dcr b ; done y e t ?
0177 C27201 jnz spi n ; no
017A 220703 sh Ld pntrtab ;save t a b le p o i n t e r
; c l e a r c u r r e n t r e c o r d number and e x t e n t i n
; f c b b e f o r e t r y i n g t o open f o r c oun t
/
017D AF xra a ; p u t 0 i n A - re g
227
Soul of CP/M®
017E 327C00 sta e r f cb ; c l e a r record #

0181 326800 sta ext ;c le a r extent #
;C 0 U N T N U M B E R OF WOR D S I N FILE
0184 CD9901 ca L I wcount ; c o u n t words i n f i l e

0187 CD7802 ca L L c r Lf ;do c r l f
018A 3AE202 Ida nmc nt r ; do ne a l l f i Les y e t ?
018D 3D dcr a
018E 32E202 sta n mcnt r
0191 C26901 jnz movnm2 ;no
0194 2AE502 alldone Lhld old sp ; r e s t o r e o ld stack p t r

0197 F9 sph I
0198 C9 ret ; r e t u r n t o CP/M
i
/ ———
;WC0UNT SUBROUTINE-COUNTS NUMBER OF WORDS IN FILE
0199 215COO wcount lxi h , f cb ; d i splay filename

019C OEOC mvi c,12 ; (number o f c h a r )
019E CD6202 ca 11 ourprn
01A1 118702 lxi d,eqmess ; t h e n t h e e qu a l s i g n
01A4 0E09 mvi c , p r i nts
01A6 CD0500 ca 11 bdos
A
; op en f i l e f i r s t t hen s t a r t c o u n t i ng words
01A9 AF xra a ;0 in A-regi s te r
01 AA 32E102 sta status ; s e t word-continue f la g
01 AD OEOF mvi c,openf ; op en f i l e
01AF 115C00 lx i d , f cb
01B2 CD0500 ca 11 bdos
01B5 3C i nr a ; c h e c k i f code was f f
01B6 CA1102 jz error ; i f s o , f i l e i s gone
r
01B9 010100 lx i b,1 ; s t a r t word c o un t = 1
01BC C5 loop: push b ; s a v e word c o un t
01BD 0E14 mvi c,readf ;re a d next record
01BF 115C00 lxi d , f cb
0 1 C2 CD0500 ca 11 bdos
01C5 C1 pop b ; r e s t o r e word c o un t
01 C6 B7 ora a ; i s i t end o f f i l e ?
228
Soul Searching
01C7 C20302 jnz e o f i Le ; d i s p l a y i t and end

01CA 218000 lxi h,dma ; s t a r t o f r e c o r d i n DMA
/
01 CD 7E loop2: mov a,m ;g e t character
01 CE E67F ani 7fh ;mask o f f h i - b i t
01 DO FE1A cpi c t r Iz ; i s i t end o f f i le?
0 1 D2 CA0302 jz e o file ; d i s p l a y i t and end
01D5 FE20 cpi 20h ; i s i t a space?
01D7 CAF501 jz space ;yes.
01 DA FEOD cpi cr ; o r cr?
01 DC CAF501 jz space
01DF FEOA cpi If ;o r If?
01E1 CAF501 jz space
r
; I t ' s some o t h e r nonspace c h a r a c t e r .
/
01E4 3AE102 Ida status / c o n t i n u a t i o n o f word?
01E7 FEOO cpi wf lag
01E9 CAFA01 jz next ; y e s , d o n ' t increment c
01 EC 03 i nx b / i n c r e m e n t word c oun t
01 ED 3E00 mvi a , w f lag ; f o l l o w i n g c h ar s a re c<
01EF 32E102 sta status ; o f word: s e t s t a t u s
0 1 F2 C3FA01 jmp next
X
0 1 F5 3E01 space mvi a,spfLag ; s e t s t a t u s t o spaces
01F7 32E102 sta status
r
01 FA 23 next i nx h / i n c r e m e n t DMA p o i n t e r
01 FB 7C mov a,h ; a t end o f DMA?
0 1 FC B7 ora a
0 1 FD CACD01 jz l oop2 ; n o , l oop
0200 C3BC01 jmp l oop ; y e s , read n e x t r e c o r d
r
0203 115C00 e o file lxi d , f cb ;close f i l e
0206 C5 push b ; s a v e w or dc ou nt
0207 0E10 mvi c , c Losef
0209 CD0500 ca ll bdos
020C C1 pop b ; g e t i t back
020D CD1C02 ca 11 b i n i dec ; p r i n t i t o u t ( i n dec )
0210 C9 ret ; n o r m a l end o f su br
0211 118B02 error lxi d ,n ofiLe ; p r i n t " no f i l e f o u n d "

0214 0E09 mvi c , p r i nts
229
Soul of CP/M®
0216 CD0500 ca 11 bdos

0219 C39401 jmp a I Idone ; r e t u r n t o CP/M
;BINIDEC s u b r o u t i n e - d i s p l a y s number i n dec on s cr ee n

/
021 C C5E1 binidec push b! pop h ! ; g e t be i n t o h i
021 E 0600 mvi b,0 ;b holds le adin g 0 f l a g
0220 11F0D8 lxi d , - 10000 ; t w o s complement o f 10000
0223 CD3F02 ca 11 subcnt ; s u b 10000 and co un t
0226 1118FC lx i d , - 1 000
0229 CD3F02 ca 11 s u b cn t /thousands
022C 119CFF lxi d , - 1 00
022F CD3F02 ca ll s u b cn t /hundreds
0232 11F6FF lx i d,-10
0235 CD3F02 c a ll subcnt ; t en s
0238 11FFFF lx i d,-1
023B CD3F02 ca ll subcnt ; on es
023E C9 ret ; th a t's a il
F
; s u b t r a c t power o f t e n and c o u n t each t i me
F
023F 0E2F
o
T—
s ub cn t mvi ; c h o l d s ASCII co un t
o
1
s
0241 0C sub2 i nr c ; i n c r e m e n t c oun t

0242 22E302 sh Id temp ; save h I
0245 19 dad d ; ad d neg num i n de t o h i
0246 DA4102 jc sub2 ; lo op t i l l h i i s neg
0249 2AE302 Ih Id temp ; g e t l a s t pos v a l u e back i
024C 79 mov a,c ; g e t d i g i t back
; check f o r l e a d i n g 0
r
024D FE31 cpi ' 11 ; l e s s t ha n 1 ?
024F D25B02 j nc n oz er ;nope
0252 78 mov a,b ;check f o r 0 fla g
0253 B7 ora a ; i s i t set
0254 79 mov a,c ; p u t c back i n a
0255 C8 rz ; s k ip le a din g 0
0256 59 mov e,c
0257 CD6C02 ca 11 condi s ; p r i n t i t (zero)
025A C9 ret
025B 06FF n ozer mvi b ,0 ffh ; s e t 0 f l a g i n b f o r nonze
025D 59 mov e,c
230
Soul Searching
025E CD6C02 ca ll c ondi s ; p r i n t i t (nonzero)

0261 C9 ret
;ourprn subroutine
; d i s p l a y s a s t r i n g , u s i n g c onout
; H L = s t a r t a dd re ss o f s t r i n g , C=l en gt h
/
0262 5E ourprn mov e,m ;g e t character
0263 CD6C02 ca 11 condi s ;p rin tit
0266 23 i nx h ; i ncrement p o i n t e r
0267 0D dcr c ; d e c r e m e n t c ount
0268 C26202 jn z ourprn ; done y e t ?
026B C9 ret ; yes
F
; c o n d i s s u b r o u t i n e - d i s p l a y s one ch ar u s i n g c onout
; e x p e c t s e t o c o n t a i n t h e char
F
026C E5D5C5 condi s push h ! push d ! push b
026F 0E02CD0500 mvi c . c o n o u t ! ca 11 bdos
0274 C1D1E1 pop b! pop d ! pop h
0277 C9 ret
F
; c r l f s u b r o u t i n e - p r i n t s a r e t u r n and l i n e f e e d
0278 0E021EODCDcr I f mvi c . c o n o u t ! mvi e , c r ! c a l l bdos

027F 0E021E0ACD mvi c . c o n o u t ! mvi e , l f ! c a l l bdos
0286 C9 ret
/
0287 203D2024 eqmess db ’ = $’
028B 0D0A6E6F20nofi Le db c r , l f , ’no f i l e f o u n d ’, c r , I f , ’$’
029D 0D0A74726Fopenerr db c r , I f , ’ t r o u b l e o pe n i ng f i l e $ ’
02B4 0D0A46696Carraymess db c r , I f , ’F i l e s Words’, c r , I f
—i
4 -
02CB 2D2D2D2D2D db
0
£_
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
1
N
V
02E1 status ds 1 ; l a s t ch ar space o r n o t ( 1 = S j

02E2 nmcntr ds 1 ;number o f words
02E3 temp ds 2 ;temporary
02E5 oldsp ds 2 ; o l d s t a c k poi n t e r
02E7 ds 32 ;new s t a c k
stktop: ;new s t a c k s t a r t s here
0307 0903 pntrtab dw table ; p t r t o c u r r e n t name i n t a b l
0309 table ds 12*30 ; t a b l e h o l d s 30 f i l e names
0471 end 100h
231
Soul of CP/M®
Set up local stack.
Set count of program

names in array to zero.
“error”
Print “No
Search for first
file found”.
occurrence of
filename.
“last file"
Print “ Files W ords”

heading.
"nm fnd” “ movnm” f
Search for next Set pointer to

occurrence of start of array.
filename.
“movnm 2 ” ł
Get one filename

from array;
put in FCB.
No
Count words
in file (“wcount”
Put filename
in array.
“alldone”
Fig. 7-4. Flowchart of the “ WORDS” portion of the program in Listing 7-1.
232
Soul Searching
Display filename
and equal sign.
T
Set status flag to "spaces".
T
Open file.
No Print ‘No
file found” .
Set wordcount = 1.
"lo op" j
Print wordcount
Set pointer to start of (In decimal)
record in DMA. using BINIDEC.
(
Get one character Exit from A
from DMA. wcount J
Is it an end-of-file?
^ Yes Set status flag

Is it a space?
to "spaces".
j T no
T no
"next"
Is it the continuation ■«^Y es
Increment
of a word? pointer to DMA
to next character.
|N o
Increment
word count.
ł
Set status flag
to "word". No Done all 128
characters in DMA
Fig. 7-5. Flow chart of the “ W C O U NT” su b ro u tin e in the ‘ ‘WORDS program
(Listing 7-1).
233
Soul of CP/M®
ever data it needs) expand upward, while they start the stack in high mem
ory and have it expand downward. This keeps a “ no-m an’s-land” free
between the program and the bottom of the stack (until, if you’re not care
ful, either the program or the stack gets too big, and they run into each
other, and the system crashes).
What do we mean by stack management? Well, so far, whether you’ve been
aware of it or not, we’ve let various other programs take care of the stack for
us. When we used DDT, it started the stack at location FF (which turned out
to be slightly inconvenient for us, since that’s where the default DMA
address is). When we ran programs in the form of COM files, we let C P/M
take care of the stack.
W hat’s wrong with that? Well, suppose we had made a mistake in our pro
gram, like putting more things on the stack than we took off (too many
...
Top of memory.
CP/M
free
memory
/
stack ------------ User’s stack, growing downward.
llllllllllllllllllllll
-4 ------------ No-man’s-land.
llllllllllllllllllllll
Assembly
----------- User’s program.
language
program 100
/
Zero page 0
/
Fig. 7-6. Location ot the u ser’s program and the stack.
PUSFles and not enough POPs). If we did that, then when we went back to
D D T or C P/M , or whatever was managing the stack for us, there would be
trouble because what it (D DT or C P/M ) was taking off the stack wouldn’t be
what it thought there should be. Or, suppose we just put too many things on
the stack for D DT or C P /M to handle. Then, we’d probably overwrite that
part of their program just under the stack, and bad trouble would result.
So, the moral of all this is to set up your own stack in your program and
make it big enough to handle everything you ever want to put in it: two bytes
for every PUSH, and two bytes for every call to a subroutine. When you start
your program, save the old stack pointer, and when you exit from your pro
234
Soul Searching
gram, restore the stack pointer with this old value. This guarantees that
C P /M or D D T will find the stack just as it was when they passed control to
your program, and they’ll be happy.
The SPH L Instruction
Several of the instructions that work on other 16-bit registers also work
on the SP-register. For instance, “lxi sp,14ffh” will put the constant 14FF
in the SP-register, and “ dad sp” will add the contents of the stack pointer to
the HL-register. However, to load something into the stack pointer, we
need another instruction, which is “sphl” . As its name implies, this instruc
tion takes the 16-bit value from the HL-register, and puts it in the stack
pointer.
Before SPHL is executed:
SP-register HL-register
/
BF00
After SPHL is executed:
SP-register HL-register
✓ y Z ■ ■ A
BF00 /-* — BF00 /
Fig. 7-7. The SPHL in stru ctio n .
Examples:
sphl
In the W ORDS program, we set up the local stack at the beginning of the
progam (locations 100 to 107), by adding the contents of the stack pointer
and storing them in “oldstack”, and then putting the address of the “top” of
our own stack (“stktop”) into the stack pointer with an lxi instruction. Later,
when we’re about to exit from our program (at location “alldone”), we
restore the old stack pointer by getting it into the HL-register and transfer
ring it into the stack pointer with an “sphl” instruction.
This is good programming practice and should be followed in all but the
smallest programs. D on’t say we didn’t warn you.
235
Soul of CP/M®
Memory to Memory Data Transfers
It is sometimes necessary to transfer a block of data from one part of mem

ory to another. This involves looping repeatedly through a section of code
which transfers a single byte. Since this can be a comparatively time-consum
ing process, even in an assembly language program, it’s im portant to make
the routine that does the transfer as short and efficient as possible. There are
various ways to do this, using different kinds of instructions. Here’s the tech
nique used in WORDS:
r e p e a t mov a,m ; g e t byte f rom s o ur c e b l o c k

inx h ;increm ent source p o i n t e r
stax d ;p u t byte in d e s t in a ti o n block
in x d ;increment d estina tion pointer
dcr b ;decrement count-done yet?
jnz repeat ;no t yet
Data to be Data is to be
transferred transferred
is in this section to this section
of memory. of memory.
1000 /I 20DA
41 41
/ / 20DB
1001
53
53
/ 1002
y\ 20DC
68 68
/ 1003
/ 20DD
HL-register DE-register
points to 7F points to 7F
byte in this / 1004 byte in this / 20DE
part of part of
memory. — 8B
/ 1005
/ 20DF
9D
/ 1006
/ 20 E0
AO
/ /
Fig. 7-8. M em ory to m em ory data transfers.
Fig. 7-8 is a pictorial idea of how the data is arranged in memory. At the
point shown in the diagram, all the data bytes down to 7F have been trans
ferred.
Since all these instructions (except the “jn z repeat”) are only one byte, the
routine is short and executes quickly. Of course, the correct values of the
236
Soul Searching
pointers to the source and destination blocks must be placed in HL and DE,
and the correct value of the count must be placed in the B-register, before the
“repeat” loop is executed.
The LDAX Instruction
You’re already familiar with the instructions that transfer 8-bit data to and
from memory using the HL-register as a pointer. They’re “mov r,m” and
“mov m,r”, where “r” stands for any of the 8-bit registers (a, b, c, d, and e),
and “m ” stands for the memory location contained in HL. Will this instruc
tion work with other registers besides HL? No, it won’t—that’s not something
the 8080 likes to do. In order to use the DE or BC registers as pointers to
memory, we have to use several other more limited instructions: “ stax” and
“ldax.” The limitation is that these instructions can transfer data only
between memory and the A-register, rather than between memory and all the
8-bit registers as “mov” can. Otherwise, they’re quite similar.
The “ldax r” instruction loads the A-register with the byte in memory at
the address pointed to by register “r”, where “r” stands for either the BC or
the DE register, but not the HL register. (Of course, you will use 1-letter
abbreviations for the registers: “b ” for the BC-register, and “d” for the DE-
register.)
Examples:
ldax b
ldax d
The STAX Instruction
Similarly, “stax r” stores the contents of the A-register into memory at the
location contained in register “r”, where “r” can be either the DE- or the BC-
register.
Examples:
stax b
stax d
237
Soul of CP/M®
Before LDAX D is executed:
DE-register
/ / 0100 Section of
memory
2011 containing
/ 0101 program.
A-register
/ 0102
/ 0103 LDAX D
1A
/ 0104
/
llilllllllllllllllll
/ 2010 Section of
memory where
/ 2011
constant is
stored.
6B
/
2012
/
A fter LDAX D is executed:
DE-register
/ / 0100
Section of
memory
containing
/ 0101 program.
/ 0102
/ 0103 ■LDAX D
12
/ 0104
/
/
//////////////////
llllllllllllllllll
/ / Section of
2010 memory where
constant is
/
2011 stored.
6B
/
2012
Fig. 7-9. The LDAX instruction.
238
Soul Searching
Before STAX B is executed:
BC-register

2011
A-register
/ 0101
containing program.
/ 0102
FA
/ 0103 STAX B
10
/ 0104
/
/
////////////////////
////////////////////
where constant is
/ 2011 stored.
2012
/
After STAX B is executed:
BC-register
Section of memory
containing program.
STAX B
Section of memory
where constant is
stored.
Fig. 7-10. The STAX instruction.
239
Soul of CP/M®
In setting up the DE register-pair at the beginning of the “putary” sub

routine, we used another instruction that you have not yet been introduced
to.
The XCHG Instruction
It’s easy to take a 16-bit value from a memory register and put it in the
HL-register; we use a “lhld” instruction. U nfortunately, there is no such
instruction which will load a value from a memory location into the DE-
register. If we knew when we were writing the program what value we
wanted to load in, we could use an “lxi” instruction, but we don’t, since this
value changes every time we load in a new file name. So how do we get a
value from memory into the DE-register? We load it into the HL-register
first, with an “lhld,” and then exchange the values of the HL and D E regis
ters with the “xchg” instruction. This instruction is used again, ju st after
the repeat loop, to save the contents of the DE-register in memory location
“pntrtab.”
Before XCHG is executed:
After XCHG is executed:
/ ....... y?---- ....... VI

BF00 /- * ------------ A123 [ /
Fig. 7-11. The XCHG instruction.

Example:
xchg
How W ORDS Handles Wildcards
As we described earlier, the program first looks through the disk directory
for all of the program names that match the name in the FCB. These names
are then stored in an array, called “table.” This is accomplished in the section
240
Soul Searching
of the program called “Scan For File Names and Put in Array.” As you can
see, the code to do this doesn’t look too different from the simple D D T pro
gram that we used to perform the same search “by hand” in the last section.
The actual transfer of the names to the array takes place in the subroutine
“putary,” and makes use of the little memory-to-memory routine described
earlier. After putting the file name in “table,” this part of the program then
increments “nmcntr,” which holds the number of file names, and, then, goes
back to look for another possible match.
Once all the file names have been transferred to “table,” the program then
goes on to its second phase, that of reading the individual files one at a time
and counting the number of words in each one. This is done in a short section
of code called “Count Number of Words in File.” All this section does is
keep track of how many files have been counted, using the “nm cntr” varia
ble. Once they’ve all been counted, it restores the old stack pointer and
returns to C P /M in “alldone.”
The real work of counting the number of words in each file is performed by
the subroutine “wcount.” This subroutine starts by displaying the file name
and opening the file. The rest of the routine consists mostly of two nested
loops: (1) the outer one, “loop,” reads a new record every time it is entered,
while (2) the inner one, “loop2,” examines a new character each time it is
entered.
We use a 1-byte variable called “status” to keep track of whether we’re in
the middle of a word, in which case “status” is set to 0, or in the middle of a
group of spaces, in which case “status” is set to 1.
Depending on what the character is that we’ve read, and what “status” is
set to, we do different things. If the character is a space, or a carriage return,
or a linefeed, then “status” is set to a 1. If the character is not any of these
things, then we assume it’s part of a word and either one of two things may
happen. If “status” is a 0 (meaning that the last character was a nonspace
character and, thus, we’re already in the middle of a word), no action is
taken. If, on the other hand, “status” is set to a 1 (meaning that the last
character was a space), then, first, the word count is incremented, and sec
ond, “ status” is set back to 0. Thus, every time we change from a space to a
nonspace character, we count one word.
Subroutines in W O RDS
If you played with the BINIDEC routine earlier in the book, you’ll notice
that it’s somewhat different here. We’ve added a refinement; it no longer
prints out leading zeros. It accomplishes this by using the B-register as a
241
Soul of CP/M®
status flag to keep track of whether or not a nonzero character has been
encountered in the process of printing the decimal number. If so, then the B-
register is set to 1, otherwise it’s 0. If the routine is about to print a zero, it
first checks to see if the B-register is 0. If so, it doesn’t print anything, but
goes on to calculate the next digit.
The “ourprn” subroutine simply prints out a string of characters on the
string, starting with the character at the address in the HL-register. This is
useful for printing out the names of the files; they aren’t terminated with
dollar signs, so we can’t use the Print String system call.
The “condis” and “crlf” subroutines should be self-explanatory; in the
interest of making them look more compact, they have been written with a
lot of ! signs.
It’s All Over but the Cheering
That about takes care of our description of the W ORDS program, which is
the longest we’re going to try to cover in this book. If it isn’t all clear to you
right away, keep working on small sections of the program. One of the best
ways to try to understand a long program is to sit down and imagine how you
would try to write a particular section of it yourself. Then, compare your
code with the program. They may be surprisingly similar, in which case,
you’ll immediately understand what that part of the program is supposed to
do. And, if they don’t look the same, then, at least you’ll have defined the
problem to yourself and, in comparing the differences, you’ll learn something
new about programming.
In the next chapter, we’re going to turn to something different: how to
interface assembly language routines with higher-level language programs.
242
CHAPTER 8
Teamwork
Using Systems Calls From BASIC
Besides being called from assembly language routines, the system calls that
we’ve described in the preceding chapters can also be called from higher-level
languages such as BASIC, Pascal, and FORTRAN. (They can even be called
from programs such as dBASE II™, a data-base program with a built-in pro
cedure for interfacing with machine-language routines.) When called in this
way from higher-level languages, the system calls are usually part of a short
assembly language routine which performs a specific function that is difficult
or time-consuming to accomplish in the higher-level language.
This chapter describes how to to call assembly-language routines from
within a BASIC program. Although BASIC is used in the examples, many of
the techniques described are applicable to other high-level languages as well.
There are four main questions that must be answered in order to connect
an assembly language routine to a BASIC program.
These are:
1. Where do we put the assembly language program in memory?

2. How do we get it there?
3. How do we transfer control between BASIC and the assembly lan
guage routine?
4. How do we pass arguments (data) between BASIC and the assembly
language routine?
dB A SE II is a tradem ark o f A sh ton -T ate, Inc.
243
Soul of CP/M®
We’re going to start off by describing the four questions that are raised
above and, then, we will use an example program to illustrate one possible set
of answers (the simplest one). D on’t worry if all the details don’t seem com
pletely clear while you’re reading about the four problems. Things will
straighten themselves out when we get to the example. In fact, you might
want to glance forward at the example program (which is called BINIHEX2)
from time to time as you’re reading about the four problems—just to keep
yourself grounded in reality.
Once we’ve everything working in the simplest possible way, we’ll go back
and, using different approaches and examples, explore some of the more
complicated alternative solutions to the problems. Before we start, let’s agree
on a convention: “assembly language” will be abbreviated to “A-L” in the
rest of this chapter. This will save a lot of writing for us, and a lot of eyestrain
for you.
WHERE DO WE PUT THE A-L PROGRAM IN MEMORY?
When there’s only one program in memory, there’s usually no problem

about where to put it. A-L programs always go at 100 hex, and BASIC pro-
244
Teamwork
grams go wherever the BASIC interpreter puts them, growing upward from
itself. Fig. 8-1 shows what that looks like with an A-L program.
The CCP need not be in memory when a program is running, so it can be
overwritten. That is, A-L programs may extend all the way up to the bottom
of BDOS, an address called FBASE. We’ll say more about FBASE later.
The BASIC interpreter always uses the CCP area. Fig. 8-2 shows how
memory looks when BASIC is loaded.
Notice how the user’s program grows upward into free memory, while the
BASIC stack grows downward to meet it. This means that we never know
exactly where the space in between the two is going to be. It can get gobbled
up by the program or by the stack and only the BASIC interpreter knows
when that’s going to happen. So this area doesn’t look like a good place to try
to put an A-L routine. Where else could it go?
The way BASIC handles this is by providing a way to “protect” a section
of memory above the stack. This is usually accomplished when BASIC is first
loaded, by specifying a memory address in the load command string. For
instance, if we loaded our particular BASIC interpreter, MBASIC5, with the
following command,
A>mbasic5 / m:a000
then, mbasic would start its stack at A000 hex, and would let it grow down
ward from there. Thus, the memory between A000 and FBASE (the bottom
of BDOS) would be available for our A-L program.
Let's see how this “protected” memory looks. It is illustrated by the dia
gram in Fig. 8-3. So if we put our A-L program at A000 hex, we know it will
be safe and happy, provided, of course, that there is enough room for it
between A000 and the bottom of BDOS (FBASE).
Anyway, that is the way things should be. The way they really are, however,
is more complicated. This is because (at least, in this first and simplest
approach) we have to load our A-L routine using D D T and, thus, it must fi t
below DDT.
Why do we have to load it using DDT? That’s a long story and we’ll get to
it in the next section. For the time being, let’s see what memory looks like
with D D T loaded. This is shown in Fig. 8-4.
The question, then, is, where is the bottom of DDT? If we know this
address, which we’ll call DBASE, then we can assemble our A-L program so
that it lies just below it.
Finding out exactly where DBASE is may not be easy. However, the fol
lowing table shows the approximate addresses for various sized systems.
245
Soul of CP/M®
z: Top of memory.
BIOS
/
BDOS
FBASE
• Can be over-written
CCP if more space is
CBASE
needed.
//////////////////
User’s
A-L
Program 0100 hex
0000 hex
Zero Page
Fig. 8-1. Location o f assem bly language program in memory.

/ .. /
BIOS
BDOS FBASE
/
Stack
//////////////////
//////////////////
User’s
BASIC
Program
/
BASIC
Interpreter 0100 hex
Zero Page 0000 hex

/
Fig. 8-2. Location o f BASIC in te rp re te r in mem ory.
z: Top of memory.
BIOS
BDOS
- A-L routine can go here.

A000
Stack
Address specified
////////////////// in BASIC load command.
//////////////////
User’s
BASIC
Program
/
BASIC
Zero Page 0000 hex
Fig. 8-3. A “ protected” memory area for the assembly language subroutine.
246
Teamwork
Top of memory.
BIOS
/
BDOS FBASE
/
DDT DBASE •* ------ W hat’s this address?
/
A-L Routine
/
Stack
llllllllllllllllll
llllllllllllllllll
User’s
BASIC
Program y
BASIC
Zero Page 0000 hex
Fig. 8-4. Memory with DDT loaded in.
Although these addresses may vary somewhat from one version of C P /M to

another, they will be good enough if you make sure that your A-L routines
leave some space as a fudge-factor between themselves and DBASE.
32K 48 K 56K 64K System Size

5400 9400 B400 D400 D BA SE (bottom o f D D T )
There’s another way to figure out where DBASE is. Load DDT, and use it
to look at itself! You should begin by turning off your system and then pow
ering it up again, to ensure that all unused memory is filled with zeros. Then,
load D DT and use the “d” command to look in high memory, somewhere
around the addresses given in the preceding table. Below a certain point,
memory will be filled with all zeros (or sometimes FFs, depending on your
system). Above that point, it will be filled with the hex code of the D DT
program. You should be able to find this point by trial and error. When you
do, you’ve found DBASE.
So now, you know where to put your A-L routine in memory: just below
the address that you’ve found for DBASE. Or even a good bit below, if mem
ory space is not critical. (It won’t be in our short demonstration programs.)
There is, of course, a problem with this approach. Since we are using
D D T to load the A-L program, we have to put it lower in memory than we
247
Soul of CP/M®
want to. Although this isn’t a problem with our example programs, it could
certainly become an inconvenience if we were using a very long BASIC pro
gram that needed all the space it could get. Normally, we can load pro
grams all the way up to FBASE (the bottom of BDOS), but now, we can
only load as far as DBASE, the bottom of DDT. Later, we’ll look at ways to
avoid this problem.
HOW TO GET THE A-L PROGRAM WHERE WE WANT IT

TO GO
Suppose we write our A-L routine with our word processor in the usual
way, assemble it with ASM, create the COM file with LOAD, and then put
the routine into memory simply by calling it from C P /M as with any other
COM-file program. W hat will happen? Well, it turns out that the LOAD
program only wants to create COM files for programs that start at 100 hex.
This is an unfortunate limitation, but that’s the way it is. So if we specify
ORG to be someplace in high memory, say A000, the routine will assemble
properly, but LOAD will not be able to digest it and error messages will
ensue.
W hat to do? This is where D DT comes in. It turns out that DDT, bless its
little heart, will load a HEX file anywhere that we want, in either high mem
ory or low. All we have to do is say:
A>asm testprog Assemble the program.

A>ddt testprog.hex Load resulting HEX file with DDT.
-g0 Back to CP/M.
A>
Now, we can go on and load BASIC, with the proper memory limit, and
we’re on our way. We’ll see exactly how this is done when we get to our
example program.
HOW DO WE TRANSFER CONTROL BETWEEN BASIC

AND THE A-L ROUTINE?
There are two parts to this question: getting from BASIC to the A-L rou
tine, and getting back.
248
Teamwork
Getting From BASIC to the A-L Routine
We tell BASIC where the A-L routine is located in memory with the
D EFUSR statement:
20 DEF USR1 = &HA000
This statement appears only once, at the beginning of the program. From
it, BASIC knows that every time the routine “USR1” is called, BASIC should
transfer control to location A000. (The “&H” specifies that the address which
follows will be in hexadecimal.)
To actually go to this routine, we execute a BASIC statement like:
50 D=USR1( A)
This statement could take a wide variety of forms. In fact, whenever “USR1”
appears in the program, BASIC will transfer control to the A-L routine at
A000.
Getting Back to BASIC From the A-L Routine.
Going this way is much easier. All we have to do in the A-L routine is a
“ret” and, presto, we’re back in BASIC.
HOW DO WE PASS ARGUMENTS BETWEEN BASIC AND

THE A-L ROUTINE?
One of the unfortunate limitations of BASIC is that only one argument can
be passed from BASIC to the A-L routine, and only one argument can be
returned. (There are ways around this problem, but they can be somewhat
complicated.) Take the BASIC statement:
B = USRKA)
The variable A is the argument that is passed from BASIC to the A-L
routine. From the viewpoint of the BASIC program, passing the value of the
variable A is automatic. When this statement is executed, the BASIC inter
preter makes sure that this value is passed to the A-L routine.
The variable B is the argument that is returned to BASIC from the A-L
routine. Again, from the viewpoint of the BASIC program, the procedure is
249
Soul of CP/M®
automatic. Once the statement has been executed, B will have whatever value
was returned by the A-L routine, and BASIC can make use of the value in
subsequent statements. So it’s fairly straightforward to deal with these argu
ments in the BASIC program. But what does the A-L routine have to do first,
to find out what the value of A is and, second, to pass the value of B back to
BASIC?
BASIC keeps a set of memory locations deep in its innards that are called
the “ Floating Point Accumulator,” or FAC. These locations are used to pass
arguments back and forth between BASIC and the A-L routine. Either 2, 4,
or 8 of these locations are used to hold the argument, depending on its varia
ble type. For integer variables, which are two bytes long in BASIC, two of the
locations are used, as shown in Fig. 8-5:
If we assume that the BASIC variable “A” is an integer, then, when the
statement “USR1(A)” is executed in the BASIC program, BASIC will auto
matically put the the value of A into the FAC. When control passes from
BASIC to the A-L routine, BASIC makes sure that the HL-register contains
the address of FAC-3. Thus, at the beginning of the A-L routine, all you have
to do is get the variables out of the FAC using the address of FAC-3 in the
HL-register.
An added nuance here, which we won’t make use of but which could come
in handy in some situations, is that the A-register holds a number which tells
you what kind of variable is in the FAC:
2 = integer
3 = string
4 = single-precision floating point
8 = double-precision floating point
FAC
z 71 higher
memory
FAC-1
hi-order byte integer

FAC-2
variable
FAC-3 lo-order byte
V
Fig. 8-5. The Floating Pointer Accumulator.
250
Teamwork
So, if your A-L routine doesn’t know what kind of variable to expect, it can
find out by looking at the A-register. (Note that these numbers also tell the
number of bytes in the variable.)
In the example that follows, we’re going to describe how integers are
passed to the A-L routine and, later in the chapter, we’ll show how strings are
communicated. We won’t cover floating point variables since these can vary
from one version of BASIC to another, but the principles involved are much
the same.
How do we pass a variable to BASIC when we return from the A-L rou
tine? The same way: we put it into the FAC. There’s no need to put anything
in the HL-register since BASIC already knows where the FAC is. The value
returned by the A-L routine should be of the same type (integer, string, etc.)
as the value that was passed to it.
BINIHEX2—A-L ROUTINE CALLED FROM BASIC
You should recognize the name of this program; you’ve seen it before in
the chapter on console system calls. We’re going to take this same program
and modify it to work with BASIC. That is, we’ll give BASIC the responsibil
ity for getting the decimal number from the user and converting it to binary
(it does this automatically). All that our A-L routine will have to do is print
out the binary number in hex digits.
This is actually a handy little routine since many versions of BASIC don’t
have a way to print out variables in hex format. Here’s the BASIC program:
10 DEFINT A-Z
20 DEF USR1=&HA000
30 INPUT"deci ma I n um be r "; A
40 PRINT"hex e q u i v a l e n t i s :
50 D=USR1( A)
60 PRINT: PRINT
70 GOTO 30
We’ll assume that you’re familiar enough with BASIC to follow what’s
happening here.
We define the entry address of our USR1 routine to be A000 because we
know this is well below the bottom of D D T (DBASE), which is at B400 in
our 56K system. (This will be different on different-sized systems. See the
preceding discussion on where to put the A-L routine.) We could have placed
251
Soul of CP/M®
it closer to DBASE, but there’s plenty of room in memory for these short
example programs, so we don’t have to be too precise. With larger programs,
it would be wise to assemble the A-L routine first, examine the PRN file to
see how long it is, and then ORG it so that the end of the A-L routine fits just
below DBASE.
For simplicity, we define all variables in the BASIC program to be inte
gers, using the D E FIN T statement. The integer variable A is passed to the
USR1 routine, which is the BINIHEX2 program (Listing 8-1).
Listing 8-1. The BINIHEX2 Program

• •k'k'k'k'k'k'k'kick'k-k'k'k'k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'kic-k'k'k'kic'k'k'k'k'k'k'k'k'k-k'k
; B I N I H E X 2 - C o n v e r t s b i n a r y t o h ex , p r i n t s i t o u t
; ( t o be c a l l e d f rom BASIC pro gr am)
0001 = coni n equ 1h

0002 = c onout equ 2h
0005 s bdos equ 5h
000A = If equ Oah
f
A000 o r g 0a000h
r
; t r a n s f e r i n t e g e r f ro m FAC t o h i reg i s t e r
; (on e n t r y h i h o l d s p o i n t e r t o lo - order
A000 5E mov e,m ; p u t lo - b y t e in e
A001 23 i nx h ;bump t he poi nte r
A002 56 mov d,m ; p u t hi - b y t e in d
A003 EB xchg ; p u t de i n h i
c o n v e r t b i n a r y t o hex and p r i n t i t o u t
(on e n t r y h i h o l d s t h e b i n a r y i n t e g e r )
A004 7C mov a , h ;p u t h in a ( f i r s t d ig it)
A005 CD15A0 c a ll p r in tl ; p r in t le ft-h a n d d ig it
A008 7C mov a ,h ; p u t h i n a ( second d ig it)
A009 CD19A0 c a ll p rin t2 ; p r in t right-hand d ig it
AOOC 7D mov a , I ;p u t I in a ( t h i r d d ig it)
AOOD CD15A0 c a ll p r in tl ; p r in t le ft-h a n d d ig it
A010 7D mov a , I ;p u t I in a (fo u r th d ig it)
A011 CD19A0 c a llp rin t2 ; p r in t right-hand d ig it
A014 C9 ret ; e x i t binihex
print contents of a
252
Teamwork
A015 07070707 p r i n t l rlc ! r l c ! r l c ! r l c ;move h i g h 4 b i t s t o Low

A019 E60F p rin t2 ani Ofh ; g e t r i d of high 4 b i t s
A01B C630 adi 30h ; cha nge hex t o ASCII
A01D FE3A c pi 3ah ; i f more t han 9
A01F DA24A0 jc notbig ; ( i t ' s not)
A022 C607 adi 7h ; t hen add b i a s (10=A, e t c . )
A024 CD28A0 notbig c a ll p c ha r ;p rin t d ig it
A027 C9 ret
/
;s u b ro u tin e to p r i n t c h a r a c t e r i n a - r e g o u t on s cr ee n
A028 E5 p cha r push h ; s a v e h i ( c o n o u t uses i t )

A029 5F mov e,a ; p r i n t hex d i g i t
A02A 0E02 mvi c,conout
A02C CD0500 c a ll bdos
A02F E1 pop h ; g e t h i back
A030 C9 ret
A031 end
We O RG the program just where we want it to go, at A000. The first thing
that the program does is get the value of the integer A out of the FAC. Since
HL is pointing to FAC-3, the “mov e,m” instruction will put the low-order
(least significant) byte of A into the E-register. Incrementing HL causes it to
point next to FAC-2, so “mov d,m” will put the high-order byte of A into the
D-register. The complete integer is now in DE, and we swap it into HL with
the “xchg” instruction so that we can process it in the way we did before in
BINIHEX.
After printing out the four hex digits from HL, we return to BASIC with a
“ret” instruction. In this case, there is no argument passed back to BASIC.
The “ D ” in the expression D = USR1(A) in line 50 is a “dummy” argument,
meaning that it’s not used but must be there for the sake of form.
W ant to try all this out? Here’s how to do it. You should have a disk that
contains the BASIC interpreter, the ASM assembler, your text editor, and
DDT.
1. Type in the BASIC program and save it on your disk as

“ BINTEST.BAS” . (Remember not to use lowercase letters in the
names of BASIC programs.)
2. Type in BINIHEX2 using your word-processing program and save it
on your disk as “binihex2.asm” .
253
Soul of CP/M®
3. Assemble it by typing:
A > a sm binihex2
4. Use D D T to load the HEX version of the program by typing:
A > d d t binihex2.hex
5. Return from D D T with a “-gO”.

6. Load the BASIC interpreter and, at the same time, protect the neces
sary space in high memory by typing:
A >m basic5 /m:&ha000
(Of course, the “aOOO” will vary, depending on your system.)

7. In BASIC, load your program back from the disk by typing:
Ok (BASIC prompt)
load “ BINTEST” (or “BINTEST.BAS”)
8. Type “run” and see if it works!
You should be able convert from decimal to hex just as you did in the
DECIHEX program.
The BINIHEX2 routine can be used in any BASIC program you like.
Y ou’ll probably be able to think of all sorts of situations where it might come
in handy. You could, for instance, explore some of the inner workings of
BASIC by using BINIHEX2 to print out the addresses of variables, and then
using PEEKs and BINIHEX2 to print out their contents in hex. (For more
on this, see the VARPTR function in your BASIC book.)
Now that you have an idea of what’s involved in linking an assembly lan
guage routine to BASIC, we’re going to go back and explore some alternative
ways of doing things.
OTHER WAYS TO PUT THE A-L ROUTINE INTO MEMORY
Maybe you think it’s not elegant to use D D T to load the A-L routine, or
maybe you don’t want to keep D D T on your disk ju st to load a small A-L
routine to work with BASIC. Is there a way to get the A-L routine into mem
ory without using DDT? Yes, more than one. They each have their draw
backs.
254
Teamwork
Using LOAD in High Memory
Here’s a way that doesn’t work very well, although it sounds reasonable
enough at first.
The idea is this. Since LOAD only works with programs that start at 100
hex, why not simply ORG our routine at lOOh and then start the program off
with “filler” —a “ds” directive that will insert enough bytes to move the pro
gram up to where we want it to be. For instance, if we have to O RG it at
lOOh, but we really want it to be at aOOO, we can change the program like
this:
****************************************************
B I NI HEX 2- Co nv er ts b i n a r y t o h e x, p r i n t s i t o u t
( t o be c a l l e d f rom BASIC pro gr am)
0001 = conin equ 1h

0002 = conout equ 2h
0005 = bdos equ 5h
000A = If equ Oah
0100 org 01 OOh
0100 ds 9fOOh
9 f0 0h ; 10Oh + 9f 00 h = aOOOh
; t r a n s f e r i n t e g e r f ro m FAC t o h i r e g i s t e r
; (on e n t r y h i h o l d s p o i n t e r t o l o - o r d e r b y t e i n FAC)
A000 5E mov e,m ; p u t lo -b y te in e
A001 23 i nx h ;bump t he p o i n t e r
A002 56 mov d,m ;p u t h i-b y te in d
A003 EB xchg ; p u t de i n h I
Well, that looks just fine. We can assemble the program with ASM, and
that’s fine too. However, when we use LOAD, we get our first clue that all is
not well.
255
Soul of CP/M®
A>load b i n i h e x 2
FIRST ADDRESS AOOO

LAST ADDRESS A030
BYTES READ 0031
RECORDS WRITTEN 3F
“Records written 3F”? That’s an awful lot of records! If we use STAT on

“binihex2.com’’, we see that it’s occupying 40K bytes on the disk. Terrific.
LOAD has actually stored all the meaningless bytes between lOOh and aOOOh
in the file.
So this scheme doesn’t seem so good. It works, but even a few such small
routines will quickly fill up our disk. There must be a better way.
Moving the A-L Routine After Loading
Let’s think about another way to get the A-L routine where we want it.
Why can’t we assemble it at 100 hex, like any other program, and then just
take all the bytes of the program and move them up to high memory where
we want them? We could use the code segment, which we discussed in the
last chapter, for moving the contents of a block of memory to another loca
tion.
Sounds good. The trouble is that if you move a program to a different
place in memory, all of the “memory reference” instructions in the program
will be wrong. Memory reference instructions are those that refer to partic
ular addresses (like “jm p ” and “ call”) which jum p to a specific memory
location. For instance, in BINIHEX2, the instruction at location A005
which is “call p rin tl”) should be CD15A0, since it wants to jum p to a sub
routine at location A015. But, if we assemble BINIHEX2 at lOOh, this
instruction will become CD 1501, which is a “call” to a subroutine at loca
tion 0115, not A015.
W hat we need, then, is a way to fool the assembler into thinking that
things are up in high memory when, in fact, they’re just down in the program,
which starts at lOOh. This way, when we move the program up to high mem
ory, the instructions will say the right thing (“call p rin tl” will be CD 15A0,
and so on).
So, how do we fool the assembler? Very cleverly! But to understand it, you
need to know what the dollar-sign symbol means to the assembler.
256
Teamwork
The Label
When the “$” symbol is used in the address field of an instruction, it takes
on the value of the current program line. For example, suppose you have the
following section of code:
; en d o f main p a r t o f program
$
0111 CD1501 c a ll p rin t

0114 C9 ret
/
; s t a r t of subroutine p r i n t
/
0115 7 C p rin t mova , h
All this shows is a program fragment that calls a subroutine and the begin
ning of the subroutine, “print” . Nothing unusual here. Now, let’s write it
slightly differently.
; end o f main p a r t o f program

0114 C9 ret
/
0115 p rin t equ $
0115 7 C mov a ,h
257
Soul of CP/M®
By using the $ symbol and an EQU directive, we’ve given “print” the value
0015, because that is the memory location at this point in the program. Sub
sequent “CALLs” to print will go to location 0015, just as they would have if
it were simply used to label the line as in the first code fragment.
So how can we use the dollar sign? Well, we can now modify the value that
the assembler gives to a label; whereas before, it could only have the value of
the line it was on. And this suggests a solution to our problem; that is, a way to
have instructions occupy one place in memory while they refer to some place
else. Since the label “print” is given its value with an EQU directive, we can
change that value by doing arithmetic on the operand field that contains the
“$”. For instance, we could change the “equ” line in the above example to:
; en d o f main p a r t o f program
f
0114 C9 ret
A
f
0315 p rin t equ $ + 200h
0115 7 C mov a ,h
This would give “print” the value of 0315h, or $ + 200h. And look at this:
the “call print” instruction changes so as to refer to address 0315, even
though the the “print” subroutine is still located at 0115. (Remember that the
high and low bytes appear in reverse order in 8080 language, so that CD 1503
means a “jm p ” to 0315.)
In our situation, we need to move our routine from some place around
lOOh, in low memory, to some place up around AOOOh (or whatever address is
appropriate to your system) in high memory. To do this, we need to come up
with a number that’s the difference between lOOh and AOOOh. Actually, we
don’t need to do the calculation. We can let the assembler do it for us.
258
Teamwork
; e n d o f main p a r t o f program
f
0111 CD15A0 c a ll p rin t
0114 C9 ret
f
A015 p rin t equ $ + (OaOOOh - 10Oh)

0115 7C mov a ,h
AOOOh minus lOOh is 9F00, and adding 115 gives A015h, which is just
where we want “print” to go when we move the program to high memory.
To summarize: we’re going to do two things. First, we will assemble and
load our program at lOOh, but move all its bytes up to where we want them in
high memory, after the program has been loaded. Second, we will change all
the labels in the program so that they will have the correct values for their
new locations in high memory.
Let’s see how BINIHEX2 looks when we make these changes. We’ll call
the result BINIHEX3 (Listing 8-2).
Listing 8-2. BINIHEX3 Program

; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
; B I N I H E X 3 - C o n v e r t s b i n a r y t o hex and p r i n t s i t o u t
; ( t o be c a l l e d f rom BASIC p r o g r a m ) .
0001 = conin equ 1h

0002 = c ono ut equ 2h
0005 = bdos equ 5h
000A = If equ Oah
A000 = d e s t i n equ OaOOOh ; w he r e t h e r o u t i n e w i 11 go
0100 org 100h

/
; r o u t i n e to m o v e r est of p r o g r a m to h i g h m e m o r y
259
Soul of CP/M®
0100 013200 lx i b , e n d i ng - s t a r t + 1 ; n b r o f b y t e s t o move

0103 111401 lx i d ,sta rt ; w h er e t h e y come from
0106 2100A0 lx i h,desti n ; w h er e t h e y ' r e g o i n g
0109 1A movem ldax d ; g e t byte
010A 13 i nx d ;increm ent p o in te r
01 OB 77 mov m,a ; s t o r e byte
010C 23 i nx h ;increm ent p o in te r
010D OB dcx b ; d e c r e m e n t c oun t
01OE 78 mov a,b ; b o t h B and C must be 0
01 OF B1 ora c ; so OR them t o see
0110 C20901 jnz movem ; o t h e r w i s e n o t done
0113 C9 ret ; r e t u r n t o CP/M a f t e r move
0114 = s t a r t equ $
A
9EEC = o f f s e t equ d e s t i n - s t a r t
A
; t r a n s f e r i n t e g e r from FAC t o h i r e g i s t e r
0114 5E mov e,m ;p u t lo -b yte in e
0115 23 i nx h ;bump t he poi n t e r
0116 56 mov d,m ;p u t h i-b y te in d
0117 EB xchg ; p u t de i n h I
W
; c o n v e r t b i n a r y t o hex and p r i n t i t o u t
; (on e n t r y h i h o l d s t h e b i n a r y i n t e g e r )
0118 7C mov a ,h ;p u t h in a ( f i r s t d i g i t )
0119 CD15A0 ca 11 p r i n t l ; p r in t le ft-h a n d d i g i t
011C 7C mov a ,h ; p u t h i n a (s eco nd d i g i t )
0 1 1 D CD19A0 cal I pr i nt2 ; p r in t right-hand d i g i t
0120 7 D mov a , I ;p u t I in a ( t h i r d d i g i t )
0121 CD15A0 c a ll p rin tl ; p r in t le ft-h a n d d i g i t
0124 7 D mov a , I ;p u t I in a (fo u r th d i g i t )
0125 CD19A0 c a l l p r i nt2 ; p r in t right-hand d i g i t
/
; s h i f t i f n e c e s s a r y , and change t o ASCII
A015 = p rin tl equ $+offset

0128 7070707 rlc ! r l c ! r l c ! rlc ;move h i g h 4 b i t s t o low
A019 = p r i nt2 equ $+offset
01 2D E60F ani Of h ; g e t r i d of high 4 b i t s
012 F C630 adi 30h ; c h a n ge hex t o ASCII
260
Teamwork
0131 FE3A cpi 3ah ; i f more t ha n 9

0133 DA24A0 jc notbi g ; ( i t 1s n o t )
0136 C607 adi 7h ; t he n add b i a s (1 0= A, e t c . )
A024 = n o t b i g equ $+offset
0138 CD28A0 ca 11 pchar ; p r in t d ig i t
013B C9 ret
/ s u b r o u t in e to p r i n t c r a c t e r i n a - r e g o u t on s c re e n
A028 = p char equ $+o f f s e t

013C E5 push h ; s a v e h i ( c o n o u t uses i t )
013D 5F mov e,a ; p r i n t hex d i g i t
013E 0E02 mvi c,conout
0140 CD0500 ca ll bdos
0143 E1 pop h ; g e t h i back
0144 C9 ret
w
0145 = e n d i n g equ $
0145 end 10Oh / s t a r t i n g add re ss
The program now has two parts. The first part is the transfer routine,
whose sole jo b is to move the rest of the program up to high memory. This is
a fairly straightforward loop, which moves all the bytes between “ start” and
“ending” to the block in high memory that starts with the location “destin”
(for “ destination”). When we’re done with the transfer, we go back to C P /M
with a “ret” .
Notice how all the labels in the main part of the program have been given
new values with the “equ $ + offset” statement. If you look at the assembled
hex code, you’ll see that all the jum ps and calls go to the appropriate loca
tions in high memory.
Here’s how we use this version of the program:
1. Type in BINIHEX3, assemble it with ASM, and create a COM file

version with LOAD. LOAD will not generate an enormous file
because the program doesn’t occupy any space in high memory—yet.
2. From C P/M , simply type:
A >binihex3
This will load the program into mem ory, where it will then move itself
261
Soul of CP/M®
up to high memory. (The “move” part of the program will be left

behind, but we don’t care.)
3. Load BASIC the same way as before:
A >m basic5 /m:&ha000
4. From BASIC, load the BINTEST program:
Ok
load “BINTEST”
5. Type “run,” and watch it go!
Unfortunately, as you will have noticed, this approach also has a glaring
defect. Because we need to use the CCP part of C P /M to load BASIC after
we have loaded the A-L routine, we can’t locate the A-L routine just under
FBASE (the bottom of BDOS) where we would like to. We must put it below
CBASE, the bottom of the CCP. This loses us about 800 hex bytes of mem
ory. Too bad.
POKEing the A-L Routine Into Memory From BASIC
Our next attem pt to put the A-L routine in memory is time-consuming to

set up, but it has a major advantage. We can overwrite the part of the mem
ory used by the CCP. Since the CCP occupies about 800 hex (2048 decimal)
bytes, this can offer a substantial saving in memory space.
But where is FBASE? Let’s summarize where the major parts of the C P /M
system are stored in various sized systems:
System Size 32K 48K 56K 64K

FBASE (BDOS) 6400 A400 C400 E400
CBASE (CCP) 5 C00 9C00 BC00 DC00
DBASE (D D T ) 5400 9400 B400 D400
Again, remember that these values are approximate. Any modifications

made to the C P /M system will cause the locations to change. For instance, if
your BIOS has been modified, it may be larger than standard-som etim es, as
much as several-K larger. Treat this table with skepticism.
There is, however, a very exact way to find out where FBASE (the starting
address of BDOS) is on your system. It’s the address stored in locations 6
262
Teamwork
and 7 of memory. Remember how, when you do a “call bdos”, you’re doing a
“call 5”? Well, the instruction at location 5 is a jum p to the beginning of
BDOS, so the two bytes following the C3 in location 5 are the address to be
jum ped to. The problem is, how do you examine these bytes?
The first idea that probably occurs to you is to look at them with the “d ”
instruction of DDT. Sorry, no cigar. When D D T is loaded, it changes the
address in this location so that it can intercept calls to BDOS and, thus, keep
control of the calling program. So, looking with D D T won’t help.
But, listen! The distant sound of trumpets! It’s HEX DU M P to the rescue!
The name may not sound too romantic, but the program is really somewhat
dashing. You’ll find it in Appendix B, and what it does is to let you do a
DDT-like dump on any 128-byte section of memory, without using DDT.
Type it in, assemble and load it, and fool around with it a little. It’s a useful
little program.
Now, use it to dump page 0. That is, after the program loads, type 0 and a
carriage return:
A>hexdump
0
You’ll see something like this:
,------------------------------ This is a “jmp” instruction.
I ^ ------------------- This is the start of BDOS address C406.
0000 C3 03 D2 94 00 C3 '06* C4 23 AF 23 36 40 23 77 23
0010 36 01 11 80 BB D5 C1 F1 AF 32 81 00 CD 06 E0 F5
(and so on)
The contents of locations 6 and 7 contain 06 and C4, so we know our

BDOS starts at C406, and we know that we can locate our A-L program any
place below this address. Note that this address differs by almost 100 hex
bytes from the one given in the table. (Again, these addresses may be differ
ent on your system.)
So, how do we go about POKEing an A-L routine in from BASIC? Let’s
summarize the steps involved:
1. Assemble the A-L routine at the desired location in high memory (just
below BDOS).
263
Soul of CP/M®
2. Using the PRN file, write down the hex values of all the bytes in the
routine.
3. Translate these hex values into decimal values. This is necessary
because most BASIC languages only understand decimal. (If your lan
guage understands hex values that are preceded by “&h”, then you can
skip this step.)
4. Add these decimal values to your BASIC program in the form of
DATA statements and, also, add a few lines to read the data state
ments and POKE them into memory, at the same address where you
assembled the routine.
Of course, the tedious part of this is in translating the hex values to deci
mal and typing them into your BASIC program by hand. However, it’s not so
bad for short routines.
Now, we have the PRN listing (Listing 8-3) for our BINIHEX program,
assembled at location C000 hex. We’ve chosen this location because, on our
56K system, FBASE (the bottom of BDOS) is at C406. We thus have more
than 400 hex bytes to put our program in, which is plenty. Actually we could
have used an ORG of C3D5, since the routine is only 30 hex bytes long
(C3D5 + 30 = C405), but that would be cutting it a little close if we ever
wanted to add a line or two to the routine.
Listing 8-3. PRN Listing for the BINIHEX Program

•*************************************************
; B I N I H E X 4 - C o n v e r t s b i n a r y t o h e x, p r i n t s i t o u t .
; To be c a l l e d f rom BASIC p r ogr am.
; V e r s i o n t o be POKEd i n f rom BASIC.
f
0001 = conin equ 1h
0002 = c o no ut equ 2h
0005 = bdos equ 5h
000A = If equ Oah
f
C000 org OcOOOh ; go es on t o p o f CCP
; t r a n s f e r i n t e g e r f rom FAC t o h i r e g i s t e r
C000 5E mov e,m ;put lo-byte in e
C001 23 inx h ;bump t he p o i n t e r
C002 56 mov d,m ;p u t h i-b y te in d
264
Teamwork
C003 EB xchg ; p u t de i n h i
; c o n v e r t b i n a r y t o hex and p r i n t i t o u t
; (on e n t r y h i h o l d s t h e b i n a r y i n t e g e r )
C004 7C mov a ,h ;p u t h in a ( f i r s t d i g i t )
C005 CD15C0 ca ll p rin tl ; p r i n t le ft-h a n d d i g i t
C008 7C mov a , h ; p u t h i n a (s ec ond d i g i t )
C009 CD19C0 ca 11 p r i n t 2 ; p r in t right-hand d i g i t
COOC 7D mov a , I ;p u t I in a ( t h i r d d i g i t )
COOD CD15C0 ca 11 p r i n t l ; p r in t le ft-h a n d d i g i t
C010 7D mov a , I ;put l i n a (fo u rth d i g i t )
C011 CD19C0 ca 11 p r i n t 2 ; p r in t right-hand d i g i t
C014 C9 ret ; e x i t b i ni hex
; p r i nt contents of a
r
C015 07070707 p r i n t l r lc ! r lc ! rlc: ! r lc ;move h i g h 4 b i t s t o
C019 E60F p r i nt2 ani Of h ; g e t r i d of high 4 b i t s
C01B C630 adi 30h ; cha nge hex t o ASCII
C01D FE3A cpi 3ah ; i f more t ha n 9
C01F DA24C0 jc notbig ; ( i t ' s not)
C022 C607 adi 7h ; t he n add b i a s (10=A, e t c . )
C024 CD28C0 notbi g c a l l p cha r ; p r in t d ig i t
C027 C9 ret
F
; s u b r o u t i n«> t o p r i n t c h a r a c t e r i n a - r e g o u t o n t o si
r
C028 E5 pchar push h ; s a v e h i ( c o n o u t uses i t )
C029 5F mov e,a ; p r i n t hex d i g i t
C02A 0E02 mvi c,conout
C02C CD0500 ca ll bdos
C02F E1 pop h ; g e t h i back
C030 C9 ret
C031 end
Look at the hex values given in the second column of the PRN listing of
this routine: 5E, 23, 56, EB, and so on, down to C9 at the end. Write down
these values and, next to each one, write its decimal equivalent:
265
Soul of CP/M®
Hex Decimal
5E 94
23 35
56 86
EB 235
C9 201
Double check your work; it’s easy to make a mistake.

Here’s the listing of the revised BASIC program needed to make use of
these values. We’ve placed them in DATA statements and added a subrou
tine (lines 100 to 140) to poke them into memory starting at location C000.
10 DE FI N T A-Z
15 G O SU B 100
20 DEF U S R 1 = & H C 0 0 0
30 I N P U T " d e c i m a l n um ber "; A
40 P R I N T " h e x e q u i v a l e n t is: ";
50 D = U S R 1 (A )
60 P R I N T :PRINT
70 GOTO 30
100 FOR I=& H C 0 0 0 TO & H C 0 3 0
110 READ D
120 POKE I,D
130 N EX T I
140 RETU RN
200 DATA 9 4 , 3 5 , 8 6 , 2 3 5 , 1 2 4 , 2 0 5 , 2 1 , 1 9 2 , 1 2 4 , 2 0 5 , 2 5 , 1 9 2 , 1 2 5 , 2 0 5 , 2 1 , 1 9 2
210 DATA 1 2 5 , 2 0 5 , 2 5 , 1 9 2 , 2 0 1 , 7 , 7 , 7 , 7 , 2 3 0 , 1 5 , 1 9 8 , 4 8 , 2 5 4 , 5 8 , 2 1 8 , 3 6 , 1 9 2
220 DATA 1 9 8 , 7 , 2 0 5 , 4 0 , 1 9 2 , 2 0 1 , 2 2 9 , 9 5 , 1 4 , 2 , 2 0 5 , 5 , 0 , 2 2 5 , 2 0 1
Type all this in, and SAVE it as BINTEST2.

After all this work, we should reap some sort of reward, and we do. It’s
easy to load the routine. First, we load BASIC, being careful to protect the
memory space where our program goes.
A>mbasic5 /m:&hc000
Then, when BASIC is loaded, we load the program :
0k
load " B I N T E S T 2 "
266
Teamwork
That’s all there is to it. Now we can type “run,” and we’ll be airborne
immediately, since the BASIC program will POKE BINIHEX4 into memory
and then jum p to it as soon as it gets to the USR1 statement.
HEX Files, and Using a BASIC Program to Load the A-L Routine
As our last method of loading an A-L routine into memory, we’ll make use
of a special BASIC program that can directly load a HEX file:
“ HEXLOAD.BAS” .
In order to understand what the program does, you need to know some
thing about the format of HEX files. HEX files are rather strange beasts.
They’re translations of a COM file (which as you know consists simply of the
bytes that make up a program, the same bytes you will find in the left-hand
columns of a PRN listing). These translations are in another format consist
ing of all ASCII characters. For instance, if you had a “mov e,m” instruction
in your assembly listing, it would be assembled as the 8-bit (one-byte)
number 5E, which is 01011110 in binary.
In a hex file, the 5 is translated into an ASCII “5”, which is represented by
the one-byte number 35 hex, or 00110101 binary. Then, the E is translated
into an ASCII “E”, which is 45 hex, or 01000101 binary. Thus, every byte of
a COM file becomes two bytes of a HEX file.
There’s more. The entire file is broken down into groups of 16 one-byte
digits (which is 32 ASCII characters). Each such group is given a separate
load address (the place where the group is supposed to be loaded in memory)
and a count (which shows how many of the characters in the 16-character
group have actually been used). Usually they’re all used, except for the last
group in the file. In addition, there’s a checksum for each group, which
neither our program nor you need to worry about.
If we take a look at an actual HEX file, we’ll see something like this:
: 1 0C000005E2356EB7CCD15C07CCD19C07DCD15C00F0D0A
: 1 0C010007DCD19C0C907070707E60FC630FE3ADA1B000A
: 1 0C0200024C0C607CD28C0C9E55F0E02CD0500E1DAODOA
: 0 1C03000C9460D0A
: 00000000000D0A
Each of these lines is read into our BASIC program as a separate string
variable, since they are separated by carriage-return and linefeed ASCII char
acters. Let’s take a look at the first line to see how it’s constructed.
267
Soul of CP/M®
---------------------------------------Number of digits in this line (in hex).
------------------------------------------ 4-digit load address.
16 data digits ^-----------------------Checksum.
: 1 0C000005E2356EB7CCD15C07CCD19C07DCD15C00F0D0A
\ ^ Linefeed.
Always 00. '-----------Carriage return.
The 10 (hex) at the beginning of the line shows that all 16 (decimal) posi
tions in the group are filled. The load address for the group is at C000. Then
come two zeros and, finally, the 16 data bytes, in the form of 32 ASCII char
acters. This is followed by the checksum and the carriage return/linefeed
characters. In the next to the last line, only one data byte is to be loaded, at
address C030. It’s C9 (which is a “ret” instruction). Finally, in the last line,
the count is 00, which is the signal for end-of-file.
This particular HEX file happens to be for BINIHEX4, which you may
remember from the last section. You might like to compare the values in this
HEX file with those in the PRN listing shown earlier. We’ll be using this
program again in a minute as an example.
First, however, take a look at the BASIC program HEXLOAD.BAS:
100 DEFINT A-Z : CLEAR 1000

110 F$="BINIHEX4.HEX" ’name of file to be loaded
120 OPEN " I " , # 1 , F $ ’open file, “input” mode
130 INPUT #1,XX$ ’read one string
140 IF M I D $ ( X X $ , 2 , 2 ) = " 0 0 " THEN END
150 AD$ = M ID $ (X X $ , 4 , 4 ) ’address to be loaded into
160 ST$=MID$( XX$, 10, LEN( XX$)-11) ’data string (hex characters)
170 PRINT CHR$( 10 ); CHR$( 13 ); AD$ ;" ’print address
180 H$=AD$ : IH=3 ’convert address to decimal
190 GOSUB 1000
200 AD =H
210 FOR J=1 TO LEN(ST$) STEP 2 ’get data from string and stor
220 DA$=MID$(ST$,J,2) ’data byte
230 PRINT DA$;" ’print data byte
240 H$ = DA$ : IH = 1 ’convert data byte to decimal
250 GOSUB 1000
260 DA=H
268
Teamwork
270 POKE AD,DA : AD=AD+1 ’store data and increment address

280 NEXT J ’go get next data byte
290 GOTO 130 ’go get next string
980 ’
990 ’s u b r o u t i n e t o c o n v e r t ASCII s t r i n g t o d e c i m a l number
1000 H=0
1010 FOR 1=0 TO IH
1020 X = A S C ( M I D $ ( H $ , I H + 1 - I , 1 ) ) - 4 8 : I F X>9 THEN X=X-7
1030 H=H + ( X * 1 6 M )
1040 NEXT I
1050 RETURN
This program reads in one line of the hex file at a time. Which HEX file?
The one put into the program at line 120. (You could also change it so it asks
you to type it in from the keyboard.) An IN PU T statement then reads one
string of 16 data bytes (with its load address, checksum, etc., as shown in the
preceding program.) This is assigned to the variable XX$. The program then
uses string functions to break up the line into the various components: the
load address AD$, the string of data, ST$, and each individual data byte
DA$. It doesn’t bother with the count number, preferring instead to derive
this directly from the length of the data string. Both the 4-digit address and
the 2-digit data have to be translated into decimal, since BASIC speaks only
decimal. This is done in the subroutine at line 1000. The subroutine looks, in
order, at the characters in the string H$ and then translates them into deci
mal numbers, using either two or four digits, depending on the value of IH. If
IH is 3, then four digits are used, if it’s 1, then two digits are used. The
conversion is done by adding the first (rightmost) digit to the second digit
multiplied by 16, then adding the result to the third digit multiplied by 256,
and adding this result to the fourth digit multiplied by 4096. These numbers
are derived by raising 16 to the IA power. (See the program H EX IDEC that
is described earlier in the book for an example of a similar approach.)
Once each data byte is found, it’s POKEd into the appropriate address.
When the line is finished, the program IN PU Ts a new line. When it sees a
count of 00, it quits.
The program prints the load address of each line of bytes and then prints
each byte as it’s decyphered and POKEd into memory. This way, you can be
assured that the program is doing what it’s supposed to do. And, it’s enjoya-
bly hypnotic to watch the little bytes marching across the screen and into
your computer’s memory. However, if you’re going to load really large A-L
programs, you may want to remove the statements that do the printing (lines
269
Soul of CP/M®
170 and 230) so the program will run faster. Once you’ve typed this program
into memory and stored it as a BAS file, using it is really rather simple.
Let’s use the same BASIC program that we used in the preceding examples
to test BINIHEX4. We’ll change it slightly so that the DEFUSR1 statement
sets up the entry address of the A-L routine at C000:
10 DEFINT A-Z
20 DEF USR1 =&HC000'"---------------------- -C h ange this to C000.
30 I NPUT"decimal n umbe r" ; A
40 PRINT"hex e q u i v a l e n t i s : " ;
50 D=USR1( A)
60 PRINT: PRINT
70 GOTO 30
We’re going to use three programs: the BASIC program BINTEST.BAS

which will call the A-L routine, the A-L routine BINIHEX4.HEX, and the
BASIC program used to load the A-L routine, HEXLOAD.BAS.
Here’s how to do it:
1. Call up BASIC, at the same time protecting the appropriate memory

address:
A >m basic5 /m:&hc000
2. Load and run HEXLOAD.BAS from BASIC:
run “HEXLOAD”
It will execute, loading in the A-L routine whose name appears in line
120 .
3. Still in BASIC, load in the BASIC program that you want to use:
run “BINTEST”
That’s all there is to it. If you try it out you should get the same results that
you got using the last approach. To simplify the loading procedure, you could
merge your own BASIC program and HEXLOAD into a single program,
which would execute HEXLOAD first, and then go on to whatever it’s sup-
270
Teamwork
posed to do. Or, you could chain them together, making the following line the
last statement of HEXLOAD to be executed:
140 IF M I D $ ( X X $ , 2 , 2 ) = " 0 0 " THEN RUN "BINTEST"
D on’t forget to make all the load addresses the same. The number you type
in when you load BASIC must be the same as the number in the D EFU SR
statement which, in turn, must be the same as the O RG of the A-L routine.
HEXIBIN2—PASSING ARGUMENTS TO BASIC FROM AN

A-L ROUTINE
Our next example shows how an argument is passed back to BASIC from
the A-L routine. This program, as you have no doubt gathered from the
name, takes a hex number typed on the keyboard and converts it to decimal
on the video screen. It is the complement of BIN IH EX —with these two pro
grams, you have a complete set of utilities for handling hex conversions.
(There’s another version of this program, called HEXIDEC, in Appendix B.
It operates as a COM file directly from C P/M , without BASIC.)
We’ll assume that this program will be loaded from DDT, although it
could be modified to be self-relocating or to be POKEd in from BASIC, as in
the preceding examples. Here’s the listing of the BASIC program:
10 DEFINT A-Z
20 DEF USR2=&HA000
30 PRINT"hex number? " ;
40 A=USR2(D)
50 PRINT"decimaL e q u i v a l e n t i s " ; A
60 STOP
That’s pretty simple. After printing “hex number?”, we go to the HEX-

IBIN2 routine to get the input from the keyboard. HEXIBIN2 converts these
typed hex digits to a binary number, which is returned to the BASIC pro
gram as the variable A. The BASIC program then (as it always does) converts
this number to decimal for printout. (Note that we can’t input hex numbers
into our BASIC program directly from the keyboard, since BASIC has no
function to do this.)
The im portant part of this example is how the A-L routine passes a value
back to BASIC. Listing 8-4 shows HEXIBIN2.
271
Soul of CP/M®
Listing 8-4. The HEXIBIN2 Program

; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
; H E X I B I N 2 - C o n v e r t s hex t ype d on k ey board t o

; b i n a r y ( t o be c a l l e d f rom BASIC p r o g r a m ) .
0001 = conin equ 1h

0002 = c o no ut equ 2h
0005 = bdos equ 5h
/
A000 org OaOOOh
/
; s a v e t h e add re ss o f FAC ( a c t u a l l y FAC-3)
AOOO 2244A0 s h l d temp
; g e t t h e number f rom k e y b o a r d , p u t i n h i
A003 CD15A0 c a ll hexibin
; p u t v a l u e i n h i back i n FAC
A006 EB xchg ; p u t number i n de
A007 2A44A0 l h l d temp ; p u t FAC a dd r es s i n h i
AOOA 73 mov m,e ; p u t l o - b y t e i n FAC-3
AOOB 23 inx h ;bump p o i n t e r
AOOC 72 mov m,d ; p u t h i - b y t e i n FAC-2
; p r i n t linefeed
AOOD 0E02 mvi c , c o n o u t
AOOF 1EOA mvi e,0ah ;ASCII f o r lin e f e e d
A011 CD0500 c a l l bdos
; b a c k t o b as i c
A014 C9 ret
; h e x i b i n - s u b r o u t i n e t o read hex number from

; keyboard, s to r e r e s u l t in b in a r y in hi
r
A015 210000 h e x i b i n l x i h , 0 ; c le a r hi
A018 E5 newch push h ;save h i
A019 0E01 mvi c , c o n i n ; g e t c h a r a c t e r
A01B CD0500 ca11 bdos
A01E E1 pop h ; r e s t o r e hI
A01 F D630 s ui 30h ; c o n v e r t ASCII d i g i t to b in a r y
A021 F8 rm ; return i f <0
A022 FEOA c pi 10d ;isit> 9 ?
A024 FA2FA0 jm a dd to ; y e s , so i t ' s d i g i t (0 to 9)
; n o t d i g i t , maybe i t ' s l e t t e r (a t o f )
272
Teamwork
A027 D627 su i 27h ; c o n v e r t ASCII L e t t e r t o b i n a

A029 FEOA cpi Oah ; i s i t l e s s t ha n a ( h e x )
A02B F8 rm ; yes, re tu rn
A02C FE10 cpi 10h ; i s i t g r e a t e r t han f ?
A02E FO rp ; yes, re turn
ł
; r o t a t e h L r egi s t e r f o u r b i t s L e f t and
; add new di g i t t o r i g h t - h a n d s i d e
A02F 57 addt o mov d , a ; s a v e new hex d i g i t i n d
A030 0E04 mvi c , 4 ; s e t up Loop t o c o un t 4 b i t s
A032 7D s h ift mov a , I ;shi f t L
A033 17 ra L
A034 6F mov I , a
A035 7C mov a , h ;shi f t h
A036 17 ra L
A037 67 mov h,a
A038 OD dcr c ; a r e we done y e t ?
A039 C232A0 jn z s h i f t ; not yet
A03C 7D mov a , I ;mask o f f Lower 4 b i t s o f L
A03D E6F0 ani Of Oh
A03F B2 ora d ; " o r " t h e new d i g i t on t o L
A040 6F mov I , a
A041 C318A0 jmp newch ; g o back f o r n e x t c h a r a c t e r
/
A044 temp ds 2
/
A046 end
The trick here is that the routine must save the contents of the HL-register
before it does anything else. T hat’s because, when we first go from BASIC to
our A-L routine, the HL-register contains a pointer to FAC-3, as described
before, and our program needs to remember where the FAC is for later use.
This is easily taken care of with a “ shld temp” instruction at the beginning of
the program, where “temp” is a two-byte location.
Having done this, we call the subroutine “hexibin” which actually gets the
value from the keyboard, and returns with it in the HL-register. Now the
problem is to get this value back into the FAC before we return to BASIC, so
that BASIC will know what value to assign to the variable A. We “xchg” the
number into the DE register, get the pointer to FAC-3 back from “tem p”,
and then move the two bytes out of DE, and store them one at a time into the
273
Soul of CP/M®
location in HL and in the following location (FAC-3 and FAC-2). This is just
where BASIC expects them to be, so our job is done and we “ret” back to
BASIC.
Something to notice here is that you can’t break into the routine from
BASIC by using control-c or the “break” key. Thus, if you changed the
BASIC program so that it continuously asked for the hex number (by adding
line “55 GOTO 30”, for example), there would be no way to get back to the
BASIC program. One way to avoid this problem is to have BASIC check for
a 0 being returned by the A-L routine. If it finds one, it knows that the user is
done with the routine and jum ps out of the loop.
OPERATING ON STRINGS WITH AN A-L ROUTINE
There are many situations where you might want to use an A-L routine to
do something to a string variable, rather than a numeric variable, as in the
previous examples. For instance, if your BASIC doesn’t have an INSTR func
tion to search one string for another, you could add this feature with an A-L
routine. Or, you could add the LINE IN PU T or PR IN T USIN G functions.
In our example, we’ll try something a little less ambitious. We’ll write a
routine to convert any lowercase letters in a string to uppercase. This might
be useful if, for example, you wanted to search the string for a name, and
didn’t want to worry about whether the word was capitalized in the string.
BASIC handles the transferring of string variables somewhat differently
than it does numeric variables. The FAC is not used at all. Instead, the DE-
register is used to point to a three-byte “descripter” which contains the
address and the length of the string. Fig. 8-6 illustrates how it’s arranged.
So, getting to the string itself becomes a two-step process. First, we find the
address of the descripter and from that we get the address of the string. The
BASIC program for our example looks like this.
10 DEF USR1=&HA000
20 INPUT A$
30 B$=USR1(A$+" " )
40 PRINT A$
50 PRINT B$
60 STOP
274
Teamwork
String stored
in memory.
“s”
“ t”
“g”
Fig. 8-6. U sing a three-byte descripter.
You type in any string you like, and the program will change any lowercase
letters that it finds to uppercase. Then, it prints out both the original version,
A$, and the modified all-uppercase version, B$.
Notice the plus sign and the space following the A$ in line 30. W hat’s all
that about? It’s a subtlety that has to do with the way BASIC handles string
variables. If we had written:
30 B$=USR1( A$)
BASIC would have actually converted the lowercase letters in A$ to upper

case and would have then set B$ equal to this same string. By including the
space (or doing any other sort of operation on the string A$) in line 30, we
cause BASIC to create a whole new string (A$ + “ ”) in a temporary work
area. It is this temporary string that is then modified by our UCASE routine.
A$, itself, remains unchanged, with its lowercase letters intact, while the tem
porary string is made permanent and assigned the name B$.
Listing 8-5 shows the program for the A-L routine UCASE, which actually
does the conversion.
When we first enter the routine, we get the address of the descripter from
the DE-register and “xchg” it into HL, where we use it to get first the length
of the string (which we put in the C-register), and, then, the two bytes of the
275
Soul of CP/M®
Listing 8-5. The A-L Routine UCASE

• ***********************************************
;UCASE-Routine t o c o n v e r t Lowercase L e t t e r s
; t o u ppercas e i n a BASIC s t r i n g
; ( t o be c a l l e d f rom BASIC).
f
AOOO org OaOOOh
; g e t c h a r a c t e r c o u n t and a d d re s s o f s t r i n g
;from d e s c rip te r
AOOO EB xchg ;p u t d e s c r ip te r p t r in hi
A001 4E mov c,m ; p u t count in c
A002 23 i nx h ;move p o i n t e r t o a dd re ss
A003 5E mov e,m ; l o - b y t e o f a d d r e ss i n e
A004 23 i nx h
A005 56 mov d,m ;h i- b y te in d
A006 EB xchg ;de (address o f s t r i n g ) in
f
; cha nge l o we rc as e l e t t e r s i n s t r i n g t o upperc.
A007 7E newch mov a,m ; g e t c h a r a c t e r f ro m s t r i n g
A008 FE61 cp i ’a’ ; i s i t l e s s t han " a " ?
AOOA FA15A0 jm no low ; y e s , so n o t l o we rc as e
AOOD FE7A c pi V ; i s i t more t han " z " ?
AOOF F215A0 jp no low ; y e s , so n o t l o we rc as e
A012 D620 sui 20h ; c o n v e r t t o uppe rc as e
A014 77 mov m,a ; p u t back i n s t r i n g
A015 23 no low i nx h ; i n c r e m e n t add re ss
A016 OD dcr c ; done y e t ?
A017 C207A0 jnz newch ; n o, g e t n e x t c h a r a c t e r
/
; b a c k t o BASIC
A01A C9 ret
F
A01B end
address of the string (which goes back in the DE-register). Once we’ve got
this address, we “xchg” it into HL, and we’re ready to start changing lower
case letters to uppercase letters.
We don’t have to pass anything back to BASIC when we return, since
BASIC already knows where the string is that we modified.
276
Teamwork
BACK TO BASICS
Now that you know how to add assembly language routines to BASIC, you
may not have so much free time anymore. All of the BASIC programmers,
who can’t get the computer to do what they want in that language, will come
to you asking, “Please, just a little routine to do a fast bubble-sort of my
data?”, “ Please, just a little routine put my output in columns on the
screen?”, and so on. You may have to get an unlisted number.
277
■
CHAPTER 9
The Innermost Soul of

CP/M
How to Modify C P / M for D ifferent
Peripherals
WHY YOU’RE READING THIS CHAPTER
Scene I: You have a nice C P /M system that runs with a dot

matrix printer. The printer is fast but the print quality leaves some
thing to be desired. So one day, after saving your pennies for a year
or two, you decide to upgrade your printer to a letter-quality daisy
wheel model. You buy the new printer, bring it home, plug it in,
a n d - it doesn’t work! The dealer says he can modify your C P /M
system to handle the new printer, but it will take three weeks and
cost more than you want to spend.
Scene II: You have just purchased, by mail order, a brand new
C P /M system, along with a printer. But, when you unpack the
boxes and set everything up, you find that the printer doesn’t work.
W hat’s more, you find that the system won’t work with any other
printer either. Someone suggests that the printer driver has not yet
been installed in the C P /M version supplied with the machine.
Scene III: You have a printer with extra features that can be
selected under software control, like compressed or expanded print
or different pitches for the type face. Unfortunately, the control
Soul of CP/M®
characters that should activate these features are already being used
by your word-processing program for something else. W hat you
need is for your printer to respond to a different set of control char
acters, but you don’t want to rewire the printer.
Given any of the above situations, and assuming that you don’t have a
resident programmer on your staff, what should you do? Stay tuned; you’ll
find the answers in this chapter.
While our discussion is mostly about printers, the techniques used are
applicable to other input/output devices as well, such as modems, tape trans
ports, different video terminals, or whatever.
WHAT IS THE BIOS ANYWAY?

In the preceding chapters, we’ve been working our way deeper and deeper
into what we call the “ soul” of C P /M ; that is, the hidden part of the operat
ing system which isn’t visible to the casual user of C F/M . In this chapter,
we’re going to penetrate to the most hidden part of C P/M : the BIOS (or
Basic Input/O utput System). You could call the BIOS the innermost soul of
CP/M .
280
The Innermost Soul of CP/M
As you may recall, the external part of C P /M is the CCP (Console Com
mand Processor), which looks at what you type on the keyboard and takes
action accordingly. The CCP is the outward facade that C P /M presents to
the world. To perform I/O , the CCP then calls the BDOS, or Basic Disk
Operating System. Applications programs do the same thing, using a “call
bdos” instruction, as you know from writing your own programs as described
in the previous chapters. The BDOS is a section of code that is the same for
all versions of C P/M , no m atter what machine it is running on. The main
purpose of BDOS is to handle disk files, but it also channels I/O requests for
other peripherals.
In order for BDOS to actually carry out its duties, it must at some point
communicate with the actual physical devices connected to the machine: the
disk drives, video screen, keyboard, printer, and so forth. Since these per
ipherals can come from a variety of manufacturers and can operate in a vari
ety of different ways, the subroutines which drive them must be different for
each piece of equipment. This collection of subroutines is what constitutes
the BIOS. These subroutines are called “driver” routines, meaning that they
“drive” a particular peripheral device. When you change from one kind of
printer to another, it’s this driver in the BIOS that must be modified to
“ speak” to the new printer.
z
THE USER
/ 7!
CCP
z 71
BDOS
z BIOS
71
Driver
Direct connection
routines
to I/O devices.
1/
1/
1/
1/
Fig. 9-1. BIOS communicates with I/O devices.
281
Soul of CP/M®
Notice that although the BIOS is at the innermost position in C P/M , it has
(as do many innermost souls) a direct connection with the outside world. In
fact, it is the only part of C P /M that can actually communicate with physical
devices.
Outline of This Chapter
W hat we’re going to do in this chapter is teach you how to modify a driver
routine so that your C P /M system can operate with a different printer. The
techniques involved will also work for adding or changing other peripherals
(such as your video display or the addition of a modem). Changes to the disk
drives are considerably more complicated and should probably be left to the
dealer unless you are a very ambitious programmer.
Because every system uses different hardware, every BIOS will be different.
We can’t, therefore, tell you exactly how to modify your own BIOS. W hat we
can do, however, is show you an example: how to modify a particular BIOS.
Once you understand our example, you should be able to apply the same
techniques to your own situation.
There are three steps involved in writing a new driver for your BIOS, and
we’ve given each of them a separate section in this chapter. The three steps are:
1. Learning your way around the BIOS. You need to be able to find the
existing driver so that you can see what it looks like, how it relates to
the rest of the BIOS, and where to put the new driver.
2. Writing the new driver routine and testing it.
3. Inserting the new driver into the BIOS file and writing the new BIOS
to the system tracks of your disk.
These steps are all somewhat involved but we’ll cover them slow and easy,
and when we’re done and you look back on everything, it’ll seem easy!
What You Need To Modify Your BIO S
There are two things you need before you can modify your BIOS. The first
is the ASM file of the BIOS. This is supplied (or can be) by the friendly
people who put your system together for you. It contains the actual 8080
code that communicates with I/O devices. This file is usually called some
thing with “ BIOS” in it, like IOBIOS.ASM or GBBIOS.ASM. If the file con
tains the I/O for the disk system, then it will be very long, like 20 or 30 pages
or so when printed out. But, often, the supplier will leave out the part of the
282
BIOS that deals with the disk system and then it will be fairly short, on the
order of a half-a-dozen pages. You need this file because it’s what you’re
going to modify. That is, you’re actually going to use your word-processor
program to alter parts of a section of this file. Then, you’ll reassemble it with
ASM and write it back onto the “system tracks” of your disk.
The second thing that you’ll need is the specifications for your U A RT or
serial board. “U ART” stands for “Universal Asynchronous Receiver/Trans
mitter.” The U ART is a “chip” or integrated circuit that is installed on one
of the boards in your computer, namely the “ serial board,” which allows the
computer to communicate in serial mode with external devices. We’ll talk
more about what all this means in the next section. U ntil then, ju st get your
hands on the spec sheet. It will tell you what numbers to output to what
“port” in the U ART in order to send signals to various I/O devices.
Some versions of the BIOS.ASM file include information on the UART at
the beginning of the listing. Thus it is possible to modify your BIOS without
the actual spec sheet, provided that the U ART is already installed and oper
ating and your listing has this information. It’s also easier if you have a
device already operating that is similar to the one you plan to install. That is,
if you already have a printer running and want to change to another printer,
you may not need the spec sheet or the comments in the listing. This is
because you can use the existing driver as a model for what to do. But, if you
don’t have any printer at all, then you really need the spec sheet. In any case,
it will make your life a little easier.
LEARNING YOUR WAY AROUND THE BIOS

Writing a new driver routine for your C P /M system is a little like being a
building contractor who lands a job in a strange city. Suppose you’re given
the jo b of tearing down the old office building at the corner of Main and
N orth Street in a city that you’ve never before visited (called Bioston) and,
then, are to build a new high-rise on the site.
You drive your pickup into town, and the first problem that you’re faced
with is finding out where the intersection of Main and N orth Street is. Right
away you need to scare up a map so you can get to the job site.
The ASM file of your BIOS (called BIOSIO.ASM, NSBIOS.ASM, or what
ever) is the map you need to get to the job site, which is the printer driver
routine. In this section, we’re going to give you a little course in map-reading;
that is, how to get where you want to go in the BIOS. The BIOS is a long
listing, but remember that you don’t need to understand all of it. Like someone
283
Soul of CP/M®
navigating in an unfamiliar city, you only need to recognize a few intersections

and landmarks along a particular route in order to get to your destination.
We’ll show you some of these im portant features first, and then introduce
you to the complete BIOS. Remember that the particular BIOS we will be
describing is only one example of the hundreds of possible versions of BIOS
out there in C P /M land. Yours will be somewhat different, but it should be
similar enough so that you can follow on your own BIOS the steps that we
describe here. Reading your own BIOS listing will make the most sense if you
assemble it with ASM and, then, refer to the PRN listing as, often, the hex
values of things are important.
The BIO S Introduces Itself
Here’s the first part of our example BIOS:
T IT LE + + B IO S FOR DIO WI TH CP /M 2 . 2 REV 2 . 7 ++

W. W. C O M P O N E N T S
•k'k'k'k'k'kicrk'k'k'k'k'k'k'k'k'k'k'k'k'k'k'krk'k'k'kic'k'kie'k'k'k'k'k-kie'k'k'k'kic'k'kic'k'k'k'kie
BIOS FOR IMSAI DIO-C CONTROLLER WITH CP/M 2 . 2

'k’
k'k'k'k'kic'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kicic'k'k'k'k'k'k'k'k-k'k'k'k'k'k'kicie'k'kic'kic-kic'k'k
BI OS V E R S I O N 2 . 7 : S I N GL E D EN S IT Y , 128 B/S
DO UB L E D E NS I TY , 256 B/S
DO UB L E D E NS I TY , 1024 B/S
***************************************************
0000 = FALSE EQU 0

FFFF = TRUE EQU NOT FALSE
0038 = MSIZE EQU 56 ;MEM0RY SIZE IN K-BYTES

0036 = SSIZE EQU MSIZE-2 ; 2K FOR CP/M,BIOS AND BUFF
001B = REVNUM EQU 27 ; B I 0 S REV #
0016 = CPMREV EQU 22 ; CP/M REV #
; " B I A S " IS ADDRESS OFFSET FROM 3400H FOR

; MEMORY SYSTEMS OTHER THAN 16K (REFERRED TO
; AS " B " THROUGHOUT THE TEXT).
8800 BIAS EQU ( S S I Z E - 2 0 ) * 1 0 2 4 ;ADDR OFFSET FROM 3400
; (20K SYSTEM)
BC00 CCP EQU 3400H+BIAS ;BASE OF CCP
C406 BDOS EQU CCP+806H ;BASE OF BDOS
D200 BIOS EQU CCP+1600H ;BASE OF BIOS
284
This BIOS starts out describing itself, where it comes from, and what it’s
for. It comes from “WW Components,” is for the Imsai 8080, and is version
2.7 of the BIOS.
Address Location Arithmetic
Next, we come to a very im portant part of the BIOS. All BIOS listings
contain some calculations in the beginning that define and then set up the
beginning address of the BIOS, itself, in memory. The addresses are usually
calculated according to a set of rules laid down by Digital Research (the
developers of C P/M ). They start out by specifying the memory size that the
BIOS is working with. In the present example, we’re looking at a BIOS that’s
set up for a 56K memory size. (If your BIOS has other weird statements in it
at this point, such as various options that must be set to true or false, ignore
them. They won’t influence this discussion.)
In the first line, we see that the size of the com puter’s memory, MSIZE, is
set to 56 (38 hex). All BIOS.ASM files should have such an equate. If we
want to change our BIOS to work on a machine with a different memory size,
the first thing that we will do is change this number to the appropriate value.
The next im portant number looks a bit strange; it’s called BIAS. (In other
listings, it may have other names, like IOBIAS.) It’s the distance, in memory,
between where the CPM system is on your system and where it is on a “vir
gin” C P /M as it comes from the factory. Brand new systems are configured
for 20K memories, and are then moved up to the top of memory where they
will reside in a particular machine. BIAS is related to a certain magic
num ber—yes, a genuinely magic number called N —which we will be discuss
ing in the last section of this chapter: how to insert your driver into the BIOS.
We’ll have a lot more to say about this later.
BIAS is used to define the starting locations of the major parts of the
C P /M system: CCP, BDOS, and BIOS. The “standard” starting location for
the bottom of the CCP is 3400 in a 20K system. As you can see, the CCP is
806 hex bytes long in this listing, since BDOS starts at CCP + 806H. The
CCP and the BDOS, together, are 1600 hex bytes long so, in our 56K system
at least, BIOS ends up starting at D200 hex.
I/O Equates and Other Goodies
In the next section of code, shown in Listing 9-1, the BIOS very kindly tells
us something about the UART: namely, the meaning of each bit when we
read the “status” of an I/O device. Thus, bit 1 is “receiver ready,” and so
285
Soul of CP/M®
forth. This will be useful information later. Following this is a series of

“equates,” which are places where certain variables and addresses in the
BIOS are given values. We see that the CRT status port “CRTST” is at 03
hex, the keyboard data port is at 14 hex, the variable RXRDY is given a
value of 2, and so on.
Listing 9-1. The Bits in an I/O Device

'k'k'k'k'k'k'k'k'kieie-k'k'k'k'k'kic-krk'k'kie'k'k'k'kic'k'k'k'k'k'kie'k'k'k'k'kic'k'k'kie'k'k'k'k'k'k
I / O DEFINITION EQUATES
★★★★I***********************************************
USEFUL THINGS TO KNOW
MPU-B STATUS PORT
(TERMINAL/TRANSMITTER REFERENCE)
0 = TxRDY TRANSMITTER READY

1 = RxRDY RECEIVER READY
2 = TxE TRANSMITTER EMPTY
3 = PE PARITY ERROR
4 = OE OVERRUN ERROR
5 = FE FRAMING ERROR
6 = SYNDET SYCN DETECT
7 = DSR DATA SET READY
CONSOLE STATUS PORT ( I N HEX) - 15 = PARALLEL

13 OR 4 = SERIAL
3 = SYSTEM
CONSOLE DATA PORT ( I N HEX) - 14 = PARALLEL
12 OR 4 = SERIAL
2 = SYSTEM
0003 =
CRTST EQU 3H ; CRT STATUS PORT
0002 =
CRTDATA EQU 2H ; CRT DATA PORT
0015 =
IKBST EQU 15H ; IKB1 STATUS PORT
0014 =
IKBDATA EQU 14H ; IKB1 DATA PORT
F803 =
VIODATA EQU 0F803H ; VIO DATA PORT
0002 =
RXRDY EQU 02H ; CONSOLE STATUS
/ READY BIT (RxRDY)
0003 = IOBYTE EQU 0003H ; INTEL I / O BYTE
F800 = V I OI NI T EQU 0F800H ; V I 0 I N I T ENTRY POINT
FFFD = VIOID EQU OFFFDH ; POINTER TO VIO ID
0023 = PRTS EQU 23H ;PRINTER STATUS PORT
0022 = PRT EQU 22H ;PRINTER DATA PORT
286
Notice especially PRTS and PRT, the printer status port and the printer
data port, respectively. We’ll be using the numbers that they’re equated to, 23
hex and 22 hex, when we write our printer driver.
The ORG Statement and the Jump Table
In the next section of code, we finally get to the actual beginning of our
program: the O RG statement. Usually, this location is defined in terms of
various other locations which, in turn, are defined in terms of the memory
size of your computer, among other things. In this case, the O RG is at the
start of BIOS plus 0C70 hex. The listing doesn’t start at the beginning of
BIOS because all the drivers for the disk system are located there, between
D200 and D200 + 0C70. Our listing is really only a small part of the BIOS:
the nondisk part.
But think about this. How is BDOS, which wants to call some driver rou
tine in the BIOS, going to find it? If we fool around- as we’re going to do in
this chapter—adding instructions to the BIOS and reassembling it so we can
insert our driver in it, the starting addresses of all the drivers following the
one we changed will be different. How will BDOS find them? The answer is
that it makes use of a clever programming idea called a “jum p table.”
A jum p table is merely a bunch of jum ps at the beginning of the listing.
Each jum p goes to one of the driver routines, like LIST, and CONST, and so
on. Since these jum ps are part of the listing we’re going to reassemble, the
values in their address fields will change when we reassemble the file. Thus,
Listing 9-2. Jump Table

■ ********************************************
; USER CUSTOMIZED I / O DEVICES. *
; DO NOT REARRANGE JMP TABLE. *
■ i e i c ' k i e i e ' k ' k i c ' k i c ' k 'k ' k i e ' k ' k ' k ' k 'k 'k 'k 'k 'k - i c 'k 'k 'k i c 'k i e 'k 'k 'k 'k 'k 'k 'k r k - k 'k i c i e 'k 'k
DE70 ORG BIOS + 0C70H
DE70 C3F8DE INITIO: JMP INITVC

DE73 C3BFDE L IS T: JMP LISTIO
DE76 C3B3DE L ISTST: JMP LISTSTIO
DE79 C388DE CONST: JMP CONSTIO
DE7C C39BDE CONIN: JMP CONINIO
DE7F C3A7DE CONOUT: JMP CONOUTIO
DE82 C3CBDE PUNCH: JMP PUNCHIO
DE85 C3D7DE READER: JMP READERIO
287
Soul of CP/M®
BIOS doesn’t care where the driver routines themselves are, it just cares
where the jum p table is, and the jum p table is always in the same place: at
the beginning of the listing. BIOS “calls” one of the locations in the jum p
table, and the jum p takes BDOS to the proper driver.
Notice, however, that BDOS assumes the jum ps in the jum p table (Listing
9-2) will always be in the same order. When it calls on the second jum p in the
table, it expects to find a jum p to LISTIO, not PUNCHIO. That’s why the
listing says “ DO NOT REA RRA N G E JU M P TABLE.”
The Dreaded IOBYTE and the Trouble It Causes
Now we can actually start to follow a trail through the listing to our desti
nation. Look at the jum p table; the second jum p is to LISTIO. This is to the
LIST device. As you recall, C P /M permits different physical devices to be
assigned to different logical devices. There are four logical devices:
CON:
RDR:
PUN:
LST:
which stand for console, reader, punch, and list. There are also various
physical devices, like TTY:, and CRT:, and LPT:. You can change the
assignments of physical to logical devices by using STAT. W hen you do
this, STAT changes something called the IOBYTE, which is location 3 in
memory.
Now, when BIOS gets a call to the LIST routine, it doesn’t know what
physical device it’s intended for until it checks the IOBYTE. Based on
w hat it finds there, it will either go to the driver for the printer, or to
some other driver. T h at’s why LISTIO and LISTSTIO (for “ list status
I /O ” ) aren’t really driver routines but, instead, are a different form of
jum p table. H ere’s w hat they look like
LIST OUT - LST:

L ISTI O:
DEBF CDE3DE CALL DISPATCH
DEC2 03 DB 3 ;USE IOBYTE BITS 7 - 6
DEC3 55DF DW CRTOUT ;00 - TTY: (CRT OUTPUT)
DEC5 55DF DW CRTOUT ;01 - CRT: (CRT OUTPUT)
DEC7 35DF DW LPTOUT ;10 - LPT: (LINE PTR OUTPUT)
DEC9 6FDF DW VI00UT ; 11 - UL1 : (VIDEO OUTPUT)
288
This section works by first calling a routine named DISPATCH which

looks at the IOBYTE and decides which of the four routines for the four
possible physical I/O devices it should go to. Usually, the line printer is
assigned to the LST: device, so DISPATCH will figure this out from the
IOBYTE and jum p to the address in the third DW statement in this routine,
which is called LPTOUT for “line printer output.”
In some versions of BIOS, the IOBYTE is not used and this whole section
of code is nonexistent. This is true of the example BIOS provided in Digital
Research’s CP/ M Alteration Guide. In other versions, it’s implemented in a
different way. Let’s follow along to LPTOUT (Listing 9-3) and see what that
looks like.
Listing 9-3. Line Printer Output Subroutine

; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
; LIST CHARACTER IN C
DF35 DB23 LPTOUT: IN PRTS ; CHECK STATUS PORT

DF37 E685 ANI 85H ;MASK OFF BITS
DF39 EE85 XRI 85H ; ALL BITS SET?
DF3B C235DF JNZ LPTOUT ; N0-N0T READY
DF3E 79 MOV A, C ; YES, CHARACTER TO A-REGISTER
DF3F D322 OUT PRT ; SEND TO PRINTER
DF41 C9 RET ;RETURN
Well, would you look at that! It’s the actual instructions to tell the UART
to accept a character and send it on to the printer. We’ve reached the end of
our journey; this is the very routine that we’re going to modify. For a change,
it doesn’t call another routine—it’s the end of the line.
The PRTS (printer status) and PRT (printer) constants were defined ear
lier to be 23 hex and 22 hex. These are the “ports” that are accessed by the
IN and OUT instructions.
The IN Instruction
IN and OUT instructions are the chief way that the 8080 microprocessor
communicates with the outside world. As their names imply, IN gets data
from a data port and puts it in the A-register, while O UT sends data from the
A-register to a data port. There are 256 possible data ports: the appropriate
289
Soul of CP/M®
Before IN 22 Is Executed:
Data ports on UART

(256 of them).
/ 21
A-register
/
22
41
/
23
After IN 22 Is Executed:
Data ports on UART

(256 of them).
/ 21
A-register
/
z 41
22
K 'J
23
Fig. 9-2. The IN in stru ctio n .
one is specified by a 2-digit hex number (or a label equated to it) in the
address field.
Note that the data ports and their addresses are not the same as memory
and its addresses. The data ports are a separate group of registers and, since
there are only 256 of them, they are addressed with 2-digit hex numbers. This
is illustrated in Fig. 9-2. Thus, the 5A in the instruction “ IN 5A” refers to a
data port, not to memory address 5A.
The byte that is read into the A-register can either be data, such as a 41 hex
“A” character read from the keyboard, or it can be a “ status byte,” whose
purpose is to inform your program about the status of a U ART or an input/
output device. The values of a status byte must be known from the operation
manuals for the U ART or input/output device.
The OUT Instruction
As noted above, O UT takes an 8-bit byte from the A-register and puts it
into the data port specified in the operand field of the instruction. This byte
can either be data that is to be transferred to an output device (such as a 41
290
Before OUT B1 Is Executed:
Data ports on UART

(256 of them).
A-register BO
B1
7F
B2
After OUT B1 Is Executed:
Data ports on UART

(256 of them).
A-register BO
7F B1
7F
B2
Fig. 9-3. The OUT in stru ctio n .

Number in A-register and

number in instruction are
XORed together.
20FF
/
A-register
EE 2100
/ XRI 66
2101
66
/
2102
OF = 0 0 0 0
66 =
1 11 1
0 110 0 110
kI Memory
address.
0 1 1 0 1 0 0 1 = 69 ■
A-register Result goes back

in the A-register.
69
Fig. 9-4. The XRI instruction.
291
Soul of CP/M®
hex “A” character to be printed on the screen), or it can be a “function byte”

which tells the UART or an input/output device what to do. The values to be
used in a function byte must be known from the operation manuals for the
U ART or the in p ut/output device.
Examples:
IN 5Ah
OUT LABEL
The XRI Instruction
This instruction performs an “ Exclusive-OR” of the one-byte data that is in

the instruction with the data that is in the A-register. An Exclusive-OR means
“one or the other, but not both.” (Whereas, a regular OR means “one or the
other, or both.”)
The following is the “ truth table” for an Exclusive-OR. N ote that a 1 that is
Exclusive-ORed with a 1 gives 0, not 1.
D ata bit in instruction: 0 1 0 1

D ata bit in A-register: 0 01 1
Exclusive-OR (XRI) 0 1 1 0
This is a useful instruction for testing bit patterns, because it will immedi
ately tell you if all the bits in a certain bit configuration are set to 1. Simply
XRI the bit pattern that you want to see with the bit pattern in the A-regis
ter. If all the bits you specify are set, but nothing else is, the result will be 0.
For example, if the A-register contains 07 hex and you XRI it with 85 hex,
you’ll have:
A-register 0000 0111
Constant 1000 0101
Result 1000 0010
which is not zero. However, if the A-register contains 85 hex, you’ll get:
A-register 1000 0101

Constant 1000 0101
Result 0000 0000
which is zero.
292
The first thing we do in LPTOUT is read the status of the printer port to
see if the printer is ready to receive data. We do this with an IN instruction to
the port that holds the printer status: number 23 hex. This will return a byte
that looks like this:
DSR SYNDET FE OE PE TxE RxRDY TxRDY
7 6 5 4 3 2 1 0
Now, what we want to see when the printer is ready to receive a character
is this: the DSR, TxE, and TxRDY bits must be set. The other bits can be
anything they like. So we first mask off the other bits with an ANI (A N D
immediate) instruction, using an 85 hex, which is a 10000101 binary. As a
result, only bits 7, 2, and 0 can have a value other than zero. They may be
zero, but they may also be a one. All the other bits are definitely a zero.
Now, we want to make sure that bits 7, 2, and 0 are set to zero, so we XRI
the A-register with 85 again. If not, we go back to check again with the JN Z
instruction.
Once all the bits are set properly in the status word, we’re ready to receive
data. The data byte has been in the C-register all along. (Remember how you
put it there yourself before doing a call to BDOS?) So we move it to the A-
register, and then OUT it to the printer output port, which is 22 hex. Then we
return.
W hat could be simpler?
I /O Initialization
Usually, the particular UART you’re using needs to be initialized before it

can function properly. Thus, there is a section of code in the BIOS that is
activated every time you do a warm boot (or a cold one). Listing 9-4 shows
what this routine looks like.
Different UARTs need different kinds of initialization. (You can find out
what yours needs from its spec sheet.) In our example, our U A RT is a strange
little fellow that wants to be told “0, 0, 0, 40, AE, 27” before he can do
anything. Look at the listing. Every time an “OUT CRTST” is executed, the
value in the A-register is sent to the crt status register (3 hex). And, every
time an “OUT PRTS” is executed, the value is sent to the printer status regis
ter (23 hex). Thus, the sequence of numbers referred to in Listing 9-4 is sent
to both the crt port and the printer port of the UART.
293
Soul of CP/M®
Listing 9-4. I/O Initialization Code

■ *****************************************************
; INIT U SE R I/O; I.E., C ON SO L E , P UN CH , AND L I ST DEV.
******************************************************
INITVC:
I N I T UART (RECOMMENDED CMDS BY IMSAI)
DEF8 AF XRA A
DEF9 D303 OUT CRTST
DEFB D303 OUT CRTST
DEFD D303 OUT CRTST
DEFF D323 OUT PRTS
DF01 D323 OUT PRTS
DF03 D323 OUT PRTS
DF05 3E40 MVI A,40H ; RST 8251
DF07 D303 OUT CRTST
DF09 D323 OUT PRTS
DFOB 3EAE MVI A,0AEH ;MODE
DFOD D303 OUT CRTST
DFOF D323 OUT PRTS
DF11 3E27 MVI A,27H ;CMD
DF13 D303 OUT CRTST
DF15 D323 OUT PRTS
If you’re changing from one printer to another, you probably won’t have to
add anything to this initialization process, but if you add a driver that wasn’t
there before, then you’ll have to add code in this section to initialize the new
ports on your UART.
THE COMPLETE BIOS LISTING

In Listing 9-5, we show the complete BIOS listing from which the various
sections used previously were extracted. Look it over and see if you can
locate them. To return to our analogy of finding your way around in a
strange city, glancing over this listing is like getting a view of the city from an
airplane. You’ll see how the various far-flung locations lie in relation to each
other. Remember that even this is not the entire BIOS, since all the disk I/O
has been (mercifully) left out by the firm that sold us the system.
294
Listing 9-5. The Complete BIOS Listing

TITLE ++ BIOS FOR DIO WITH CP/M 2 . 2 REV 2 . 7 ++
BIOS FOR IMSAI DIO-C CONTROLLER WITH CP/M 2 . 2

*******************************************************
BIOS VERSION 2 . 7 : SINGLE DENSITY, 128 B/S
DOUBLE DENSITY, 256 B/S
DOUBLE DENSITY, 1024 B/S
0000 = FALSE EQU 0

FFFF = TRUE EQU NOT FALSE
0038 = MSIZE EQU 56 ;MEMORY SIZE IN K-BYTES

0036 = SSIZE EQU MSIZE-2 ; 2K FOR CP/M, BIOS, AND BUFF
001B = REVNUM EQU 27 ;BIOS REV #
0016 = CPMREV EQU 22 ;CP/M REV #
/ " B I A S " IS ADDRESS OFFSET FROM 3400H FOR

MEMORY SYSTEMS OTHER THAN 16K (REFERRED TO
AS " B " THROUGHOUT THE TEXT).
8800 = BIAS EQU ( S S I Z E - 2 0 ) * 1 024 ; ADDR OFFSET FROM 3400

W (20K SYSTEM)
BC00 = CCP EQU 3400H+BIAS ;BASE OF CCP
C406 = BDOS EQU CCP+806H ;BASE OF BDOS
D200 = BIOS EQU CCP+1600H ;BASE OF BIOS
*******************************************************
I / O DEFINITION EQUATES
*******************************************************
USEFUL THINGS TO KNOW
MPU-B STATUS PORT
(TERMINAL/TRANSMITTER REFERENCE)
0 = TxRDY T R A N S M I T T E R READY
1 = R xR DY R E C E I V E R R EA DY
2 = TxE T R A N S M I T T E R E MPTY
3 = PE P A R I T Y ER ROR
4 = OE O V E R R U N ER ROR
5 = FE FR A MI N G ER ROR
6 = S YN D E T S YCN D ET E C T
295
Soul of CP/M®
7 = DSR DATA SET READY
CONSOLE STATUS PORT ( I N HEX) 15 = PARALLEL

13 OR 4 = SERIAL
3 = SYSTEM
CONSOLE DATA PORT ( I N HEX) 14 = PARALLEL
12 OR 4 = SERIAL
f 2 = SYSTEM
0003 = CRTST EQU 3H ;CRT STATUS PORT
0002 = CRTDATA EQU 2H ; CRT DATA PORT
0015 = IKBST EQU 15H ; IKB1 STATUS PORT
0014 = IKBDATA EQU 14H ; IKB1 DATA PORT
F803 = VIODATA EQU 0F803H ;VI O DATA PORT
0002 = RXRDY EQU 02H ;CONSOLE STATUS
/ READY BIT (RxRDY)
0003 = IOBYTE EQU 0003H ; INTEL I / O BYTE
F800 = VI OI NI T EQU 0F800H ;VI O I N I T ENTRY POINT
FFFD = VIOID EQU OFFFDH ; POINTER TO VIO ID
0023 = PRTS EQU 23H ;PRINTER STATUS PORT
0022 = PRT EQU 22H ;PRINTER DATA PORT
*******************************************************
USER CUSTOMIZED I / O DEVICES. *
DO NOT REARRANGE JMP TABLE. *
*******************************************************
DE70 ORG BIOS + 0C70H
DE70 C3F8DE INITIO: JMP INITVC

DE73 C3BFDE L IST: JMP LISTIO
DE76 C3B3DE LISTST: JMP LISTSTIO
DE79 C388DE CONST: JMP CONSTIO
DE7C C39BDE CONIN: JMP CONINIO
DE7F C3A7DE CONOUT: JMP CONOUTIO
DE82 C3CBDE PUNCH: JMP PUNCHIO
DE85 C3D7DE READER: JMP READERIO
; CONSOLE STATUS CON:

CONSTIO:
DE88 CD8FDE CALL CONS ;GETS STAT OF SPECIFIC DEVICE
DE8B C8 RZ ; IF NOT READY RETURN 0 IN A
DE8C 3EFF MVI A,OFFH ;ELSE RETURN FF
DE8E C9 RET ;Z FLAG SET CORRESPONDINGLY
296
DE8F CDE3DE CONS: CALL DISPATCH

DE92 01 DB 1 ;USE IOBYTE BITS 1-0
DE93 45DF DW CRTSTAT ;00 - TTY: (CRT STATUS)
DE95 45DF DW CRTSTAT ;01 - CRT: (CRT STATUS)
DE97 45DF DW CRTSTAT ;10 - BAT: (CRT STATUS)
DE99 5FDF DW IKBSTAT ; 11 - UC1: (IKB1 STATUS)
r CONSOLE IN - CON:
C0NINI0
DE9B CDE3DE CALL DISPATCH
DE9E 01 DB 1 ;USE IOBYTE BITS 1-0
DE9F 4ADF DW CRTIN ;00 - TTY: (CRT INPUT)
DEA1 4ADF DW CRTIN ;01 - CRT: (CRT INPUT)
DEA3 4ADF DW CRTIN ;10 - BAT: (CRT INPUT)
DEA5 64DF DW I KB IN ;1 1 - UC1: ( IKB1 INPUT)
r CONSOLE OUT - CON :

C0N0UTI0:
DEA7 CDE3DE CALL DISPATCH
DEAA 01 DB 1 ;USE IOBYTE BITS 1-0
DEAB 55DF DW CRTOUT ;00 - TTY: (CRT OUTPUT)
DEAD 55DF DW CRTOUT ;01 - CRT: (CRT OUTPUT)
DEAF 55DF DW CRTOUT ; 10 - BAT: (CRT OUTPUT)
DEB1 6FDF DW VIOOUT ;11 - UC1 : (VIO OUTPUT)
r LIST STATUS - LST :

LISTSTIO:
DEB3 CDE3DE CALL DISPATCH
DEB6 03 DB 3 ;USE IOBYTE BITS 7 - 6
DEB7 42DF DW LISTSTC ;00 - TTY: (CRT OUTPUT)
DEB9 42DF DW LISTSTC ;01 - CRT: (CRT OUTPUT)
DEBB 42DF DW LISTSTC ; 10 - LPT: (LINE PTR OUTPUT)
DEBD 42DF DW LISTSTC ;11 - UL1 : (VIO OUTPUT)
r LIST OUT - LST:

LI STI O:
DEBF CDE3DE CALL DISPATCH
DEC2 03 DB 3 ;USE IOBYTE BITS 7-6
DEC3 55DF DW CRTOUT ;00 - TTY: (CRT OUTPUT)
DEC5 55DF DW CRTOUT ;01 - CRT: (CRT OUTPUT)
DEC7 35DF DW LPTOUT ;10 - LPT: (LINE PTR OUTPUT)
DEC9 6FDF DW VIOOUT ; 11 - UL1 : (VIDEO OUTPUT)
297
Soul of CP/M®
; PUNCH OUT - PUN:

PUNCHIO:
DECB CDE3DE CALL DISPATCH
DECE 05 DB 5 ;USE IOBYTE BITS 5-4
DECF 55DF DW CRTOUT ;00 - TTY: (CRT OUTPUT)
DED1 73DF DW PUNOUT ;01 - PTP: (H. S. PUNCH OUTPUT)
DED3 6FDF DW VIOOUT ;10 - UP1: (VIO OUTPUT)
DED5 55DF DW CRTOUT ;11 - UP2: (CRT OUTPUT)
; READER IN - RDR:
READERIO:
DED7 CDE3DE CALL DISPATCH
DEDA 07 DB 7 ;USE IOBYTE BITS 3-2
DEDB 4ADF D W CRTIN ;00 - TTY: (CRT INPUT)
DEDD 74DF DW RDRIN ;01 - PTR: ( H . S . READER INPUT)
DEDF 4ADF DW CRTIN ; 10 - UR1 : (CRT INPUT)
DEE1 4ADF DW CRTIN ; 11 - UR2: (CRT INPUT)
DISPATCH:
DEE3 E3 XTHL ;SAVE CALLER'S H, GET TABLE ADD
DEE4 56 M OV D,M ;SHIFT COUNT
DEE5 23 INX H ; POINT TABLE
DEE6 3A0300 LDA IOBYTE ;GET 10 ASSIGNMENTS BYTE
DEE9 07 DSHFT: RLC
DEEA 15 DCR D
DEEB C2E9DE JNZ DSHFT ; SHI FT TO POSITION BITS
DEEE E606 ANI 06H ;MASK BITS
DEFO 5F MOV E, A ; D ALREADY CLEAR
DEF1 19 DAD D ; INDEX INTO TABLE
DEF2 7E MOV A,M
DEF3 23 INX H ;TABLE WORD TO HL
DEF4 66 MOV H,M
DEF5 6F MOV L,A
DEF6 E3 XTHL ;PUT ADDR OF ROUTINE, GET CALLER'S H
DEF7 C9 RET ;G0 TO ROUTINE
• 'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'kic'k'k'k'k'k'k'k'k'k'k'kit'k'k'kif'k'k'k'k'k
; ; I N I T USER I / O ; I . E . CONSOLE, PUNCH, AND LIST DEV.

■ *******************************************************
I NI TVC:
; I N I T UART (RECOMMENDED CMDS BY IMSAI)
DEF8 AF XRA A
DEF9 D303 OUT CRTST
DEFB D303 OUT CRTST
298
DEFD D303 OUT CRTST

DEFF D323 OUT PRTS
DF01 D323 OUT PRTS
DF03 D323 OUT PRTS
DF05 3E40 MVI A,40H ;RST 8251
DF07 D303 OUT CRTST
DF09 D323 OUT PRTS
DFOB 3EAE MVI A,OAEH ;MODE
DFOD D303 OUT CRTST
DFOF D323 OUT PRTS
DF11 3E27 MVI A,27H ;CMD
DF13 D303 OUT CRTST
DF15 D323 OUT PRTS
DF17 2 1FDFF LXI H,VIOID ; VI O ID 1 ADDRESS

DF1A 3E56 MVI A, ’V’ ;1 ST ID
DF1C BE CMP M ;SAME?
DF1D C22FDF JNZ NOVIO
DF20 23 INX H ; VIO ID 2 ADDRESS
DF21 3E49 MVI A /I’ ;2ND ID
DF23 BE CMP M ;SAME?
DF24 C22FDF JNZ NOVIO
DF27 CD00F8 CALL V I OI NI T ; I N I T VIO
DF2A 3E97 MVI A,97H ; VIO AS OUTPUT
DF2C C331DF JMP INITI01
DF2F 3E94 NOVIO: MVI A,94H ;CRT AS OUTPUT
IN ITI01:
DF31 320300 STA IOBYTE
DF34 C9 RET
■*******************************************************
; LIST CHARACTER IN C
■ *******************************************************
DF35 DB23 LPTOUT: IN PRTS ; CHECK STATUS PORT
DF37 E685 ANI 85H ;CHECK BOTH READY BITS
DF39 EE85 XRI 85H
DF3B C235DF JNZ LPTOUT
DF3E 79 MOV A,C
DF3F D322 OUT PRT
DF41 C9 RET ;USER PRINTER 10
299
Soul of CP/M®
• *******************************************************
; RETURN LIST STATUS (FF I F READY, ELSE 0)
; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
DF42 3EFF LISTSTC:MVI A,0F FH
DF44 C9 RET
• *******************************************************
; CONSOLE STATUS RETURNED IN A.
* *******************************************************
CRTSTAT:
DF45 DB03 IN CRTST ;STATUS PORT
DF47 E602 ANI RXRDY ;TEST RxRDY
DF49 C9 RET ; Z = 1 , CHAR NOT READY
:
• k'k'k-k'k'k'k'k-k-kie-k'k'k'k'k'k'k'k'kic'k'k'kicic'k'k'kicic'kic'k'k'kie'k'kic'k-k'k'k'kic'kieic'k'k'k'k-k'k
; CONSOLE IN RETURNS THE CHARACTER IN A

• 'k'kickicie-k'k'k'kie'kic'k'k'kic'kieie'k'k'k'k'k'kick'k'k'k'k'k'k'k'k'kic'kie'kicic'kic'k'k'k'k'k-k-k-k'k'k
CRTIN:
DF4A CD45DF CALL CRTSTAT
DF4D CA4ADF JZ CRTIN ;GET RxRDY
DF50 DB02 IN CRTDATA ;GET CHARACTER
DF52 E67F ANI 7FH ;STRIP PARITY
DF54 C9 RET
; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
; CRTOUT SENDS THE CHARACTER IN C TO OUTPUT

• ‘
k’
k'k'k'k'k'k'kicie'kif'k'k'k'k'k'k'kick'kic'k'kic'ick'k'k'k'k'k'k'kicic'k'k'k'k'k'k'k'k'kic'k'kicic'k'k'k'k
CRTOUT:
DF55 DB03 IN CRTST ;GET STATUS
DF57 OF RRC ;TxRDY?
DF58 D255DF JNC CRTOUT ;REPEAT, NOT READY
DF5B 79 MOV A,C ;CHAR TO ACCUM
DF5C D302 OUT CRTDATA ;CHARACTER TO PORT
DF5E C9 RET
"k'kickic'k'k'k'k'k'k'k'kic'k'k'k'kic'k'kick'k'k'k'k'k'k'k'k'k'k'k'kie'k'kic'k'k'k'k'kie'k'k'k'k'k'k'kic'k'k
IKB1 STATUS RETURNED IN A.

*******************************************************
IKBSTAT:
DF5F DB15 IN IKBST ; STATUS PORT
DF61 E602 ANI RXRDY ;TEST RxRDY
DF63 C9 RET ; Z = 1 , CHAR NOT READY
300
• *******************************************************
; IKB1 IN RETURNS THE CHARACTER IN A
■ *******************************************************
IKBIN:
DF64 CD5FDF CALL IKBSTAT
DF67 CA64DF JZ IKBIN ;GET RxRDY
DF6ADB14 IN IKBDATA ;GET CHARACTER
DF6C E67F ANI 7FH ;STRIP PARITY
DF6E C9 RET
• •k'k'k'k'k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k
; VIOOUT SENDS THE CHARACTER IN C TO VIO

; *******************************************************
VIOOUT:
DF6F 79 MOV A,C
DF70 C303F8 JMP VIODATA ; VI O RETURNS TO CALLER
■ *******************************************************
; PUNCH CHARACTER IN REGISTER C
; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
PUNOUT:
DF73 C9 RET ;NULL ROUTINE
• k'k'kie'k'k'k'k'k'k'k'k'k'k'kit'k'k'k'k'k'k'k'k'kic'k'k'k'k'k'k'k'k'k'k-k'kic'kickick'k'k'k'k'k'k'kic'k'k'k
; READ CHARACTER INTO A FROM READER DEVICE

• 'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'kick'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k
RDRIN:
DF74 3E1A MVI A, 1AH ;ENTER END OF FILE
; (REPLACE LATER)
DF76 E67F ANI 7FH ;REMEMBER TO
; STRIP PARITY BIT
DF78 C9 RET
DF79 END
HOW TO MODIFY YOUR PRINTER DRIVER
In order to create a new driver for our BIOS, you first must determine the
kind of driver program you need to write. You must know what kind of
printer you have and which communications “protocol” it uses. “ Protocol” is
just a fancy word for “procedure.” In this case, it means the procedure by
which the the printer tells the computer that it is ready to accept data.
301
Soul of CP/M®
Protocols and Other Diplomatic Niceties
With some printers, you can simply wait for it to be ready, throw a charac
ter at it, wait for it to be ready, throw a character at it, and so on, until you’re
done, and it will print the characters ju st fine. Such a printer is called a “stan
dard serial printer,” or a “teletype-like printer.” The Epson is such a beast.
Other more complex printers, such as the “daisy-wheel” printers, require one
of two possible advanced protocols, either “xon/xoff” or “etx/ack.” For
instance, the NEC printer needs etx/ack while the Diablo 630 likes xon/xoff.
These protocols are designed to allow the printer to work with a bunch of
characters at a time rather than with single characters.
X O N /X O FF Protocol
You have probably already used xon/xoff and not known it. X on/xoff is
the same thing as the “control-s/control-q” that C P /M uses to freeze and
unfreeze the scrolling of the display on the screen. In C P /M , control-s will
freeze the display. Striking any key, thereafter, generates a control-q which
will unfreeze the display. Control-s means xoff, i.e., “turn off transmission”
while control-q means xon, i.e., “turn on transmission.”
A printer uses this technique of xon/xoff when it has a built-in “character
buffer” that can hold a certain number of characters for printing. The buffer
may be, for example, 1024 bytes long. W hat the buffer does is allow the com
puter to send characters to the printer at a fairly fast rate (say, 1200 baud, or
about 120 characters per second) and then hold them while the slower printer
mechanism prints them out (which may occur at roughly 30 characters per
second). This way, while the buffer in the printer is emptying, the computer
can go on its merry way and do more processing. Provided the com puter is
set up properly, you could then be editing a file while the printer was spitting
characters out on the paper, and your text editor would not be slowed down
by the 30 character/second printer. You would only notice a delay when the
printer needed its buffer filled again, and this would occur at a rate of 1200
or more baud, so it wouldn’t take long.
Normally, the way all this happens is that after your printer driver sends
each character, it reads a status word from the printer and looks to see if the
printer is sending back a control-s, which means “Stop! my buffer is full.
D on’t send any more characters until it’s empty.” If there is no control-s
being sent back, the computer sends the next character, and so on, until it
302
receives a control-s. At that point, it goes into a wait loop searching for a
control-q to come from the printer. The control-q means the printer buffer is
once again empty. (“Hello, I’m empty; you can send more data.”) Fig. 9-5
shows how this looks in flowchart form.
The point of all this protocol is that the computer only waits for the printer
after every 1024 characters, instead of after every character, and is, therefore,
free to do other tasks while printing is taking place.
ETX/ACK Protocol
E tx/ack protocol is similar to that of the xon/xoff procedure, but it is

implemented differently. In this case, a block of characters (often 128) is sent
to the printer followed by an “etx” character (03 hex = control-c). “ Etx”
means “end of text.” Then, after the printer has printed out the entire block
of characters, it sends an “ack” (06 hex = control-f) back to the computer.
“Ack” means “Acknowledge. I have received your last transmission.”
Writing a Sample Driver
In the last section, where we explored the BIOS listing, we found a driver
for the simplest kind of printer—a “teletype-like” device with no advanced
protocol. W hat we’re going to do in this section is write a driver for a printer
that uses xon/xoff protocol. Then, in the next section, we’ll show you how to
insert this driver into your BIOS so your entire C P /M system can use the
new printer.
Specifically, our printer will be a Diablo 630 daisy wheel. We are using it
for word processing and it is hooked to our C P /M system through a serial
board running at 1200 baud. The serial board uses an Intel 8251 UART,
which is what our driver must talk to.
Look back at the driver in the last section. When it wants to know if it can
send a character, it checks to see if 3 bits are set: number 7 for “D ata Set
Ready,” number 2 for “Transmitter Empty,” and number 0 for “Transmitter
Ready.” Here’s how the status word looks with these bits set:
DSR SYNDET FE OE PE TxE RxRDY TxRDY

1 0 0 0 0 1 0 1
Bit number 7 6 5 4 3 2 1 0
303
Soul of CP/M®
Fig. 9-5. Flowchart of the XON/XOFF protocol program.
304
Using the xon/xoff protocol is somewhat more complicated. We need to

ask the U ART two different kinds of questions: first, whether the UART is
ready to receive a character from the BIOS, and second, whether the UART
has a character ready to give to the BIOS. In the first case, we ask the UART
whether bits 0 and 2, for “transm itter ready” and “ transm itter empty” are
set. In the second case, we want to know whether bit 1, for “receiver ready,”
is set.
When a program CALLed the driver for the simple “teletype-like” printer
driver in the last section, there was only one possible outcome. The driver
would wait until the U ART said the printer was free and then send the char
acter.
With “xon/xoff,” there are two things that can happen when a program
calls the driver to send a character to the printer. In either case, a character
gets sent to the UART to be transmitted to the printer. Then, either (1) the
U ART will not have sent an “xoff ’ (in which case, control will return to the
calling program so that it can get another character) or (2) the U ART will
have sent an “xoff” (in which case, the driver will not return to the calling
program, but will wait until the “xon” is received before it goes on). Listing
9-6 is the listing for the new driver.
We’re assuming here that we don’t need to do anything further to initialize
the UART. If we did, we’d need to add the appropriate instructions to the
initialization part of the program. From the preceding descriptions, you
shouldn’t have any trouble following the operation of the driver.
Testing the Driver

If you’re very confident about your programming, you may want to go
right ahead and assemble your new driver right into the BIOS without testing
it out. If so, you can skip the next few paragraphs.
Inserting the new driver into the BIOS and writing it on the system tracks of
a diskette (as we’ll describe in the next section) is somewhat involved, and not
something you want to do too many times. It would be nice if there was an
easier way to test out your new driver to see if it works. Then, you could debug
it without going through the whole procedure of assemblying a new BIOS
every time you change a single instruction in your code. Here’s how we do it:
1. We put the driver routine at 100 hex, just like any other program. We
can use either the D D T “ a” command, or assemble it with ASM.
2. We put a “jm p 100” instruction at the start of the printer driver rou
tine in the BIOS.
305
Soul of CP/M®
Listing 9-6. New Driver Program

• **********************************************************
; LIST CHARACTER IN C *
• **********************************************************
; New x o n / x o f f p r i n t e r d r i v e r .
; (was j u s t a RET r e t u r n i n s t r u c t i o n . )
LPTOUT: i n prts ; I n p u t 8251 s t a t u s

ani 05h ;AND 8251 f o r r eady t o send
xr i 05h ; E x c lu s iv e - 0 R to get zero f l a g
jn z Iptout ; Loop t i l l UART r e g i s t e r ready
mov a,c ; G e t l i s t c h a r a c t e r f rom C t o A
out prt ; 0 u t p u t t o UART d a t a r e g i s t e r and send
in prts ; I s UART r eady w i t h a c h a r a c t e r
ani 02h ;Does r e c e i v e r have a c h a r a c t e r ready
xri 02h ;Mask
rnz ; I f n o t z e r o , t h en c o n t i n u e n o r m a l l y
in prt ;Y e s -g e t the c h a r a c te r
cpi 13h ; I s i t a AS f r e e z e ( x o f f )
rnz ; N o pe - s o s k i p i t
Lp 11 : in prts ; I t was a AS so now we must w a i t f o r
; a AQ t o r e t u r n
ani 02h
xri 02h
jn z Lpti
in prs ; C h a r a c t e r i s r eady
cpi 11 h ; I s i t a AQ ( x o n )
jnz Lpti ; N o , so lo op t i l l i t i s , i . e . , l e t p t r
; b u f f e r empty
ret ; F i n a l l y , a AQ so r e t u r n f o r n e x t c har
We’ll assume at this point that you’ve written an appropriate driver routine
of your own. It may not be perfect, but it’s ready for a preliminary test. Thus,
as we describe how to test our routine, you can—if you’re ready—follow the
same steps with your own routine.
First, you have to know where to put the “jum p 100” instruction. This isn’t
hard if you’ve assembled your existing BIOS into a PRN file. Simply look
through the listing for the printer driver routine and write down the address
where it starts. In our 56K system, this address is DF35 hex, as you can see
from the BIOS listing that was described in the last section.
306
So, either write your driver with your word-processing program (call it
NEWDRIVE.ASM), assemble it to get a HEX file, and call it in with DDT:
A>ddt n e w d r i v e . h e x
or, type it in directly from D D T using the “a” command. In either case, ORG
it at 100 hex.
At this point, your printer should not be operating (you have not toggled it
on with control-p). Use the “a” command to insert a “jm p 100” at the start
of the driver routine in BIOS. For our particular BIOS, we’d say:
-aDF35
DF35 jmp 100
DF38 .
N ote that you are modifying the very BIOS that you’re operating with. If you
do something wrong, the system may die, so save your files before you get in
too deep.
Now comes the moment of truth. Toggle on the printer by typing control-
p. H it “return” a few times. The printer should respond. Type something,
and then hit return. It should be printed out. If the wrong thing, or nothing,
happens, either your driver is defective or your “jm p 100” instruction is in
the wrong place. Back to the old drawing board.
INSTALLING THE NEW DRIVER INTO YOUR BIOS

Once you have the driver working in this nonstandard location, you can
install it into your C P /M system. That’s the subject of this section.
Before we can complete this process, you’ll need to learn about two new
C P /M utility programs, MOVCPM and SYSGEN, and about the magic
number N that we mentioned earlier. We’ll cover these topics first, and then
summarize the complete procedure at the end of the section.
The M OVCPM Program—W hat’s It Hiding?
MOVCPM is an amazing program. It actually contains within it most of

the C P /M operating system. That is, it contains the CCP and BDOS. It may
also have part of the BIOS in it. If the people who configured your system
307
Soul of CP/M®
did not put the disk part of BIOS in your BIOS.ASM file, then they put it in
the MOVCPM program. W hat MOVCPM may not have in it are the drivers
for the other I/O peripherals: the console, the printer, and so on. They’re
probably in the BIOS.ASM file. MOVCPM may have these routines in it, but
they may not work on your equipment, or they may be merely skeletal drivers
that don’t work on any equipment.
Here’s how MOVCPM works. When you call it, it loads three things into
memory: (1) the MOVCPM program itself, (2) the CCP, BDOS, and maybe
part of BIOS in the form of a COM file, and (3) a bit map, which tells it
which bytes of the COM file need to be “relocated” and which don’t.
One question that should immediately occur to you is, “where in memory
does the MOVCPM put this COM file?” It can’t put it in high memory where
C P /M normally goes, since the actual system we’re operating with is already
there, and you can’t make major changes in the very same sections of code
that constitute your operating system, without getting into big trouble. So
MOVCPM keeps this version of C P /M in low memory, starting at location
900 hex, which just leaves room for the program and the bit map below it.
This version of C P /M is called the system “image,” a name that means that
the instructions of code look just like the actual operating version of C P /M
in high memory, but are in the wrong place to actually execute.
Fig. 9-6 illustrates what memory looks like when MOVCPM is at work.
When you call MOVCPM from C P /M , you need to specify two parameters.
The first is the size memory that your machine has, 64K or whatever. Second,
you need to tell it whether you want the image of C P /M to be moved to high
memory and executed. This is something you almost never want, since the
C P /M image is probably incomplete and won’t work, and will result in a
crashed system if you try to execute it. If you don’t want this to happen, you
type an asterisk after the size:
A>movcpm 56 *
This means “leave the image in low memory; don’t relocate or execute it.'
This means “we want to generate CP/M for a 56K system.”
You can also use an asterisk in the memory field if you want to simply use
all the available memory.
Axnovcpm * * (Takes 64K in a 64K system, etc.)
308
■
In our particular case, we can’t do that because the upper 8K of our

machine, although present, is used for special video drivers. (The routine
figures out how much memory you have by testing higher and higher
addresses to see if it can put something into each location and then read it
out. When it can’t, that’s the top of memory.)
How does MOVCPM go about moving this “image” of C P /M to high
memory? It starts off with all the individual 8080 instructions written as if
they were in a 20K system. Next, it figures out the difference or “bias”
between a 20K system and the size that we specified, like 56K. Then it uses
the bit map to change only those bytes which represent addressees in the
code (the last two bytes of a “jm p ” instruction, for instance). T hat’s it. The
resulting new “image” sits in low memory waiting for the next thing that we
want to do with it. Even though the addresses are changed as i f the BIOS
were in high memory, it is not actually moved there.
What we do now is save this image using the SAVE utility. MOVCPM is
very helpful here because it tells us just what to type:
/ / Top of memory.
BIOS
/
“Active” CP/M system.
BDOS
FBASE /
CCP
CBASE /
Space available, depending
on size of system.
/
BIOS (maybe)
/ “ Image" of CP/M.
BDOS
/
CCP
900 /
Bit Map
/
MOVCPM
100 /
Zero Page
0 /
Fig. 9-6. Memory when MOVCPM program is operating.
309
Soul of CP/M®
A>movcpm 56 *
CONSTRUCTING 56K CP/M v e r s 2 . 2

READY FOR "SYSGEN" OR
"SAVE 45 CPM56.COM"
A>
So we type “save 45 cpm56.com” . The image is 45 separate 256-byte “pages”

long, and MOVCPM suggests we call the file “CPM56.COM”, which we’re
happy to do.
The Urge to Merge
Once we have the file of the C P /M image, CPM56.COM, safely stored on

our disk, what then? Well, we’re going to merge the BIOS.ASM file, which
we’ve modified by putting our new driver into it, into CPM56.COM, using
both a special technique in D D T and the magic number N. Then we’ll take
the resulting complete image of C P /M (which we can call “CPM56n.COM” ,
where “n” stands for new) and write it onto the system tracks of a formatted
but otherwise virgin disk, using SYSGEN.
The Magic Number “N”
Now that you know how to use MOVCPM, you can be admitted to the
small and privileged group who know how to find the magic num ber N.
W hat is this number? Really, it is the difference, or offset, between where
MOVCPM puts the image of C P /M and where C P /M actually goes in high
memory.
In Figure 9-7, notice how the “image” of CPM that is placed in low mem
ory by the MOVCPM program is related to the image of C P /M that will be
placed on the system tracks of the new disk. This new image will occupy
exactly the same addresses as the C P /M that is currently running in high
memory, except for the changes made to BIOS by the addition of the new
driver.
The CCP is located at 980 hex in the system image, but will be at BCOO hex
(in our 56K system) when actually installed and running. BDOS is located at
1186 in the image, but will be at C406 when running, and so forth. You can
see that all these pairs of numbers are related by the same constant, which we
can find by subtracting any two of them.
310
How Do We Find Out All These Addresses, Anyway?
In order to find the magic number N, we need to know at least one pair of
addresses: the one in the MOVCPM image in low memory and the one that is
in the running C P /M in high memory. A good “pair” to work on is CBASE,
the bottom of the CCP. The first half of this is easy because, in the system
image, the CCP is always at 980 hex, no matter what size system you have.
CBASE for high memory, as we discussed before in the chapter on BASIC, is
not quite so easy to find. However, if you look at locations 6 and 7 hex in
memory while C P /M is running (not DDT), you’ll find an address that is
close to the start of BDOS. The CCP is usually about 800 hex bytes long, so if
you subtract 800 from this address, you’ll get CBASE. In our case, C406 -
800 = BC06. But we know that the CCP is going to start on a page bound
ary, so we figure that it’s probably at BC00.
Another way to find CBASE is to look at the BIOS.PRN (not the ASM)
listing. As we described earlier in the chapter, CBASE and several other fas-
DFFF
_____ /
Old BIOS New BIOS D200
/
BDOS BDOS C406

FBASE /
CCP CCP BC00
CBASE /
BOOT BB80
(Unused)
/
2D7F Image written
New BIOS to system tracks.
1F80
BDOS
1186
CCP
980
BOOT
900
Bit Map
MOVCPM All these pairs

100 of numbers are
related by the
Zero Page
same constant.
0
Image in memory.
Fig. 9-7. Location of CP/M image in memory.
311
Soul of CP/M®
cinating addresses are often part of the address location arithmetic in the
beginning of the file. Checking this file, we find that BCOO is, in fact, the start
of the CCP.
D D T ’s H ex Arithmetic Function
Did you know that D D T had a handy function that will perform arithme
tic on hexadecimal numbers? Of course you did. If we type:
-hx,y
where x and y are 4-digit hex numbers, D D T will print out x + y and x-y in
hex, for our gratification and amusement.
In this case, we want to know the difference between, say, 980 and BCOO.
It would also be nice if we got a negative number, so that we could simply
add it to other numbers later to perform the conversions. Thus, we get into
D D T and type:
-h980,bc00
D D T responds with:
C580,4D80
The difference between these two numbers is what we want: 4D80. It is, in
fact, our magic number N.
Finding the Magic Number the D.R. Way
In the C P / M Alteration Guide, Digital Research provides a table of these

magic numbers for different memory sizes. This table will work for some
C P /M systems but not for others (such as the one in our examples). The
problem is that the table assumes a certain size BIOS. If your BIOS has been
enlarged, either by you or by the vendor who configured the system, the table
will give you the wrong value.
These are the values of N that are shown in the CP/ M Alteration Guide:
312
Memory Size Offset N

20K D580
24K C580
32K A580
40K 8580
48K 6580
56K 4580
62K 2D80
64K 2580
N ote that for our 56K system, it gives a value of 4580 instead of the 4D80
that we know is correct. The difference between these two values is 800 hex,
which is just how much additional space our modified BIOS takes up.
If you have the standard-size BIOS, then the table will be useful to you,
but you should verify the actual location of your C P /M system by one of the
methods previously described before you accept the figures in the table at
face value.
W hat Good Is This Magic Number?
We need to know this number for two reasons. First, we want to be able to
look at certain sections of code in the MOVCPM image in low memory and
know what we’re looking at. We know where things are in BIOS in high
memory from the BIOS.ASM listing, and we need to be able to translate this
into equivalent locations in low memory. The magic number N does this, as
we shall see.
Secondly, we’re going to use another one of D D T ’s useful features-the
ability to load a HEX file with a “bias” or offset, instead of at the ORG
address of the file. Thus, if we have a HEX file that is ORGed at, say, D200,
and we want to load it into memory somewhere else, say at 1F80, we simply
figure out the magic number that is the difference of these two numbers and
type it into D D T following the “r” (for “read”) command. As you can see,
this is the same old magic number, 4D80. If, for example, we want to load a
HEX file called NEWBIOS.HEX (which is ORGed at D200) using this bias,
we type:
-inewbios.hex
-r4d80
and the file will be placed in m em ory at 1F80.

313
Soul of CP/M®
INSERTING THE NEW DRIVER INTO THE CP/M SYSTEM
At this point, you should have a working driver routine that you’re ready
to insert into your C P /M operating system. In the procedure that we’re going
to describe, we’ll make use of the knowledge you’ve acquired in the previous
sections.
Merging Your New Driver Into the BIO S.ASM File
The first thing that we want to do is create a new version of the BIOS.ASM
file: one which incorporates your new driver. (Remember that this file will
have different names depending on your system: BIOSIO.ASM,
GBBIOS.ASM, or whatnot.)
Start by making a copy of the old BIOS.ASM file. Call it
NEWBIOS.ASM:
A>pi p n e w b i o s . a s m = b i o s i o . a s m
Bring NEWBIOS.ASM into your word-processing or text-editing program.

Delete the program lines for the existing driver. Then, either type in the
assembly code for the new driver, or (if your word processer will let you)
copy the file containing the new driver into the right place in
NEWBIOS.ASM.
Also, if you need to add anything to the initialization part of BIOS to get
the U ART off on the right foot, now is the time to do it.
Reassemble the new BIOS:
A>asm newbios
You now have NEWBIOS.HEX and NEWBIOS.PRN.
Create the C P /M Image
You can now use MOVCPM to create the C P /M image, as described in the
last section. If you already have the system image (CPM56.COM or what
ever) stored as a file, you can skip this step. Refer to the last section to see
how MOVCPM is used.
314
A>movcpm 56 *
A>save 45 cpm56.com
Of course, the numbers here will be different, depending on your system.
Read in the C P /M Image Using DDT
We’re going to use D D T to do the actual merging of the new driver into
the system image. Load the system image as you call DDT:
A>ddt cpm56.com
To make sure that everything is where you think it is, use D D T to explore
this image. Here’s the beginning of the CCP in the system image:
-d980
0980 C3 5C BF C3 58 BF 7F 00 20 20 20 20 20 20 20 20 .\. .X ...
0990 20 20 20 20 20 20 20 20 43 4F 50 59 52 49 47 48 C0PYRIGH
09A0 54 20 28 43 29 20 31 39 37 39 2C 20 44 49 47 49 T (C) 1979, DIGI
(e tc.)
It should be just the same as the running CCP in high memory, so look at
that:
-dbcOO
BCOO C3 5C BF C3 58 BF 7F 00 20 20 20 20 20 20 20 20 . \ . .X . ..
BC10 20 20 20 20 20 20 20 20 43 4F 50 59 52 49 47 48 C0PYRIGH
BC20 54 20 28 43 29 20 31 39 37 39 2C 20 44 49 47 49 T (C) 1979, DIGI
(e tc.)
Using the “d” command lets us see that the sign-on message is really there.
Check the beginning of BIOS. It should be a jum p table:
- 1 1 f 80
1F80 JMP D3D3
1F83 JMP D334
1F86 JMP DE79
1F89 JMP DE7C
(etc . )
315
Soul of CP/M®
Now look in the running BIOS. It should be the same thing:
- Ld200
D200 JMP D3D3
D203 JMP D334
D206 JMP DE79
D209 JMP DE7C
(etc . )
Find the old driver routine (if there is one) in the system image and in the
running BIOS. They may not be the same.
Merge in the New BIOS File
We’re going to use D D T to merge the NEWBIOS.HEX file into the image
of C P /M in low memory. This is where the magic offset number N comes in.
Although NEWBIOS.HEX is ORGed in high memory (at DE70 in our case),
we want to lay it down on top of the BIOS part of the system image in low
memory (at 2BF0 in our case).
-inewbios.hex
That puts the file name in the FCB.
-r4d80
That reads in the file with an offset of 4d80. You should now look at the
image with the “1” command to make sure that the new driver is where you
want it to be. If so, you’re ready to save the image as a file back onto the disk.
-gO
A>save 45 cpm56n.com
The “n” means “new.”
----------------------------This is the same number of 256-byte pages that MOVCPM told

you to save originally (unless your modification has expanded
BIOS past a page boundary).
316
Writing the New Image to the System Tracks
Now, we’re ready to actually create a new system disk. Take a formatted
disk and put it in drive B.
SYSGEN is often used, as you no doubt know, to simply copy the current
C P /M system from the system tracks of the working disk to those of a
formatted disk. In that case, no file name is specified when we call it. How
ever, we want to use the CPM56n.COM file when we generate our new sys
tem, so we type:
| ------------------- Don’t forget the “n”.
A>sysgen cpm56n.com
SYSGEN will reply with:
■Type this “b.”
SYSGEN VER 2 . 0
DESTINATION DRIVE NAME (OR RETURN TO REBOOT)b
DESTINATION ON B, THEN TYPE RETURN-------------------
FUNCTION COMPLETE
DESTINATION DRIVE NAME (OR RETURN TO REBOOT)-
■Type returns here.
SYSGEN will write the new version of the operating system onto the system
tracks of the new disk.
T hat’s it! You’re done! You have a new custom-configured operating sys
tem that you made yourself. There are a lot of people out there who will pay
good money for this sort of talent. Test it out using D IR and TYPE to see if
it will really print out when you toggle on the printer with control-p. If you’re
testing an xon/xoff or an etx/ack printer, you’ll need to send enough charac
ters at once to fill up the printer buffer.
If it doesn’t work, go back to the beginning of this section and follow the
steps very carefully. Check that you know where everything is in memory,
both in the system image in low memory and in the running C P /M in high
memory. If your driver worked when you tested it with D D T at location 100,
it should work when installed in the driver.
Good luck!
317
Soul of CP/M®
Quick Summary of Driver Installation Steps
Once you are able to perform this installation process quickly, this is what
you’ll be typing on the screen. (We’ll assume that you aren’t going to check
memory with DDT.) Of course, the memory size and the number of pages to
SAVE will be different depending on your system.
A>pi p n e w b i o s . a s m = b i o s i o . a s m
(Add d r i v e r t o newbios. asm w i t h word p r o c e s s o r , store

r e v i s i o n as NEWBIOS.ASM)
A>asm newbios
A>movcpm 56 * (These steps won’t be necessary each time.)

A>save 45 cpm56.com
A>ddt cpm56.com
-inewbios.hex
-r4d80
-gO
A>sysgen
A SHORTCUT
Under some special circumstances, you don’t even need to use the assem
bler to modify your BIOS. You can do it directly with DDT, using a process
similar to that previously described, but somewhat shorter. Essentially what
this involves is using the “a” command of D D T to put the code for the new
driver into BIOS, rather than reassemblying the BIOS.ASM file. This could
be useful if the driver you want to install is not too complex, or if you’re
making minor changes in an existing driver, or debugging it.
The limitation of this process is that the new driver must fit into the space
occupied by the old one. Otherwise, when you type in the instructions using
the “a” command, you may be overwriting something im portant. Actually,
you might be able to expand the driver a little, depending on what routine
318
follows the driver. If it’s the routine that returns the status of the list device, it
may never be used, so you can overwrite it. Check your BIOS.ASM listing to
see what’s there.
As described in the last section, get your new driver working at 100 hex by
placing a “jm p 100” at the start of printer driver in the running BIOS. Once
it’s working at 100 hex, move it up to high memory with the “m” command
of DDT. For instance, if your routine is 44 hex bytes long and is going to be
installed in location F209, you’d type:
-ml 0 0 , 4 4 , f 209
N ote that you’re directly modifying the operating system that you’re using,
so if you make a mistake, things could die a quick death. You don’t (obvi
ously!) want to use this system to modify the drivers of any peripherals that
are currently in use.
The instructions for your driver are now at the right place in the running
BIOS, but they have the wrong addresses, having been assembled at 100 hex.
Go through the code with the D D T “a” command and change the memory
reference instructions to the correct values. For instance, if there’s a “jm p
100” instruction in the program, you’ll need to change it to “jm p f209” .
Now, turn on your printer. (It should work since it’s running with the new
driver, right?) Use D D T ’s “1” command to dump the code for the driver rou
tine to the printer:
- Lf 209
You’re going to need this printout in a minute.

If you don’t already have it, create a file containing your current system
image, using MOVCPM:
A>movcpm 64 *
A>save 43 cpm64.com
This assumes that your MOVCPM contains a working version of BIOS. If it

doesn’t (some MOVCPM’s have only a skeletal BIOS), then you’ll have to
make up a current version of CPM64.COM (or whatever) by assemblying
BIOS.ASM and merging it into CPM64.COM with D D T as described in the
last section. This may make the process seem like not much of a shortcut, but
if you’re debugging, you’ll only have to create this CPM64.COM file once.
319
Soul of CP/M®
After that, you can skip this step entirely. Bring this image into memory
with:
A>ddt cpm64.com
Now you have to find the old driver in the image in low memory. You can
either use the magic number N as described earlier or you can simply search
through the code with DDT, looking for the instructions that you know are
in the driver.
Once you find the old driver, you type the new one over the top of it, using
the “ a” command. Type it in exactly as it appears on the printout that you
made above. The memory reference instructions will be wrong for their cur
rent locations in low memory, but they’ll be right later when loaded from the
disk system tracks into high memory.
Save this modified image as CPM64N.COM:
-gO
Use SYSGEN to write this new image to the system tracks of a formatted
disk:
A>sysgen cpm64n.com
There you are again! A complete working C P /M system with your own
custom modification. Boot up the new disk and test the driver by using it to
TYPE some long files.
MODIFYING BIOS FOR DIFFERENT CONTROL

CHARACTERS
It may happen that you have a printer with special functions like com
pressed or elongated print fonts, different color ribbons, or the like. It may
also be the case that there’s no convenient way to send these control codes to
the printer from your program, so these special functions are difficult to use.
One solution to this problem is to modify the printer driver in your BIOS to
reinterpret certain characters.
320
Listing 9-7. Print Driver Program

**************************************************
;new p r i n t e r d r i v e r f o r Epson MX-80

r
; i n c o r p o r a t e s compressed-mode f a c i l i t y
; c o n t r o l - w t o g g l e s between compressed and normal
W
; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
r
0100 o r g 100h
/
0100 DB23 test in 23h ;ge t p r in t e r status
0102 E685 ani 85h ;mask o f f test b its
0104 EE85 xri 85h ; a r e they a l l on
0106 C20001 jnz test ;no-wai t
0109 79 mov a,c ; g e t c h a r a c t e r i n A - re g
010A FE17 c pi 17h ; i s i t ac o n t r o l - w ?
010C CA1201 jz control ;yes
01 OF C32801 j mp exi t ;no
; i t 1s a c o n t r o l - w
0112 3A2B01 c o n t r o l Ida t o g g l e ; i s to g g le set to 0 ?

011 5 B7 ora a
0116CA2201 j z comp ;yes
; t o g g l e s e t t o n o n z e r o , so t u r n OFF compressed p r i n t
0119 2 F cma ; cha nge A - r e g i s t e r t o 0
011A 322B01 sta toggle ; set toggle
011D 3E92 mvi a,92h ; g e t code t o t u r n OFF c . p .
0 1 1 F C32801 jmp e x i t
; t o g g l e s e t t o z e r o , so t u r n ON compressed p r i n t
0122 2F comp cma ; cha nge A - r e g i s t e r t o non-0
0123 322B01 sta to g g le ; set toggle
0126 3E0F mvi a , 0 f h ; g e t code t o t u r n ON c . p .
; p r i n t t he c h a r a c t e r and r e t u r n
0128 D322 e xit o u t 22h ; s e nd t o p r i n t e r
012A C9 ret ; return
012B 00 toggle db 0 ; i f 0 , norma I mode

; i f n o n - 0 , compressed mode
012C end
321
Soul of CP/M®
As an example, let’s take the Epson MX-80. If you send it a control-o (OF
hex), it will start printing in compressed mode. If you send it a control-r (12
hex) it will go back to the normal mode. However, our word-processing pro
gram lets us use only a few control characters for user-defined functions and
neither control-o or control-r are among them. However, control-w is. We’d
like to set things up so that when the driver sees one control-w, it sends a
control-o to turn on the compressed mode, and when it sees the second con
trol-w, it turns off the compressed mode with a control-r.
Listing 9-7 is a new driver program that will do exactly that.
As shown here, it’s ORGed at 100, ready to be checked out by DDT. Once
you know it works, it can then be assembled into BIOS and merged into
CPM64.COM with DDT, as previously described.
THE SKY’S THE LIMIT

There are, of course, dozens of things you can do along these lines once
you know how to get in and modify your BIOS. The only limit is your imagi
nation. Have fun!
322
APPENDIX A
Hexadecimal N otation
WHY USE HEXADECIMAL NOTATION?

Why don’t computers ju st use decimal notation like everyone else?
W ouldn’t that be a lot simpler for everyone involved? Yes, it would be sim
pler for humans, no question about it. We’re used to counting by tens. How
ever, it would be much more difficult for the computer. Computers, as every
one knows, are full of transistors, and transistors are really just very small
switches that can be turned on and off by other transistors. And these switch
es, like the light switches on your wall at home, have only two positions: on
and off. N o one has yet figured out how to make a transistor that has ten
positions (at least one that will work reliably in a computer). So humans must
think of a digit as having ten possible values (from 0 to 9), while computers
think in terms of a binary digit that has only two possible values: either 0 or
1. This binary digit (binary means “two”) is called a “bit.”
BINARY NOTATION
When a computer counts, it starts with 0, like everyone else. It then goes to
one. So far, we can identify with that. But what happens next? The poor thing
has run out of all possible values for this digit! There are only 0 and 1! So it
does just what we do in the decimal system when we run out of digits. It adds
a new column to the left of the one’s column, which gives it 10.
Of course, this 10 isn’t 10 decimal but 10 binary, which is the same as 2
decimal. The column next to the one’s column isn’t the ten’s column, as it is
in decimal notation, it’s the two’s column. (The third column over is the
323
Soul of CP/M®
four’s column, the fourth column is the eight’s column, and so on.) Thus, 11
binary is the same as 3 decimal, and 100 binary is the same as 4 decimal.
Here is a list of the first 16 binary numbers:
Binary Decimal Binary Decimal

0 0 1000 8
1 1 1001 9
10 2 1010 10
11 3 1011 11
100 4 1100 12
101 5 1101 13
110 6 1110 14
111 7 1111 15
So four columns in the binary system lets us count from 0 to 15 (decimal).

A piece of information that is 4 bits long is sometimes called a “nybble” and
a piece of information that is 8 bits long is called a “byte.” Since there are 16
possible numbers (counting 0) in a nybble, there are 16 times 16, or 256,
possible numbers in a byte. For instance, the binary number 11111111 is 255
324
Hexadecimal Notation
decimal, the binary number 1000000 is 128 decimal, and the binary number
10000 is 16 decimal. (See the list of binary to decimal equivalents given later
in this appendix.)
DECIMAL NOTATION
All right, now we know something about binary notation and why com
puters like to use it. But, what does binary have to do with hexadecimal? The
problem is that while computers are happy thinking in binary, the binary
system turns out to be very difficult for humans to read. For example, here’s
the decimal number 48458 expressed in binary: 1011110101001010. Who can
handle this long a string of ones and zeros? How would you like to do arith
metic on such a number, or try to remember it, or write it down accurately?
N ot so easy. Well then, why not just translate each binary number into its
decimal equivalent, and talk about that? The computer can then think in
binary and convert to decimal when it wants to communicate with humans.
Good idea, and one that’s used very often in the computer business. Most
applications programs communicate with the user in decimal notation, and
even whole languages, like BASIC and FORTRAN, are made to speak in
decimal to the user.
However, when we really want to talk about what is going on in the com
puter on a detailed level (as we often do when we write assembly language
programs), the decimal system has certain glaring disadvantages. For one
thing, the decimal number doesn’t tell us anything about how the bits look in
the binary number and, in many programming applications, we need to deal
with patterns of bits. It’s not instantly obvious, for example, that 240 decimal
is 11110000 in binary. Another related problem is that the number of digits
used for a particular binary number has no easy relationship to the number
of digits used in a decimal number. Thus, 1001 and 1010 both have four
digits, but 1001 is 9 decimal (which has one digit), and 1010 is 10 decimal
(which has two digits). This is awkward for printouts and for visualizing
what’s going on.
HEXADECIMAL NOTATION
Fortunately, in the dim and distant past of computer development, some
one came up with a compromise between binary (which is easy for the com
puter to read) and decimal (which is easy for the hum an to read). This com-
325
Soul of CP/M®
promise is called “hexadecimal” notation (or “hex” for short). Where binary
is a number system based on two, and decimal is based on ten, hexadecimal
is based on sixteen. Hexadecimal works by grouping together 4 bits (a nyb
ble) and assigning a symbol to each value that those 4 bits can represent.
Since 4 bits can have any of 16 possible values, we need 16 symbols. It seems
natural to assign 0 (hexadecimal) to the value 0 (decimal), and to assign 1
(hex) to 1 (decimal), and so on, up to 9. But what happens then? We’ve run
out of decimal digits, and we still have six more values to represent. We need
more symbols and they shouldn’t be too obscure, or it will be hard to find
hardware to print them out. Why not use letters of the alphabet? “A”
through “F ” will handle it nicely. This is illustrated in Table A -l.
Table A -l. Binary, Decimal, and H ex Equivalents
Binary Decimal Hexadecimal

0 0 0
1 1 1
10 2 2
11 3 3
100 4 4
101 5 5
110 6 6
111 7 7 .
1000 8 8
1001 9 9
1010 10 A
1011 11 B
1100 12 C
1101 13 D
1110 14 E
1111 15 F
Now every possible value of a nybble (4 bits) has a unique symbol. Also,
every possible value of a byte (8 bits) can be represented by two of these sym
bols: FF (hex), for example, represents 11111111 binary, or 255 decimal. Also
44 (hex) represents 10001000 binary, or 68 decimal, and so on. Remember the
number 11110000 that we referred to above and which is 240 decimal? It’s
represented by F0 in hex, where the F represents the 1111, and the 0 represents
the 0000. Notice how easy it is to recognize the bit-pattern 11110000 when you
look at “F0.” The hex number lets you “see” the binary number, whereas, the
decimal number doesn’t. Each byte can be uniquely specified by two hex
adecimal symbols, and each symbol represents exactly 4 bits.
326
Learning to Think in H ex
Now we have a whole new numbering system: hexadecimal, or base 16.

How hard is it to learn to get around in hex? If it were necessary to learn, for
instance, how to multiply two 4-digit hex numbers together using pencil and
paper, then it might take a long time to become proficient in hex. Fortu
nately, we don’t have to learn that much about the hex system to deal with
computers. If you need to do arithmetic on hex numbers, it is usually a sim
ple addition or subtraction. You can either do this in your head (after a little
practice), or you can convert the hex numbers to decimal, do the arithmetic
on the decimal equivalents, and then convert the answer back to hex. We’ll
show how these conversions are done in the next section.
Hexadecimal Arithmetic
Let’s try a little arithmetic in hexadecimal just to see what it’s like. For
simplicity at this point, we’ll adopt the convention used in many assemblers
and other programs; an “h” immediately following a number means it’s a hex
number and a “d” immediately following a number means it’s a decimal
number. Thus, 22h is 22 hex, which is 34 decimal, while 22d is 22 decimal,
which is 16 hex.
W hat’s 2h plus 2h? Since both these numbers are the same as their decimal
equivalents and the answer is also the same as its hex equivalent, there’s no
problem. The answer is 4h. Similarly, 4h plus 3h is 7h. W hat about 5h plus
5h? Let’s count on our fingers. While we count out loud, “six, seven, eight,
nine,” we put up one, two, three, and four fingers. Now what? We don’t
count “ten.” Because we’re in hexadecimal, the next digit after nine is “A.”
So, as we put up the fifth finger, we count “A,” and that’s the answer.
What about Ah plus 4h? Let’s count on our fingers again. Starting with
“A,” we’ll count until we have four fingers in the air: “ B, C, D, E.” E is the
answer. To add 7h to Bh, we’d start at “ B” and count until we had seven
fingers in the air: “C, D, E, F, 10, 11, 12.” So the answer is 12h. (Notice how
“F ” in hex is similar to 9 in decimal, in that the next number after it is 10.)
Let’s try adding some 2-digit hex numbers. We’ll write them down in col
umns just as we do when doing arithmetic in decimal notation.
4 B h
+ 1 9 h
6 4 h
327
Soul of CP/M®
Starting with B, we can count 9 more: “C, D, E, F, 10, 11, 12, 13, 14.” So,
Bh plus 9h is 14h. We write down the 4 and carry the 1 to the next column
(the sixteen’s column), where we add 4h and lh and, then, the lh we carried,
giving us 6h. Thus, the answer is 64h.
What about larger hex numbers? Try this:
B C 9 0 h
+ 2 A 2 h
B F 3 2 h
The addition of 2h and Oh is 2h (in the one’s column). Then, 9h and Ah is

13h (in the sixteen’s column), so we write down the 3 and carry 1 to the next
column (the 256’s column). Here, we add Ch and 2h and the 1 we carried,
giving us Fh (with nothing to carry). Bh and nothing is Bh, so that’s the
answer: BF32h.
Subtraction is easy too:
C F 3 4 h
- A 1 6 h
C 5 1 E h
We start by trying to take 6h from 4h, but we can’t, since it’s smaller, so,
just as in decimal subtraction, we borrow one from the next column over.
(This is the sixteen’s column, so we’re really borrowing 16d, which is lOh.)
We add the lOh to the 4h, giving 14h, and 14h less 6h is Eh, as you can prove
by counting backwards on six fingers: “ 13, 12, 11, 10, F, E.” Since we bor
rowed 1 from it, the 3 at the top of the sixteen’s column has been reduced to
2, so when we take 1 from it again, only 1 is left. In the 256’s column, we take
Ah away from Fh, which leaves 5h (counting on five fingers: “ E, D, C, B,
A ”). And, finally, in the 4096’s column, nothing taken away from Ch leaves
Ch. And that’s our answer: C51Eh.
T hat’s not so bad, is it? It took you years to learn decimal arithmetic, and
here you are, learning a whole new numbering system in ju st a few minutes!
Hexadecimal Bit Patterns
Another thing that it is useful to do in hex is being able to recognize the bit
patterns of the sixteen hex digits. A good approach to this is to copy down
328
Table A-l on a filing card and tape it up near your computer. If you do a lot
of assembly language programming, you will find that you will refer to it so
much that eventually the bit patterns will become second nature.
The most useful bit patterns to recognize are 0000 binary which, of course,
is Oh, and 1111 binary, which is Fh. Often, a routine will set all the bits in a
section of the computer’s memory to 1 and, then, if you look into memory
with D D T or a similar program, you’ll find it filled with F ’s. Another useful
bit pattern is 7Fh, which is all the bits in a byte being set except the leftmost
one (01111111). This can be used to “mask off” an extraneous upper bit to
obtain the ASCII code for a character. The ASCII character codes for letters
run from 41h to 7Ah, so if you see memory filled with these values, you know
you’re looking at text.
CONVERTING HEX TO DECIMAL
Finding the decimal equivalent of a hex number is mostly a m atter of

remembering that the digit in each column of a hex number is sixteen times
larger than the same digit would be in the column to the right. (Just as in a
decimal number, each digit is ten times bigger than the same digit in the
column to the right.)
Let’s find the decimal equivalent of BF3Ch. (For clarity, we’ll show deci
mal numbers without the “d”.) The one’s column is easy. Just look up the
value of Ch on your little card (Table A -l). Ch is 12, so write that down.
Now, take the 3 in the sixteen’s column and multiply it by 16: that’s 48. In
the 256’s column, we first need to convert the Fh to 15, and then we can
multiply it by 256 to arrive at 3840, which we also write down. Finally, in the
4096’s column, we convert Bh to 11, which we multiply by 4096, obtaining
45056. Now we can add 12, 48, 3840, and 45056. This gives us 48956, and
that’s the answer. The following entry shows how this looks.
BF 3C
Ch = 12, 12 * 1 12
3h = 3, 3 * 16 = 48
Fh = 15, 15 * 256 = 3840
Bh = 11, 11 * 4096 = 45056
48956
329
Soul of CP/M®
CONVERTING DECIMAL TO HEX

It’s not quite so easy to extract a hex number from a decimal number since,
instead of multiplication, we must now use division. The idea is this. To con
vert a 4-digit hex number to decimal, we first see how many 4096’s there are
in it. Then, we convert that number to hex and write it down; it’s the digit in
the 4096 column. Then, we work with the remainder of this division. We see
how many 256’s there are in the remainder, convert this number to hex, and
write it down in the 256’s column. The remainder of this division we then
divide by 16, obtaining a value which we convert to hex and write down in
the sixteen’s column. The remainder of this division is the number of one’s,
which we convert to hex and write down in the one’s column. Let’s try it with
a number that may look strangely familiar (it’s the result of the previous
section’s conversion): 48956.
First, we find that 4096 goes into 48956 exactly 11 times, with a remainder
of 3900. Decimal 11 is Bh, so we write down B in the 4096’s column. We
divide the remainder of 3900 by 256 (the next column), which gives 15 with a
remainder of 60. Decimal 15 is Fh, so we write down F in the 256’s column.
Next, we divide 60 by 16, which gives us 3 with a remainder of 12. We know
that 3d is 3h, so we write down 3 in the sixteen’s column. And, finally, we
convert 12 (the remainder) to Ch, and write that down in the one’s column.
And, amazing as it may seem, we get what we started with in the last section:
BF3Ch. Let’s illustrate this.
48956 / 4096 = 1 1 , l i d = Bh
remainder = 3900.
3900 / 256 = 15, 15d = Fh
remainder = 60.
60 / 16 = 3, 3d = 3h
remainder = 12.
12 / 1 = 12, 12d = Ch
no remainder.
As with most things, it takes practice to become comfortable with hex

adecimal. Practice doing some conversions and some arithmetic and, before
long, you’ll be able to work with hex almost as well as your computer!
330
APPENDIX B
U tility Programs
In this appendix, we’ve collected several programs that may prove to be
useful or amusing, but which did not fit into the rest of the book.
HEXDUMP
This program will dum p—that is, print out the contents in hex numbers—
any 128-byte section of memory. It is very similar to the “d” command of
DDT, except that it doesn’t print the ASCII representations of each byte
alongside the hex. This would be easy to add to the program, however, if you
want it.
This program is useful for looking at parts of memory when you don’t
want to use DDT. For example, D D T modifies the page zero addresses when
it’s loaded, so if you want to see what they are in their normal state,
HEXDUM P is just what you want.
Listing B-1. The HEXDUMP Program

• ‘
kickie'k'k'k-k'k'k'k'k'k'k'k'kie'k'k'k'k'kieieieie'k'k-kic'k'k'k'k'k'k'k'kif'kicie'kie'k'k'k'k'k
;HEXDUMP-Program t o dump 128 b y t e s o f memory.

; R e q u i r e s s t a r t i n g a d d r e ss i n hex.
0002 = c onout equ 2h ;console out

0001 = coni n equ 1h ;console in
/
0100 org 10Oh
331
Soul of CP/M®
; g e t a dd re ss f rom u s e r and i n i t i a l i z e c o u n t s
0100 CD7101 c a ll hexibin ; g e t a dd re ss i n hex
0103 7D mov a ,I ;mask o f f r i g h t - h a n d d i g i t
0104 E6F0 ani Of Oh
0106 6F mov 1/3
0107 0E08 mvi c,8 ; s e t number o f l i n e s
0109 CD2E01 c a ll p c rlf ; p r i n t line fee d
; p r i n t a d d r e ss and s t a r t new l i n e
010C 0610 n uline mvi b, 16 d ; s e t n br o f b y t e s p e r l i n e
010E CD2E01 c a ll p c rlf ; p r i n t linefeed
0111 CD3F01 c a l l phex ; p r i n t a dd re ss
0114 CD3901 c a l l pspac ; p r i n t two spaces
0117 CD3901 c a l l pspac
; p r i n t t he b y t e s f o r t h i s I i n e
011A 56 n u b y t e mov d,m ; g e t byte in t o d
011B CD4801 c a l l pbyte ;p rin t it
0 1 1E CD3901 c a l l pspac ; p r i n t space
0121 23 i nx h ;increm ent hi
0122 05 dcr b ; do ne w i t h t h i s l i n e ?
0123 C21A01 jnz n u b yt e ; not ye t
; do ne t h i s l i n e
0126 0D dcr c ; do ne a 11 I i nes?
0127 C20C01 jnz nuline ; not yet
012A CD2E01 c a l l per I f ; y e s - p r in t lin e fee d
012D C9 ret ; b a c k t o CP/M
; s u b r o u t i n e t o p r i n t a r e t u r n and l i n e f e e d
012E 3E0D p c rlf mvi a,0dh ; p r i n t carriage return
0130 CD6401 c a l l p cha r
0133 3E0A mvi a,0ah ; p r i n t linefeed
0135 CD6401 c a l l p cha r
0138 C9 ret
/ s u b r o u t i n e t o p r i n t a space
0139 3E20 pspac mvi a,20h ; p r i n t space
013B CD6401 c a l l p char
013E C9 ret
332
Utility Programs
; p h e x - r o u t i n e t o p r i n t b i n a r y number i n h i
; o u t on s c re e n i n hex
F
013F 54 phex mov d ,h ; p r i n t 2 d i g i t s f rom H
0140 CD4801 c a l l pbyte
0143 55 mov d , l ; p r i n t 2 d i g i t s f rom L
0144 CD4801 ca 11 p b y t e
0147 C9 ret
w
; subrou t i n e t o p r i n t 2 - d i g i t hex number ( i n d)
0148 7A pbyte mov a , d ; p r in t left-hand d ig it
0149 CD5101 ca 11 p r i n t l
014C 7A mov a , d ; p r i n t right-hand d i g i 1
014D CD5501 ca 11 p r i n t 2
0150 C9 ret
f
; subrou t i ne t o p r i n t one hex d i g i t ( i n a)
0151 07070707 p r i nt1 r I c ! r I c ! rl c ! rIc ! ;move hi 4 b i t s
0155 E60F p r i nt2 ani Of h ; g e t r i d of high 4 b i t s
0157 C630 adi 30h ; ch an ge hex t o ASCII
0159 FE3A cp i 3ah ; i f i t ' s more t han 9
0 15B DA6001 jc pdig ; ( i t ' s not)
015E C607 adi 7h ; add b i a s (A=10, e t c . )
0160 CD6401 pdig ca 11 p c ha r ;p rin t d ig it
0163 C9 ret
;s u b ro u tin e to p r i n t character in a - r e g is t e r
0164 E5C5D5 p c ha r push h! push b! push d! ;save r e g i s t e r s
0167 0E02 mvi c,conout ; p r i n t character
0169 5F mov e , a
016A CD0500 c a l l bdos
016D D1C1E1 pop d! pop b! pop h! ; g e t r e g i s t e r back
0170 C9 ret
*************************************************
h e x i b i n - r e a d s hex number f rom k e y b o a r d ,
stores r e s u lt in b in a ry in hi
0171 210000 hexibin Ix i h,0 ; c l e a r hi

0174 E5 newch push h ; s a v e hI
333
Soul of CP/M®
017A E1 pop h ; r e s t o r e hi
017B D630 su i 30h ;ASCII d i g i t to b in a r y
017D F8 rm ; return i f <0
017E FEOA cp i 10d ;is i t > 9 ?
0180 FA8B01 jm a dd to ; n o , so i t ' s 0 t o 9
; n o t d i g i t , maybe i t ' s L e t t e r (a t o f )
0183 D627 sui 27h ; c o n v e r t ASCII t o b i n a r y
0185 FEOA cpi Oah ; i s i t < a (hex)
0187 F8 rm ; yes, return
0188 FE10 cp i 10h ; i s i t > f (h ex)
018A F0 rp ; yes, re tu rn
; r o t a t e HL 4 b i t s L e f t and add d i g i t t o l e f t s i d e
018B 57 a dd t o mov d ,a ; s a v e new hex d i g i t i n d
018C 0E04 mvi c,4 ; s e t C to count 4 b i t s
018E 7D s h ift mov a , I ;shi f t I
018F 17 ra I
0190 6F mov I , a
0191 7C mov a ,h ;s h ift h
0192 17 ra L
0193 67 mov h,a
0194 0D dcr c ;do ne 4 b i t s y e t ?
0195 C28E01 jnz s h ift ; not yet
0198 7D mov a , L ;mask o f f Lo 4 b i t s o f L
0199 E6F0 ani OfOh
019B B2 ora d ; " o r " new d i g i t o n t o L
019C 6F mov I,a
019D C37401 jmp newch ;go get next c h a r a c te r
01A0 end
MICRO SPACE INVADERS

This program (Listing B-2) is ju st about the smallest possible space game
that you can have on a C P /M system.
You’re in charge of a battery of four phasers, each of which is aimed at a
different quadrant of the galaxy. Your mission is to shoot down the invading
Klipson battle cruisers. They may appear in any of the four sectors and you
must respond by firing the phaser in the appropriate sector. However, you
don’t have much time as the Klipsons will be approaching at warp-factor 11.
Keep your fingers poised over the number keys 1, 2, 3, and 4. When the
Klipson appears (symbolized on your screen by an evil-looking asterisk),
334
Utility Programs
press the key corresponding to the sector that he’s appeared in. If you get the
wrong sector, you lose a point. And, if you’re not fast enough and he gets
through and destroys the earth, you also lose a point. It is only when you’re
fast and accurate that you gain a point.
Listing B-2. Game Program

■ ****************************************************
;MICR0 SPACE INVADERS
/
; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0005 = bdos equ 5h

0001 = coni n equ 1h
0002 = conout equ 2h
0009 = pri n tf equ 9h
000B = chkcon equ Obh
0020 = space equ 20h
002A = aster equ 2ah
OOOA = If equ Oah
000D = cr equ Odh
F800 = time equ 0f800h
0003 = mask equ 3h
W
0100 org 100h
r
; p r i n t header
i
0100 0E09 start mvi c ,p rin tf
0102 118301 Ixi d,header
r
; g e t random number, use i t t o p r i n t spaces
r
0108 3A8101 Ida random ; g e t random number
010B 07 r Lc ; s h i f t Left twice
010C 07 r Ic ; t o m u L t i p L y by 4
010D 47 mov b,a ; p u t i n b as c o u n t e r
010E 04 i nr b ; add 1 t o e ns ur e i t ' s n o t 0
010F C5 newsp push b ;save i t
0110 0E02 mvi c , c o n o u t ; p r i n t space
0112 1E20 mvi e,space
335
Soul of CP/M®
0114 CD0500 ca 11 bdos

0117 C1 pop b ; g e t i t back
0118 05 dcr b ; i s c o un t 0 y e t ?
0119 C20F01 jnz newsp ; n o , so p r i n t a n o t h e r space
/
; p r i n t a s t e r i sk
/
011C 0E02 mvi c,conout
01 IE 1E2A mvi e ,aster
i
; r u n t i m e r w h i l e c h e c k i n g keyboard
f
0123 0100F8 Ixi b,tim e ; s e t t i me i n be
0126 C5 loop push b ; s a v e be
0127 0E0B mvi c,chkcon ; c h e c k ke yboard f o r ch ar
0129 CD0500 ca 11 bdos
012C B7 ora a ; a n y t h in g yet?
01 2D C23F01 jn z q u i ck ; y e s , c h a r a c t e r t y pe d
0130 C1 pop b ; n o , g e t be back
f
0131 0C in r c ; increment c
0132 C22601 jnz l oop ; l oop i f n o t 0 y e t
0135 04 in r b ; increment b
0136 C22601 jnz l oop ; lo op i f n o t 0 y e t
f
; t i m e r o u t - n o t q u i c k enough
f
0139 119801 Ixi d,messnq ; s e t up " n o t q u i c k " message
013C C35A01 jmp p rin t ;go p r i n t i t
f
; c h a r a c t e r h i t b e f o r e t i m e o u t - q u i c k enough
/
013 F C1 q ui ck pop b ; g e t be back
0140 79 mov a,c ;save c f o r l a t e r
0141 328201 sta hold
f
; read c h a r a c t e r
f
0144 0E01 mvi c,conin ;read character
0146 CD0500 ca 11 bdos
0149 0631 mvi b , ’0’+1 ;ASCII 0 p lu s 1
336
Utility Programs
pbOUB 90 sub b ; s u b t r a c t f rom c h ar i n a

014C 47 mov b ,a ;save in b
F
; s e e i f c h a r a c t e r t y pe d matches random number

F
014D 3A8101 Ida random ;random number i n a

0150 B8 cmp b ;compare w i t h c h a r a c t e r
0151 11AD01 Ixi d,messw ; s e t up " w r o n g " message
0154 C25A01 jnz p rin t ; g o p r i n t i f n o t match
0157 11BE01 Ixi d ,m es sr ; m a t c h - u s e " r i g h t " message
F
015A 0E09 p rin t mvi c,pri n tf ; p r i n t message

015C CD0500 ca ll bdos
F
;make up new random number

F
015F 3A8201 setran Ida h ol d ; g e t l a s t v a l u e o f count

0162 47 mov b ,a ;save in b
0163 3A8101 Ida random ; g e t l a s t random number
0166 80 add b ; add o l d c oun t
0167 E603 ani mask ;mask o f f upper s i x b i t s
0169 328101 sta random ;save r e s u l t
F
; w a i t f o r u s e r t o s i g n a l ready
F
016C 0E09 mvi c,pri n tf ; a s k i f u s e r ready

016E 11CA01 Ixi d ,mess j
0171 CD0500 ca 11 bdos
0174 0E01 wai t mvi c,conin ; w a i t f o r key p r e s s
0176 CD0500 ca 11 bdos
0179 FE20 cp i space ; i s i t t he s p a c e - b a r ?
017B C27401 jnz wai t ;no t yet
F
017E C30001 jmp start ; b e g in again

F
0181 02 random db 2
0182 h ol d ds 1
f
0183 0D0A0A0A20header db c r , I f , I f , l f , ’ 1— 2— 3— 4’, c r , l f , ’$

0198 0D0A0A4E4Fmessnq db c r , I f , I f , ’N0T QUICK ENOUGH.$’
01 AD 0D0A0A5752messw db c r , I f , I f , ’WRONG TARGET.$ ’
337
Soul of CP/M®
01B E 0 D 0 A 0 A 4 1 2 0 m e s s r db c r , I f , Lf,’
A H I T !!!$’
01 CA 0 D 0 A 0 A 5 0 7 2 m e s s j db cr,Lf,Lf,’
Press s p a c e - b a r to start a g a i n .
/
r
HEXIDEC
This program will print out the decimal equivalent to any positive 4-digit hex
number that you type in from the keyboard. It is called directly from CP/M .
Listing B-3. Hex-to-Decimal Conversion Program

• *******************************************************
; h e x i d e c - C o n v e r t s number t y pe d i n hex on keyboard
; i n t o d e c i m a l , and p r i n t s i t o u t on s c r e e n .
000A = Lf equ Oah ; Li nef eed
0100 org 100h

r
0100 CD0C01 cal L hexibin ; g e t hex c h a r a c t e r
0103 3E0A mvi a ,If ; p r i n t Linefeed
0105 CD6C01 ca L L pc ha r
0108 CD3B01 ca L L binidec ; p r i n t d e c i m a l number
010B C9 ret ; t h a t 1s a i l
■* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
; h e x i b i n - r e a d s hex number f rom k e y b o a r d .
r stores r e s u lt in bin ary in hi
F
0001 = coni n equ 1 h
0005 = bdos equ 5h
0030 = ascO equ 30h
000A = dec10 equ 10d
0027 = bia s equ 07h
00F0 = mask equ OfOh
f
010C 210000 h e x i b i n I x i h,0 ;cLear hi
01 OF E5 newch push h ;save hi
338
Utility Programs

0112 CD0500 ca I I bdos
0115 E1 pop h ; r e s t o r e hi
0116 D630 s ui ascO ; c o n v e r t ASCII d i g i t t o b i n a r y
0118 F8 rm ; return i f < 0
0119 FEOA cpi dec10 ; is it > 9 ?
011B FA2601 jm a d d to ; y e s , so i t ' s d i g i t ( 0 t o 9 )
; n o t d i g i t , maybe i t ' s l e t t e r (a t o f )
0 1 1E D627 su i bia s ; c o n v e r t ASCII l e t t e r t o b i n a r y
0120 FEOA cp i Oah ; i s i t l e s s t ha n a ( h e x )
0122 F8 rm ; yes, re tu rn
0123 FE10 cp i 10h ; i s i t g r e a t e r t ha n f ?
0125 FO rp ; yes, re tu rn
; r o t a t e h i r e g i s t e r f o u r b i t s L e f t and
; add new d i g i t t o r i g h t : -hand s i d e
0126 57 addt o mov d , a ; s a v e new hex d i g i t i n d
0127 0E04 mvi c,4 ; s e t up lo op t o c o u n t 4 b i t s
0129 7D shi f t mov a , L ;s h ift I
012A 17 ra I
012B 6F mov l , a
012C 7C mov a , h ;shi f t h
012D 17 ral
012E 67 mov h , a
0 12 F OD dcr c ; a r e we done y e t ?
0130 C22901 jn z s h ift ; not yet
0133 7D mov a ,L ;mask o f f l o w e r 4 b i t s o f I
0134 E6F0 ani mask
0136 B2 ora d ; " o r " t he new d i g i t on t o I
0137 6F mov l , a
0138 C30F01 jmp newch ; g o back f o r n e x t c h a r a c t e r
W
; b i n i d e c - c o n v e r t s b i n a r y number i n hL t o
¥ deci m a l , p r i n t s r e s u l t on s cr ee n
W
0002 = conout equ 2 ;console output
0005 = bdos equ 5 ;BD0S e n t r y p o i n t
F
013B 11F0D8 b i n i dec Lxi d , - 10000 ; p r i n t number o f 10, 000s
013E CD5A01 ca L L s u b c n t
0141 1118FC Lxi d , - 1 000 ; p r i n t number o f t housands
0144 CD5A01 ca L L s u b c n t
335
Soul of CP/M®
0147 119CFF Lxi d,-100 ; p r i n t number o f hundreds

014A CD5A01 ca L L subcnt
014D 11F6FF Lxi d,-10 ; p r i n t number o f t e ns
0150 CD5A01 ca L L subcnt
0153 11FFFF Lxi d,-1 ; p r i n t number o f ones
0156 CD5A01 ca L L subcnt
0159 C9 ret ; t h a t 1s a l L
f
015A 0E2F subcnt mvi c , ’0 ’-1 ; c h o l d s ASCII v e r s i o n o f c oun t
015C 0C sub2 in r c ; i n c r e m e n t c o un t
015D 227901 sh Ld temp ; save hI
0160 19 dad d ; ad d neg c o n s t f rom de t o h i
0161 DA5C01 jc sub2 ; l o o p u n t i L r e s u l t i n h i goes neg
0164 2A7901 Lh Ld temp ; g e t Last p o s i t i v e v a l u e back i n
0167 79 mov a , c
0168 CD6C01 ca L L p cha r ;p rin t d ig it
016B C9 ret
; p r i n t c h a r a c t e r i n a-- r e g i s t e r on s cr ee n
016C D5C5E5 p char push d ! push b ! push h ! ;save r e g is t e r s
016F 5F mov e ,a ;c h a ra c te r in e
0170 0E02 mvi c,conout
0172 CD0500 ca L L bdos ; c a l l c o no ut r o u t i n e
0175 E1C1D1 pop h ! pop b ! pop d ! ; g e t r e g i s t e r s back
0178 C9 ret
/
0179 0100 temp du 1
f
017B end
FILEDUMP
This program (Listing B-4) takes any file and prints out the contents in a
hex format similar to the “d” function of D D T (except that ASCII
equivalents aren’t printed out). Each 128-byte record is shown separately.
Scrolling can be stopped and started with control-s.
This is a useful program for investigating how the records of a particular
file are actually stored on the disk. It is a more convenient version of the
technique that is shown in Chapter 5 for examining the contents of files in
hex, where each record had to be read in separately and examined using
DDT.
340
Utility Programs
Listing B-4. Program for Outputting a File in Hex

• **********************************************************
; FILEDUMP-Program t o dump a f i Le t o t h e s c r e e n o r p r i n t e r
; i n hex f o r m a t .
• **********************************************************
bdos equ 5h ; o p e r a t i n g system

c onout equ 2h ;console output
f cb equ 5ch ; f i le c o n t r o l block
dma equ 80h ; record b u f f e r
o penf equ Of h ; op en f i l e
readr equ 14h ;re a d record
p rin ts equ 9h ;p r in t strin g
f
org 10Oh
; s e t up l o c a l s t a c k
lxi h,0 ;save old stack p o in te r
dad sp
shld old sp
lxi s p , s t k t o p ; lo ad new s t a c k p o i n t e r
r
; op en f i l e , read r e c o r d s
mvi c,openf ; op en f i l e
lx i d , f cb
c a l l bdos
in r a ; ad d 1 t o A - r e g i s t e r . I f i t was f f .
jz n o f i l e ; now i t ' s 0 0 , so no such f i l e
'C c a l l p c r l f ; p r i n t return & linefeed

mvi c , p r i nts ; p r i n t header
lx i d,hmess
c a l l bdos
mvi c,readr ;re a d record

lx i d , f cb
ca 11 bdos
ora a ; c h e c k A - r e g i s t e r t o see i f EOF
jn z done ; non -0 i s EOF
; p r i n t o u t c o n t e n t s o f DMA i n hex f o r m a t
c a ll pbuff
jmp newrec
341
Soul of CP/M®
; e n d - o f - f i Le, o r no f i Le, so p r i n t message and r e t u r n t o CP/M

n o f i l e Lxi d , n f m e s s ; p r i n t " no f i l e " message
mvi c,p rin ts
c a l l bdos
done Lhl d o l d s p ; r e s t o r e old stack p o in te r
sph L
ret ; r e t u r n t o CP/M
■ 'k'k'k'k'k'k'k'k'k'kieie'k'k'k'kick'k'icicie'k'k'k'k'kic'kieierk'k'k'k'kie'k-k'k'k'k'ic'kickick'k'k'k'k'k'kic'k'kie
;pb u ff-subroutine to p r i n t c o n t e n t s o f DMA i n hex

r
; s e t a dd r es s and i n i t i a l i z e c o u n t s
p bu f f Lxi h,dma ; p u t add r o f r e c o r d i n HL-reg
mvi c,8 ; s e t number o f Li nes
ca ll p c rlf ; p r i n t Linefeed
; p r i n t a dd r es s and s t a r t new l i n e
nu I i ne mvi b ,1 6d ; s e t number o f b y t e s p er l i n e
c a l l p er Lf ; p r i n t Linefeed
; p r i n t t he 1b y t e s f o r t h i s l i n e
n u b y te mov d,m ; g e t b y t e p o i n t e d t o by h i i n t o
ca IL p b y t e ;p rin t i t
ca IL pspac ; p r i n t space
i nx h ;increm ent hi
dcr b ; do ne a l l b y t e s on t h i s l i n e ?
jn z nubyte ; not ye t
/
; done t h i s I i ne
dcr c ; do ne a l l l i n e s ?
jnz nu Li ne ; not yet
c a ll p c rlf ;yes - p r i n t r e t u r n & lin e f e e d
ret ; b a c k t o main program
f
; s u b r o u t i ne t o p r i n t a c a r r i a g e r e t u r n and l i n e f e e d
p er Lf mvi a,0dh ; p r i n t carriage return
ca IL pchar
mvi a,0ah ; p r i n t lin e fee d
ca 11 pc ha r
ret
f
; s u b r o u t i ne t o p r i n t a space
pspac mvi a,20h ; p r i n t space
ca IL pchar
ret
342
Utility Programs
**********************************************************
phex - r o u t i n e t o p r i n t b i n a r y number i n h i
o u t on s c r ee n i n hex
phex mov d ,h /p rin t two d i g i t s f rom h

ca L L pbyte
mov d,L /p rin t two d i g i t s f rom L
ca L L pbyte
ret
r
/ s u b r o u t i n e t o p r i n t 2 - d i g i t hex number ( i n d)
pbyte mov a , d / p r i n t Left-hand d i g i t
ca L L p r i n t l
mov a , d / p r i n t right-hand d i g i t
ca L L p r i n t 2
ret
/ s u b r o u t i n e t o p r i n t one hex d i g i t ( i n a)
p r i n t l r L c ! r L c ! rLc ! rLc /move h i g h 4 b i t s t o Low
p r i n t 2 ani Of h / g e t r i d of high 4 b i t s
adi 30h / c h an ge hex t o ASCII
c pi 3ah / i f i t ' s more t han 9
jc pdig / ( i t ' s n ot)
adi 7h / t h e n add b i a s (A=10, e t c . ]
pdig caL L p cha r /p rin t d ig it
ret
/
/ s u b r o u t in e to p r i n t c h a r a c te r in a - r e g i s t e r out
p cha r push h! push 1 b! push d /save r e g i s t e r s
mvi c,conout / p r i n t character
mov e ,a
ca L L bdos
pop d! pop b! pop h / g e t r e g i s t e r s back
ret
r
nfmess db ’No such f i Lename.$’
hmess db ’0 1 2 3 4 5 6 7 8 9 A B C D E F$’
oLdsp ds 2
ds 32
stktop:
/
end
343
APPENDIX C
Summary of 8 0 8 0
Instructions
This appendix summarizes the architecture of the 8080 and the 8080
instruction set. Most of the instructions are explained in detail in the main
part of the book. If you don’t have any assembly language programming
experience, don’t read this appendix until you’ve read the first part of this
book. This will avoid the possibility of your being blown away by seeing so
many instructions all at once.
8080 ARCHITECTURE
The diagram shown in Fig. C -l illustrates the principal 8080 registers.
Registers
Registers B and C can be accessed either as separate 8-bit registers, or

together as a single 16-bit register called the BC-register. Similarly, the D-
and E-registers can be combined into the 16-bit DE-register, and the H- and
L-registers can be combined into the 16-bit HL-register.
The 8-bit A-register (sometimes called the “Accumulator”) is the principal
arithmetic register on the 8080 microprocessor. The term “arithmetic” used
in this section includes the Boolean (logical) operations of “ A N D , ” “OR,” and
“Exclusive-OR.” The A-register is almost always used alone as an 8-bit regis
ter, but it can be combined with the Program Status Word (PSW) to form a
16-bit entity that can be stored on the stack.
345
Soul of CP/M®
■16 bits
8 bits 8 bits -
PSW
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 -* ------------- Bit numbers

(8-bit registers).
1 1 1 1 1 1 9 8 7 6 5 4 3 2 1 0 ------------- Bit numbers

5 4 3 2 1 0 (16-bit registers).
Fig. C-1. R egisters o f the 8080 m icroprocessor.
The 16-bit HL-register is often used as a pointer to a particular address in

memory. When this is done, the 8-bit data in the address pointed to by HL
can be called “M” (for “memory”) in some 8080 instructions. In this case,
“ M” is referred to as if it were another register. For example,
mov c,m
means, move the contents of the memory location pointed to by the HL-
register into the C-register. There is no “M ” register—it is simply the memory
location pointed to by HL.
The BC- and DE-registers can be used for temporary storage and for a few
arithmetic operations on 16-bit numbers. They can also be used as pointers
to memory, using the LDAX and STAX instructions, although this is not
quite as easy as using the HL-register.
All of the 8-bit registers (A, B, C, D, E, H, and L) can be used for tempo
rary storage of 8-bit data.
346
Summary of 8080 Instructions
The Stack Pointer (SP) holds the 16-bit address that is the current top of
the stack. If you PUSH something onto the stack, it will be placed in memory
at the address in the SP, and if you CALL a subroutine, the address to which
you will RETurn is placed in memory at this address. When something is
placed on the stack (by a PUSH or a CALL) the SP is automatically decre
mented two locations (since two bytes hold a 16-bit address), and when some
thing is taken off the stack (by a POP or a RET), the SP is incremented. This
is the opposite of what you might expect because the stack grows downward
in memory.
In addition to the registers shown in Fig. C -l, there is also a 16-bit Pro
gram Counter (PC) (which holds the address of the instruction currently
being executed) and an 8-bit Instruction register (I) (which holds the instruc
tion being executed). These registers are seldom accessed in normal 8080 pro
gramming.
Program Status Word
The Program Status Word contains the five “flags” used in the 8080
processor. These flags are set, following the completion of some instructions
(mostly 8-bit arithmetic instructions), to indicate the outcome of different
operations. They can have either of two values, 1 or 0. Jumps, calls, and
returns can sample these values automatically to decide what to do. (For
example, JZ will cause a jum p if the zero flag is set, but not if it isn’t.)
The flag bits, and the mnemonic associated with each value, is shown in
Table C-l. The sign flag is used to indicate whether the result of an arithmetic
instruction is plus or minus (positive or negative). The Zero flag indicates
whether the result of an operation is zero or nonzero. The Auxiliary Carry flag
indicates whether there has been a carry from Bit 3 to Bit 4 in an arithmetic
operation. Its primary use is in BCD (binary-coded decimal) arithmetic.
Table C -l. Flags of the PSW

M N EM O M IC
BIT NAM E
FLAG (In PSW ) Bit = 0 B it= 1
Sign S P (plus) M (minus)
Zero z N Z (nonzero) Z (zero)
Auxiliary carry A (N o M nemonics)
Parity P PO (parity odd) PE (parity even)
Carry C N C (no carry) C (carry)
347
Soul of CP/M®
The Parity flag is set to 1 whenever the result of an arithmetic operation

contains an even number of bits, and set to zero when it contains an odd
number of bits. This is useful for running parity checks on data to see if a bit
has been lost. (Neither the parity flag nor the Auxiliary Carry flag is used in
this book.) The Carry flag is used to indicate when the result of an arithmetic
or shift operation results in a bit being carried or shifted out of the A-register.
8080 INSTRUCTIONS
Most summaries of assembly language instructions list them either in

alphabetical order or in order of numerical op codes. Neither of these
approaches is ideal, since when you want to look something up, you usually
don’t know the instruction yet. You start with an idea of what you want to
accomplish in the program and you want to know what instruction will do it
for you. Accordingly, we’ve arranged the instructions in seven functional
groups:
1. 8-bit Transfers.
2. 16-bit Transfers.
3. 8-bit Arithmetic.
4. 16-bit Arithmetic.
5. Jumps, Calls, and Returns.
6. Rotates.
7. Other instructions.
“Transfers” means moving data from one register to another, or between a

register and memory. In a transfer, the data are not altered.
In general, instructions that have an X in them, like LXI, operate on regis
ter pairs and 16-bit values. Also, an I at the end of an instruction stands for
“immediate,” which means that the data referred to in the instruction are
stored immediately next to the instruction in the program, and not someplace
else in memory.
We’ve made no attem pt in this summary to show such niceties as how
many bytes each instruction takes, how long it takes to execute, or exactly
what flags are set. For this, you should consult the 8080 or 8085 reference
manuals available from the Intel Corporation.
Remember: when “M ” and “m ” are referred to in the following descrip
tions, they stand for the memory location contained in the HL-register. Of
348
course, for this to work, you must put the appropriate address in the HL-
register before executing an instruction with an “m” as an operand.
Also remember: numbers used in an ASM listing are assumed to be in deci
mal unless otherwise specified. If a number is meant as a hex number, it must
be followed by an “h,” as in Offh. Also, hex numbers starting with a letter
must be preceded by a zero, or ASM will think they’re a name. For clarity,
it’s probaby best to put a “d” after decimal numbers as well, although this is
optional. Numbers followed by “b” are assumed to be in binary notation, as
in 11110000b.
8-Bit Transfers
MOV R1,R2 Moves data from register R2 to register R l, where R1 and R2

can be any one of the registers A, B, C, D, E, H, L, or M.
Examples:
mov a,b
mov h,d
MVI R,data Puts an 8-bit data byte into R, where R can be any one of the
registers A, B, C, D, E, H, L, and M. (The data are stored in
the byte immediately following the MVI instruction.)
Examples:
mvi d,31
mvi b,const (where “const” is given a numerical value
in an EQU statement)
LDA Addr Puts an 8-bit byte, located in memory address Addr, into the
A-register.
Examples:
Ida 3c00h
Ida const
STA Addr Stores an 8-bit byte from the A-register into memory address
Addr.
Examples:
sta eOlOh
sta temp
LDAX RR Loads the A-register with 8-bit data contained in memory loca
tion that is pointed to by register RR, where RR is either “b”
or “d,” meaning the BC- or DE-register.
349
Soul of CP/M®
Example:
ldax b
STAX RR Stores an 8-bit value from the A-register into memory location
that is pointed to by register RR, where RR is either “b ” or
“d,” meaning the BC- or DE-register.
Example:
stax d
16-Bit Transfers
LHLD Addr Loads the HL-register with a 16-bit value that is stored in
memory addresses A ddr and A ddr + 1.
Example:
lhld pointr
SH LD Addr Stores a 16-bit value from the HL-register into memory loca
tions A ddr and A ddr-f 1.
Example:
shld 0bd80h
LXI RR,data Loads a 16-bit data word into register RR, where R R can be
“b,” “d,” “h,” or “sp,” meaning BC, DE, HL, or SP. The data
are in the two bytes immediately following the instruction.
Examples:
lxi d,0005h
lxi h,ptrl
PU SH RR Puts the 16-bit contents of register RR onto the top of the
stack, where RR can be “b,” “d,” “h,” or “psw,” meaning BC,
DE, HL, or the register-pair formed by the A-register and the
PSW. It decrements the stack pointer twice.
Example:
push h
PO P RR Takes the 16-bit value from the top of stack and puts it in reg
ister R R (where R R is defined as in PUSH). It increments the
stack pointer twice.
Example:
pop b
XTHL Exchanges the two 16-bit values in the HL-register and the top
of the stack.
350
Example:
xthl
SPH L Loads the 16-bit contents of the HL-register into the stack
pointer (SP) register.
Example:
sphl
PCHL Loads the 16-bit contents of the HL-register (usually an ad

dress) into the program counter (PC) register. This has the ef
fect of causing a JM P to that address.
Example:
pchl
XCHG Exchanges the two 16-bit values in the HL-register and the
DE-register.
Example:
xchg
8-Bit Arithmetic
In the instructions that follow, R stands for any of the registers A, B, C, D,

E, H, L, or M (written as “a,” “b,” “c,” “d,” “e,” “h,” “1,” or “m ”).
Examples:
add b
cmp c
In those instructions involving two operands, the first operand is always in

the A-register and the second is in register R. The result is always left in the
A-register. (Register R is unchanged.) Thus, in the first example given above,
the contents of the B-register are added to the contents of the A-register, and
the result is left on the A-register.
Note that all these 8-bit arithmetic instructions set the various flags to the
appropriate values: zero or nonzero, plus or minus, and so on.
ADD R Adds contents of register R to the A-register.

SU B R Subtracts contents of register R from A-register.
INR R Increments the contents of register R.
DCR R Decrements the contents of register R.
351
Soul of CP/M®
CM P R Compares the contents of register R with the contents of the A-

register. (This causes the flags to be set as if a subtraction had
taken place, although the contents of register A are unchanged.)
ANA R Logically ANDs the contents of register R with the contents of the
A-register.
ORA R Logically ORs the contents of register R with the contents of the A-
register.
XRA R Logically Exclusive-ORs the contents of register R with the con
tents of the A-register.
In the instructions that follow, “data” means a numerical or a symbolic

representation of an 8-bit data item.
Examples:
adi Offh
ori mask (where “mask” is defined in an “equ” statement)
ADI data Adds 8-bit data to contents of A-register.

SU I data Subtracts 8-bit data from contents of A-register.
CPI data Compares 8-bit data with contents of A-register.
ANI data Logically ANDs 8-bit data with contents of A-register.
ORI data Logically ORs 8-bit data with contents of A-register.
XRI data Logically Exclusive-ORs 8-bit data with contents of A-register.
16-Bit Arithmetic
In the following instructions, R R stands for registers BC, DE, HL, or SP

(written as “b,” “d,” “h,” or “sp”). N ote that these instructions do not set the
flags!
DAD RR Adds contents of register RR to contents of HL-register.

INX RR Increments register RR.
DCX RR Decrements register RR.
Jumps, Calls, and Returns
JM P Addr Transfers control of the program to memory location Addr,

where A ddr can be either a number or a symbolic label.
Examples:
jm p lOOh
jm p start
352
CALL Addr Transfers control of the program to memory location Addr,

and also puts the return address (the location of the next in
struction following the CALL) on the stack. Decrements the
stack pointer twice.
RET Transfers control of the program to the memory location

pointed to by the contents of the top of the stack. Increments
the stack pointer twice.
The JMP, CALL, and RET instructions all have variants that only execute
when a particular condition is true. Thus,
jz start
will only transfer control of the program to “start” if the results of a previous
arithmetic operation left the zero flag set to 1. If the condition is not met,
control simply passes to the next instruction in line. Rather than list all of
these instructions separately, we’ve arranged them in a table (Table C-2). The
most-used of these instructions are probably JNZ, JZ, JNC, JC, JP, and JM.
Table C-2. Variants olr the JM P, CALL, and iE T Instructions
Instruction executes
if flag set to JU M P CALL RETURN
Nonzero JNZ CNZ RNZ
Zero JZ CZ RZ
N o Carry JNC CNC R NC
Carry JC CC RC
Parity Odd JPO CPO RPO
Parity Even JPE CPE RPE
Plus JP CP RP
Minus JM CM RM
Rotations
All rotations are done on the contents of the A-register. The A-register can
be rotated either right or left, and the bits pushed off the end can either circle
round and appear on the other end of the A-register, or they can go to the
carry bit of the program status word. The diagrams shown in Fig. C-2 illus
trate the various possibilities.
353
Soul of CP/M®
RAL "Rotate Accumulator Left.”
/ 7 6 5 4 3 2 1 0
/l
H 3 Carry
I I A-reg ster
Bit
Example: ral
R AR ‘Rotate Accumulator Right”
7 6 5 4 3 2 1 0
/ yi
ii
i !
i
____ I____
A-register
! I :T>
Carry
Bit
Example: rar
RLC “Rotate Accumulator Left Through Carry"

i------------------------------------
7 6 5 4 3 2 1 0
0 _L .........
Carry A-register
Bit
Example: rlc
R RC “Rotate Accumulator Right Through Carry”
7 6 5 4 3 2 1 0
/ m A
i------- ►
i i i : i i i
W - - G )
A-register Carry
Bit
Example: rrc
Fig. C-2. Rotations.

354
O ther Instructions
The 8080 microprocessor communicates with the outside world by using

only two instructions:
IN Inputs an 8-bit byte of data into the accumulator from the data port
specified in the instruction. The data ports are numbered from 1 to FF
(hex).
Example:
in 23h
OUT Outputs an 8-bit byte of data from the A-register to the data port
specified in the instruction.
Example:
out p tr (where “p tr” is defined elsewhere).
There are several instructions that you can use to alter the bit in the carry
flag:
CMC Complements the carry flag. That is, it changes it to 0 if it was 1, and
vice versa.
Example:
cmc
STC Sets the carry flag to 1, no m atter what it was before.
Example:
stc
You can also complement the A-register; that is, change every bit that’s a 1
to a 0, and vice versa.
CMA Compliments the A-register.

Example:
cma
There are a number of instructions that are designed to operate on BCD

(binary-coded decimal) format numbers. This is a way of using 4 bits to rep
resent the 10 decimal digits and it is popular on mainframe computers that
are used for business. We aren’t going to describe BCD here, so these instruc
tions will go unexplained. The “ auxiliary carry” bit in the program status
word is used with BCD calculations.
355
Soul of CP/M®
DAA Means “ Decimal Adjust Accumulator.”

ADC Means “Add to Accumulator with Carry.”
ACI Means “Add with Carry Immediate to Accumulator.”
SBB Means “Subtract from A-register with Borrow.”
SBI Means “ Subtract Immediate from A-register with Borrow.”
You can halt the operation of the computer and you can also have an
instruction which does nothing.
HLT Halts the computer, which is then paralyzed, unless there’s an inter
rupt. N ot to be used frivolously.
Example:
hit
NOP Means “N o Operation.” It can be used as a “filler” in a program.
Example:
nop
And, finally, there are several instructions connected with the use of the
interrupt system. Since we are not concerned with the use of interrupts in this
book, we won’t attem pt to explain them. However, they are:
DI Means “Disable Interrupts.”

El Means “Enable Interrupts.”
RIM Means “ Read Interrupt Mask.”
SIM Means “ Set Interrupt Mask.”
The instruction RST (which we use when returning from a program we’ve
written in DDT) was designed for use in the interrupt system. However, it
can be executed by any program. There are 8 such instructions: RST 0
through RST 7. They are each the equivalent of a CALL instruction, but they
transfer control only to certain predefined locations in memory.
RST 0 is a CALL to location 0000 hex

356
Since these are one-byte instructions, instead of a three-byte instruction as

CALL is, you might find a use for them if you’re writing a very short or very
fast code. D D T uses them because it uses the interrupt system. Of course,
you have to be very careful, since the addresses are located in C P /M ’s semi-
sacred zero page. You don’t want to overwrite or jum p to an area that C P /M
is using for something important.
RST n Causes a CALL to a location indicated by “n” , as shown in the pre

ceding list.
Example:
rst 3
ASSEMBLER DIRECTIVES
Assembler directives are placed in the instruction field of an ASM listing
as if they were 8080 instructions, but they’re not. They’re instructions to the
ASM program itself. For this reason, they’re sometimes called “pseudo-ops.”
ORG Causes ASM to start assemblying at the memory location given in the
address field.
Example:
org lOOh (causes assembly to start at location 100 hex)
END Causes the assembly to end. Any subsequent statements will not be
processed. If followed by an address, this address will be the starting
address used in HEX files.
Example:
finish end lOOh
EQU Defines a symbolic label as having a specific value. N ote that this di
rective does not set aside any memory to hold the value, it simply
causes ASM to remember what value is associated with a label.
Example:
bdos equ 5h (defines the label bdos to have the value of 5
hex)
Example:
lnfeed equ Oah (defines the label lnfeed to have the value of
0a hex)
357
Soul of CP/M®
DB Means “define bytes.” This directive is used to set a single 8-bit byte
or strings of bytes in memory to a specific value. A number of bytes
can be placed in the same db directive by separating them with com
mas. A string of ASCII characters can be used if it starts and ends with
single quotes (’). Symbolic values (labels) can be used to represent
bytes if they are defined elsewhere.
Examples:
decten db lOd
crlf db Odh, Oah
messl db ’Type your name ’,Odh,Oah
mess2 db ’What?’,cr,lf
DW This directive is similar to DB, except that it defines 16-bit words. A
number of words can be used if they are set off with commas, and
ASCII characters can be used if they are delimited by single quotes.
However, strings must be limited to 2 characters.
Examples:
mask dw OffOOh
data dw 0d4h, 63h, 7dh, 0c9h
crlf dw OdOah
abee dw ’ab’
DS This directive is used to set aside an area of memory for storage of
bytes or groups of bytes. The number given in the address field is the
number of bytes to be set aside. The memory locations thus reserved
are filled with zeros by the assembler.
Examples:
temp ds 2 (sets aside two-byte word)
stemp ds 1 (sets aside 1 byte)
buffer ds 400d (sets aside 400 bytes)
358
APPENDIX D
Tables
This appendix contains the following charts and tables:
1. ASCII character set with hexadecimal equivalents.

2. Hexadecimal-to-Decimal conversion (one-byte values).
3. Multiples of IK (1024), in decimal and hexadecimal.
4. Decimal, Hex, and Binary conversion (4-bit values).
ASCII CHARACTER SET WITH HEXADECIMAL

EQUIVALENTS
First, we give you the hexadecimal values for some common needs, like the
linefeed or carriage return, and then we furnish the complete ASCII Code
and show the hexadecimal values for each ASCII character.
H ex ASCII
07 bell (or beep)
09 tab
0A linefeed
0D carriage return
359
Soul of CP/M®
H ex ASCII H ex ASCII H ex ASCII H ex ASCII H ex ASCII H ex ASCII

t
20 Space 30 0 40 @ 50 P 60 70 P
I a
21
II
31 1 41 A 51 Q 61 71 q
22 32 2 42 B 52 R 62 b 72 r
23 # 33 3 43 C 53 S 63 c 73 s
24 $ 34 4 44 D 54 T 64 d 74 t
25 % 35 5 45 E 55 U 65 e 75 u
26 & 36 6 46 F 56 V 66 f 76 V
27 ’ 37 7 47 G 57 W 67 g 77 w
28 ( 38 8 48 H 58 X 68 h 78 X
29 ) 39 9 49 I 59 Y 69 i 79 y
2A * 3A 4A J 5A Z 6A 7A z
j
2B + 3B * 4B K 5B t 6B k 7B {
, 11
2C 3C < 4C L 5C \ 6C 1 7C
2D - 3D = 4D M 5D } 6D m 7D }
2E m 3E > 4E N 5E A 6E n 7E
2F / 3F 9 4F 0 5F — 6F 0 7F rubout
HEXADECIMAL-TO-DECIMAL CONVERSION
On the next page, we furnish an easy-to-use listing that will permit you to
make fast and accurate conversions between hex and decimal notations, and
vice versa.
360
Tables
Hex Dec H ex D ec H ex Dec H ex D ec H ex D ec H ex Dec
00 0 2B 43 56 86 81 129 AC 172 D7 215

01 1 2C 44 57 87 82 130 AD 173 D8 216
02 2 2D 45 58 88 83 131 AE 174 D9 217
03 3 2E 46 59 89 84 132 AF 175 DA 218
04 4 2F 47 5A 90 85 133 BO 176 DB 219
05 5 30 48 5B 91 86 134 BI 177 DC 220
06 6 31 49 5C 92 87 135 B2 178 DD 221
07 7 32 50 5D 93 88 136 B3 179 DE 222
08 8 33 51 5E 94 89 137 B4 180 DF 223
09 9 34 52 5F 95 8A 138 B5 181 EO 224
0A 10 35 53 60 96 8B 139 B6 182 El 225
OB 11 36 54 61 97 8C 140 B7 183 E2 226
OC 12 37 55 62 98 8D 141 B8 184 E3 227
OD 13 38 56 63 99 8E 142 B9 185 E4 228
OE 14 39 57 64 100 8F 143 BA 186 E5 229
OF 15 3A 58 65 101 90 144 BB 187 E6 230
10 16 3B 59 66 102 91 145 BC 188 E7 231
11 17 3C 60 67 103 92 146 BD 189 E8 232
12 18 3D 61 68 104 93 147 BE 190 E9 233
13 19 3E 62 69 105 94 148 BF 191 EA 234
14 20 3F 63 6A 106 95 149 CO 192 EB 235
15 21 40 64 6B 107 96 150 Cl 193 EC 236
16 22 41 65 6C 108 97 151 C2 194 ED 237
17 23 42 66 6D 109 98 152 C3 195 EE 238
18 24 43 67 6E 110 99 153 C4 196 EF 239
19 25 44 68 6F 111 9A 154 C5 197 FO 240
1A 26 45 69 70 112 9B 155 C6 198 FI 241
IB 27 46 70 71 113 9C 156 Cl 199 F2 242
1C 28 47 71 72 114 9D 157 C8 200 F3 243
ID 29 48 72 73 115 9E 158 C9 201 F4 244
IE 30 49 73 74 116 9F 159 CA 202 F5 245
IF 31 4A 74 75 117 AO 160 CB 203 F6 246
20 32 4B 75 76 118 A1 161 CC 204 F7 247
21 33 4C 76 77 119 A2 162 CD 205 F8 248
22 34 4D 77 78 120 A3 163 CE 206 F9 249
23 35 4E 78 79 121 A4 164 CF 207 FA 250
24 36 4F 79 7A 122 A5 165 DO 208 FB 251
25 37 50 80 7B 123 A6 166 D1 209 FC 252
26 38 51 81 7C 124 A7 167 D2 210 FD 253
27 39 52 82 7D 125 A8 168 D3 211 FE 254
28 40 53 83 7E 126 A9 169 D4 212 FF 255
29 41 54 84 7F 127 AA 170 D5 213
2A 42 55 85 80 128 AB 171 D6 214
361
Soul of CP/M®
MULTIPLES OF IK (1024), IN DECIMAL AND

HEXADECIMAL
A “ K” is simply a number that is equal to 1024 (decimal). It’s a convenient
number to use in the computer world since it’s almost 1000 (decimal) and, at
the same time, is exactly equal to 400 hex, both of which are nice round
numbers. The numbers shown in the table listing are common memory sizes
for 8-bit computers (which, in general, use a 16-bit address bus), thus limiting
them to addresses smaller than F F F F (hex). Note: The “ Hex —1” column in
the table shows the highest memory location in a computer with the given K-
bytes of memory.
K Decimal H ex H ex -1
IK 1024 400 3FF
2K 2048 800 7FF
4K 4096 1000 F FF
8K 8192 2000 1FFF
16K 16384 4000 3FFF
20K 20480 5000 4F F F
32K 32768 8000 7F FF
48K 49152 cooo BFFF
56K. 57344 E000 D FFF
64 K. 65536 10000 F FF F
362
Tables
DECIMAL, HEX, AND BINARY CONVERSION

In this section, we have a chart that will allow a fast and easy conversion
between the three numerical value systems of decimal notation, hexadecimal
notation, and binary notation.
Deci mal He x Bi nary

0 0 000 0
1 1 0 0 0 1
2 2 0 0 10
3 3 0 0 11
4 4 0 10 0
5 5 0 10 1
6 6 0 110
7 7 0 111
8 8 10 0 0
9 9 10 0 1
10 A 10 10
11 B 1 0 11
12 C 110 0
13 D 110 1
14 E 1110
15 F 1111
363
APPENDIX E
Summary of BDOS System

Calls (For C P / M 2 .2 )
This appendix lists all of the 36 system calls used in C P /M 2.2. The typical
calling sequences are written in D D T format for brevity. This means that all
numbers in this column are in hexadecimal notation. N o attem pt is made to
show how a returned value is dealt with following the call to BDOS “call 5.”
For more information on system calls, check the program examples in the
text.
Function
Number in Refer to
C-register Value passed Value returned Typical calling page
D ec H ex Function to function by function sequence number
0 00 System Reset N one N on e mvi c,0 68
call 5
1 01 Console Input N one A = ASCII mvi c,l 63
character call 5
2 02 Console Output E = ASCII N on e mvi c,2 32
character mvi e,65
call 5
3 03 Reader Input N one A = ASCII mvi c,3 96
character call 5
4 04 Punch Output E = ASCII N on e mvi c,4 98
character mvi e,65
call 5
365
Soul of CP/M®
Function
Number in Refer to
C-register Value passed Typical calling page
5 05 List Output E = ASCII N on e mvi c,5 93
(Printer) character mvi e,65
call 5
6 06 Direct Console E = ff (hex) A = 00 or mvi c,6 87
I/O (Input) A = ASCII mvi e,ff
character call 5
(note 1)
Direct Console E = ASCII N on e mvi c,6
I/O (Output) character mvi e,65
call 5
7 07 G et I /O Byte N one A = I/O mvi c,7 98
byte value call 5
8 08 Set I/O Byte E = I/O N on e mvi c,8 105
byte value mvi e,D 2
call 5
9 09 Print String (see D E = string N on e mvi c,9 72
note 2) address lxi d,200
call 5
10 0A Read Console D E = buffer Characters in mvi c,a 76
Buffer address buffer lxi e,300
call 5
11 OB G et Console N one A = F F (hex) mvi c,b 45
Status or A = 00 call 5
12 0C Return Version N one HL = version mvi c,c *
Number number call 5
13 0D Reset D isk System N one N on e mvi c,d *
call 5
14 0E Select Disk E = disk N one mvi c,e *
drive number mvi e,2
call 5
15 OF Open File D E = FCB A = directory mvi c,f 142
address code (note 3) lxi d,5c
call 5
16 10 C lose File D E = FCB A = directory mvi c,10 173
call 5
17 11 Search For First D E = FCB A = directory mvi c, 11 210
call 5
366
Summary of BDOS System Calls (For CP/M 2.2)
Function
Number in Refer to
18 12 Search For N ext D E = FCB A = directory mvi c,12 214
call 5
19 13 D elete File (note 5) D E = FCB A = directory mvi c,13 182
call 5
20 14 Read Sequential D E = FCB A = directory mvi c,14 147
Record address code (note 4) lxi d,5c
call 5
21 15 Write Sequential D E = FCB A = directory mvi c,15 171
call 5
22 16 Make File D E = FCB A = directory mvi c,16 170
call 5
23 17 Rename File D E = FCB A = directory mvi c,17 *
call 5
24 18 Return Login N one HL - login mvi c,18 *
Vector vector call 18
25 19 Return Current N one A = current mvi c,19 *
D isk disk drive call 5
26 1A Set D M A Address D E = new N on e mvi c ,la 149
D M A address lxi d,80
call 5
27 IB Get Allocation N one HL = alloca mvi c ,lb *
Address tion address call 5
28 1C Write Protect Disk N on e N on e mvi c ,lc *
call 5
29 ID Get R ead/O nly N one HL = read/ mvi c ,ld *
Vector only vector call 5
30 IE Set File Attributes D E = FCB A = directory mvi c ,le *
call 5
31 IF Get D isk Para N one HL = disk mvi c ,lf *
meters Address parameters call 5
address
367
Soul of CP/M®
Function
Number in Refer to
32 20 Set User Code E = user N on e mvi c,20 *
code (0 to 31) mvi e,l
call 5
Get User Code E = FF A = user mvi c,20
code call 5
33 21 Read Random D E = FCB A = error mvi c,21 185
call 5
34 22 Write Random D E = FCB A - error mvi c,22 187
call 5
35 23 Compute File Size D E = FCB bits rO, r l, r2 mvi c,23 196
address in FCB set to lxi d,5c
file size call 5
36 24 Set Random D E = FCB bits rO, r l, r2 mvi c,24 197
address in FCB set to lxi d,5c
record number call 5
NOTES: 1. On Input, AA = 0 means no character is ready yet. Direct console I/O does not
recognize the normal control codes (AP, AS, etc.)
2. The string must terminate with a “$” character.
3. Directory Code (I)
= FF if file cannot be found.
= 0, 1, 2, or 3 if file found. Number corresponds to position o f file entry in
directory page.
4. Directory Code (II)
= 00 if operation was successful.
= nonzero if end-of-file (reading), disk full (writing), or directory full (make
file).
5. Wildcards (“?” characters) can be used in the program name.
6. Error codes returned in random record operations:
00 Operation successful.
01 Reading unwritten data (read only).
02 (Unused).
03 Cannot close current extent.
04 Seek to unwritten extent (read only).
05 Directory overflow opening new extent (write only).
06 Seek past physical end of disk.
7. The descriptions of the Functions marked with an asterisk (*) are not included
in this book.
368
APPENDIX F
Summary of DDT
Commands
This appendix summarizes the commands used in DDT. Except for the
first section, which is about loading DDT, they are arranged in alphabetical
order: A, D, F, G, H, I, L, M, R, S, T, U, and X.
LOADING DDT
From C P/M , type:
A>ddt
A COM or HEX program can be loaded into memory from the disk at the
same time that D D T is loaded, by appending the program name to “d d t” .
(Different file extensions can be used for COM files, like “d d t” .)
A>ddt t e s t p r o g . c o m
D D T loads itself into the CCP area of high memory and also uses various
parts of page zero. It loads the COM or HEX program into the TPA, starting
at address 100 hex for COM files, and, at the starting address specified by the
program, for HEX files.
369
Soul of CP/M®
“A” FOR ASSEMBLE
This command lets you type in programs in a symbolic format; that is,
instructions mnemonics may be used, but not labels.
From DDT, type “a” followed by the address (in hex) where you want to
start the assembly:
- a 100
or
-a20B0
D D T responds with the address in memory of the next instruction:
----------------------------- You type symbolic instructions in this column.
100 mvi c , 0
102 ca ll 5
105 ret
106 —
---------------------------- Type a “return” when you’re done.
I—-------—------------------------------ DD T tells you the address of the next instruction.
“D” FOR DUMP MEMORY
“Dum p” means to display a portion of memory in hexadecimal format.

From DDT, type “d” followed by the starting address of the memory block
you want to look at.
-d400
0400 41 0A 00 00 00 DE DO 00 01 B7 D8 AC 7E E9 42 43 A....................... ~.BC
(16 lines will be displayed)
ASCII equivalents to the hex values are printed on the right, with periods
used for nonprintable values.
If no ending address is specified, 16 lines of 16 bytes each are displayed.
An ending address can also be used, following the starting address:
370
Summary of DDT Commands
-d400,42f
This will cause the dump to stop when the ending address is reached (in this
case, after 3 lines).
If neither a starting nor an ending address is typed, 16 lines will be
dumped starting at the last address used (initially 100, when D D T is loaded).
“F” FOR FILL

This command is used to fill an area of memory with a constant hex value.
After “f”, type the starting address, the ending address, and the constant that
is to be filled in (all in hex):
-f4 00 ,5 00 ,ff
will fill the block of memory from 400 to 500 with the value ff. The constant
must be a one-byte value—in the range 0 to ff hex.
“G” FOR GO
This command is used to transfer control to a program at a particular
address in m em ory-in other words, to execute the program. The usual form
is “g” followed by the starting address:
-g100
which will cause the program that starts at 100 hex to be executed. It is simi
lar to a jum p instruction in assembly language, or a GOTO in BASIC. A “g”
to location 0 brings you back to C P /M (with a cold boot):
-g0
A>
Note that the only way to get back to D D T once you’ve used “g” is is to
have your program end with an “RST 7” instruction (or you can use
breakpoints).
You can also use the “g” command to set “breakpoints,” which are tempo
rary jum ps back to D D T that are inserted automatically in your program and
371
Soul of CP/M®
then deleted once they’ve been used. Breakpoints are useful if you want to
execute only a portion of a program that you’re debugging. You insert a
breakpoint at the end of the section you want to execute, and D D T will
regain control from your program at that point, leaving your program
unchanged in memory. Thus, only the section of your program between the
starting address (the first address specified in the “g” command) and the
breakpoint (the second address specified) will be executed.
Either one or two breakpoint addresses can be typed following the starting
address:
- g 1 0 0 , 1 24 Sets a breakpoint at 124.

-g100,127,13d Sets breakpoints at 127 and 13d.
“H” FOR HEXADECIMAL ARITHMETIC
D D T can be used to perform addition and subtraction of hexadecimal

numbers, using the “H ” command. After “h” , type the two numbers sepa
rated by a comma:
-h980,bc00-— — You type this.

C580,4D80 « --- DD T types this.
------------- Difference of 980 and BCOO.

------------- Sum of 980 and BCOO.
“I” COMMAND
See the “ R ” Command.
«¥
L” FOR LIST
This command is used to list a program in disassembled symbolic form (as

opposed to dumping it in hex numbers with “d”). It can be thought of as the
inverse operation of the “A ” command.
If you type a “1” followed by an address, 12 lines of instructions will be
displayed:
372
-1 1 0 0 ------------- You type this.

100 MVI A , 50 '
102 STA 0 1 FE DD T displays this.
105 MVI C, A
e tc.
You can also specify an ending address, in which case, the last address
displayed will be the one you specify:
-1100,116
If no address is specified, disassembly will start at the current line, which is

initially 100 when D D T is loaded, but which is set to the last line displayed
whenever “1” is used.
-I
“M” FOR MOVE
“M” allows the contents of one block of memory to be moved to another

part of memory. After “b ”, type the starting address of the block to be
moved, the ending address of the block to be moved, and the address that the
block is to be moved to.
- m 10 0 ,1 2 4, 2 00
I---------- Starting address of destination block.

-------------------- Ending address of source block.
------------------------------- Starting address of source block.
“R” FOR READ

This command is used in conjunction with the “I” command to permit
D D T to read a program from the disk into the Transient Program area (TPA)
of memory. Once in memory, the program can either be executed by DDT, or
debugged using any of D D T’s various commands. Either COM or HEX files
may be loaded, although COM files can be given different file types, like
“ D D T.”
373
Soul of CP/M®
Before this command is used, the “I” command is used to insert the name
of the COM or HEX program into the File Control Block at 5C hex. To do
this, simply type the name of the program, along with its file type, following
- i testprog.hex
Now to actually read the program into the TPA, type “r” :
-r
COM files will be loaded at 100 hex and HEX files will be loaded at the
address that you specified in the “end” statement of the ASM file when you
created the program. Make sure the program does not overwrite the zero
page (0 to ff hex), since D D T uses this area.
Note that using “i” and “r” together like this has the same effect as loading
in the COM or HEX program when you first load DDT:
A>ddt t e s t p r o g . h e x
is the same as
A>ddt
- i t e s t p r o g . hex
-r
An optional offset can also be used with the “R” command. This causes
the program to be loaded into a different address than the one that it nor
mally would be; that is, 100 hex for COM files and the address specified in
the ASM file’s “end” statement for HEX files. The new address is found by
adding the offset to the normal ad d ress-th at is, the offset is the difference
between the new address and the normal one. To use this option, type the
offset after the “r” :
-r40
If, in this case, a COM file had already been specified by the “I” com
mand, the program would be loaded at 140, since 100 (the normal loading
address of COM files) plus 40 equals 140.
374
“S” FOR SET MEMORY

This command lets you insert hexadecimal values into memory. It is
invoked by typing “s” followed by the address at which you want to start
inserting values. It responds by typing a line number and the current con
tents of the line:
- s 1 10
110 B5
You can now type in a new value or, if you want to leave this address
unchanged, you can simply press “return” to go on to the next address. A
period is used to terminate the function.
You type numbers in this column.
- s 1 10
110 B5 cO
111 00 b6
112 00 Nothing is inserted here; “return” leaves current value unchanged.
113 2D c9
114 76 0
114 7 F Type period to terminate function.
“T” FOR TRACE

Tracing is a very clever function whereby D D T can execute the instruc
tions of your program and at the same time keep control of the computer
itself, so that it can print out all sorts of useful information about what your
program is doing.
The information printed out consists of the contents of the various 8080
registers. To use this command, you must first have your program in memory
ready to be executed. You then type a “t” followed by the number of instruc
tions you want to see executed, in hexadecimal.
For example, we show in Listing F -l what happens when you load and
then use “t” to trace the first 8 instructions of the program “barber.ddt” from
Chapter 2 in this book.
375
Soul of CP/M®
Listing F-1. Using “T” for Trace

DDT VERS 2 . 2
NEXT PC
02 00 01 00
-t8
C0Z0M0E0I0 A = 00 B =: 0000 =0000 H= 0000 S = 0100 P = 0100 MVI E,20
C0Z0M0E0I0 A = 00 B =: 0000 =0020 H= : 0000 S = 0100 P = 0102 MVI C,02
C0Z0M0E0I0 A = 00 B =: 0002 =0020 Hi : 0000 S = 0100 P = 0104 PUSH D
C0Z0M0E0I0 A = 00 B =:0002 =0020 H= 0000 S = 00FE P = 0105 CALL 0005
C0Z0M0E0I0 A = 00 B =:0002 =0020 H= 0000 S = 00FC P = 0005 JMP A800
C0Z0M0E0I0 A= 0 0 B= : 0002 =0020 H= 0000 S = 00FC P = A800 JMP AEA2
C0Z0M0E0I0 A = 00 B =! 0002 =0020 H= 0000 S = 00FC P = AEA2 XTHL
.COZOMOEOIO, A = 00. B =■0002 , =0020, H= 0108, S = £ 0 ^ P=£EA3, .SHLD B74A,
Contents of flags. ♦ Instruction

Contents of
executed.
DE register.
Contents of
C = carry
Contents of program counter.
Z = zero BC register. —► Contents of stack pointer.
M = minus
" Contents of ------ Contents of HL register.
E = even parity A-register.
I = interdigit carry
“U” FOR UNTRACE
This command is very similar to trace, except that nothing is printed out.
You simply type “u” and the number (in hex) of the instructions you want
D D T to execute:
-u10
This is useful if you want to trace a particular segment of your program

using “t,” but this part isn’t at the start of the program. Using “u,” you can
skip over the first part of your program without the printout (which can be
time-consuming for even a few hundred instructions), but, at the same time,
let D D T keep control of the program so that it will stop at the point you
want it to. Once these initial instructions have been “untraced,” that is,
traced without printing, you can trace the next, defective, group of instruc
tions using “t.”
376
Thus, if you know, for example, that your program executes a loop of say,
10 instructions correctly five times, but does something incorrect on the sixth
iteration of the loop, you can say:
-u 5 0 -*--------- Skips over 50 good instructions.

-t10 ------ — Traces 10 bad instructions.
“X” FOR EXAMINE REGISTERS
It’s often helpful to be able to look a t—and alter—the contents of the vari
ous 8080 registers when you’re trying to debug a program. The “x” command
lets you do both these things. You can also examine and change the contents
of the flags. To do this, you type “x” followed by a one-letter mnemonic for
the register that you want to look at or modify. For instance,
- xp -«----------- If you type this,

P=1024 100 - ------- — DDT will respond with “P = 1024”, the contents of the program
~ . counter.
I------------------ You change it to 100 hex by typing the number in this column. If
you only type a carriage return, the number is unchanged.
Sometimes you have to type a 4-digit hex number, as in the case of the
registers BC, DE, HL, the program counter P, and the stack pointer S. For
the A-register, you must type a 2-digit number and, for the flags, you must
type a single binary digit: 0 or 1.
Here’s a list of the mnemonics used for the various registers, together with
the range of values that can be put into them:
A A-register 0 to FF
B BC-register 0 to FFFF
D DE-register 0 to F F FF
H HL-register 0 to F FFF
S Stack Pointer 0 to FF FF
P Program Counter 0 to FF FF
M Minus Flag 0 to 1
C Carry Flag 0 to 1
Z Zero Flag 0 to 1
E Even Parity Flag 0 to 1
I Interdigit (Auxiliary) Carry Flag 0 to 1
377
Soul of CP/M®
Notice that if you want to put just a 2-digit (8 bit) number into, say, the
B-register, you must put an entire 4-digit (16 bit) number into the BC-regis
ter. W ith the “x” command, there is no way to work with the B, C, D, E, H,
or L registers as separate 8-bit registers.
378
APPENDIX G
Summaries of Programs
Used and Locations of
Instruction Descriptions
This appendix provides an itemized listing of the programs used in this

book and the instruction descriptions given in the book. They are arranged
by chapter for your convenience.
PROGRAMS USED
Alongside each program name is a short description of what it does.
Chapter 2
test.ddt Prints “H I” returns to DDT.

test 1.ddt Prints series of “HLs”.
test2.ddt Prints “ H is” with Check Console Status.
barber.ddt Prints ASCII characters.
test3.ddt Beeps keyboard.
test4.ddt Beep with AC escape.
test4.com Beep with RET instead of RST.
379
Soul of CP/M®
Chapter 3
test5.ddt Print string.

test6.ddt Read console buffer.
test7.ddt Read console and print string,
namedisp.ddt Parabola name display.
test8.ddt Direct console I/O .
test9.ddt Password.
testlO.ddt Type to printer,
te stll.d d t Get I/O byte.
Chapter 4
test 1.asm Assembled version of test 1.ddt.

decibin.hex Decimal to binary routine.
binihex.asm Binary to hex routine.
decihex.asm Decimal to hex conversion.
Chapter 5
testlOO.ddt Open file.

test 101.ddt Open file, return directory code.
testl02.ddt Read record.
testl03.ddt Read record with DMA at 400.
testl04.ddt Read record, DM A at 400, print directory code.
type2.com Imitates C P /M TYPE function.
lines.com Counts lines in a file.
Chapter 6
testl05.ddt Write sequential record.

store.asm Store text in file (add to existing file).
store2.asm Store text in file (delete existing file).
testl06.ddt Read random record.
testl07.ddt Write random record (new file).
testl08.ddt Write random record (old file).
randymod.asm Modify a random record.
store3.asm Version of store using compute file size.
380
Summaries of Programs
Chapter 7
testl09.ddt Search For First (in disk directory).

test 1lO.ddt Search For First and next.
testl 1l.ddt Save erased file.
words.asm Counts words in file, uses wildcards.
Chapter 8
binihex2 Decimal to hex converter.

binihex3 Version to be relocated in memory.
binihex4 Version to be POKEd in from BASIC.
LOADHEX.BAS BASIC program to load HEX files.
hexibin2 Hex to decimal converter (runs from BASIC).
ucase Convert lowercase letters to uppercase.
DESCRIPTIONS OF INSTRUCTIONS
Alongside each instruction is listed the specific section in the chapter

where the instruction is described.
Chapter 2
MVI Console Out

CALL Console Out
RST Console Out
JMP Console Out
ORA Get Console Status
JZ Get Console Status
PUSH Get Console Status
POP Get Console Status
IN R Get Console Status
MOV Get Console Status
CPI Get Console Status
JNZ Get Console Status
RET Console Input
IN R Get Console Status
381
Soul of CP/M®
Chapter 3
LXI Print String

STA Read Console Buffer
D CR Name Display Program
INX Direct Console I/O
LDA List O utput
RLC Get I/O Byte
ANI Get I/O Byte
ADI Get I/O Byte
Chapter 4
RM Decibin Routine
RP Decibin Routine
SUI Decibin Routine
DAD Decibin Routine
Chapter 5
SHLD Lines Program

LHLD Lines Program
Chapter 7
SPHL Words Program

LDAX Words Program
STAX Words Program
XCHG Words Program
Chapter 9
IN Printer Driver
OUT Printer Driver
XRI Printer Driver
382
Index
A A SM —cont.
and D D T , format differences between,
“A ” command, 109 111-112
explained, 38 assembler, 108, 109-116, 136
Add Immediate instruction; see A D I file(s), 110, 118, 223, 283
instruction defined Assembler
Addresses, reverse order, 43, 114 D D T mini, 29
A D I instruction defined, 104 directives, 357
A-L using the, 107-136
program, 244-248 Assem bly language
routine, 248-277 8080, 136
getting back to BASIC from, instructions, 348
249 routine, 243, 246, 277, 325
getting from BASIC to, 249 Assemblying
how do we pass arguments between and using DECIH EX, 134
BASIC and, 249-251 a program, 110, 113-115
m oving after loading, 256
operating on strings with, 274-276
passing arguments to BASIC from, B
271-274
POKEing into memory, 262-267 Barber-Pole display program, 51-63
putting into memory, 255-271 BASIC, 243, 244, 248, 262-267
transferring control between BASIC using system calls from, 243-277
and, 248-249 Basic
using a BASIC program to load the, disk operating system; see BDOS
267-271 input/output system; see BIOS
Allocation BC-register, 27
units, 138-139, 170, 202, 205, 207-209, BDOS, 22, 143, 17 0 -1 7 1 , 182, 185, 207,
221 221-222, 310;
vector; see bit map see also basic disk operating sys
A n d logical operation, 102-103 tem
A N I instruction defined, 102-103 system calls, summary of, 365-368
A-register, 27, 129 talking to, 139-142
Arguments, 243, 249-251, 271-274 BEEP program, 64-66
ASCII, 72, 78, 105, 123, 130, 133, 155, Bias or offset, 314
159, 213, 267, 359-360 Binary, 116, 129
character set, 51 decimal, and hex conversion, 363
defined, 25 notation explained, 323-325
ASM , 14, 15, 108, 153, 248 numbers, 29
383
Soul of CP/M®
Binary—cont. Cold boot, 45, 65, 293

-to-decimal conversion routine, 126, 157 COM file(s), 110, 118, 120, 134, 155, 234,
B IN ID E C SU BR O U T IN E , 157-160, 242 248, 261, 308
BIN IH EX Comment field, 113
program, 264-265 Compute File Size system call, 196-197
routine, 126-130 Console
BIN IH EX 2 routine, 251-254 buffer, read, 76-81
BIN IH EX 3 routine, 259-262 Command Processor, 281; see also CCP
BIOS, 22, 32, 215; see also basic input/ field, 100
output system Input system call defined, 63
file, merge in the new, 316-317 Output, 52
installing the new driver in your, 308- system call defined, 32
314 system calls, 31-70
learning your way around, 283-294 advanced, 71-106
listing, 295-301 Control
modifying for different control charac -c, 41, 65, 303
ters, 320-322 characters, 279-280
what is the?, 280-283 modifying BIOS for different, 32 0 -
what you need to modify your, 282-283 322
Bit -P, 106
map, 221-222, 308 -q, 302-303
patterns, 292 -s, 42, 302-303, 340
hexadecimal, 329 feature, using, 42-45
Buffer Converting
D M A , 140, 172, 175, 188, 194, 215-216 decim al to hex, 330
printer, 302-303 hex to decimal, 329
read console, 76-81 CPI instruction defined, 61
Byte(s), 202, 205, 208 C P /M
I/O , 99-101, 105-106 executing programs from, 66-68
image
create the, 315
C using D D T , 315-316
operating system, 308
CALL instruction defined, 36-37 parts of, 21-24
Calls CPM 56.COM program, 310
advanced console system, 71-106 CR byte, 172-173
console system, 31-70 Create the C P /M image, 315
disk system, 137-167 Creating a new FCB, 220
Carry flag, 104, 124, 359 Current extent, 145
CBASE, 262-263 byte, 173, 183, 188
CCP, 22, 68, 212, 215, 245, 262, 263, 281,
285, 310-311, 315;
see also console command D
processor
C lose File system call, 169, 170, 173-174, D A D instruction defined, 123-124
218 Data
Code, source and object, 115-116 statements, 264, 266
384
Index
D ata—cont. D isk—cont.
transfers, memory to memory, 236-240 operating system, C P /M , 167
DB directive defined, 155-156 system calls, 137-167
DBASE, 245-247, 251-252, 263 utility program, 202
dBASE II, 243 writing to, 169-199
“D ” command, 81, 109 DMA
explained, 73 address, 141
D C R instruction defined, 85-86 buffer, 140, 146, 149, 150, 172, 175, 180,
D D T , 14, 107-109, 136, 143-147, 212, 234, 188, 194-196, 215-216
245, 247, 248-254, 320, 331, 340 dilemma, 146-147, 149
and ASM , format differences between, location problem, 146-147
111-112 “$” label, 257-258
commands, summary of, 369-378 D ollar-sign label, 256, 258; see also “$ ”
hex arithmetic function, 312 label
loading, 369 Drive
-the programmer’s x ray and probe, 2 9 - code, 207, 210
30 default, 145
typing in number, 141
a message with, 73-75 Driver
the program using, 39-41 installation steps, quick summary of,
D EC IBIN routine, 110, 116, 118-120, 318
122-123, 196 into the C P /M system, inserting new,
assemblying and executing, 125-126 314-318
D EC IH EX program, 126, 130-132 in your BIOS, installing, 308-314
Decimal routines, 281, 314
converting hex to, 329 testing the, 305-307
hex, and binary conversion, 363 writing a sample, 303-306
notation explained, 325 D ummy argument, 254
-to-binary conversion, 116-118 D W directive defined, 160-163
-to-hexadecimal conversion routine,
126-130
to hex, converting, 330 E
D E F IN T statement, 252
D E F U S R statement, 249, 270, 271 8-bit
D elete File system call, 169, 182-183 arithmetic, 351-252
DE-register, 27, 77 transfers, 349-350
Descripter, 274-275 8080
D IR, 216 8080A, 8085 microprocessor chips, 13
D IRECT CONSOLE I/O system program, architecture, 24-28, 345-348
87-93 assembly language, 136
Directory, 219-220 instructions, 345, 348-357
code, 212; see also return code microprocessor, 27, 289
disk, 205, 209-210 register, 234
scanning the entire, 216 E5, 210, 217, 219
Disk ECHO program, 82-83
directory, 144, 174, 202, 205, 209-210 Editing commands, 76-77
and wildcards, 201-242 C P /M ’s built-in, 76
385
Soul of CP/M®
End File(s)—cont.
directive, 132 erased, 217
-of-file; see EOF getting the vital information about the,
marker, 148 219-220
statement, 120 merging, 310
EOF, 153, 155, 180 on the disk, how C P /M stores, 202-210
EQU directive, 180, 258 opening, 205
defined, 132-133 outputting in hex, 341-343
Erased files storage, 340
saving, 218-221, 222 writing to a new, 188-189
using E5 with, 210, 217 F IL E D U M P program, 340-343
E T X /A C K protocol, 303 F lag(s), 124, 353
Examining the FCB, 206 list of, 347-348
Exclamation point directive defined, Floating Point Accumulator, 250; see also
129 FAC
Exclusive-OR, 292 Flowchart defined, 53
Executing programs from Format differences between D D T and
C P /M , 66-68 ASM , 111-112
D D T , 42 FO R TR A N , 243
Existing record, writing to, 189 Full disk operating system; see FDO S
Extents, 138-139, 173, 186, 202, 205 Function byte, 292
opening new, 207, 208, 211
G
F
“G ” comm and explained, 41
FAC, 250-251, 253, 273, 274 Get
FBASE, 245, 262-263, 264 Console Status, 52
FCB, 140, 142-144, 148, 170-172, 185, system call defined, 45
195-196, 205, 207, 316; I/O Byte system call, 98-105
see also file control block Golden Rule, C P /M ’s, 21
creating new, 220
examining the, 206
FDO S, 23, 68 H
Field(s)
comment, 113 Hex
label, 113 arithmetic function, 312
operand, 34 converting decimal to, 329-330
operation, 34 decimal, and binary conversion, 363
statement, 33-36 files, 110, 115, 118, 120, 248, 267-271
File(s), 148, 211-212 -to-decim al conversion program, 3 3 9 -
ASM , 223 340
control block, 140-142, 203-205; see Hexadecimal, 112, 116
also FCB arithmetic, 327-328
count words in, 222-242 bit patterns, 329
close the, 220-221 digits, 127
defined, 139 instruction codes, 35
386
Index
Hexadecim al—cont. Jump(s)—cont.

notation explained, 323-330 -on-not-zero; see JNZ instruction
numbers, 29 table, 287, 316
-to-decimal conversion, 360-361 JZ instruction defined, 50
H E X D U M P program, 263, 331-334
HEX IBIN 2 program, 271-274
HEXIDEC program, 338-340 L
High memory, 255, 261, 315
using load in, 255-256 Label(s)
“H I” program, 38 field, 113
HL-register, 27 symbolic, 112-113
H ow C P /M stores files on the disk, 2 0 2 - “ L” command explained, 40
210 L D A instruction defined, 96
L D A X instruction defined, 237-238
L H LD instruction, 160, 162, 240
I LINES program, 157-167
List
field, 100
command, 206, 212 Output to Printer system call, 93-96
instruction, 152 LOAD, 14, 110, 255, 256, 261
program, using the, 115, 248
command explained, 145-146 using, 115
(“immediate”) used in instructions, 74 Loading
Imitating the “TYPE” command, 153-157 D D T , 369
“Immediate” used in instructions, 74 programs with D D T , 42
IN instruction defined, 289-290 Logical
Input call, console, 63-66 and physical I/O devices, 99
IN R instruction defined, 59 devices, 99
Inserting the new driver into the C P /M LXI instructions, 74-75, 77, 240
system, 314-318
Instructions, assembly language, 26
Interpreter, BASIC, 245, 246, 254 M
Interrupt system, 38
IN X instruction defined, 92 MAC, 29
I/O , 285-287 M achine transportability, 20
byte, 99-101, 105-106 Magic number
devices, logical and physical, 99 find the, 313
initialization, 293-294 “N ”, 310, 320
IOBYTE, 288-289 what good is this?, 313
Make File system call, 169, 170-171, 172
M apping, 174
J Masking off bits, 103
Memory, 24-26, 248
JMP instruction defined, 43 -4 4 other ways to put the A-L routine into,
JNZ instruction defined, 62 255-271
Jump(s) protected, 245, 246
calls, and returns, 352-353 to memory data transfers, 236-240
387
Soul of CP/M®
Merge in the new BIOS file, 316-317 O utput—cont.

Merging to printer, 93-96
files, 310
your new driver, 314
M ICRO SPACE IN V A D E R S program, P
334-338
M odifying Page zero, 23
BIOS, 282-283 Parts o f C P /M , 21-24
for different control characters, 3 2 0 - Pascal, 243
322 Passing arguments between BASIC and
C P /M for different peripherals, 279-322 the A-L routine, 249-251
the STORE program, 182-183 PASSW O RD program, 89-90
your printer driver, 301-307 PC (program counter), 44
MOV instruction, 60, 237 PCH AR subroutine, 133
MOVCPM utility program, 308-310, 311, Peripherals, 279, 281
320 Phantom “M ” register, 90-92
“M ” register, 90-92, 237, 346 Physical
MVI instruction, 34-36, 60, 74 devices, 99
I /O devices, 99
PIP command, 14, 183, 197
N POKEing the A-L routine into memory
from BASIC, 262-267
N A M E DISPLA Y program, 83-87 POP instruction, 55, 57-59, 234
NEX T, 44 Printer(s), 94, 106, 279, 286-287
N ondisk system calls, 106 buffer, 302-303
daisy-wheel, 302
driver, 301-307
O how to modify your, 301-307
program, 321
Object code, 115 list output to, 93-96
and source code, 115-116 program to type to, 94-96
Open serial, 302
files, 205 Print String system call, 72-75, 82, 242
File system call, 142-146, 148, 170 PRN files, 110, 113, 118, 125, 264-265,
Operand field, 34 267
Operating system(s), 18 Program(s)
C P /M , 308 assemblying the, 113-115
what is an?, 18 beep, 64-66
Operation field, 34 executing, 66-68
O r logical operation, 49 running the, 63
OR A instruction defined, 49 saving the, 41-42
OR G Status Word, 345, 347-348
directive, 111, 115, 132, 252, 253 to type to the printer, 94-96
statement and the jum p table, 287 transportability, 18-19
O U T instruction defined, 290-292 typing in the, 39-41
Output using the LOAD, 115
system call, console, 32-45 utility, 331-343
388
Index
Programmer’s probe, D D T , 29-30 Rotate Left instruction; see RLC instruc

Protected memory, 245, 246 tion defined
Protocols, 301-303 Rotations, 353-354
PSW; see Program Status Word RP instruction defined, 120-121
Punch RST instruction defined, 38-39
field, 100 Rubout character, 180
Output system call, 98
PU SH instruction, 56, 57, 234
Putting the A-L routine into memory, S
255-271
16-bit
arithmetic, 352
R transfers, 350-351
SAVE command, 40, 310
Saving D D T programs, 41
Random “S” command D D T explained, 73
and sequential system calls, 186 Scanning the entire directory, 216
record(s), 170, 183-185, 186, 194 Search For
program to modify a, 189-195 First system call, 202, 210-211, 214,
R A N D Y M O D program, 170, 185, 189— 223-224
195 N ext system call, 202, 214-217,
Read 223-224
C onsole Buffer system call, 76-81, 82 “ Search” system calls, 223
Random Record system call, 185-187, Sectors, 138-139, 202-203, 205, 208
189 Sequential records, 148
Record program, 151-153 Serial printer, 302
Sequential system call, 147-149, 172, Set
182, 183 D M A Address system call, 149-153
Reader I /O Byte system call defined, 105
field, 100 Random Record system call, 197-198
Input system call, 96-98 SH L D instruction defined, 160, 161
Reading a record, 148-149 Sign flag defined, 121-122, 124, 359
Record(s), 138-139, 202-203, 205, 208, 209 Source code, 115
defined, 139 and object code, 115-116
random, 170, 183-185, 186 Space game, 334
reading a, 149-149 SPHL instruction defined, 235
sequential, 148 SP-register, 56, 234
storage, 340 Stack, 54-56, 66, 105, 146
writing to existing, 189 defined, 54
Register(s), 26-28, 34, 345-347 management, 96, 234-236
phantom “ M ”, 90-92 pointer, 347
Reloading D D T programs, 42 register; see SP-register
RET instruction, 36, 66-67 STA instruction defined, 79
Return code, 186, 187; see also directory STAT, 14, 216, 256
code Statement fields, 33-36
RLC instruction, 102, 130 Status byte, 290
RM instruction defined, 120-121 STAX instruction, 237, 239
389
Soul of CP/M®
STORE U
program, 171, 177-182, 190, 196, 197,
219 U A R T , 283, 285, 290, 292, 293, 305
modifying, 182 U C A SE program, 275-276
text in file, 177 Universal Asynchronous R eceiver/Trans
String(s) mitter; see U A R T
argument in BASIC, 274 U se factor, 114
defined, 72 U sing
-handling system calls, 82 a BASIC program to load the A-L rou
in D B directives, 157 tine, 267-271
operating on with an A-L routine, 2 7 4 - the L O A D program, 115
276 U SR function, 249, 250, 275
SU BM IT utility, using C P /M ’s, 134-136 U tility
Subroutines, 36, 120-125 program(s), 331-343
in W ORDS, 242 disk, 202
SUI instruction defined, 121-122
Symbolic labels, 112-113, 195
SY SG E N utility, 317, 320
W
System
calls, 12, 19-20, 31-106, 223
console, 31-106 Warm boot, 41, 66, 68-69, 221, 222, 293
disk, 137-167 Wildcards, 211-213, 215, 222
nondisk, 106 and the disk directory, 201-242
string-handling, 82 how W O R D S handles, 240-241
summary o f BDOS, 365-368 Word processor, using the, 110
Reset system call defined, 68 WORDS
tracks, 317 program, 199, 202, 216, 222-242
subroutines in, 242
Write
Random system call, 187-189
T Record system call, 171, 182
Sequential Record system call, 169, 170,
171-173, 183
Talking to BDOS, 139-142
Writing
Text editor, your own, 182
a sample driver, 303-306
TPA, 21, 68; see also transient program
to a new file, 188-189
area
to existing record, 189
Tracks, 138-139, 202, 203, 205
Transferring control between BASIC and
the A-L routine, 248-249
Transient program area; see TPA X
Transportability
machine, 20 “X ”
program, 18 command explained, 126
TYPE2 program, 153-157 used in instructions, 74
Typing in X C H G instruction, 240, 275-276
a message with D D T , 73-75 X O N /X O F F protocol, 302, 304, 305
the program using D D T , 39—41 X RI instruction defined, 291-293
390
Index
Your first program, 33
Z-80 microprocessor chip, 13

Zero flag, 48, 104, 124, 359
391
TO THE READER
S am s C o m p u ter books cover F u n d am en tals — Program m ing — In terfac in g — Techn olo gy w ritte n to m eet the
needs of co m p uter engineers, profession als, sc ientists, te chn icians, students, educators, business ow ners, per
sonal co m p u te ris ts and hom e hobbyists.
Our Tradition is to meet your needs and in so doing we invite you to tell us what
your needs and interests are by completing the following:
1. I need books on th e fo llow ing topics:
2 . I have the fo llow ing Sam s titles:
3 . M y occupation is:
______ S cien tis t, E ngineer ______ D P P rofessional
______ Personal com p uterist ______ B usiness ow ner
______ T e ch n icia n , S ervicem an _ _ _ C o m p u ter store ow ner
______ E ducator ______ H om e hobbyist
______ S tud en t O th er ______________________
N am e (print)_______________________________
A ddress___________________________________
C i t y ______________________________________ S t a t e _____________________Zip
M a il to: Howard W. Sams & Co., Inc.

M arketin g Dept. #C B S 1/80
4300 W. 62nd St., P.O. Box 7092
In dian apo lis, In d ian a 46206 22 0 3 0
□ MS™-DOS * Bible Pascal Primer
A step beyond D isc o v e rin g M S -D O S . Take an in- G uides you sw iftly thrctgr:
depth look at M S-DO S, particularly at com m ands such procedures, variables
as D E B U G , LIN K , E D L IN . P rovides quick and easy numeric functions. Contains
access to M S-DOS features and clear explanations of and eigh t appendices. Waite ano F OX-
DO S utilities. S teven Simrin. No. 21793, $17.95
No. 22408, $18.95
Printer Connections Bible
MS-DOS Developer's Guide Covers major com puter/printer com binations, supplies
T his useful guide is w ritten expressly for detailed diagram s of required cables, dip-sw itching
program mers who w ant to learn tricks for gettin g se ttin g s, etc. Includes diagram s illustrating numerous
their softw are running in the M S-DOS environm ent. printer/com puter com binations. H ouse and Marble.
Included are assem b ly coding tips, explanations of No. 22406, $16.95
the differences am ong M S-DO S version s 1.1, 2.1, and
3.1, and betw een M S-DO S and IBM® PC-DO S™ . Modem Connections Bible
Angerm eyer and Jaeger.
This book describes m odem s and how they work, how
No. 22409, $24.95
to hook up major brands of m icrocom puters, and what
68000, 68010, 68020 Primer happens w ith the RS-232C interface. A m ust for users
The new est 68000 fam ily of chips is covered in this and technicians. Richmond and Majhor.
tim ely and up-to-date primer. G ives you a com plete No. 22446, $16.95
understanding of M otorola's powerful m icroprocessor
chip and features actual program m ing exam ples such
as file locking and data handling techniques.
K elly-Bootle and Fowler. T hese and other Sam s books are available from your
No. 22405, $21.95 local bookstore, com puter store or distributor. If there
are books you are interested in th at are unavailable in
IB M ® PC/PCjr™ Logo Programming Primer your area you can order directly from Sams.
Em phasizes structured, top-down program ming
techniques with box charts th at help you m axim ize Phone Orders — Call toll-free 800-428-SA M S tin
effectiven ess in planning, changing, and debugging A laska, Hawaii or Indiana call 317-298-5566) to charge
Logo programs. Covers recursion, outp uts, and your order to your V ISA or M asterCard account.
utilities. Several sam ple program ming projects
included. M artin, Prata, and Paulsen.
M ail Orders — U se the order form provided or on i
sh eet of paper include your name, address and dayiz=»r
No. 22379, $24.95
phone number. Indicate the title of the book, p r o c . "
number, q u antity and price. Include S2.50 for s n i
The Official Book for the Commodore 128™ ping and handling. AR, CA, FL, IN , NC. NY'. OH
Personal Computer TN, W V resid en ts add local sales tax. To cnargr y i m
D iscover Com m odore’s m ost excitin g com puter and its V IS A or M asterCard account, list your account
three different operating m odes — 64®, 128, and number, expiration date and signature. Ma_ ;
CP/M®. Create ex citin g graphics and anim ation, order to: H oward W. Sam s & Co.
program in three-voice sound, u se spreadsheets, word D epartm ent DM 061
4300 W est 62nd St.
processing, database, and much more.
Indianapolis, IN 46268
W aite, Lafore, and Volpe.
No. 22456, $12.95
SAMS.
PRODUCT NO. QUANTITY PRICE TOTAL
N a m e (p le a s e print)
S ig n a tu re __________
Address __________
C ity _______________
S ta te /Z ip ________________________________
D Check _ - :t
S ubtotal □ VISA Z V c r e - lD - :
A ccoun t N um b er
AR, CA, FL, IN, NC, NH, OH, TN, WV
residents add local sales tax
_
H a n d lin g C harge $2.50 E xpiratio n Date _____________________________ __
O ffe r g o o d m U SA o n ly P r< e s s o f t e r »o c*xx» g e « nt+ vxj* n o tic e
WC020 Total A m o u n t Enclosed F u ll p a y m e n t m u s t o c c o m p o n y y o u r or&e<
More Books from Sams and The Waite Group
□ C Primer Plus □ Artificial Intelligence Programming on
P rovides a clear and com plete introduction to the C the Macintosh™
program m ing language. This well illustrated primer Includes tutorials in Logo as well as in Lisp and
guides you in the proper use of C program m ing Prolog, the three main A I langu ages. For
m ethodology and interfacing C w ith assem bly program m ers w hose background is in B A SIC , an
language. W aite, Prata, and Martin. appendix show s how to convert the program exam ples
No. 22090, $22.95 to th a t language. D an Shafer.
No. 22447, $24.95
UNIX™ Primer Plus
P resents the elem ents of U N IX clearly, sim ply, and CP/M ® Primer (2nd Edition)
accurately, for ready understanding by anyone in any C om pletely updated to give you the know-how to
field who needs to learn, use, or work w ith U N IX in begin working with new or old CP/M versions
some way. Fully illustrated. W aite, Martin, and Prata. im m ediately. Includes CP/M term inology, operation,
No. 22028, $19.95 capabilities, internal structure, and more.
W aite and Murtha.
U N IX SYSTE M V Primer No. 22170, $16.95
Show s you how to work w ith multi-user, m ulti-tasking
U N I X S ystem V, including its built-in u tilities and CP/M Bible: The A u thoritative Reference
softw are tools. Reference cards included. Guide to CP/M
W aite, Martin, and Prata. G ives you instan t, one-stop access to all CP/M
No. 22404, $19.95 keywords, com m ands, utilities, conventions, and more.
A m ust for any com puterist usin g any version of
A dvanced UNIX — A Programmer's Guide CP/M. W aite and Angermeyer.
U se U N IX in problem -solving. Learn to develop No. 22015, $19.95
shells, use U N IX tools, functions, and U N I X graphics,
and use C w ith U N IX . E xercises and qu estion s test Soul of CP/M: How to Use the Hidden
your progress. Stephen Prata. Power o f Your CP/M System
No. 22403, $17.95 T eaches you how to use and m odify CP/M ’s internal
features, use CP/M sy stem calls, and more. You'll
□ The UNIX™ Shell Programming need to read C P /M P R IM E R or be otherw ise familiar
Language with CP/M 's outer-layer utilities. W aite and Lafore.
An advanced program m ing guide em phasizing the No. 22030, $19.95
Bourne shell, while including the C shell and the
Korn shell as well. This book dem onstrates how the Discovering MS™-DOS®
pow erful U N IX shell program m ing language is From com plete description of the basic com mand set
creating a revolution in program ming. M any easy-to- through analysis of architectural im plications, you will
use exam ple program s can be run on any com puter. gain a com plete understanding of this operating
environm ent. K ate O'Day.
M anis and Meyer.
No. 22407, $15.95
No. 22497, $24.95
PLACE
STAMP
HERE
Howard W. Sams & Co., Inc.

D e p a rtm e n t DM
P.O. Box 7092
In d ia n a p o lis , IN 46206
Sams books cover a wide range of technical topics. We are
S A M S always interested in hearing from our readers regarding their in
form ational needs. Please complete this questionnaire and
return it to us w ith your suggestions. We appreciate your com
ments.
Book MarlofJBjAI >[oog 1. W hich brand and model
of computer do you use?
6. Are you interested in ser
vicing and repair of any of
□ A p p le _______________________ _ the following (please
□ Com m odore____________________ specify)?
□ IBM ___________________________
□ V C R s __________________________
□ Other (please specify) __________
□ Compact disc players ____________
□ Microwave o v e n s________________
□ Television________________________
2. Where do you use your □ Computers __________
computer? □Autom otive electronics _
□ Home D W ork □ Mobile telephones ___
□ O ther _______________
3. Are you planning to buy
a new compbter? 7. How many computer or
□ Ye s QNo electronics books did you buy
If yes, whatbrand are you planning in the last year?
to b u y?____________________________ □ One or two □ T h re e or four
□ Five or six □ More than six
4. Please specify the brand/
type of software, operating 8. What is the average price
system s or languages you use. you paid per book?
□ W o rd P r o c e s s in g ________________ □ Le ss than $10 □$10-$15
□ Spreadsheets ___________________ □ $16-$20 D$21-$25 D $26 +
□ Data Base Management _________
□ Integrated S o ftw a re ______________ 9. What is your occupation?
□ O perating System s ______________ □ Manager
□ Computer Languages ___________ □ Engineer
□ Technician
5. Are you interested in any □ Programmer/analyst
of the following electronics or □ Student
□ O the r __________________________
technical topics?
□ Amateur radio
□ Antennas and propagation
10. Please specify your
□ Artificial intelligence/ educational level.
expert system s □ High school
□ Audio □ Technical school
□ Data communications/ □ College graduate
telecommunications □ Postgraduate
□ Electronic projects
□ Instrumentation and measurements 11. Are there specific books
□ Lasers you would like to see us
□ Power engineering publish? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
□ Robotics
□ Satellite receivers
Com m ents.
Name _ ________________ _________________________

A d d r e s s ________________________________________
City ___________________ _________________________
S tate/Z ip _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ i
S W t fS 22 0 3 0 '
sms
Book Mark>[j[B]/\j >[00g

5 00
D y > »c
Q. o =1 sCo cn
Q
D CP z 2
o
ni
-o O T)
Q
O m
co
— fO 73
CD
rTi
cn
Z (D_
2
o^ro =oQT. 6
CD
8 5 00 -<
o n Oo
o O Z)
"D rn
Cn
2
Q * n
-I CO
rri
3 rri
CD
3
-
e o
y*
Z
a
5MW5
SAMS
T ftć A f/aćtŁ
Soul of CP/M*
How to Use the Hidden Power of Your CP/M System
Do you w a n t to le a rn the u niversal "system ca lls" th a t m a ke C P /M the most p o p u la r
o p e ra tin g system in the m icro co m p u te r w o rld ? W o u ld yo u lik e to k n o w h o w to pro g ra m
in 8080 assem bly la n g u a g e ? If so, read this bo o k! Using a u n iq u e a p p ro a ch , it teaches
you both C P /M system calls and 8080 assem bly la n g u a g e at the sam e tim e !
Y our vo ya g e o f discovery w ill ta ke you d e e p inside C P /M to its Soul. Y o u 'll d iscover h o w
to m o d ify BIOS so y o u r C P /M system w ill run w ith d iffe re n t p e rip h e ra ls, h o w to in te rfa ce
8080 program s to BASIC, h o w to access the disk system, a n d m uch m ore. A n d , it's easy to
le a rn , using o u r n e w c o d e -fra g m e n t a p p ro a ch w ith DDT. If y o u 're re a d y to a d va n ce
be yo n d sim p ly ru n n in g a p p lic a tio n program s, then this b o o k is fo r you!
• Learn 8080 A ssem bly Language P rogram m ing
• Find out h o w C P /M re a lly w orks
• G et started fast w ith our easy DDT C ode-F ragm ent a p proach
• D iscover h o w to use C P /M System Calls
• Access C P /M fro m BASIC
• Learn h o w to M o d ify BIOS
The W aite G roup is a San R afael, C a lifo rn ia based p ro d u ce r o f h ig h q u a lity books on

personal c o m p u tin g . A c k n o w le d g e d as a le a d e r in th e indu stry, the W a ite G ro up has
w ritte n an d p roduce d o v e r th irty titles, in c lu d in g such best sellers as U N IX P rim er Plus,
C o m p u te r G ra p h ics P rim er, C P /M P rim er, a n d S o u l o f C P /M . In te rn a tio n a lly kn o w n
and a w a rd w in n in g , W a ite G ro u p books are d istrib u te d w o rld w id e , and ha ve been
re p a cka g e d w ith th e products o f such m a jo r com panie s as Epson, W ang , X erox, Radio
Shack, NCR, a n d Exxon O ffic e Systems. M r. W a ite , P resident o f the W a ite G ro up, has
been in v o lv e d in the C om p uter Industry since 1972 w h e n he b o u g h t his first A p p le I
c o m p u te r fro m S teven Jobs.
Robert Lafore is M a n a g in g Editor o f th e W a ite G ro up, a co m p a n y w h ic h produces

c om pute r books in San R afael, C a lifo rn ia . M r. Lafore has w o rk e d w ith com puters since
1965, w h e n he firs t le a rn e d assem bly la n g u a g e on the DEC PDP-5. He has
p ro g ra m m e d on m a ny d iffe re n t m achines, a n d is flu e n t in a v a rie ty o f com pute r
languages. He holds degree s in m a them atics and e le c tric a l e n g in e e rin g , and is the
co-a u th o r o f S ou l o f C P /M , an assem bly la n g u a g e bo ok fo r C P /M systems. M r. Lafore
fo u n d e d In te ra c tiv e Fiction, a c o m p u te r g a m e com pany, a n d has also been a
p e tro le u m e n g in e e r in Southeast A sia, a n o ve list, a n e w sp a p e r colum nist, a systems
e n g in e e r fo r the U n iversity o f C a lifo rn ia 's Law rence B erke le y Laboratory, and has
s a ile d his o w n b o a t to th e South Pacific.
Howard W. Sams & Co.

A Division o f M acm illa n , Inc.
4300 West 62nd Street, Indianapolis, IN 46268 USA o 81262 22030
$19.95/22030 ISBN: 0-672-22030-X

Soul of CP-M

Uploaded by

Copyright:

Available Formats

Soul of CP-M

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Soul of CP-M

Uploaded by

Copyright:

Available Formats

SOUL OF CP/M ®

(How to Use the Hidden Power of Your

Mitchell W aite and Robert Lafore

Howard W. Sams & Co.

All rights reserved. N o part of this book shall be repro­

International Standard Book Number: 0-672-22030-X

Edited by: Frank N. Speights

Printed in the United States o f America.

C P /M is the registered trademark of Digital Research, Inc., Pacific Grove, CA

Dedication by Robert Lafore

What do we mean by the “Soul” of C P/M ? One of C P /M ’s most pleasant

WHO IS THIS BOOK FOR?

This book is aimed primarily at BASIC or other high-level language pro­

WHAT THIS BOOK WILL TEACH YOU

between I/O devices and computers, it is almost always necessary to write a

8080, 8080A, 8085, Z-80: WHAT’S THE DIFFERENCE?

WHAT YOU NEED TO KNOW TO GET THE MOST OUT OF

HOW THIS BOOK IS ORGANIZED

WordStar is the registered trademark of MicroPro™ International Corp., San Rafael, CA

HOW TO ENJOY THIS BOOK

The Big Picture

In this chapter, we’re going to talk, in very general terms, about C P /M

WHAT IS AN OPERATING SYSTEM, ANYWAY?

WHAT’S SO GREAT ABOUT CP/M?

An analogy may make clearer what we mean by “program transportabil­

to be as similar to one another as possible. Thus, the furnishings, the interior

The “system call” is the connection between a program operating in a

The subroutine that a particular program calls will be different, depend­

User’s Program Interchangeable with

System System calls are always

/ ... / / / This part ot CP/M is always

Fig. 1-1. How CP/M is organized.

The preceding ideas can be summarized in what is sometimes called

THE PARTS OF CP/M

The C P /M operating system is divided into several parts, each of which

Fig. 1-2. The parts of CP/M.

these subroutines which must be modified when the hardware is changed in a

Fig. 1-3. CP/M is like an onion.

As you already know, a com puter’s memory consists of a large number of

(M emory co n tin u e s on down to 0000 hex)

The program, which consists of a list of instructions, each of which is rep­

There is another place a program can store data; it is in special hardware

Fig. 1-5. Three instructions stored in memory.

faster than a memory location, which is on a separate memory chip located

Fig. 1-6. The p rin cip a l 8080 registers.

8 bits wide ► 8 bits wide

Fig. 1-7. The prin cip a l parts o f the 8080 m icroprocessor.

DDT—THE PROGRAMMER’S X RAY AND PROBE

adecimal conversions in Appendix A.) However, even this is hard to remem­

Fig. 1-8. N um ber conversion.

BACK DOWN TO EARTH

One Toe in the W a te r

routines in BIOS (the Basic Input/O utput section of C P/M ) to communicate

CONSOLE OUTPUT SYSTEM CALL

CONSOLE OUTPUT FUNCTION 2 (dec) = 2 (hex)

Enter with: REG C = 2

1. Put the number 2 in the C-register.

Your First Program

Each of the three lines in the preceding program is called a “statement.” As

All rights reserved. N o part of this book shall be repro

This book is aimed primarily at BASIC or other high-level language pro

An analogy may make clearer what we mean by “program transportabil

The subroutine that a particular program calls will be different, depend

The program, which consists of a list of instructions, each of which is rep

adecimal conversions in Appendix A.) However, even this is hard to remem

“MVI” is an instruction that means “move immediate.” The word “imme

Since 0 is where the computer automatically goes to do a warm boot, typ

A JM P instruction is just like a GOTO in BASIC. When the program exe