Sams Commodore 128 User manual

UDWJ8S!8H ., P!ADC
S.I8WWD.1&0.1d .101
ap1n0 8)U8.1818ll
®8~l 8.10pOWWO)
PNrfS

Commodore 128
Reference
Guide
for Progrommers
David L. Heiserman
Howard W. Sams & Co.
A Division of Macmillan, lnc.
4300 West 62nd Street, lndianapolis, IN 46268 USA

© 1986 by David L. Heiserman
FIRST EDITION
FIRST PRINTING-1986
All rights reserved. No part of this hook shall be reproduced, stored in a
retrievalsystem, or transmitted by any means, electronic, mechanica!,
photocopying, recording, or otherwise, without written permission from the
publisher. No 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 hook, the publisher and author assume 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-22479-8
Library
of Congress Catalog Card Number: 86-60936
Acquisitions Editor: Greg Michael
Editor: Katherine Stuart Ewing
Designer:
T. R. Emrick
Illustrators: Don Clemons
and Ralph E. Lund
Cover Artist: Gregg Butler
Compositor: Shepard Foorman Communications, Indianapolis
Printed in the United Statesof America
Trademark Acknowledgments
All terms mentioned in this book that are known to be trademarks or service
marks are listed below. In addition, terms suspectedof being trademarks or
service marks have been appropriately capitalized. Howard W. Sams & Co.
cannot attest to the accuracy of this information. Use of a term in this
book should not be regarcled as affecting the validity of any trademark or
service mark.
CP/Mis aregistered trademark of Digital Research, Inc.
Amiga,
Commodore 64, and Commodore 128 are registered
trademarks of Commodore Electronics, Limited.

Contents
Preface
ix
1 General Operating Procedures 1
The Three Main Operating Modes 2
Getting Familiar with the Keyboard 8
Quote-Mode Operations 16
Essential
Disk Operations 17
2 BASIC Operations and Programming Procedures 23
Numeric and String Constants for BASIC 24
Numeric and String Variables in BASIC 28
Operators for Commodore BASIC 34
BASIC 7.0 Commands, Statements, and Functions 43
Keyboard Abbreviations of BASIC Operations 92
Dealing
with BASIC Error Conditions 96
Tokenized BASIC Formats 106
3 DOS Operating and Programming Procedures 111
Preliminary Considerations 112
4
DOS-Related Commands, Functions, and Statements 113
DOS-Related
Error Conditions 115
The Disk Directory 119
Disk Pormatting Procedures 121
Procedures for Saving Programs on Disk 125
Procedures for Loading Programs from Disk 132
Procedures for Copying Disk Files 138
Procedures for Cleaning Up Disks 140
Using the TEST/DEMO DISKETTE and DOS Shell 143
Sequentia!
Text Files 144
Relative File
Procedures 150
Direct-Access
Disk Procedures 152
Monitor and Assembly Language Procedures
T~e Monitor's Hexadecimal Format 162
Essential
Monitor Operations 163
The Monitor' s Machine- Language Aids 170
161

vi Contents
5
6
Summary of 8502 Op Codes 175
The 8502 Instruction Set 180
Introduetion to CP/M Procedures
Bringing Up CP/M on the Commodore 128 202
Help for Beginners 202
Summary of CP/M Commands 206
Makinga Backup Copy of the CP/M Disk 212
Text Screen Procedures
Preliminary Considerations 216
Switching Column Formats 220
Switching Character Sets 224
Setting
the Normal/Inverse Character Format 229
Setting Screen
and Character Colors 231
Using Cursor Control Features 241
Setting Alternative Text Windows 243
Using
the Screen-Editing Features 250
Printing Text from Machine Language Programs 255
Working
with the Character Sets 264
Working Directly
with Screen Data 272
Using Alternative Screen RAM Locations 276
Writing Directly to
the 80-Column Screen 279
201
215
7 Bit-Mapped Graphics Procedures 283
Bit-Mapped Screen Formats 284
Plotting Figures
on the Graphics Sereens 290
Rescaling
the Screen 300
Saving
and Reloading Bit-Mapped Shapes 301
Setting Graphics Sereens from Machine Language Routines 304
Working Directly
with Standard Bit-Mapped Sereens 307
Working Directly
with the Multicolor Bit-Map Screen 314
8 Sprite Animation Procedures 317
9
Creating Sprite Figures 318
Saving
and Reloading Sprites 322
Specifying, Positioning,
a:qd Moving Sprites 323
Detecting Sprite Collisions' 329
Sprites
and Machine Language Routines 337
Sound and Music Procedures J
Preliminary Considerations 348 i
Using BASIC'sVOL and SOUND Staterne ts 351
Using BASIC's PLAY
and TEMPO Staterne ts 356
Using
the ENVELOPE Statement 360
Using the FILTER Statement 362
347

