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