Commodore Plus/4 User manual

Programmer's Reference Guide for the
Commodore Plus /4
Cyndie Merten • Sarah Meyer

Programmer's
Reference Guide
for the
Conunodore Plus/4

Programmer's
Reference Guide
for the
Commodore Plus/4
Cyndie Merten
Sarah Meyer
SCOTT, FOKESMAKT AND COMPANY
Glenview, miaols London

Graphics characters that appear in Table 3-1 and Appendixes C and E are used with permission of Commodore
Business Machines, Inc.
Copyright © 1986 Cyndie Merten and Sarah Meyer.
All Rights Reserved.
Printed in the United States of America.
ISBN 0-673-18249-5
Library of Congress Cataloging-in-Publication Data
Merten, Cyndie.
Programmer's reference guide for the Commodore
Plus/4.
Includes index.
1. Commodore Plus/4 (Computer)—Programming.
2. BASIC (Computer program language) 1. Meyer, Sarah C.
II. Title.
QA76.8.C65M47 1986 005.2'65 85-18409
ISBN 0-673-18249-5
2 3 4 5 6-RRC-90 89 88 87 86
The following are trademarks of Commodore Business Machines, Inc.: Commodore and the Commodore
logo, Commodore Plus/4, Commodore 16, Commodore 64, VIC-20, VIC-1541, 1531 Datassette, C2N/1530
Datassette, Modem/300 Model 1660, MPS-801, Joystick T-1341, VIC-1526, VIC Modem 1600,
Automodem 1650. The following is a registered trademark of Parker Brothers: Boggle.
Notice of Liability
The information in this book is distributed on an "As Is" basis, without warranty. Neither the author nor
Scott, Foresman and Company shall have any liability to customer or any other person or entity with
respect to any liability, loss, or damage caused or alleged to be caused directly or indirectly by the programs
contained herein. This includes, but is not limited to, interruption of service, loss of data, loss of business or
anticipatory profits, or consequential damages from the use of the programs.

Preface
The Commodore Plus/4 represents an important advance in home computer
design. The low-priced Plus/4, which Commodore refers to as its productivity
computer, includes significant improvements over the phenomenally popular
Commodore 64 and over any other computer in the home computer class. The
built-in features include an expanded version of BASIC (Version 3.5), a machine-
language monitor, graphic-drawing commands, improved disk- and error-
handling commands, and integrated software that combines three programs:
A word processor
A spread sheet, with a graph generator linked to it
A file manager
The built-in programs are accessed by a function key.
The Plus/ 4 has 64 K RAM built in, 60671 bytes of which are available for use in
BASIC. The Plus/4 also has eight defined function keys that are easy to redefine
with the KEY command. Escape key functions simplify screen editing tasks and
let you create screen windows. The Plus/4 also has simple color settings that let
you select from 121 different hues. In addition, the graphics modes let you use the
drawing commands to draw pictures in high-resolution or multicolor modes. You
can also select split-screen graphics modes that display regular text in a five-line
screen window while the top of the screen is in a graphic mode. Graphic handling
is much easier in BASIC Version 3.5 than it is in the Version 2.0 built into the
Commodore 64.
Although the Plus/4 is superior to the Commodore 64, it does have one
disadvantage: a full library of software is not yet available for the Plus/4. In
addition, the Plus/4 does not have sprite graphics, which are available on the
Commodore 64, and the Plus/4 music features are not as sophisticated, although
music is easier to program.
When Commodore introduced the Plus/4, it was called the Commodore 264.
The name was changed to Plus/4 when Commodore decided to include the
built-in integrated software. At the time of the name change, Commodore also