10
11
12
13
14
A
Contents vii
Working Directly with the SID Registers 363
Working with Sound Enhancement Registers 369
Summary of SID Registers 372
Keyboard Procedures
Keyboard Scanning Operations 378
Working with the Non-Scanned Keys 382
Using
the Keyboard Queue and GETIN 382
Using
the Main Keyboard Buffer 388
Using
the Function Keys 389
joystick, Paddle, Light Pen, and Mouse
Procedures
Joystick Procedures 394
Game Paddle Procedures 398
Printer and Communications Procedures
Printer Procedures 402
Using
the RS-232-C Communications Feature 406
Commodore 128 Memory Maps
The Lower RAM Addresses: $0000-$03FF 416
The Upper RAM-Only Area: $0400-$3FFF 437
BASIC ROM: $4000-$AFFF 443
Screen Editor ROM: $COOO-$CFFF 453
I/0, ROM, and RAM Block: $DOOO-$DFFF 456
Kernal ROM: $EOOO-$FFFF 475
Memory Management Procedures
The Standard Bank Configurations 508
Bank-Switching Statements, Registers,
and Procedures 515
Using
the BANK 1 Contiguration 521
Summary of MMU Configuration Registers 525
Bank Switching Procedures 526
Number-System Base Conversions
Hexadecimal-to-Decimal Conversions 532
Decimal-to-Hexadecimal Conversions 533
Conventional Decimal
to Two-Byte Decimal Format 534
Two-Byte Decimal to Conventional Decimal
Format 535
Binary-to-Decimal Conversion 536
Binary-to-Hexadecimal Conversion 537
Hexadecimal-to-Binary Conversion 538
Decimal-to-Binary Conversion 538
A Complete Conversion Table for Decimal
0-255 538
377
394
401
415
507
531

viii Contents
B Derived Trigonometrie Functions
Index
544
545

Preface
Like the Commodore 128 Computer, this hook can mean a lot of dif-
ferent things to different people. And like the Commodore 128, this
hook is assembied so that it can be used by a variety of users who
possess a wide range of skills and computer know-how.
• Beginners with no previous programming experience can bene-
fit immediately from the elemental topics presented in the first
two chapters--how to operate the computer and how to write
programs in BASIC.
• Readers already familiar
with other personal computers and BA-
SIC can note in the first two chapters the differences and move
quickly to special applications topics in the remaining chapters.
• Readers
who have already mastered BASIC and 6502 machine
language programming from other sourees can note the en-
hancements builtinto the new version of DOS (Chapter 3) and
the machine-language monitor (Chapter 4).
• Readers
who have the desire to use CP/M in a Z-80 or 8080A
environment will be pleased to find that the Commodore 128
supports it. A Z-80 microprocessor is built into the system and is
fully
dedicated to the CP/M features that are briefly described in
Chapter 5.
Chapters 2 through 5 deal with the eight programming formats
available on the "stock" Commodore 128-BASIC (actually both
BASIC 2.0 and 7.0), DOS (the new Commodore disk operating sys-
tem),
the machine language monitor and 8502 machine/assembly lan-
guage,
and CP/Mand Z-80/8080A machine language programming.
Chapters 6 through 12 describe the individual features of the
Commodore 128 system. A reader who wishes to study sprite anima-
tion or RS-232-C communications procedures, for example, will find
complete descriptions of those subjects
in Chapters 8 and 12, re-
spectively.
Chapter 13 is a memory map of the Commodore 128 system.
This
chapter outlines the principal blocks of memory, describes the
most important registers, and summarizes the built-in Kernal routines
that are readily available to the programroer.

x Preface
Chapter 14 deals with procedures for rnanaging the entire 128K
of memory.
Wherever possible, each principle cited in the hook is
first demonstrated
in a format that should be familiar to most read-
ers-in BASIC; then the sameprinciple is illustrated in termsof moni-
tor and machine-language programming.
The use of
many examples written in 8502 assembly language
directly reflects
the fact that the Commodore 128 is designed to
encourage machine-language programming
and calls to Kernal sub-
routines.
Unlike
much of the early literature dealing with the Commo-
dore 128, no underlying assumption is made
that the reader is already
familiar
with the features and quirks of the earlier Commodore per-
sonal computers, notably the Commodore 64.
I believe
that paying twice the suggested retail price for this sys-
tem would be a bargain. The Commodore 128 is a powerful system
that stands on its own merits and promises to engage a lot of users
who have no previous experience with earlier Commodore systems.
DAVID L. HEISERMAN

1
General
Oparating
Procedures

2 Commodore 128
The m1mmum Commodore 128 system consists of a console-key-
board unit, an external power supply for the console, a display unit,
and a disk or cassette-tape unit. The power supply is included with
the console, and the remairring items are available separately.
You should count on using one of Commodore's own disk or
cassette-tape units. Most discussions in this book assume you are
using the Commodore 1571 disk drive, but you will find references to
other Commodore disk drives and cassette-tape units where such ref-
erences are particularly relevant.
Unlike the disk and cassette-tape units, you are not strictly
bound to use a Commodore display (monitor). If you choose not to
use a Commodore display, you can get the full benefit of the video
features by using a high-resalution color monitor that includes both
composite-video and RGB (separate red-green-blue) inputs. The RGB
conneetion is absolutely necessary for displaying text in the 80-
column format.
A color monitor that uses only the composite-video conneetion
is less expensive than the models that include the RGB feature, but
composite video units are adequate for all 40-column text and graph-
ics applications.
Y ou can use an ordinary co lor TV set as the display unit. The
video quality is not quite as good as that of a composite-video moni-
tor, and TVs lack the RGB feature that is necessary for displaying 80-
column text.
The connectors on the Commodore equipment are clearly and
meaningfully labeled as shown in Figure 1-1.
Understand that the grooves cut across the housings for the con-
sole
and disk drive are air vents. Although you may be tempted to
stack disks, papers and books on those attractive, flat surfaces, do not
do so. Blocking the vents can cause serious overheating problems that
will greatly reduce the working life of the units.
The Three Main Oparating Modes
Many of the features of the Commodore 128 computer can be de-
scribed in the context of its three main operating modes:
• C128 mode
• C64mode
• CP/Mmode
These three operating modes are so distinctly different that you
may be convineed that they represent three entirely different com-
puter systems.
C128 mode is the default operating mode. That is, the Commo-