vi Preface
announced the Commodore 16, which is compatible with the Plus/4. The Com
modore 16 has only 16 K RAM and no built-in software. The two new computers
are compatible, so all Commodore 16 software and peripherals are compatible
with the Plus/4.
About This Book
The Programmer's Reference Guide for the Commodore Plus/4 is a reference
book for programmers of all levels. The book provides information for both
BASIC and machine language programmers. The authors assume that readers
are familiar with the general operations of the Plus/4 and understand all the
keyboard functions. Neither BASIC nor machine language is taught in this book,
but extensive information is provided on programming in both languages. Pro
grammers of either BASIC or machine language will find the information they
need to write programs for themselves or for commercial distribution.
The authors have written and tested all the programs in this book. (Please note
that the programs are copyrighted and cannot be used for commercial purposes.)
Cyndie Merten, programmer and mathematician, is a founding member of
Dyadic Software Associates, a group of microcomputer consultants. Sarah
Meyer is a free-lance technical writer who has published another book about the
Plus/4. Together they have published several articles about Commodore comput
ers. The authors combine their perspectives as programmer and writer to produce
a book that is thorough, technically accurate, and clearly written. Please note that
Commodore Business Machines, Inc. has not been involved in the preparation of
this book. The authors bear responsibility for the accuracy of the material
presented here.
The Programmer's Reference Guide for the Commodore Plus/4 is divided into
six chapters. The chapters cover BASIC, the built-in software, programming
techniques, machine language, graphics, and peripheral devices. Memory maps
and other technical information are covered in the appendixes.
Chapter 1, The BASIC Language, provides complete descriptions of all 75+
commands, 36 functions, and the system variables that constitute BASIC 3.5. To
simplify looking up BASIC keywords, the elements of BASIC 3.5 are presented
in alphabetical order, with commands, functions, and system variables inter
mixed. For each keyword, the following information is given:
1. The abbreviation (when there is one).
2. A complete syntax, so you can quickly review the order of parameters.
3. A description of all uses for the command or function.
4. An explanation and range of possible values for each parameter.
5. Examples.

Preface vii
Graphics commands are given additional coverage in Chapter 4, Programming
Graphics. Commands for controlling peripherals are also discussed in Chapter 6,
Using Peripheral Devices. Chapter 3, Some Programming Techniques, also
provides more information on BASIC commands.
The commands for use in the built-in programs are explained in Chapter 2, The
Built-in Software. Chapter 2 is divided into four sections: word processor com
mands, commands for formatting printed output, spreadsheet commands
(including commands for controlling the graph generator), and file manager
commands. Within each section, commands are explained in alphabetical order.
Examples are given where appropriate.
Chapter 3, Some Programming Techniques, is a collection of sections on
diverse programming topics. Both BASIC and machine-language programming
techniques are discussed. Sections include coverage of the following topics:
Editing the screen
Using the Escape key screen-editing functions
Using screen windows
Using text strings
Redefining the function keys
Using mathematical functions
Programming sound and music
Using arrays
Error handling
Chapter 4, Programming Graphics, explains the operations of the graphics
modes in both BASIC and machine language. Color and screen control, drawing
commands, and animation are among the topics discussed in this chapter. Many
example programs are also provided.
Chapter 5, Machine Language on the Commodore Plus/4, explains the use of
the built-in monitor commands and the application of 6502 machine-language
programming on the Plus/4. This chapter does not teach machine language, but
it does review the instruction set and describe the operating system for machine
language programmers of all levels.
Chapter 6, Using Peripheral Devices, describes the operations of the disk drive,
cassette recorder, printers, modem, and joystick in BASIC and machine lan
guage. Each peripheral, and the commands that control it, is explained in a
separate section. Particular attention is given to disk-handling operations. Disk
operating system (DOS) error messages are explained in Appendix A.
The appendixes are provided to explain additional technical information and
to provide quick reference material. The six appendixes cover error messages for

viii Preface
BASIC and DOS errors, BASIC tokens, character string (CHR$) codes, ASCII
codes, screen display codes, a musical note chart, and memory and register maps.
The Programmer's Reference Guide for the Commodore Plus/4 also contains
an extensive index that is designed to make finding information in this book
quick and easy. We advise users to consult the index first when seeking specific
information.
The authors have taken great care to ensure accuracy and thoroughness in the
topics that are presented in this book. We cannot guarantee, however, that the
book is error free. We have tried to make the book easy to use and understand,
and we hope you find it helpful and instructive. We welcome your comments and
corrections.

Acknowledgments
The authors thank Bill Hindorff for reviewing this manual. We are grateful for his
suggestions and constructive criticism.
We thank COMMODORE Magazine for publishing a Plus/4 memory map in
their November/ December 1984 issue and Jim Butterfield for sharing his map in
Transactor (Volume 5, Issue 5).
Also of great assistance in preparing the disk drive section of this manual was
Richard Immers and Gerald G. Neufeld's book, Inside Commodore DOS.
ix

The BASIC Language
This chapter contains information on each of the BASIC commands, functions,
and system reserved variables. Other important details about BASIC are
included in the beginning sections.
The Elements of BASIC
The BASIC built into the Plus/4 is called Version 3.5. This version of BASIC is
considerably more sophisticated than the Version 2.0 built into the Commodore 64.
Version 3.5 contains about twice the number of BASIC commands and is easier
to use.
This chapter explains each of the 75+ BASIC commands in Version 3.5. In
addition, all BASIC functions are explained. The functions and the commands
are explained together in alphabetical order. The possible parameters of all
commands and functions are discussed. For some commands, such as the draw
ing commands, you must type a place-holder comma when you use the default
value for a parameter. Be sure to note the requirements for each command.
BASIC lets you perform a large variety of tasks; despite this versatility, BASIC
has very strict syntax rules. You must enter commands according to their formats
and use only legal parameters. When you make a mistake, BASIC usually aborts
the program and displays an error message. Appendix A explains the error
messages that BASIC prints to help you diagnose your mistakes. The description
of the HELP command explains how to use the HELP key to find errors in
programming lines.
Note the following definitions if you are unsure of some terms:
Keyword A keyword is a word that is reserved as part of BASIC. Keywords
include commands, parts of commands (such as TO, which is part of the FOR
command), operators, function names, and certain reserved variables such as
TI$, a hardware timing value, and ER, an error-diagnosing variable. Keywords
cannot be used as variable names or be embedded in variable names.
1

Z The BASIC Language
Function A function is a text string or numeric operation that returns a value.
You can use any of the functions that are part of BASIC, and you can create your
own with the DEF FN command.
Operator We use the term operator to mean a symbol or keyword (such as
AND) that performs a mathematical task or compares two values. The types of
operators available in BASIC are mathematical, comparison, and logical.
Parameter A parameter is a nonkeyword part of a BASIC command or func
tion. Parameters usually have multiple possible values. You supply the parameter
to define the way you want to use the BASIC command. Some parameters must
be used in a command and many others are optional.
Default Some parameters have a default value, which means that a certain
value is automatically used for that parameter if you do not specify some other
value. To select the default value, you can generally just omit the parameter. In
some commands, such as CIRCLE, you must type a placeholder comma for a
default value if additional parameters follow the default. For example, to accept
the default value for the color source in a CIRCLE command, type a comma in
the color source position. The color source is the first parameter, so the command
could look like this: CIRCLE, 160,100,60,50.
Expression Occasionally we will use the term expression to mean a number or
string.that can be a constant, variable, or function that results in an appropriate
value.
Constants and Variables
Constants are data values that you can use in a BASIC command. Variables are
symbolic names that stand for one or more possible values in a BASIC command.
For example, in the command PRINT "TOTAL:";T, the character string TOTAL
is a constant and T is a variable that stands for the numeric value being printed.
BASIC 3.S accepts three types of constants and variables:
1. Integer numbers (whole numbers)
2. Floating-point nuijibers (decimal numbers)
3. Character strings (text)

The Elements of BASIC 3
Data T^ypes
Floating-point numbers can be any type of number, whole or decimal (decimal
numbers are also called real numbers), between 2.93873588E-39 and
1.70141183E+38, the negatives of those numbers, or zero. Floating-point
numbers are stored in RAM using a 5-byte binary format.
Integer numbers can be any whole number between -32767 and 32767. (Note
that you can use larger and smaller values for floating-point numbers.) Numbers
with decimal parts are not accepted; they are truncated and ignored by BASIC.
Integer numbers are stored in RAM in a 5-byte binary format. Numbers in
integer arrays are stored as 2-byte binary numbers.
Character strings, or text strings, can be any characters in quotes, including
numbers, blank spaces, and special symbols. The only keyboard character that
cannot be directly included in a character string is a quotation mark. This is
impossible because a quotation mark is used to begin and end strings. If you try to
type a quotation mark in a string, BASIC assumes the quotation mark signifies
the end of the string; any additional characters are assumed to be a variable name.
For example, the command PRINT "HELLO" MOM prints HELLO 0. BASIC
prints the 0 as the value for what it assumes is the variable MOM. However, a
quotation mark may be used in a string with the help of the CHR$ function. Note
that a number in quotation marks is treated like any text and has no mathematical
value.
BASIC discriminates between these three data types in variable form by the
way you name the variable. The three variable types are shown in Table 1-1 with
the symbols used to distinguish them.
Floating-point variables can stand for any type of number, whole or decimal,
between 2.93873588E-39 and 1.70141183E+38, the negatives of those numbers,
or zero. Integer variables can stand for any whole number between -32767 and
32767. (Note that you can use larger and smaller numbers for floating-point
variables.) Numbers with decimal parts are not accepted. If you assign a decimal
number to an integer variable, the decimal part of the number is ignored. For
Table 1-1. BASIC Variable Types
Floatingpoint Integer Character String
Symbol None % $
Meaning Decimal or Whole numbers Characters
whole numbers only in quotes
Examples X, X5, RX X%, X5%, AGE% S$, R5$, NAMES