PORT
(PROGRAM
CARTRIDGES)
CONTROlLER
PORT
1
SERlAL
PORT
TV
CHANNEL
SELECTOR
SWITCH
USER
PORT
3
__,.
<D
-n
1\.)
0
::J
-·
co
::J
-+
cp
ooQ.7'
Ooo
....
~30)>
Q.3~~
<Do
<Do
cO.O:J
::J
0
-+(Q
:::;:
.....
Q<D
cn<Dcn,
~
g
;-,:
;-,:
~
;;;
.....
w
Oo
...,
o\5"
::;
~
-=
(ij•
~
:§
g
;-,: ;-,:
~
;;; ,....
w
Oo
;;; 1:>
...,
-=
(ij•
~
G)
CD
::J
CD
g_
~
a
5-
(Q
a
0
CD
~
(J.)

4 Commodore 128
Fig. 1-2 Heading
message that
appears when
system
is first set to
C128 mode. Border
and characters are
light green and
background is
dark gray
dore 128 computer starts and runs in C128 mode unless directed oth-
erwise-either from the keyboard or programmed commands. If you
have any intention of using or writing programs that function in C64
and CP/M modes, understanding their essential features and how to
switch from one mode to another is vital.
Features of C128 Mode
C128 mode is unique to the Commodore 128 personal computer sys-
tem. This mode is the system's default mode and is the subject of
most of the discussions in this book. In fact, you can assume any dis-
cussionconcerns C128 mode unless clearly stated otherwise.
One essential feature of C128 mode is Commodore's enhanced
BASIC interpreter, version 7.0. That language is builtinto the system
as non-destructible, read-only
memory (ROM) and is readily available
without having to load any kind of external programming. Turning on
the computer automatically sets up the system for running BASIC 7.0
in C128 mode and so does operating the Reset pushbutton. Bath opera-
tions bring
up a screen display similar to the one shown in Figure 1-2.
r COMMODORE
BASIC V7.0 122365 BYTES FREE
(C) 1985 COMMODORE ELECTRONICS, LTD.
(C) 1977 MICROSOFT CORP.
ALL RIGHTS RESERVED
....,
..J
This display confirms that the system is running BASIC 7.0 and,
by inference, in C128 mode as well. The screen also indicates that the
C128 mode takes advantage of the full range of built-in random-
access memory (RAM).
C128
mode also supports:

GenerolOperotingProcedures 5
• the full range of keyboard operations
• a choice of 40-
or 80-column text sereens
• a machine-language monitor mode, including a disassembler
and a mini-assembler
• high-speed, double-sicled 1571 disk
drives
• RGBvideo
• a mouse
• joysticks
and game paddies
• a light pen
• RS-232-C I/0, including telephone communications via an exter-
nal modem àccessory
• Commodore Datasette
tape player-recorder
• serial
output for other accessories such as a line printer
In short, C128 mode takes full advantage of all features built
into the Commodore 128 console unit. The two other major operating
modes, C64
and CP/M, are actually subsets of the C128 mode.
C64Mode
C64 mode reconfigures the Commodore 128 to work like its predeces-
sor,
the Commodore 64 personal computer. The internal workings of
the Commodore 128 are significantly different from those of the older
Commodore 64, and a good many programs developed for the 64 can-
not run properly on the 128. Rather than allow all Commodore 64
software
to become instantly obsolete, Commodore decided to in-
clude
the C64 mode-one that properly runs all software developed
over the years for the Commodore 64 system. C64 mode is built ihto
the system and does not have to be loaded from an external souree of
programming.
Commodore didn't forget about the disk drive, either. The 1571
disk drive
recommended for the Commodore 128 computer is quite
different from the 1541 model commonly used with the older Com-
modore 64. The 1571 disk drive is "smart" enough to know what
kind of disk your computer is using. If your disk happens to be one
that was originally formatted on a 1541 drive, the computer automati-
cally
makes appropriate adjustments. (The 1571 disk drive actually is
a small, microprocessor-based
computer in its own right.)
The Commodore 128 does not enter C64 mode unless the com-
puter is directed to do so. As described previously, the system always
starts in C128 mode. Getting into C64 mode is a simple matter of exe-
cuting this
command:
G064

6 Commodore 128
Fig. 1-3 Heading
message that
appears when
system
is first set to
C64 mode. Border
and characters are
light blue and
background is
dark blue
When you type G064 and press the RETURN key, the system
prompts ARE YOU SURE? If you do indeed want to go to C64 mode,
pre ss the Y key and then the RETURN key.
Mter a short delay, the screen changes to the blue colors that
characterized the Commodore 64 system and displays the heading
shown in Figure 1-3.
L.
**** COMMODORE 64 BASIC V2 ****
64K RAM SYSTEM 38911 BASIC BYTES FREE
.....,
The heading confirms that the system is operating as a Commo-
dore 64
and shows that the amount of available memory has been
reduced to the level of the older system.
An alternative
way to go to C64 mode is to hold down the
"Commodore key" (the Or key in the lower-left corner of the key-
board)
when you turn on the power to the computer. This procedure
takes the system directly to C64 mode.
The material
in this book is directed toward the wider range of
features available
in C128 mode. Users whowant to use C64 features
should consult
other resources such as Commodore 64 Programmer's
Reference Guide (Sams #22056).
The simplest
and most effective way to return to C128 mode
from C64 mode is by operating the Reset pushbutton.
CP/M Mode
CP/M mode configures the Commodore 128 to run as an entirely dif-
ferent
kind of computer. This mode bypasses the 8502 microproces-

Fig. 1-4 Heading
message that
appears when
system is eperating
in CP/M mode.
Border is brown,
background is
black, and
characters are
purple
GeneralOperating Procedures 7
sor used for the other operating modes and switches in an entirely
different microprocessor, Z-80.
Unlike C128
and C64 modes, CP/Mis not an integral part of the
system. CP/M must be loaded into RAM from the CPIM System Disk.
Assuming that the system is currently operating in C128 mode, the
general procedure for getting into CP/M mode is as follows:
1. If you can run 80-column text on your system, set the monitor
for RGB input and latch down the 40/80 DISPLAY key. CP/M
can be run on a 40-column screen, but you can see only half the
display at any given time.
2. Insert the CP/M System Disk into the disk drive.
3.
Operate the system Reset pushbutton or enter the BOOT
command.
After a short delay and some changing screen displays, the sys-
tem setties in to CP/M mode. The screen generally has a brown bor-
der,
black background, and purple characters. The heading shown in
Figure 1-4 and the A> prompt characters confirm that the system is
ready.
CP/M 3.00n the Commodore 128
80 column display 1
AUG 85
Bear in mind that CP/M mode transfarms the Commodore 128
into a different
kind of system. Many of the key fundions are quite
different, and the I/0 fundions are defined in entirely different ways.
Chapter 5 in this book can help you become oriented in the CP/M

8 Commodore 128
environment, but you will have to consult other sourees for addi-
tional information. Consider, for instance,
the CP/M order card that is
included
in your Commodore 128 Personal Computer System Guide.
You can return to C128 mode by first removing any sart of
CP/M disk from
the drive, then operating the Reset pushbutton.
Getting Familiar with the Keyboard
After the computer is properly started in the C128, BASIC 7.0 mode,
the system prints the following prompt:
READY.
foliowed by the text cursor-a blinking rectangle. Those two ele-
ments on the screen indicate that the system is ready to accept BASIC
cammancts
and other key functions from the keyboard.
Much of the material in this book deals with the nature of
BASIC commands. The computer is virtually useless without some
commands. Unless
they are loaded in the farm of prescribed pro-
grams from a disk, cammancts
must come directly from typing opera-
tions
at the keyboard.
As indicated
in Figure 1-5, most of the keys on the Commodore
128 keyboard are identical to those of a conventional typewriter,
and
can serve the samegeneral purpose. However, some keys are irrele-
vant for ordinary typing operation but are quite important for operat-
ing
the computer.
The RETURN key is perhaps the most frequently used computer
key. Y
au must press this key when you want the computer to execute
a
cammand that you've typed. When you are ready to execute a BASIC
program, for example, type RUN on the keyboard, then press the
RETURN key, and the computer reacts and executes that program.
The keyboard includes 26 keys for the letters of the alphabet.
The top surfaces of
the keycaps show those letters in an uppercase
farm.
When the computer is turned on, pressing the alphabetic keys
prints uppercase characters
on the screen.
The two SHIFT keys serve
much the same function as the shift
keys
on an ordinary typewriter. Pressing the 3 key while notholding
down either SHIFT key prints that numenil to the screen. Pressing the
same key while holding down one of the shift keys prints the upper-
case character
shownon the keycap, a pound sign (#), to the screen.

o-
!
(])
()
~
Ol
:§
!
e
(])
~
I I C
~._________,
nlOij
o~
~[±]Q[]JQQQGJJQQGJQGJJQJQJ
UQQQ
~
N0013H~Q[J]OJOJQQQ)G)J(QGJJQQ~~
QQQQ
QQQQQQOJGQQQQQ~g
QQQQ
[Gi]rti]QQQ[jj[J][]J[][][][]J[]OJJ r
~·
IQ
Q QQ I
IEJHEJJ
m
mI
[;]
[Q]
C
[J
'00"0
0 N
"-
E..,..
o
E
<D
o
0"-.0
0
0>-
"0<D
IQ
:x.
"""'
0)
i.i:
~lMOd
=

10 Commodore 128
Pressing alphabetic keys without holding down one of the
SHIFT keys normally prints uppercase letters, so you might suppose
that holding down a SHIFT key while pressing one of the alphabetic
keys
would print a lowercase character, which is not necessarily the
case. In fact, holding down a SHIFT key while pressing alphabetic
keys
prints special graphics characters to the screen-one of the
graphics characters appearing on the front surfaces of the keycaps.
The system can print both uppercase and lowercase letters, but
only after you press the C• key (located at the lower-left corner of
the keyboard) while holding down one of the SHIFT keys. Once
you've done that, you can print both upper- and lowercase letters of
the alphabet in the same way as you do with a typewriter. Pressing
the C• key while holding down a SHIFT key returns the system to
the normal uppercase/graphics format.
When operating in the 40-column mode, switching the charac-
ter-set format changes all
characters currently on the screen as well
as those subsequently written to it. The 80-column mode supports
both character sets at the same time, so changing the character-set
format does not affect any text already printed to the screen. This
change affects only
the characters printed after the change takes
place.
Using ESC, CONTROL, and (K Functions
The ESC, CONTROL, C•, and ALT keys greatly multiply the number
of key functions that is available. These keys do nothing when used
alone. They must be used in conjunction with a second key. The
CONTROL key, for example, works in a fashion similar toa SHIFT
key: it
has no effect unless you press it while pressing another key.
As a simple example of
how the CONTROL key works, hold it
down while pressing the G key. This combination of keystrokes pro-
duces the system's bell sound.
CONTROL-key
where key is some other key operation. For example, the technique
for sounding the beU-holding down the CONTROL key while press-
ing
the G key-is presented as:
CONTROL-G
The Commodore key, C•, works the same way: hold down this
key while pressing some other key. Consicter the following notation:
C•-8

General Operating Procedures 11
The notation instructs you to hold down the C• key while press-
ing
the 8 key. C•-8 instructs the system to plot all subsequent ebar-
aeters
in light gray. Y ou can return to the normal light green by
pressing a C•-6.
NOTE: Invoke CONTROL and C• functions by holding
down the key while pressing some other designated key.
The general notation used tbraughout this book is:
CONTROL-key and C•-key
where key is some other designated keystroke.
The ESC key is used in a somewhat different manner. Instead
of holding down the key while pressing another, the procedure is
divided into
two separate steps: press the ESC key, release it, then
press a second key. The general notation used in this book is:
ESC/key
where key is some other designated key.
The following ESCape function, for example, farces the system
to show the text cursor as a non-blinking rectangle:
ESC/E
First press the ESC key, release it, then press the E key. This opera-
tion disables
the cursor's normal blinking mode. Use the following
ESC function
to restare the normal blinking effect:
ESC/F
NOTE: Invoke an ESCape function by first pressing the ESC
key, releasing it,
then pressing some other designated key.
The general notation used throughout this book is:
ESC/key
where key is some other designated keystroke.