4 The BASIC Language
example, if you assign 1.99 to X%, the value accepted fe*X% is 1.
part is truncated, not rounded.
Character string, or text string, variables can stand for My characters in
quotes, including numbers, blank spaces, and special symbols. The only key
board character that cannot be directly included in a character string is a
quotation mark. A number in quotation marks is treated like any text and has no
mathematical value.
Scientific Notation
Numbers can appear as simple numbers or in scientific notation. In scientific
notation, a number is reduced to its simplest one-whole-digit form. The number
of missing digits is shown in the exponent. The format for representing numbers
in scientific notation is as follows:
mantissa E sign exponent
The mantissa is a floating-point number with one whole digit (e.g., 1.55). The
E, which is the operator for scientific notation, stands for times 10 raised to the
following power. The sign is a negative or, positive sign; it indicates whether the
exponent is negative or positive. The exponent is the absolute value of the power
to which the number 10 is raised. This is always a whole number.
Both the mantissa and the exponent can be positive or negative numbers. The
following examples show how the signs of each number affect the value of the
number being represented.
Mantissa Exponent Number Example
Positive
Positive
Negative
Negative
Positive
Negative
Positive
Negative
Positive
Positive fraction
Negative
Negative fraction
1E+03
1E-03
-1E+03
-1E-03
= 1000
= .001
= -1000
= -.001
BASIC automatically displays numbers with absolute value smaller than .01 or
higher than 999999999 in scientific notation. If you enter a number outside this
range without typing it in scientific notation, BASIC rounds the number. This
rounding can cause a slightly inaccurate result if the number is used in a calcula
tion. To avoid this distortion, always enter small or large numbers in scientific
notation. In any case, BASIC can keep track of only about nine decimal digits in
the mantissa.

The Elements of BASIC 8
Variable Names
Variable names can be one letter followed by other letters or numbers, plus either
% or $ when appropriate. Note, however, that although longer variable names are
accepted, BASIC reads only the first two characters (plus $ or %) in any variable
name. Additional characters are ignored; use them only to make your program
more readable. Because BASIC reads only the first two characters, make sure all
variables in a program have unique names for the first two characters. In other
words, do not use COMPANYS and COUNTRYS as variables in the same
program unless you want them to have the same value.
Also be sure that variable names do not contain any BASIC keywords. If this
occurs, the program aborts in a SYNTAX ERROR. For example, do not use a
variable such as WORDEF, which contains the keyword DEF. Keywords cannot
appear in variable names even if they are not the first two characters.
Using Variables in Parameters
Note that in most cases a variable can be used in place of a number or text string in
a command parameter. The variable must, of course, be the right type of variable.
You can generally use a calculation in place of a number or numeric variable in a
command parameter. For example, any of the following forms is legal:
FOR X = 1 TO 5
FOR X = 1 TO A
FOR X = A TO B-l
Arithmetic Operators
Table 1-2 shows the operators that are used for solving mathematical problems.
Note that the multiplication symbol is an *, not an x, and that the exponentiation
symbol is an up arrow.
Table 1-2. Mathematical Operators
t Exponentiation
* Multiplication
/ Division
+ Addition
Subtraction and negation

6 The BASIC Language
BASIC solves compound mathematical problems in this order:
First Priority: Exponentiation
Second Priority: Multiplications and divisions
Third Priority: Additions and subtractions
Fourth Priority: Comparison operations
Fifth Priority: Logical NOTs
Sixth Priority: Logical ANDs
Seventh Priority: Logical ORs
When a problem contains more than one calculation from each priority group,
the problems of the same priority are solved left to right.
Parentheses override this priority scheme. BASIC solves parts of a problem
that are enclosed in parentheses before any other parts of a calculation. Multiple
problems within parentheses are solved according to the standard priority order.
Problems can contain multiple sets of parentheses, but you must be sure that the
number of left parentheses equals the number of right parentheses. When paren
theses are nested within parentheses, the calculations in the innermost set of
parentheses are solved first. *
Comparison, or Relational, Operators
BASIC recognizes six symbols that are used to compare two values. These
symbols, which are called either comparison operators or relational operators,
are described in Table 1-3. The comparison operators can be used to compare
constants, variables, numbers, or text strings.
Table 1-3. Comparison Operators
> The left-side value is greater than the right-side value.
< The left-side value is less than the right-side value.
= The values are equal.
<> or >< The values are not equal.
=> or >= The left-side value is equal to or greater than the right-side value.
<= or =< The left-side value is less than or equal to the right-side value.
Logical Operators
You can also use logical operators in calculations and in comparisons of values.
There are three logical operators: AND, OR, and NOT. These operators are also

The Elements of BASIC 7
called Boolean operators. Their role is to check the truth value of two values,
which may be constants, numeric variables, or calculations. A result of 0 is false,
and any other value is considered true.
Numeric values (operands) on either side of a logical operator should be
integer numbers, not floating-point numbers, so that they are between -32767
and 32767. If you use a floating-point number, it is converted to an integer
number. The result of a logical operation is always an integer value.
You can also use the logical operators to AND or OR individual bits (binary
digits) in two operands. You can use NOT to invert individual bits in a single
operand.
The following chart shows how each of the logical operators provides a result
after combining the truth values of two values. A value of -1 is used for a true
result.
-1AND-1 = -1 -1OR-1=-1 NOT-1= 0 -1 XOR -1 = 0
-1 AND 0= 0 -1OR 0 = -l NOT 0 = -1 -1 XOR 0 = -l
0AND-l= 0 0OR-l = -l 0XOR-l=-l
OAND 0=0 0OR 0= 0 0 XOR 0= 0
Logical AND
AND requires both values to be true for the result of the ANDed expression to be
true. Any other combination produces a false result. AND lets you set compound
comparisons in a conditional command such as IF or WHILE. When you join a
compound IF or WHILE command with AND, the result of the compound
comparison is false if one or both of the conditions are false. For example
10 INPUT "AGE, ANNUAL INCOME"; X, Y
20 IF X=>60 AND Y<= 10000 THEN PRINT "ELIGIBLE": ELSE PRINT
"INELIGIBLE"
RUN
AGE, ANNUAL INCOME ? 60,15000
INELIGIBLE
RUN
AGE, ANNUAL INCOME ? 65, 9900
ELIGIBLE
The IF command in the first execution is false because only one IF condition is
true (X is greater than or equal to 60, but Y is not less than or equal to 10000).
Therefore the THEN clause does not execute, and the ELSE clause does execute.
In the second execution of the program, the IF command is true because both the
first AND the second condition are true.

8 The BASIC Language
Logical OR
OR requires only one of the two conditions to be met for the compound expres
sion to be true. An ORed comparison is false only when both values are false. For
example
10 INPUT "AGE, ANNUAL INC0ME";X, Y
20 IF X=>60 OR Y<=10000 THEN PRINT "ELIGIBLE": ELSE PRINT
"INELIGIBLE"
RUN
AGE, ANNUAL INCOME ? 60, 15000
ELIGIBLE
RUN
AGE, ANNUAL INCOME ? 65, 9900
ELIGIBLE
RUN
AGE, ANNUAL INCOME ? 55, 12000
INELIGIBLE
This modification of the previous program shows the difference between AND
and OR. In the first program, the input 60 and 15000 makes the IF command false
because both conditions must be met before the IF command is true. In the
second program with OR in the IF command, the same input makes the IF
command true because only one of the two conditions has to be met for the whole
IF command to be true, the third execution shows that the only time ORed IF
commands are false is when NEITHER condition is met.
Logical NOT
NOT is somewhat different from AND and OR. NOT does not compare two
values. Instead, NOT lets you negate any value or comparison operator. For
example, we will add NOT to an IF command that compares a value to see if it is
greater than another value: IF NOT X > Y. Without the NOT, this command
checks to see if X is greater than Y. When NOT is added, this command checks to
see if X is NOT greater than Y; in other words, if X is less than or equal to Y.
When you use NOT, you must type NOT before the values you are comparing.
This may seem awkward because we would say "if X is NOT greater than Y," but