Atari 400, 800 Basic Reference Manual

ERROR CODES

ERROR

CODE

ERROR

CODE

MESSAGE

2

Memory Ins

ufficient

3

Va

lue

Error

4

Too

Many

Variabl

es

5

String

Length

Error

6

Out

of

Data

Error

7

Number

greater

than

32767

8

Input

Statement

Error

9

Array

or

String

DIM

Error

10

Argument

Stack

Overflow

11

Fl

oating

Point

Overflow

/

Underflow

Error

12

Line

Not

Found

13

No

Matching

FOR Statement

14

Line

Too

Long

Error

15

GOSUB

or

FOR

Lin

e Del

eted

16

RE

TURN Error

17

Garbage

Error

18

Invalid

String

Character

Note

:

Th

e foll

owing

are

INPUT/OUTPU

T er -

rors

that

resu

lt during the u

se

of

disk

dri

ves,

printers, or oth

er

accessory devices. Furth

er in-

fo

rmation is

provid

ed

with the auxilia

ry

hard

-

ware

.

19

LOAD

program Too

Long

20

Device

Number

Larger

21

L

OAD

File

Error

128

BREAK

Abort

129

IOCB

130

Nonexistent

Device

131

IOCB

Write

Only

132

Invalid

Command

133

Device or

File

not Open

134

BAD IO

CB

~umb

er

135

IO

CB Read On

ly

Error

136

EOF

137

Truncat

ed R

eco

rd

138

De

vice

Timeout

139

D

evice

NAK

140

Seri

al

Bus

141

C

ursor

Out

of Rang

e

ERROR CODE

ERROR

CODE

MESSAGE

142

Ser

ial Bus

Data

Frame Overr

un

143

Serial

bu s

data frame

checks

um error

144

DevicP

rlone err

or

145

Read aft

er

write

compare

error

146

Funct

ion

not

implemen

ted

147

In

sufficient

RAM

160

Drive

numb

er error

161

Too

many

OPEN

files

162

Disk

full

163

U

nrecoverab

le

system

data I/0 error

164

File

number mismatch

165

File

name

error

166

POINT data length

error

167

File l

ocked

168

Command

inva

lid

169

Directory full

170

Fil e

not

found

171

POINT invalid

For expl

ana

tion

of

Err

or

Mes

sages

see

Appendix

B.

TABLE OF MODES

AND

SCREEN FORMATS

Vert.

(Rows)

Vert.

(Rows)

RAM

Gr.

Mode

Horiz.

Split

Full

II

Of

Requir

ed

Mod

e Ty

pe

(Column

s)

Scre

en

Screen

Colors

(B

y tes)

0

TE

XT

40 -

24

2

993

1

TEXT

20

24

5

513

2

TEXT

20

10

12

5

26

1

3

GRA PHI

CS

40

20

24

4 2

73

4

GR

APHICS

80

40

48

2

537

5

GRA PHI

CS

80

40

48

4

1

017

6

GR

A PHI

CS

160

80

96

2

2025

7

GR

APHI

CS

160

80

96

4

3945

8

GRAPH

ICS

320

1

60

1

92

1/2

7900

MODE, SET COLOR, COLOR TABLE

SETC

OLOR

(aexpl)

De

fault

Mode or

C

olor

C

olo

r

C

ol

ors

Co

nditi

on

Re

gi

st er No .

(aex

p)

D ESC RIP

TION AN

D COMMENTS

0 COLOR data

-

LIGHT BLUE MODE 0 a

nd

1 ac

tu

ally

Cha

ra

cter

luminance (sa

m e color as

bac

kground

)

DARK BLUE ALL

TEXT

2

determines

Back

ground

WINDOWS

3

ch

aracter

to

-

BLACK

4

be plot

ted

Borde1·

ORANGE

0 COLOR

data

Cha1·acter

LI

GHT

GREEN

MODES

1 1

actually

determine

s Ch

aracte

r

DARK BLUE

a

nd

2

cha

ra

cter

to

be Ch

aracter

RED 2

3 plott

ed

Char

acte

r

BL

ACK

(

Text

Modes)

4

Backgro

und, Bord

er

ORANGE

0 1

Graphics

poin

t

LIGHT GREEN MODES

3,

5, 1 2

Graphi

cs

poin

t

DARK BLUE

and

7 2

3

Graph

ics

poi

nt

(Four-color

3

-

BLACK

Mode

s)

4 0

Gr a

phics

point

(bac

kground

defa

ult

), Border

ORANGE

MODES 4

0 1

Grap

hics

point

an d 6 1

-

(Two-color

2

-

Modes)

3

-

BLACK 4 0

Graphi

cs

point (background default),

Bor

der

LIG

HT GREEN

0 - -

DARK BLUE

1

Graphics p

oin

t lum i

nan

ce

(sa

me

col

or

as background)

MODE 8

2

0

Graphi

cs

poi

nt

(ba

ckgroun

d de liiUlt )

(1 Col

or

3

-

BLACK 2 Lumin

ances)

4

Bor

der

CONTENTS

PREFACE

vii

1

GENERAL INFORMATION

Terminolog

y

1

Special

Notations Used In

This Manual

3

Abbreviations Used

In

This Manual

4

Operating

Modes

5

Spec

ial

Function Keys

5

Arithmetic

Operator

s

6

Operator

Precedence

7

Built-In

Functions

7

Graphics

8

Sound

and

Games

8

Wrapa

round

and

Key

board

Rollover

8

Error

Messages

8

2

COMMANDS

BYE

9

CONT

9

E

ND

9

LET

10

LIST

10

NEW

10

REM

10

RUN

11

S

TOP

11

3

EDIT FEATURES

Screen E

diting

13

Control

(CTRL) Key

13

Shift

Key

13

Doub le K

ey Functi

ons

14

Cursor

Control

Key s

14

Keys

Used With

CTRL Key

14

Keys

Used W

ith

Shi

ft Key

14

Special

Function

Key s

14

Break Key

14

Escape Key

14

4

PROGRAM STATEMENTS

FOR/NEXT/STEP

15

GOSUBIRETURN

16

GOTO

17

I

F/THEN

18

Contents

iii

ON/GOSUB

20

ON!GOTO

20

POP

20

RESTORE

21

TRAP

22

5 INPUT/OUTPUT COMMANDS

Input/Output

Devices

23

CLOAD

24

CSAVE

24

DOS

25

ENTER

25

INPUT

25

LOAD

26

LPRINT

26

NOTE

26

OPEN/CLOSE

26

POINT

28

PRINT

28

PUT/GET

28

READ/DATA

28

SAVE

29

STATUS

29

XIO

30

Chaining

Programs

30

6

FUNCTION LIBRARY

Arithmetic

Functions

33

ABS

33

CLOG

33

EXP

33

INT

33

LOG

34

RND

34

SGN

34

SQR

34

Trigonometric

Functions

34

ATN

34

cos

34

SIN

35

DEG/RAD

35

Special

Purpose

Functions

35

ADR

35

FRE

35

PEEK

35

POKE

35

USR

36

7 STRINGS

ASC

37

CHR$

37

iv

Contents

LEN

38

STR$

38

VAL

38

Str

ing Manipulation

s

39

8

ARRAYS

AND

MATRICES

DIM

41

CLR

43

9

GRAPHICS

MODES

AND

COMMANDS

GRAPHICS

45

Graphics

Modes

45

ModeO

46

Modes 1

and

2

46

Mod

es

3, 5, and 7

47

Modes4 and6

48

Mode8

47

COLOR

48

DRAWTO

48

LOCATE

48

PLOT

49

POSITION

49

PUT/GET

49

SETCOLOR

50

XIO (Spe

cial

Fill

Application)

54

Assigning

Colors

to

Text Modes

54

Graphic

s Contr

ol Char

acter

s

56

10

SOUND

AND

GAME

CONTROLLERS

SOUND

57

PADDLE

59

PTRIG

59

ST

ICK

59

STRIG

60

11

ADVANCED

PROGRAMMING

TECHNIQUES

Mem or y Con

servat

ion

61

Programming

In Mac

hin

e La

ngu

age

63

APPENDIX

A

BASIC

RESERVED

WORDS

A-1

APPENDIX

B

ERROR

MESSAGES

B-1

APPENDIX

C

ATASCII

CHARACTER

SET

WITH

DECIMAL

/

HEXADECIMAL

LOCATIONS

C-1

APPENDIX

D

ATARI

400/800

MEMORY

MAP

D-1

Conte

nts

V

APPENDIX

E

DERIVED FUNCTIONS

E-1

APPENDIX

F

PRINTED

VERSIONS

OF

CONTROL CHARACTERS

F-1

APPENDIX

G GLOSSARY

G-1

APPENDIX

H USER PROGRAMS

H-1

APPENDIX

I MEMORY LOCATIONS

1-1

INDEX

117

vi

Contents

PREFACE

This

manual

assumes

the

user

has

read

the

Atari

BASIC - A Self-Teaching

Guide

or

some

other

book

on

BASIC.

This

manual

is

not

intended

to

"teach"

BASIC.

It

is a

reference

guide

to

the

commands,

statements,

functions,

and

special

applications

of

Atari® BASIC.

The

programs

and

partial

programming

examples

used

in

this

manual

are

photostats

oflistings

printed

on

the

Atari

820™

Printer.

Some

of

the

special

sym-

bols

in

the

Atari

character

set

do

not

appear

the

same

on

the

printer;

e.g.,

the

clear

screen

symbol

'~"

appears

as a " }

".

The

examples

in

the

text

were

chosen

to

illustrate a particular

function-

not

necessarily

"good"

programming

techniques.

Each

of

the

sections

contains

groups

of

commands,

functions,

or

statements

dealing

with a particular

aspect

of

Atari

BASIC.

For

instance,

Section 9

contains

all

the

statements

pertaining

to

Atari's

unique

graphics

capabilities.

The

appen-

dices

include

quick

references

to

terms,

error

messages, BASIC

keywords,

memory

locations,

and

the

AT

ASCII

character

set.

As

there

is

no

one

specified

application

for

the

Atari

Personal

Computer

System,

this

manual

is

directed

at

general

applications

and

the

general

user.

Appendix

H

contains

programs

that

illustrate a few

of

the

Atari

system's

capabilities.

Preface

vii

TERMINOLOGY

1

GENERAL

INFORMATION

This

section

explains

BASIC

terminology,

special

notations, and

abbreviation

s

used

in

this

manual,

and

the

special

keys

on

the

AT

ARI 400™

and

AT

ARI

800

™

Personal

Computer

Systems

keyboard

.

It

also

points

to

other

sections

where

BASIC

commands

deal

with

specific

applications.

BASIC:

Beginner's

All-purpose

Symbolic

Instruction

Code.

BASIC

Keyword:

Any

reserved

word

"legal" in

the

BASIC

language.

May

be

used

in a statement, as a command,

or

for

any

other

purpose.

(See

Appendi

x A

for

a list

of

all

"reserved

words"

or

keywords

in

AT

ARI BASIC.)

BASIC

Statement:

Usually

begins

with a keyword, like

LET,

PRINT,

or

RUN.

Constant:

A

constant

is a

value

expressed

as a number

rather

than

represented

by a variable

name. For

example,

in

the

statement

X =

100

, X is a v

ariable

and

100

is a constant.

(See

Variable.)

Command

String:

Multiple commands

(or program statem ents) plac

ed

on the

same

numbered

line

separated

by

colons.

Expression:

An expression

is i

my legal combination

of variables

, c

onstan

ts,

operators,

and

functions

used

together

to

compute a value.

Expressions

can

be

either

arithmetic,

logical,

or

string

.

Function:

A

function

is a

computation

built

into

the

computer

so

that

it

can

be

called

for

by

the

user

's

program. A function

is

NOT

a

statement

; it

is

part

of

an

expression.

It

is really a subroutine used

to comput

e a value which

is

then

"returned"

to

the

main

program

when

the

subroutine

returns.

COS (Cosine),

RND

(random),

FRE

(unused

memory

space),

and

INT

(integer) are examples

of

functions. In

man

y cases the v

alue

is simpl

y as

sign

ed to a variabl

e (stor ed

in

a

var

iable)

for

lat

er use.

In

other cas

es

it

may

be

print

ed

out

on the

scr

een

im-

mediately.

See Section 6

for

more

on

functions.

Examples

of

functions

as

they

might

appear

in

programs

are:

10

PF.:HH

F.l[l(

0)

(

print out

the

random

numb

er ret

urn

ed)

(add

the

value

re-

return

ed to 100 a

nd

sto

re the tota

l in

variable

X)

General Information 1

2 Gene

ral

Inf

ormation

Logical

Line: A logical

line

consists

of

one

to

three

physical

lines,

and

is

ter-

minated

either

by

a l;i#iii;lli

or

automatically

when

the

maximum

logical

line

limit

is

reached.

Each

numbered

line

in

a BASIC

program

consists

of

one

logical

line

when

displayed

on

the

screen.

When

entering a line

which

is

longer

than

one

physical

line,

the

cursor

will

automatically

go

to

the

beginning

of

the

line

when

the

end

of

the

current

physical

line

is

reached. Ifi@ii!;lllis

not

entered,

then

both

physical

lines

will

be

part

of

the

same

logical

line.

Operator:

Operators

are

used

in

expressions.

Operators

include

addition

( + ),

subtraction (-),

multiplication ( *

),

division (/), exponentiatinn

(A),

greater

than

(>), less

than

(<),equal

to

(=),greater

than

or

equal t

o(>=),

less

than

or

equal to

(

<,:::

),

and

not equal

to

( < >

).

The

logical

keywords

AND,

NOT

and

OR

are

also

operators.

The + and -operators

can

also

be

used

as

unary

operators; e.g.,

-3.

Do

not

put

several

unary

operators

in a row;

e.g.,--3, as

the

computer

will

in-

terpret

it

incorrectly.

Physical

Line:

One

line

of

characters

as

displayed

on a television

screen.

String:

A

string

is a

group

of

characters

enclosed

in

quotation

marks.

"ABRACADABRA"

is a

string.

So

are "ATARI

MAKES

GREAT

COMPUTERS"

and

"123456789"

. A

string

is

much

like a constant,

as

it

too,

may

be

stored

in

a

variable

. A

string variable

is

different,

in

that

its

name

must

end

in

the

character$.

For

example,

the

string

"AT

ARI

800"

may be

assigned

to a variable

called

A$

using

(optional)

LET

like

this:

10

LET

A$="ATAF.J

8H0"

OR

(note quot

ation

marks)

(LET is optional;

the

quotes are required.)

Quotation

marks

may

n

ot

be

used

within a string.

However, the

closing

quota-

tion

can

be

omitted

if

it

is

the

last

character

on a logical

line.

(See

Section

7 -

STRINGS).

Variable:

A

variable

is

the

name

for a numerical

or

other

quantity

which

may

(or

may

not)

change.

Variable

names may be

up

to

120

characters

long.

However, a variable

name

must

start

with

an

alphabetic

letter,

and may

contain

only

capital

letters

and

numerical

digits.

It

is adv

isable

not

to

use a ke

yw o

rd

as a

variable

name

or

as

the

first

part

of

a va

riable

name

as

it

m ay

not

be

interpreted

correctly.

Examples

of storing a value

in a variable:

LETC

123Dt..J8=

1 .

234

LETI

.

.JARIABLE112=267

.

543 LETA=1 LET

F5TH=6

. 5

LET

TH

J::;HO = 59

.

:::£19

Note:

LET

is

optional

and

may

be

omitted)

Variable

Name

Limit:

ATARI BASIC

limits

the

user

to

128

variable

names

. To

bypass

this

problem, use

individual

elements

of

an

array instead

of

having

separate

variable

names.

BASIC

keeps

all

references to a variable which

has

been

deleted

from a program, and

the

name

still

remains

in

the

variable

name

table.

SPECIAL NOTATIONS USED

IN

THIS

MANUAL

Ifthe

screen

displays

an

ERROR-4 (Too

Many

Variables)

message,

use

the

follow

-

ing

procedure

to

make

room

for

new

variable

names:

LIST

f i 1

eSPec

I'£~J

ENTER

f i 1

esPec

The

LIST filespec

writes

the

untokenized

version

of

the

program

onto a disk

or

cassette.

NEW

clears

the

program

and

the

table

areas.

The

program

is

then

re-

entered,

re-tokenized,

and a new

variable

table

is

built. (The

tokenized

version

is

Atari

BASIC's

internal

format.

The

untokenized

versions

in

ATASCII

which

is

the

version

displayed

on

the

screen).

Arrays

and

Array

Variables:

An

array

is a list

of

places

where

data

can

be

filed

for

future

use. Each

of

these

places

is

called

an

element,

and

the

whole

array

or

any

element

is

an

array

variable.

For

example,

define

"Array

A"

as

having

6

elements.

These

elements

are

referred

to

by

the

use

of

subscripted variables

such

as

A(2),

A(3), A(4),

etc. A

number

can

be

stored

in

each

element.

This

may

be

accomplished

element

by

element

(using

the

LET

statement),

or

as a

part

of

a

FOR/NEXT

loop

(see

Chapter

8).

Note:

Never

leave

blanks

between

the

element

number

in

parentheses

and

the

name

ofthe

array.

Correct

A(23) ARRAY(3) X123(38)

Incorrect

A ARRAY X123

(23)

(3)

(38)

Line

Format:

The

format

of a line

in

a BASIC

program

includes a line

number

(abbreviated

to

lineno)

at

the

beginning

of

the

line, followed

by a statement

keyword,

followed

by

the

body

of

the

statement

and

ending

with a line

ter-

minator

command

(Wi!li13key).

In

an

actual

program,

the

four

elements

might

look

like

this:

Line

Number

100

STATEMENT

Keyword

PRINT

Body

A/X * (Z

+ 4.

567)

Terminator

l;ljilt;t:•

Several

statements

can

be

typed

on

the

same

line

provided

they

are

separated

by

co

lons

(:).

See

IF/THEN

in

Section

5,

and

Section

11.

Capital

Letters:

In

this

book,

denote

keywords

to

be

typed

by

the

user

in

up-

per

case

form

exactl

y as

they are

printed

in

this

text.

Reverse-video

characters

will

not

work

except

in

the

case

of

the

RUN

command.

Here

are a few

ex-

amples: PRINT

INPUT LIST END

GOTO

GO SUB

FOR NEXT

IF

Lower

Case

Letters:

In

this

manual,

lower

case

letters

are

used

to

denote

the

various

classes

of

items

which

may

be

used

in a program,

such as

variables

(var)

,

expressions

(exp),

and

the

like. The

abbreviations

used

for

these

classes

of

items

are

shown

in

Table

1.1.

General

Information

3

ABBREVIATIONS USED IN THIS MANUAL

4 General Information

Items

in

Brackets:

Brackets, [ ],

contain

optional

items

which

may

be

used

,

but

are

not

required.

If

the

item

enclosed

in

brackets

is

followed

by

three

dots

[exp, ... ],

it

means

that

any

number

of

expressions

may

be

entered,

but

none

are

required.

Items

stacked

vertically

in

braces:

Items

stacked

vertically

in

braces

indicate

that

any

one

ofthe

stacked

items

may

be

used,

but

that

only

one

at a time

is

per-

missible.

In

the

example

below,

type

either

the

GOTO

or

the

GOSUB.

{

GOTO}

100

GOSUB

2000

Command

abbreviations

in

headings:

If a command

or

statement

has

an

ab-

breviation

associated

with

it,

the

abbreviation

is

placed

following

the

full

name

of

the

command

in

the

heading;

e.g., LET (L.).

The

following

table

explains

the

abbreviations

used

throughout this

manual:

avar

svar

mvar

var

aop

lop

aexp

lexp

TABLE

1.1

ABBREVIATIONS

Arithmetic

Variable:

A

location

where a numeric

value

is

stored.

Variable

names

may

be

from 1 to

120

alphanumeric

characters,

but

must

start

with

an

alphabetic

character,

and

all

alpha

characters

must

be

unreversed

and

upper

case.

String

Variable:

A

location

where a string

of

characters

may

be

stored.

The

same

name

rules

as

avar

apply,

except

that

the

last

character

in

the

variable

name

must

be a$.

String

variables

may

be

subscripted.

See Section 7,

STRINGS.

Matrix

Variable:

Also

called

a Subscripted Variable.

An

ele-

ment

of

an

array

or

matrix.

The

variable

name

for

the

array

or

matrix

as a whole

may

be

any

legal variable

name

such

as

A,

X,

Y,

ZIP,

or

K.

The

subscripted

variable

(name

for

the

particular

element)

starts

with

the

matrix variable,

and

then

use

s a

number,

variable,

or

expression

in

parentheses

immediately

following

the

array

or

matrix

variable.

For

example,

A(ROW),

A(1),

A(X + 1).

Variable:

Any

variable.

May

be

mvar,

avar,

or

svar

.

Arithmetic

operator.

Logical

operator.

Arithmetic

Expression:

Generally

composed

of a variable

,

function,

constant,

or

two

arithmetic

expressions

separated

by

an

arithmetic

operator

.

Logical

Expression:

Generally composed

of

two

arithmetic

or

string

expressions

separated

by a logical

operator.

Such

an

ex-

pression

evaluates

to

either

a 1 (logical

true)

or

a 0 (logical false).

For

example,

the

expression

1<

2 ev

aluates

to

the

value 1 (true)

while

the

expression

"LEMON" = "ORANGE"

evaluates

to a zero

(false) as

the

two

strings

are

not

equal.

OPERATING MODES

SPECIAL FUNCTION KEYS

sexp

exp lineno

a

data

filespec

String

Expression:

Can

consist

of a string

variable,

string

literal

(constant),

or a function

that

returns a string

value.

Any

expression,

whether

sexp

or

aexp.

Line

Number:

A

constant

that

identifies a particular

program

line

in a deferred

mode

BASIC

program.

Must

be

any

integer

from 0 through

32767. Line

numbering

determines

the

order

of

program

execution.

ATASCII

Data:

Any

AT

ASCII

character

excluding

commas

and

carriage

returns.

(See

Appendix

C.)

File

Specification:

A

string

expression

that

refers

to a device

such

as

the

keyboard

or

to a disk

file.

It

contains

information

on

the

type

of

I/0

device,

its

number,

a colon,

an

optional

file

name,

and

an

optional

filename

extender.

(See

OPEN,

Section 5.)

Example

filespec:

"D1:NATALIE.ED"

Direct

Mode:

Uses

no

line

numbers

and

executes

instruction

immediately

after

i;IJiiJ;I:I

key

is

pressed.

Deferred

Mode:

Uses

line

numbers

and

delays

execution

ofinstruction(s)

until

the

RUN

command

is

entered

.

Execute

Mode:

Sometimes

called

Run

mode. After

RUN

command

is

entered

,

each

program

line

is

processed

and

executed.

Memo

Pad

Mode:

A

non-programmable

mode

that

allows

the

user

to

experi-

ment

with

the

keyboard

or

to

leave

messages

on

the

screen.

Nothing

written

while

in

Memo

Pad

mode

affects

the

RAM-resident

program.

II

Reverse

(Inverse)

Video

key,

or

"ATARI

LOGO KEY".

Press-

ing

this

key

causes

the

text

to

be

reversed

on

the

screen

(dark

text

on

light

background).

Press

key a second

time

to

return

to

normal

text.

MOJ.Iitillo!ZJ;I

Lower

Case

key:

Pressing

this

key

shif

ts

the

screen

characters

from

upper

case

(capitals)

to

lower

case.

To

restore

the

characters

to

upper

case,

press

the

Ki@M

key

and

the

MOfW!l!l£.'1;1

key

simultaneously.

Escape

key:

Pressing

this

key

causes a command

to

be

entered

into a program

for

later

execution.

Example:

To

clear

the

screen,

you

would

enter:

10 PRINT "

IB

Bi3

MijUi;l

"

and

press

1&13 .

Escape is also

used

in

conjunction

with

other

keys

to

print

special

graphic

control

characters.

See

Appendix F and

back

cover

for

the

specific

keys

and

their

screen-character

representations.

General Information 5

ARITHMETIC OPERATORS

LOGICAL OPERATORS

6 General Information

l{if31;5f.J:I

Break

key:

Pressing

this

key

during

program

execution

causes

execution

to

stop.

Execution

may

be

resumed

by

typing

CONT

followed

by

pressing

tw!lltl .

System

Reset

key:

Similar

to

l!mEI

in

that

pressing

this

key

stops

program

execution.

Also

returns

the

screen

display

to

Graphics

mode

0,

clears

the

screen,

and

returns

margins

and

other

variables

to

their

default

values.

Tab

key:

Press

Emm

and

theki!i13!;§i·i:ikeys

simultaneously

to

set a

tab.

To

clear a tab,

press

the

Gi3

and

4iiiid!;U!:I

keys

simultaneously.

Used

alone,

thekiU3!;§t.j;iadvances

the

cursor

to

the

position.

In

Deferred

mode,

set

and

clear

tabs

by

preceding

the

above

with a line

number,

the

command

PRINT, a

quotation

mark,

and

press

the

Iakey.

Examples:

100 PRINT "

Ia

E!llil! k1U3!;$f.i:i "

200

PRINT "

..

BD

Ki#@d!;lt.i;i

"

Default

tab

settings

are

placed

at

columns

7,

15,

23,

31,

and

39

.

EmiiJ

Insert

key:

Press

the

1@1$4

and

EmiiJ

keys

simultaneously

to

insert

a line.

To

insert a single

character,

press

the

Bi3

and

mm

keys

simultaneously.

l@§ij:f.\3¥1

Delete

key:

Press

the

«i:U:iM

and

ED

keys

simultaneously

to

delete a line.

To

delete a single

character,

press

Gi3

and

llE!DJ

simultaneously.

Mh!J:H3¥i

Back

Space

key:

Pressing

this

key

replaces

the

character

to

the

left

of

the

cursor

with a space

and

moves

cursor

back

one

space.

Emil

Clear

key:

Pressing

this

key

while

holding

down

the

41:11$4

or

mill

key

blanks

the

screen

and

puts

the

cursor

in

the

upper

left

corner.

Return

key:

Terminator

to

indicate

and

end

of a line

of

BASIC.

Pressing

this

key

causes a

numbered

line

to

be

interpreted

and

added

to

a BASIC

program

RAM.

An

unnumbered

line

(in

Direct

mode)

is

interpreted

and

executed

immediately.

Any

variables

are

placed

in a variable

table.

The

Atari

Personal

Computer

System

uses

five

arithmetic

operators:

+

addition

(also

unary

plus;

e.g.,

+ 5)

subtraction

(also

unary

minus;

e.g., - 5)

*

multiplication

I

division

A

exponentiation

The

logical

operators

consists

of

two

types:

unary

and

binary.

The

unary

operator

is

NOT.

The

binary

operators

are:

OPERATOR

PRECEDENCE

AND

OR

Logical

AND

Logical OR

Examples:

10

IF

A=12

AND

T=0

THEN

F'RWT

"Q)00

11

Both expressions

must be true before GOOD is printed.

10

A=(C>l)

AND

(N<1)

10

A =

(C+l)

OR

Ol-1)

Hi

A =

NOT<

C+

1 )

If

both

expressions

true,

A= + 1;

otherwise

A=O.

If

either expression

true, A=

+

1;

otherwise

A=O.

If

expression is false,

A= + 1;

otherwise

A=

0.

The

rest

of

the

binary

operators

are

relational.

<

The

first

expression

is less

than

the

second

expression.

>

The

first

expression

is

greater

than

the

second.

-

The

expressions

are

equal

to

each

other.

< =

The

first

expression

is less

than

or

equal

to

the

second.

> =

The

first

expression

is

greater

than

or

equal

to

the

second.

<

>The

two

expressions

are

not

equal

to

each

other.

These

operators

are

most

frequently

used

in

IF/THEN

statements

and

logical

arithmetic.

Operations

within

the

innermost

set

of

parentheses

are

performed

first

and

pro-

ceed

out

to

the

When

sets

of

parentheses

are

enclosed

in

another

set,

they

are

said

to

be

"nested".

Operations

on

the

same

nesting

level

are

performed

in

the

following

order:

Highest

<,

>,=,<=,

>=,<->

precedence

* ' I

+,

-

Lowest precedence

NOT

AND

OR

Relational

operators

used

in

string

expres-

sions.

Have

same

precedence

and

are

per-

formed

from

left

to

right.

Unary

minus Exponentiation. Multiplication

and

division

have

the

same

precedence

level

and

are

performed

from

left

to

right.

Addition

and

subtraction

have

the

same

precedence

level

and

are

performed

from

left

to

right.

Relational

operations

in

numeric

expressions

have

the

same

precedence

level

from

left

to right. Unary

operator

Logical

AND

Logical OR

General

Information

7

BUILT-IN FUNCTIONS

GRAPHICS

SOUND

AND GAMES CONTROLLERS

WRAPAROUND AND

KEYBOARD

ROLLOVER

ERROR MESSAGES

8 General Information

The

section

titled

FUNCTION

LIBRARY

explains

the

arithmetic

and

special

functions

incorporated

into

Atari

BASIC.

Atari

graphics

include 9 graphics

modes.

The

commands

have

been

designed

to

allow

maximum

flexibility

in

color

choice

and

pattern

variety.

Section 9 ex-

plains

each

command

and

gives

examples

of

the

many

ways

to

use

each.

The

Atari

Personal

Computer

is

capable

of

emitting a large

variety

of

sounds

.

including

simulated

explosions,

electronic

music,

and

"raspberries."

Section

10

defines

the

commands

for

using

the

SOUND

function

and

for

controlling

pad-

dle,

joystick,

and

keyboard

controllers.

The

ATARI

Personal

Computer

System

has

screen

wraparound

thus

allowing

greater

flexibility.

It

also

allows

the

user

to

type

one

key

ahead.

If

the

user

presses

and

holds

any

key,

it

will

begin

repeating

after 1h

second.

If a data

entry

error

is

made,

the

screen

display

shows

the

line

reprinted

preced-

ed

by

the

message

ERROR-

and

the

offending

character

is

highlighted.

After

correcting

the

character

in

the

original

line,

delete

the

line

containing

the

ERROR- before

pressing

IDi!liJI.

Appendix B contains

a list

of

all

the

error

messages

and

their

definitions.

BYE (B.)

CONT(CON.)

END

2

COMMANDS

Whenever

the

cursor

(D)

is

displayed

on

the

screen,

the

computer

is

ready

to

ac-

cept

input.

Type

the

command

(in

either

Direct

or

Deferred

mode),

and

press

IDiJ3.

This

section

describes

the

commands

used

to

clear

computer

memory

and

other

useful

control

commands:

The

commands

explained

in

this

section

are

the

following:

Format:

Example:

BYE BYE

BYE

CONT

END

LET

LIST

NEW

REM

RUN

STOP

The

current

function

of

the

BYE

command

is

to

exit

BASIC

and

put

the

com-

puter

in

Memo

Pad

mode.

This

allows

the

user

to

experiment

with

the

keyboard

or

to

leave

messages

on

the

screen

without

disturbing

any

BASIC

program

in

memory.

To

return

to

BASIC,

press

Htih&i;lihh.

Format:

Example:

CONT CONT

Typing

this

command

followed

by

a l;ijili;ill

causes

program

execution

to

resume.

If

a

l:l;liiM,

STOP,

or

END is

encountered,

the

program

will

stop

until

CONT

W1!llilli

is

entered.

Execution

resumes

at

the

line

number

following

the

statement

at

which

the

program

stopped.

Note:

If

the

statement

at

which

the

program

is

halted

has

other

commands

on

the

same

numbered

line

which

were

not

executed

at

the

time

of

the

l:l;q.l4'

STOP,

or

END,

they

will

not

be

executed.

On

CONT,

execution

resumes

at

the

line. A

loop

may

be

incorrectly

executed

if.the

program

is

halted

before

the

loop

completes

execution.

This

command

has

no

effect

in a Deferred

mode

program.

Format:

END

Example:

1000 END

This

command

terminates

program

execution

and

is

used

in

Deferred

mode.

In

Atari

BASIC,

an

END is

not

required

at

the

end

of a program.

When

the

end

of

the

program

is

reached,

Atari

BASIC

automatically

closes all files

and

turns

off

sounds

(if

any).

END

may

also

be

used

in

Direct

mode

to

close files

and

turn

off

sounds.

Commands

9

LET (LE.)

LIST (L.)

NEW

REM (R.

or

·'*'491)

10

Commands

Format: Example:

[LET]

var = exp

LET X = 3.142 * 16 LET

X=

2

This

statement

is

optional

in

defining

variables.

It

can

just

as

easily

be

left

out

of

the

statement.

It

may

be

used,

however,

to

set a

variable

name

equal

to a value.

Format:

Examples:

LIST

[lineno

[ ,

lineno]

]

LIST [filespec [

,lineno [ ,lineno]

] ]

LIST LIST

10

LIST I 101

100

LIST

npn

LIST 110:

DEt10.

LST"

This

command

causes

the

computer

to

display

the

source

version

of

all

lines

cur-

rently

in

memory

if

the

command

is

entered

without

line

number(s),

or

to

display a specified

line

or

lines.

For

example,

LIST 10,100 mi!Im

displays

lines

10

through

100

on

the

screen.

If

the

user

has

not

typed

the

lines

into

the

com-

puter

in

numerical

order,

a LIST

will

automatically

place

them

in

order.

Typing

L.

"P

will

print

the

RAM-resident

program

on

the

printer.

LIST

can

be

used

in

Deferred

mode

as

part

of

an

error

trapping

routine

(See

TRAP

in

Section

4).

The

LIST

command

is

also

used

in

recording

programs

on

cassette

tape.

The

sec-

ond

format

is

used

and a filespec

is

entered.

(See

Section 5 for

more

details

on

peripheral

devices.)

If

the

entire

program

is

to

be

listed

on

tape,

no

line

numbers

need

be

specified.

Example:

LIST

"C1"

1000 LIST

"C1"

Format:

NEW

Example:

NEW

This

command

erases

the

program

stored

in

RAM.

Therefore,

before

typing

NEW,

either

SAVE

or

CSAVE

any

programs

to

be

recovered

and

used

later.

NEW

clears

BASIC's

internal

symbol

table

so

that

no

arrays

(See Section

8)

or

strings

(See

Section

7)

are

defined.

Used

in

Direct

mode.

Format:

REM

text

Example:

10

REM

ROUTINE

TO

CALCULATE X

This

command

and

the

text

following

it

are

for

the

user's

information

only.

It

is

ignored

by

the

computer.

However,

it

is

included

in

a LIST

along

with

the

other

numbered

lines.

Any

statement

on

the

same

numbered

line

which

occurs

after

a

REM

statement

will

be

ignored.

RUN

(RU.)

STOP (STO.)

Format:

RUN [filespec]

Examples:

RUN RUN

"D:MENU"

This

command

causes

the

computer

to

begin

executing a program.

If

no

filespec

is specified,

the

current

RAM-resident

program

begins

execution.

If

a filespec is

included,

the

computer

retrieves

the

specified,

tokenized

program

from

the

specified file

and

executes

it.

All

variables

are

set to

zero

and

all

open

files

and

peripherals

are

closed.

All

ar-

rays,

strings,

and

matrices

are

eliminated

and

all

sounds

are

turned

off. Unless

the

TRAP

command

is

used,

an

error

message

is

displayed

if

any

error

is

detected

during

execution

and

the

program

halts.

RUN

can

be

used

in

Deferred

mode.

Examples:

19

PRINT 110VER

At()

OJ..IER

AGAIN."

20

R~

Type

RUN

and

press

l;ljili;lli.

To

end,

pressl:!dy.i:i.

To

begin

program

execution

at a point

other

than

the

first

line

number,

type

GOTO

followed

by

the

specific

line

number,

then

pressl;liiili;!li,

Format:

STOP

Example:

100 STOP

When

the

STOP

command

is

executed

in a program,

BASIC

displays

the

message

STOPPED

AT

LINE

___

,

terminates

program

execution,

and

returns

to Direct

mode.

The

STOP

command

does

not

close files

or

turn

off

sounds,

so

the

program

can

be

resumed

by

typing

CONT l;l§iii;lll.

Commands

11

NOTES

12

Not

es

SCREEN EDITING

3

EDIT

FEATURES

In

addition

to

the

special

function

keys

described

in

Section 1,

there

are

cursor

control

keys

that

allow

immediate

editing

capabilities.

These

keys

are

used

in

conjunction

with

the

4.jiii$M or

Gml

keys.

The

following

key

functions

are

described

in

this

section:

Gml Gml

11

H-i3;il

m1l

1

41

11114

Gml

mDI

Gml

2

Gml

D

41111jM

•t:M3;''

m1l

3

Gml

D

AiU!il

mma

'='d:t.U'

Gml

=

@I

hiM

MIP.!itiJ«•M;M

..

Gml

=

The

keyboard

and

display

are

logically

combined

for a mode

of

operation

known

as

screen

editing.

Each

time a change

is

completed

on

the

screen,

the

l;iiiii!;ill

key

must

be

pressed.

Otherwise,

the

change

is

not

made

to

the

program

in

RAM.

Example:

1

f1

F.~Ei'1

PF.~E~:;::;

~:ET~JR~·~

AFTEF

L I

f·~E

EDIT

2t1

F·R

I

~-iT

:

PP

I

f·.iT

30

F·~~Ir·iT

HTHI~:;

IS

LI:·-~E

1

Ot·~

THE

:::cPEEf·-i.

!1

To

delete

line

20

from

the

program,

type

the

line

number

and

press

the

l;iiill;lll

key.

Merely

deleting

the

line

from

the

screen

display

does

not

delete

it

from

the

program.

The

screen

and

keyboard

as

I/0

devices

are

described

in

Section 5.

41111$4

Control

key.

Striking

this

key

in

conjunction

with

the

arrow

keys

produces

the

cursor

control

functions

that

allow

the

user

to

move

the

cursor

anywhere

on

the

screen

without

changing

any

characters

already

on

the

screen.

Other

key

combinations

control

the

setting

and

clearing

of

tabs,

halting

and

restarting

program

lists,

and

the

graphics

control

symbols.

Striking a key

while

holding

the

Gml

key

will

pro-

duce

the

upper-left

symbol

on

those

keys

having

three

functions.

Shift

key:

This

key

is

used

in

conjunction

with

the

numeric

keys

to

display

the

symbols

shown

on

the

upper

half

oft

hose

keys.

It

is also

used

in

conjunction

Edit Features

13

DOUBLE-KEY

FUNCTIONS

14

Edit Features

1£11

D

with

other

keys

to

insert

and

delete

lines,

return

to

a

normal,

upper

case

letter

display,

and

to

display

the

function

symbols

above

the

subtraction

, equals,

addi-

tion,

and

multiplication

operators

as

well

as

the

brackets,

[ ],

and

question

mark,?.

Cursor

Control

Keys

Moves

cursor

up

one

physical

line

without

changing

the

program

or

display

.

Moves

cursor

one

space to

the

right

without

disturb-

ing

the

program

or

display.

Moves

cursor

down

one

physical

line

without

chang-

ing

the

program

or

display.

Moves

cursor

one

space

to

the

left

without

disturbing

the

program

or

display.

Like

the

other

keys

on

the

Atari

keyboard,

holding

the

cursor

control

keys

for

more

than 1h

second

causes

the

keys

to

repeat.

Bml

2

Bml

3

«iUii+ 1Vt1:taM

41hliM

l:mm

Keys

Used

With

BiD

Inserts

one

character

space.

Deletes

one

character

or

space.

Stops

temporarily

and

restarts

screen

display

without

"breaking

out" of

the

program.

Rings

buzzer

.

Indicates

end-of-file.

Keys

Used

With

E!71J1!

Inserts

one

physical

line.

Deletes one

physical

line.

Returns

screen

display

to

upper-case

alphabetic

characters.

Special

Function

Keys

Stops

program

execution

or

program

list,

prints

a

READY

on

the

screen,

and

displays

cursor.

Allows

commands

normally

used

in

Direct

mode

to

be

placed

in

Deferred

mode;

e.g

.,

In

Direct

mode,

Gml

190.1;1

clears

the

screen

display.

To

clear

the

screen

in

Deferred

mode,

type

the

following

after

the

program

line

number.

Press

1B

then

press

Em1l

and

E!D

together.

PRINT "

Ia

GmJ

IUf.i;i

"

FOR

(F.),

TO,

STEP/NEXT

(N.)

4

PROGRAM

STATEMENTS

This

section

explains

the

commands

associated

with

loops,

conditional

and

un-

conditional

branches,

error

traps,

and

subroutines

and

their

retrieval.

It

also ex-

plains

the

means

of

accessing

data

and

the

optional

command

used

for

defining

variables.

The

following

commands

are

described

in

this

section:

FOR,

TO,

STEP/NEXT GOSUB/RETURN GOTO

IF/THEN ON,GOSUB ON,GOTO

POP RESTORE TRAP

Format:

FOR

avar = aexp1

TO

aexp2

[STEP

aexp3]

Examples:

FOR X = 1

TO

10 NEXT X FOR Y = 10

TO

20

STEP 2 NEXT Y FOR INDEX

= Z

TO

100 * Z

NEXT INDEX

This

command

sets

up a loop

and

determines

how

many

times

the

loop

is exe-

cuted.

The

loop

variable

(avar) is

initialized

to

the

value

of

aexp1.

Each

time

the

statement

is

encountered,

the

loop

variable

is

incremented

by

the

aexp3

in

the

STEP

statement.

The

aexp3

can

be

positive

or

negative

integers,

decimals,

or

fractional

numbers.

If

there

is

no

STEP

aexp3

command,

the

loop

increments

by

one.

When

the

loop

completes

the

limit

as

defined

by

aexp2,

it

stops

and

the

program

proceeds

to

the

statement

immediately

following

the

it

may

be

on

the

same

line

or

on

the

line.

Loops

can

be

nested,

one

within

another.

In

this

case,

the

innermost

loop

is

com-

pleted

before

returning

to

the

outer

loop.

The

following

example

illustrates

a

nested

loop

program.

10

FOF.:

>=:=

1

TO

3

:::IJ

PF.:HH 110UTER

LOOP"

30

Z=f1

40

Z=Z+2

50

FOP

'·.1-i

1-1

6~3

PF.:It·H

II

7f1

t·~E>::T

'··'

I

:::0

t·4E>::T

>=:

90

am

TO

C" ,-......

~:,

-,

·-'

.::

I t.:-

.::..

I

Nt·iE~:

LOOP

n

Figure

4-1.

Nested

Loop

Program

Statements

15

GOSUB (GOS.)

RETURN (RET.)

16

Program Statements

In

Figure

4-1,

the

outer

loop

will

complete

three

passes

(X

= 1

to 3 ).

However,

before

this

first

loop

reaches

its NEXT X

statement,

the

program

gives

control

to

the

inner

loop. Note

that

the

for

the

inner

loop

must

precede

the

for

the

outer

loop.

In

the

example,

the

inner

loop's

number

of

passes

is

determined

by

the

STEP

statement

(STEP

Z).

In

this

case, Z

has

been

defined

as 0,

then

redefined

as Z +

2.

Using

this

data,

the

computer

must

complete

three

passes

through

the

inner

loop

before

returning

to

the

outer

loop.

The

aexp3

in

the

step

statement

could

also

have

been

defined

as

the

numerical

value

2.

The

program

run

is

illustrated

in

Figure

4-2.

OUTEF.:

LOOP

I

t·~t·-IEF.:

LOOF'

I

t-~t-~EF.:

LOOP

I

t-~HEP

LOOP

OUTEP

LOOF'

I

t·~t-lE~:

LOOP

I

t-~t-~EP

LOOP

I

t-~t-~ER

LOOP

OUTEP

LOOP

IHt·4ER

LOOP

I

t·4t-~EF.~

LlJOP

I

t·~HE~~

LOOP

Figure

4-2.

Nested

Loop

Execution

The

return

address

for

the

loops

are

placed

in

a special

group

of

memory

ad-

dresses

referred

to

as a stack.

The

information

is

"pushed"

on

the

stack

and

when

used,

the

information

is

"popped"

off

the

stack

(see

POP.)

Format:

GOSUB

lineno

RETURN

Example:

100

GOSUB

2000 2000 PRINT "SUBROUTINE" 2010 RETURN

A

subroutine*

is a

program

or

routine

used

to

compute a certain

value, etc.

It

is

generally

used

when

an

operation

must

be

replaced

several

times

within a pro-

gram

sequence

using

the

same

or

different

values.

This

command

allows

the

user

to

"call"

the

subroutine!,

if

necessary.

The

last

line

ofthe

subroutine

must

contain

a RETURN

statement.

The

RETURN

statement

goes

back

to

the

physical

line

following

the

GOSUB

statement.

Like

the

preceding

FOR/NEXT

command,

the

GOSUB/RETURN

command

uses a

stack

for

its

return

address.

If

the

subroutine

is

not

allowed

to

complete

normally;

e.g., a GOTO

lineno

before

a RETURN,

the

GOSUB

address

must

be

"popped"

off

the

stack

(see

POP)

or

it

could

cause

future

errors.

• Generally, a

subroutine

can

do

anything

that

can

be

done

in a program.

It

is

used

to

save

memory

and

program-entering

time,

and

to

make

programs

easier

to

read

and

debug.

GOTO

(G.)

To

prevent

accidental

triggering

of a subroutine

(which

normally

follows

the

main

program),

place

an

END

statement

preceding

the

subroutine.

The

follow-

ing

program

demonstrates

the

use

of

subroutines.

H3

PRH-H

")"

:::·r_-1

:;,

.·.F~~-~.

E',:-!,H·.

~.

i,F'L

....

t '

~.-.

E

,-,r

~-,-

..

-.,

'P

'F.'ET'jr•L'

-'"

- L!.:r - r

·.liJ.::~_

Iu.··

•, : ! f':.ri

30

>=:=100

4~-:-1

co::;tJE:

1

oo~J

5[

1

::<=120

6~1

GOSUE:

1

0(1~3

70

>::=50

:::o

Go::;ut: 1 a·.;:Jo

90

Et·~D

1

~1(1~1

'/=3::;::::-::

101[1

;:-:;:;;::+\'

(Clear

screen)

Figure

4-3.

GOSUB/RETURN

Program

Listing

In

the

above

program,

the

subroutine,

beginning

at

line

1000, is

called

three

times

to

compute

and

print

out

different

values

of X andY.

Figure

4-4

illustrates

the

results

of

executing

this

program.

400

301-J

480

360

200

15(1

Figure

4-4.

GOSUB/RETURN

Program

Run

Format:

{GO

TO} aexp

GOTO

Examples:

100 GOTO 50 500 GOTO

(X+ Y)

The

GOTO

command

is

an

unconditional

branch

statement

just

like

the

GOSUB

command.

They

both

immediately

transfer

program

control

to a target

lin

e

number

or

arbitrary

express

ion. How

ever,

using

anything

other

than

a con-

stant

will

make

renumbering

the

program

difficult.

If

the

target

line

number

is

non-existent,

an

error

results.

Any

GOTO

statement

that

bran

ch es

to

a

preceding

line

may

result

in

an "endless" loop. Statements

following

a GOTO

statement

will

not

be

executed.

Note that a conditional

branching

statement

(see

IF/THEN)can

be used

to break out

of

a GOTO

loop. The

following

program

il-

lustr

ates

two

uses

of the GOTO

command.

Program

Stat

eme

nts

17

IF/THEN

18

Program

Statements

10

PRHH

20

F'~:ItH

:PRINT

"ONE

11

30

PR

nn

"n.~r

40

P~:

HH

"THPEP

50

PRI~H

"FOUP"

6f1

P~:nn

"FI'..JE

11

65

GOTO

101:1

70

PF.:ItH

"$$$$$$$$$$$$$$$$$"

:::0

P

F.~

I

r-~T

II~-~~-~;-~~-~~-~~-~~-~~-~~·~~-~~

-~~-

~~-~~-~~-~~-~~-~"

90

F•k: I t·iT

11

???'??????:?????'?'?? n

95

Et-iD

1

fij

F'F.:

H-iT

!!

~=;I:=-::

II

11(1

FtR

I

t·iT

II

::;El.)Et

·f'

E'0

F'F.:It·H

aEIGHF

130

F,F.:

I

f·~T

II

t·i1

t·~E

H

14(1

F)~~

I

~-iT

!I

TEf·~

II

150

GOTO

70

Figure

4-5.

GOTO

Program

Listing

Upon

execution,

the

numbers

in

the

above

listing

will

be

listed

first

followed

by

the

three

rows

of

symbols.

The

symbols

listed

on

lines

70,

80,

and

90

are

ignored

temporarily

while

the

program

executes

the

GOTO

100

command.

It

proceeds

with

the

printing

of

the

numbers

"SIX"

through

"TEN

",

then

executes

these

-

cond

GOTO

statement

which

transfers

program

control

back

to

line

70

.

(This

is

just

an

example.

This

program

could

be

rewritten

so

that

no

GOTO

statements

were

used.)

The

program, when

executed,

looks

like

the

follow ing:

Ot

·£

HID

Tl-f.:EE

FOUF.:

FI!..JE

~:;£1.,.1£

t·~

EIGHT

t·HNE

THl

$$$$$$$$$$$$$$$$$

'?'??????'?'

'?'

?''?'?'?'?'???

Format:

Examples:

Figure

4-6.

GOTO

Program

Run

IF

aexp

THEN {

lineno

}

statement [:statement

... ]

IF

X =

100

THEN 150

IF

A$

= "

AT

ARI

" THEN

200

IF

AA

= 145

and

BB

= 1 THEN PRINT

AA,

BB

IF X =

100

THEN X = 0

The

IF/THEN

statement

is a conditional

branch

statement.

This

type

ofbranch

occurs

only

if

certain

conditions

are

met.

These

conditions

may

be

either

arithmetical

or

logical.

If

the

aexp

following

the

IF

statement

is

true

(non-zero),

the

program

executes

the

THEN

part

of

the

statement.

If,

however,

the

aexp

is

false

(a

logical

0),

the

rest

ofthe

statement

is

ignored

and

program

control

passes

to

the

line.

In

the

format,

IF

aexp

THEN lineno,

lineno

must

be

a cons

tant,

not

an

expression

and

specifies

the

line

number

to go to

if

the

expression

is

true.

If

several

statements

occur

after

the

THEN, se

parated

by

colons,

then

they

will

be

ex-

ecuted

if

and

only

if

the

expression

is

true.

Several IF

statements

may

be

nested

on

the

same

line. For

example:

The

statements

R=9

: GOTO 100

will

be

executed

only

if

X=S

and

Y=3. The

statement

Y = 3

will

be

executed

if

X=

5.

The

following

program

demonstrates

the

IF/THEN

statement.

5

GRAPHIC~;

0:?

:?

II

IF

DH10

11

10

? =?

"ENTER

Au

j:

HlPUT

A

20

IF

A=

1

THEH

4t1 : F.:Et-1

t·1i-'ttT I PLE

:::TATH1Et·H

~:;

HEF.~E

~·JILL

t£UEF.~

BE

E:=<ECUTED!

!

30

? = ?

II

A

I~:

;

HOT

1 .

E:=<ECUT

I

oN

com r

t·UE

s

HH~E

L·JHH~

THE

D~PPE::s

I

Ot

·i r s

FALSE

.

II

40

IF

A=l

THEt

·i ? ; '?

11

A=1

II:?

"\'ES..

IT'

IS

REALL'l'

1.

II

:

REt-1

t1UL

iiPLE

:~;TATEt1HHS

HEPE

WLL

BE

E>TCUTED

ot·ll\'

IF

A=l

! !

50

·?

:?

HE>~ECUTIOf·~

COt·iT

I

~-iUE~;

HEF.:E

IF

A<

>

1

OF.:

AFTEF:

I 'rE; ·'

IT

I

~3

REALL'r'

1 I

Is

D I

SF'

LA'r'ED.

u

6f1

GOTO

10

Figure

4-7. IF/

THEN

Program

Et-HER

A

IS

t·WT

1 .

E:;::ECUT

IOH

COt-H

H~UE~3

HEF.~E

~JH

Et·l

THE

E:=O::PRESSIOt-~

IS

FAL~3E.

E>{ECUTIOt-~

COtH

H~UES

HERE

IF

A<> 1 OR

AFTE

R ''lES)

IT

IS

REALL\'

1'

IS

DISPLAYED

.

EtHER

A

A=1

'/ES ) IT

IS

F.:EALL

\'

1 .

E::<ECUTIOt-~

COtH

H4UE::;

HEF.:E

IF

A<>

1

OR

AFTE

R

"'i'E~:;

..

IT

I::;

F.:EALL'r'

1'

IS

DISPLA'/ED.

ENTEP

A

Figure

4-8. IF/

THEN

Program

Execution.

(enter

ed

Z)

(enter

ed

1)

Program

Statements

19

ON/GOSUB/

RETURN

ONIGOTO

POP

20

Program

Stat

emen

ts

Format:

ON

aexp

{ GOTO}

lineno [ ,lineno

..

.]

GO

SUB

Examples:

100

ON

X GOTO 200, 300, 400

100

ON A GOSUB

1000, 2000

100 ON

SQR(X)

GOTO

30,

10, 100

Note:

GOSUB

and

GOTO

may

not

be

abbreviated.

These

two

statements

are

also

conditional

branch

statements

like

the

IF/THEN

statement. However,

these

two

are

more

powerful.

The

aexp

must

evaluate

to

a

positive

number

which

is

then

rounded

to

the

nearest

positive

integer

(whole

number)

value

up

to

255.

If

the

resulting

number

is

1,

then

program

control

passes

to

the

first

lineno

in

the

list

following

the

GOSUB

or

GOTO.

If

the

resulting

number

is 2,

program

control

passes

to

the

second

lineno

in

the

list,

and

so on.

If

the

resulting

number

is 0 or

is

greater

than

the

number

of

linenos

in

the

list,

the

conditions

are

not

met

and

program

control

passes

to

the

which

may

or

may

not

be

located

on

the same

line.

With ON/GOSUB,

the

selected

subroutine

is

executed

and

then

control

passes

to

the

ment.

The

following

routine

demonstrates

the

ON/GOTO

statement:

1 a

:=<=r.:

+ 1

:C.'€1

Ot-.1

:=<

GOTO

100

..

200

..

30f1

..

400}

500

313

IF

:-:::>5

Tli'H~

PRHH

"CIX1PLETE.

II :

HID

413

GOTO

10

50

END

100

PRHH

"t·IDL·J

L·JO~~f:::WG

AT

LH~E

100'':

GOTO

10

200

PF.:IrH

"t·[I~J

~·JO~:K

I

~-~G

AT

LH~E

200" =

GOTO

Hi

3tl)

F'RHH

"t·KIL·J

L·JOF.:K

I

t·~G

AT

LWE

300" :

GOTO

10

40J)

PF.:ItH

"t·[ll·J

l

·JORK

I

t·~G

AT

LH~E

400

11

:GOTO

10

50t1

PF.:HH

"t·~O~·J

l·

JOF.:KIHG

AT

Lir~E

501-3"

:

GOTO

w

Figure

4-9 ON/

GOTO

Program

Listing

When

the

program

is

executed

, it

looks

like

the

following:

t·~Ol·J

~·JOF.:KH~

AT

LmE

100

t·~C~·l

L·lO~:t:::

WG

AT

LINE

200

r~Ql.l

~·lORK

n~,;

AT

LI

t-~E

300

t·mL·l

l·lORK

Hf.~

AT

L

It-~E

40(1

t·mL·J L·JOF.:K

I

t·~

~

AT

L I

t·~E

500

COt·1PLETE

.

Figure

4-10 ON/

GOTO

Program

Execution

Format:

POP

Example:

1000 POP

RESTORE (RES.)

In

the

description

of

the

FOR/NEXT

statement,

the

stack

was

defined

as a

group

of

memory

addresses

reserved

for

return

addresses.

The

top

entry

in

the

stack

controls

the

number

of

loops

to

be

executed

and

the

RETURN

target

line

for

a

GOSUB.

If a subroutine

is

not

terminated

by

a RETURN

statement,

the

top

memory

location

of

the

stack

is still

loaded

with

some

numbers.

If

another

GOSUB

is

executed,

that

top

location

needs

to

be

cleared.

To

prepare

the

stack

for a new

GOSUB,

use

a POP

to

clear

the

data

from

the

top

location

in

the

stack.

The

POP

command

must

be

used

according

to

the

following

rules:

1.

It

must

be

in

the

execution

path

of

the

program.

2.

It

must

follow

the

execution

of

any

GOSUB

statement

that

is

not

brought

back

to

the

main

program

by

a RETURN

statement.

The

following

example

demonstirates

the

use

of

the

POP

command

with

a

GOSUB

when

the

RETURN is

not

executed:

10

Go~:;us

1000

15

F.:Et-1

LINE

20

WLL

t·mT

BE

E>=:ECUTED

:::1:.1

PF.:

I

t·n

II

t·~OPt·1AL

F.:ETuft:t·~

FR I t·ns

TH

I~=;

t·1Ef;~:;

AGE.

H

30

PF.:WT

11

ABt·iOlmAL

PETUF:t-l

PPrt-n::;

THI::;

r·1E

SSAGE.

11

40

POP

999

HiD

1

f1t-:::1~~1

F~~~

I

t·iT

II

t·~o~~J

E::<ECiJT

I

t·i~~

~:;uE:F.:CHJT

I

t·1E

.

!I

1010

GOTO

30

1020

~:ETUF:ti

Figure

4-11.

GOSUB

Statement

With

POP

Format: Example:

RESTORE [aexp] 100 RESTORE

The

Atari

Personal

Computer

System

contains

an

internal

"pointer"

that

keeps

track

ofthe

DATA

statement

item

to

be

read

next.

Used

without

the

op-

tional

aexp,

the

RESTORE

statement

resets

that

pointer

to

the

first

DATA

item

in

the

program.

Used

with

the

optional

aexp,

the

RESTORE

statement

sets

the

pointer

to

the

first

DATA

item

on

the

line

specifed

by

the

value

ofthe

aexp.

This

statement

permits

repetitive

use

of

the

same

data.

10

FOR

N=1

TO

2

20

READ

A

30

RESTORE

40

READ

B

50

t·l=A+B

60

PRIHT 11TOTAL

EQUALS 11;M

70

NE:>\T

N

00

END

90

DATA

30,15

Figure

4-12.

Restore

Program

Listing

On

the

first

pass

through

the

loop, A

will

be

30

and B will

be

30 so

the

total

line

50

will

print

SUM

TOTAL

EQUALS

60,

but

on

the

second

pass, A

will

equal15

Program

Statements

21

TRAP

(T.)

22

Program

Statements

and

B,

because

of

the

RESTORE

statement,

will

still

equal

30.

Therefore,

the

PRINT

statement

in

line

50

will

display

SUM

TOTAL

EQUALS

45.

Format: Example:

TRAP

aexp

100 TRAP 120

The

TRAP

statement

is

used

to

direct

the

program

to

a

specified

line

number

if

an

error

is

detected. Without

a TRAP

statement,

the

program

stops

executing

when

an

error

is

encountered

and

displays

an

error

message

on

the

screen.

The

TRAP

statement

works

on

any

error

that

may

occur

after

it

has

been

ex-

ecuted,

but

once

an

error

has

been

detected

and

trapped,

it

is

necessary

to

reset

the

trap

with

another

TRAP

command.

This

TRAP

command

may

be

placed

at

the

beginning

of

the

section

of

code

that

handles

input

from

the

keyboard

so

that

the

TRAP

is

reset

after

each

error.

PEEK(195)

will

give

you

an

error

message

(see

Appendix

B).

256

*PEEK(187)+ PEEK(186)

will

give

you

the

number

of

the

line

where

the

error

occurred.

The

TRAP

may

be

cleared

by

executing

a

TRAP

statement

with

an

aexp

whose

value

is

from

32767

to

65535 (e.g., 40000).

INPUT/OUTPUT

DEVICES

5

INPUT/OUTPUT

COMMANDS

AND

DEVICES

This

section

describes

the

input/output

devices

and

how

data

is

moved

between

them.

The

commands

explained

in

this

section

are

those

that

allow

access

to

the

input/output

devices.

The

input

commands

are

those

associated

with

getting

data

into

the

RAM

and

the

devices

geared

for

accepting

input. The

output

com-

mands

are

those

associated

with

retrieving

data

from

RAM

and

the

devices

geared

for

generating

output

.

The

commands

described

in

this

section

are:

CLOAD CSAVE DOS ENTER

INPUT LOAD LPRINT NOTE

OPEN/CLOSE

POINT

PRINT

PUT/GET

READ/DATA SAVE STATUS XIO

The

hardware

configuration

of

each

of

the

following

devices

is

illustrated

in

the

individual

manuals

furnished

with

each.

The

Central

Input/Output

(CIO)

sub-

system

provides

the

user

with a single

interface

to

access all

of

the

system

peripheral

devices

in

a (largely)

independent

manner.

This

means

there

is

a

single

entry

point

and a device-independent

calling

sequence.

Each

device

has

a

symbolic

device

name

used

to

identify

it;

e.g.,

K:

for

the

keyboard.

Each

device

must

be

opened

before

access

and

each

must

be

assigned

to

an

Input/Output

Con-

trol

Block

(IOCB).

From

then

on,

the

device

is

referred

to

by

its

IOCB

number.

ATARI

BASIC

contains 8 blocks

in

RAM

which

identifies

to

the

Operating

System

the

information

it

needs

to

perform

an

I/0

operation.

This

information

includes

the

command,

buffer

length,

buffer

address,

and

two

auxiliary

control

variables.

AT

ARI BASIC

sets

up

the

lOCH's,

but

the

user

must

specify

which

IOCB

to

use.

BASIC

reserves

IOCB

ItO

for

1/0

to

the

Screen

Editor,

therefore

the

user

may

not

request

IOCB

11'0.

The

GRAPHICS

statement

(see Section

9)

opens

IOCB

11'6

for

input

and

output

to

the

screen.

(This

is

the

graphics

window

S:).

IOCB

11'7

is

used

by

BASIC

for

the

LPRINT, CLOAD,

and

CSA

VE

commands.

The

IOCB

number

may

also

be

referred

to

as

the

device

(or

file)

number.

IOCB's 1

through 5 are

use.d

in

opening

the

other

devices

for

input/output

operations.

If

IOCB

11'7

is

in

use,

it

will

prevent

LPRINT

or

some

of

the

other

BASIC

I/0

statements

from

being

performed.

Keyboard:

(K:)

Input

only

device.

The

keyboard

allows

the

user

to

read

the

converted

(ATASCII)

keyboard

data

as

each

key

is

pressed.

Line

Printer:

(P:)

Output

only

device.

The

line

printer

prints

ATASCII

characters, a line

at a time.

It

recognizes

no

control

characters.

Program

Recorder:

(C:)

Input

and

Output

device.

The

recorder

is a

read/write

device

which

can

be

used

as

either,

but

never

as

both

simultaneously.

The

cassette

has

two

tracks for

sound

and

program

recording

purposes.

The

audio

track

cannot

be

recorded

from

the

ATARI

system,

but

may

be

played

back

through

the

television

speaker.

I/0

Commands

and

Devic

es

23

Disk

Drives:

(Dt:,

D2:, D3:,

D4:)

Input

and

Output

devices.

If

16K

of

RAM is

installed,

the

ATARI

can

use

from

one

to

four

disk

drives.

If

only

one

disk

drive

is

attached,

there

is

no

need

to

add a number

after

the

symbolic

device

code

D.

Screen

Editor:

(E:)

Input

and

Output

device.

This

device

uses

the

keyboard

and

display

(see

TV

Monitor)

to

simulate a screen

editing

terminal.

Writing

to

this

device

causes

data

to

appear

on

the

display

starting

at

the

current

cursor

position.

Reading

from

this

device

activates

the

screen

editing

process

and

allows

the

user

to

enter

and

edit

data.

Whenever

the

l;ljiil;ill

key

is

pressed,

the

entire

logical

line

within

which

the

cursor

resides

is

selected

as

the

current

record

to

be

transferred

by

CIO

to

the

user

program.

(See Section

9).

TV

Monitor:

(S:)

Input

and

Output

device.

This

device

allows

the

user

to

read

characters

from

and

write

characters

to

the

display,

using

the

cursor

as

the

screen

addressing

mechanism.

Both

text

and

graphics

operations

are

supported.

See

Section 9 for a complete

description

of

the

graphics

modes.

Interface,

RS-232:

(R:)

The

RS-232

device

enables

the

AT

ARI

system

to

inter-

face

with

RS-232-compatible

devices

such

as

printers,

terminals,

and

plotters.

It

contains a parallel

port

to

which

the

80-column

printer

(ATARI

825TM)

can

be

at-

tached.

CLOAD

(CLOA.)

Format:

CLOAD

CSAVE

(CS.)

24

I/0

Commands

and

Devices

Examples:

CLOAD 100 CLOAD

This

command

can

be

used

in

either

Direct

or

Deferred

mode

to

load a program

from

cassette

tape

into

RAM

for

execution.

On

entering

CLOAD,

one

bell

rings

to

indicate

that

the

PLAY

button

needs

to

be

pressed

followed

by

lam

.

However,

do

not

press

PLAY

until

after

the

tape

has

been

positioned.

Specific in-

structions

for

CLOADing a

program

are

contained

in

the

ATARI

410

Program

Recorder

Manual.

Steps

for

loading

oversized

programs

are

included

in

the

paragraphs

under

CHAINING

PROGRAMS

at

the

end

of

this

section.

Format: Examples:

CSAVE CSAVE

100 CSAVE

100

cs.

This

command

is

usually

used

in

Direct

mode

to

save a RAM-resident

program

onto

cassette

tape.

CSA

VE

saves

the

tokenized

version

ofthe

program.

On

enter-

ing

CSA VE

two

bells

ring

to

indicate

that

.the

PLAY

and

RECORD

buttons

must

be

pressed

followed

by

li!IBJ. Do

not, however,

press

these

buttons

until

the

tape

has

been

positioned.

It

is

faster

to

save a program

using

this

command

rather

than

a SAVE

"C"

(see SAVE)

because

short

inter-record

gaps

are

used

.

Notes:

Tapes

saved

using

the

two

commands,

SAVE

and

CSA VE,

are

not

com-

patible

It

may

be

necessary

to

enter

an

LPRINT (see

LPRINT)

before

using

CSAVE.

Otherwise,

CSAVE

may

not

work

properly.

For

specific

instructions

on

how

to

connect

and

operate

the

hardware,

cue

the

tape,

etc.,

see

the

ATARI

410

Program

Recorder

Manual.

DOS

(DO.)

ENTER(E.)

INPUT

(I.)

Format: Example:

DOS DOS

The

DOS

command

is

used

to

go

from

BASIC

to

the

Disk

Operating

System

(DOS).

If

the

Disk

Operating

System

has

not

been

booted

into

memory,

the

com-

puter

will

go

into

Memo

Pad

mode

and

the

user

must

press

IMMM';!i@!ll

to

return

to

Direct

mode.

If

the

Disk

Operating

System

has

been

booted,

the

DOS

Menu

is

displayed.

To

clear

the

DOS

Menu

from

the

screen,

press

*'itii#&l;li!Mi.

Control

then

passes

to

BASIC.

Control

can

also

be

returned

to

BASIC

by

selecting B (Run

Cartridge)

on

the

DOS

Menu.

The

DOS

command

is

usually

used

in

Direct

mode;

however,

it

may

be

used

in

a

program.

For

more

details

on

this,

see

the

Atari

DOS

Manual.

Format:

ENTER filespec

Examples:

ENTER

"C

ENTER "D:DEMOPR.INS"

This

statement

causes a

cassette

tape

to

play

back a program

originally

recorded

using

LIST (see

Section

2,

LIST).

The

program

is

entered

in

unprocessed

(un-

tokenized)

form,

and

is

interpreted

as

the

data

is

received.

When

the

loading

is

complete,

it

may

be

run

in

the

normal

way.

The

ENTER

command

may

also

be

used

with

the

disk

drive.

Note

that

both

LOAD

and

CLOAD (see Section 2)

clear

the

old

program

from

memory

before

loading

the

new

one

. ENTER

merges

the

old

and

new

programs.

This

ENTER

statement

is

usually

used

in

Direct

mode.

Format:

INPUT [

#aexp

{ ; } ] {

~~;~

}

[,

{

~~~~

} ... ]

Examples:

100 INPUT X 100 INPUT N$ 100 PRINT "ENTER THE VALUE

Of

X"

110 INPUT X

This

statement

requests

keyboard

data

from

the

user.

In

execution,

the

com-

puter

displays

a?

prompt

when

the

program

encounters

an

INPUT

statement.

It

is

usually

preceded

by

a PRINT

statement

thCJ.t

prompts

the

user

as

to

the

type

of

information

being

requested.

String

variables

are

allowed

only

if

they

are

not

subscripted.

Matrix

variables

are

not

allowed.

The

#aexp

is

optional

and

is

used

to

specify

the

file

or

device

number

from

which

the

data

is

to

be

input

(see

Input/Output

Devices).

If

no

#aexp

is

specified,

then

input

is

from

the

screen

editor

(E:).

If

several

strings

are

to

be

input

from

the

screen

editor,

type

one

string,

press

liiii!Jml,

type

the

l;i§iii;lll , etc.

Arithmetic

numbers

can

be

typed

on

the

same

line

separated

by commas.

10

PRWT 11Et-iTER 5 NUt"18EPS

TO

BE

SUt·1t·1ED

11

20

FOR

t·~=

1

TO

5

30

I

t·~PUT

::-::

40

C=C+>::

50

NE>::T

t·~

60

PR r HT

II

THE :::ut

·1

oF

'/OUP

Nut·1E:ER::: If:

II

; c

70

um

Figure

5-1

Input

Program

Listing

I/0

Commands

and Devices

25

LOAD

(LO.)

LPRINT (LP .)

NOTE

(NO.)

OPEN

(0.)

CLOSE (CL.)

26

J/0

Commands

and

Devices

Format:

LOAD filespec

Example:

LOAD "D1:JANINE.BRY"

This

command

is

similar

to

CLOAD

except

the

full file

name

system

can

be

used.

LOAD

uses

long

inter-record

gaps

on

the

tape

(see

CLOAD)

and

uses

the

token-

ized

version

ofthe

program.

When

using

only

one

disk

drive,

it

is

not

necessary

to

specify a number

after

the

"D"

because

the

default

is

disk

drive

#1.

Format: Example:

LPRINT

[exp][

{ : }

exp

... ]

LPRINT "PROGRAM TO CALCULATE

X"

100 LPRINT X;" ";Y;"

";Z

This

statement

causes

the

computer

to

print

data

on

the

line

printer

rather

than

on

the

screen.

It

can

be

used

in

either

Direct

or

Deferred

modes.

It

requires

no

device

specifier

and

no

OPEN

or

CLOSE

statement.

(BASIC

uses

IOCB

#7.)

The

above

program

listing

illustrates a program

that

will

add 5 numbers

entered

by

the

user.

To

print a program

listing

on

the

line

printer,

see

LIST.

Format: Example:

NOTE

#aexp,

avar,

avar

100 NOTE #1,

X,

Y

This

command

is

used

to

store

the

current

disk

sector

number

in

the

first

avar

and

the

current

byte

number

within

the

sector

in

the

second

avar.

This

is

the

current

read

or

write

position

in

the

specified

file

where

the

to

be

read

or

written

is located.

This

NOTE

command

is

used

when

writing

data

to

a

disk

file (see

POINT).

The

information

in

the

NOTE

command

is

written

into

a

second

file

which

is

then

used

as

an

index

into

the

first

file.

Formats:

OPEN

#aexp,aexp1,aexp2,

filespec

CLOSE

#aexp

Examples:

100 OPEN #2,8,0,

"D1:A

T ARI800.BAS"

100 A$

=

"D1:A

TARI800.BAS" 110 OPEN #2,8,0,A$ 150 CLOSE #2

Before a

device

can

be

accessed,

it

must

be

opened.

This "opening"

process

links

a specific

IOCB

to

the

appropriate

device

handler,

initializes

any

CIO-related con-

trol

variables,

and

passes

any

device-specific

options

to

the

device

handler.

The

parameters

for

the

OPEN

command

are

defined

as follows:

#

Mandatory

character

that

must

be

entered

by

the

user.

aexp

Reference

IOCB

or

file

number

to

same

parameters

for

future

use

(as

in

CLOSE

command).

Number

may

be 1 through

7.

aexp1

aexp2

filespec

Code

number

to

determine

input

or

output

opera

-

tion.

Code 4

8

12

6

9

input

operation

output

operation

input

and

output

operation

disk

directory

on

the

printer.

11. To

return

to BASIC,

type

B liill!m

or

press

Utiii!&l;li@:U

.

IIO

Commands

and

Devices

31

NOTES

32

Notes

ARITHMETIC FUNCTIONS

ABS

CLOG

EXP

INT

6

FUNCTION

LIBRARY

This

section

describes

the

arithmetic,

trigonometric,

and

special

purpose

func

-

tions

incorporated

into

the

ATARI BASIC. A

function

performs a computation

and

returns

the

result

(usually a number)

for

either a print-out

or

additional

computational

use.

Included

in

the

trigonometric

functions

are

two

statements,

radians

(RAD)

and

degrees

(DEG),

that

are

frequently

used

with

trigonometri

c

functions.

Each

function

described

in

this

section

may

be

used

in

either

Direct

or

Deferred

mode.

Multiple

functions

are

perfectly

legal.

The

following

functions

and

statements

are

described

in

this

section:

ABS

ATN

ADR

CLOG

cos

FRE

EXP

SIN

PEEK

INT

DEG/RAD

POKE

LOG

USR RND SGN

SQR

Format:

ABS(aexp)

Example:

100 AB = ABS (-190)

Returns

the

absolute

value

of a number

without

regard

to

whether

it

is

positive

or

negative.

The

returned

value

is

always

positive.

Format:

CLOG (aexp)

Example:

100 C = CLOG(83)

Returns

the

logarithm

to

the

base

10

of

the

variable

or

expression

in

paren-

theses.

CLOG(O)

should

give

an

error

and

CLOG(1)

should

be

0.

Format:

EXP

(aexp)

Example:

100 PRINT EXP(3)

Returns

the

value

ofe

(approximately

2.71828283),

raised

to

the

power

specified

by

the

expression

in

parentheses.

In

the

example

given

above, the

number

returned

is 20.0855365.

In

some

cases

, EXP is

accurate

only

to six

signifi

cant

digits.

Format:

INT (aexp)

Examples:

100 I = INT(3.445) 100 X

=

INT(-

14.66778)

(3

would

be stored

in

I)

(-15

would

be

stored

in

X)

Function Li

brary

33

LOG

RND

SGN

s~

Returns

the

greatest

integer

less

than

or

equal

to

the

value

of

the

expression.

This

is

true

whether

the

expression

evaluates

to a

positive

or

negative

number.

Thus,

in

our

first

example

above, I is

used

to

store

the

number

3.

In

the

second

example,

X is

used

to

store

the

number-

15

(the

first

whole

number

that

is

less

than

or

equal

to

-14.66778).

This

INT

function

should

not

be

confused

with

the

function

used

on

calculators

that

simply

truncates

(cuts

off)

all

decimal

places.

Format:

LOG(aexp)

Example:

100 L = LOG(67.89/2.57)

Returns

the

natural

logarithm

of

the

number

or

expression

in

parentheses.

LOG(O)

should

give

an

error

and

LOG(1)

should

be

0.

Format:

RND(aexp)

Example:

10

A=RND

(0)

Returns a hardware-generated

random

number

between 0 and

1,

but

never

returns

1.

The

variable

or

expression

in

parentheses

following

RND is a

dummy

and

has

no

effect

on

the

numbers

returned.

However,

the

dummy

variable

must

be

used.

Generally,

the

RND

function

is

used

in

combination

with

other

BASIC

statements

or

functions

to

return a number

for

games,

decision

making,

and

the

like.

Here's a simple

routine

that

returns a random

number

between 0 and

999 .

1 0

:~~=~~NO(

0)

20

F.::x:=IHT<

1000:~~:;()

33

PRINT

R?i

Format:

SGN(aexp)

Example:

100 X = SGN(-199}

(0

is

dummy

variabl

e)

(-1

would

be returned)

Returns a -1

ifaexp

evaluates

to a negative

numbe

r;

a 0

ifa

exp

evaluates

to 0,

or

a

1

if

aexp

evaluates

to a

positive

number.

Format:

SQR(aexp)

Example:

100 PRINT SQR(100) (10

would

be printed)

Returns

the

square

root

of

the

aexp

which

must

be

positive.

TRIGONOMETRIC

FUNCTIONS

ATN

Format:

ATN(aexp)

Example:

100 X = ATN(65)

Returns

the

arctangent

of

the

variable

or

expression

in

parentheses

.

cos

Format:

COS(aexp)

Example:

100 C = COS(X+Y+Z)

Note:

Presumes

X,

Y, Z previously

defined

!

Returns

the

trigonometric

cosine

of

the

expre

ssion

in

parentheses.

34

Funct

ion

Library

SIN

DEGIRAD

SPECIAL PURPOSE FUNCTIONS

ADR

FRE

PEEK

POKE

Format:

SIN(aexp)

Example:

100 X = SIN(Y)

Note:

Presumes Y previously

defined.

Returns

the

trigonometric

sine

of

the

expression

in

parentheses.

Format:

DEG RAD

Example:

100 DEG 100

RAD

These

two

statements

allow

the

programmer

to

specify

degrees

or

radians

for

trigonometric

function

computations.

The

computer

defaults

to

radians

unles

s

DEG is specified.

Once

the

DEG

statement

has

been

executed,

RAD

must

be

used

to

return

to

radians.

See

Appendix E for

the

additional

trigonometric

functions

that

can

be

derived.

Format: Example:

ADR(svar) ADR(A$)

Returns

the

decimal

memory

address

ofthe

string

specified

by

the

expression

in

parentheses.

Knowing

the

address

enables

the

programmer

to

pass the

informa-

tion

to

USR

routines,

etc. (See

USR

and

Appendix

D)

Format:

FRE(aexp)

Examples:

PRINT FRE (0) 100 IF

FRE

(0)<1000

THEN PRINT "MEMORY CRITICAL"

This

function

returns the

number

ofbytes

of user

RAM

left.

Its

primary

use

is

in

Direct

mode

with a dummy

variable

(0)

to

inform

the

programmer

how

much

memory

space

remains

for

completion

of a program.

Of

course

FRE

can

also

be

used

within

a BASIC

program

in

Deferred

mode.

Format:

PEEK(aexp)

Examples:

1000 IF PEEK (4000) =

255

THEN

PRINT

"255"

100 PRINT

"LEFT

MARGIN IS"; PEEK (82)

Returns

the

contents

of a specified

memory

address

location

(aexp).

The

address

specified

must

be

an

integer

or

an

arithmetic

expression that

evaluates to

an in-

teger

between 0 and

65535

and

represe

nts

the

memory

address in

decimal

nota-

tion

(not

hexadecimal). The

number

returned

will

also

be a decimal

integer

with

a

ran

ge from

0 to

255.

This

function

allows

the

user

to

examine

either

RAM

or

ROM locat

ion

s.

In

the

first

examp

le

above, the

PEEK is us

ed

to

determine

whether location

4000

(decimal)

contains

the

number

255.

In

the

second

exam

-

ple,

the

PEEK

function

is u

sed

to

examine

the

left

margin.

Format:

POKE

aexp1,

aexp2

Examples:

POKE 82, 10 100 POKE 82,

20

Function Li

brary

35

USR

36

Function

Library

Although

this

is

not a function,

it

is

included

in

this

section

because

it

is closely

associated

with

the

PEEK

function.

This

POKE

command

inserts

data

into

the

memory

location

or

modifies

data

already

stored

there. In

the

above

format,

aexp1

is

the

decimal

address

of

the

location

to

be

poked

and

aexp2

is

the

data

to

be

poked.

Note

that

this

number

is a decimal

number

between 0 and

255. POKE

cannot

be

used

to

alter

ROM

locations.

In

gaining

familiarity

with

this

command

it

is

advisable

to

look

at

the

memory

location

with a PEEK

and

write

down

the

contents

of

the

location.

Then,

if

the

POKE

doesn't

work

as

anticipated,

the

original

contents

can

be

poked

into

the

location.

The

above

Direct

mode

example

changes

the

left

screen

margin

from

its

default

position

of

2 to a

new

position

of

10.

In

other

words,

the

new

margin

will

be

8

spaces

to

the

right.

To

restore

the

margin

to

its

normal

default

position,

press

ti"ti•341;1J1jj

0

Format:

Example:

USR

(aexp1

[,

aexp2][,

aexp3

..

.])

100 RESULT =

USR

(ADD1,A *2)

This

function

returns

the

results

of a machine-language

subroutine.

The

first

ex-

pression,

aexp1,

must

be

an

integer

or

arithmetic

expression

that

evaluates

to

an

integer

that

represents

the

decimal

memory

address

of

the

machine

language

routine

to

be

performed.

The

input

arguments

aexp2,

aexp3,

etc.,

are

optional.

These

should

be

arithmetic

expressions

within a decimal

range

of 0 through

65535. A

non-integer

value

may

be

used;

however,

it

will

be

rounded

to

the

nearest

integer.

These

values

will

be

converted

from

BASIC's

Binary

Coded

Decimal

(BCD)

floating

point

number

format

to a two-byte

binary

number,

then

pushed

onto

the

hardware

stack,

composed

of a group

of

RAM

memory

locations

under

direct

control

of

the

6502

microprocessor

chip.

Figure

6-1

illustrates

the

struc-

ture

of

the

hardware

stack.

(Number

of

arguments

on

the

stack-may

be

0)

(High

byte

of

argument

X)

(Low

byte

of

argument

X)

(High

byte

of

argument

Y)

(Low

byte

of

argument

Y)

(High

byte

of

argument

Z)

(Low

byte

of

argument

Z)

(Low

byte

of

return

address)

(High

byte

of

return

address)

Figure

6-1.

Hardware

Stack

Definition

Note:

X is

the

argument

following

the

address

of

the

routine, Y is

the

second,

Z is

the

third,

etc.

There

are N pairs

of

bytes.

See Section 11

for a description

of

the

USR

function

in

machine

language

pro-

gramming.

Appendix D defines

the

bytes

in

RAM available for

machine

language

programming.

ASC

CHR$

7

STRINGS

This

section

describes

strings

and

the

functions associated

with

string

handling.

Each

string

must

be

dimensioned

(see

DIM

statement,

Section

8)

and

each

string

variable

must

end

with

a $. A

string

itself

is a group

of

characters "strung"

together.

The

individual

characters

may

be

letters, numbers,

or

symbols

(including

the

Atari

special

keyboard

symbols.) A substring

is a part

of a longer

string

and

any

substring

is

accessible

in

Atari

BASIC

if

the

string

has

been

pro-

perly

dimensioned

(see

end

of

section).

The

characters

in a string

are

indexed

from 1 to

the

current

string

length,

which

is

less

than

or

equal

to

the

dimen-

sioned

length

of

the

string.

The

string

functions

described

in

this

section

are:

ASC

STR$

CHR$

VAL

LEN

Format:

ASC(sexp)

Examples:

100A

= ASC(A$)

This

function

returns

the

AT

ASCII

code

number

for

the

first

character

of

the

string

expression

(sexp).

This

function

can

be

used

in

either

Direct

or

Deferred

mode. figure

7-1

is a short

program

illustrating

the

ASC

function.

10

DH1

A$0::

3)

20

A:f.=11P

30

A=ASC(

A$)

40

PF.:H-H

A

Figure

7-1.

ASC

Function

Program

When

executed,

this

program

prints

a 69

which

is

the

AT

ASCII

code

for

the

let-

ter

"E".

Note

that

when

the

string

itself

is used,

it

must

be

enclosed

in

quotation

marks.

Format:

CHR$ (a

exp)

Examples:

100

PRINT

CHR$ (65)

100

A$

= CHR$ (65)

This

character

string

function

returns

the

character,

in

string

format,

represented

by

the

A TASCII

code

number(s)

in

parentheses.

Only

one character

is

returned.

In

the

above

examples,

the

letter

A is

returned.

Using

the

ASC

and

CHR$

functions,

the

following

program

prints

the

upper case

and

lower

case

let-

ters

of

the

alphabet.

Str-ings

37

LEN

STR$

VAL

38

Strings

10

FOR

I=0

TO

25

~'0

PR I HT

CHfU(

ASC(

..

A

11

)+I ) )

CHF.:$(

A:

:;C(

"a"

)+

I)

30

t·~E>=:T

I

Figure

7-2.

ASC

and

CHR$

Program

Example

Note:

There

can

be

only

one

STR$

and

only

one

CHR$

in

a logical

comparison.

Format:

LEN (sexp)

Example:

100 PRINT LEN(A$)

This

function

returns

the

length

in

bytes

of

the

designated

string. This

informa-

tion

may

then

be

printed

or

used

later

in a program.

The

length

of a string

variable

is

simply

the

index

for

the

character

which

is

currently

at

the

end

of

the

string. Strings

have a length

ofO

until

characters

have

been

stored

in

them.

It

is

possible

to

store

into

the

middle

of

the

string

by

using

subscripting.

However,

the

beginning

of

the

string

will

contain

garbage

unless

something

was

stored

(using

STO)

there

previously.

The

following

routine

illustrates

one

use

of

the

LEN

function:

10

Dir-1

A!(

10

>

2~3

A:i=u

AT

A~~

In

3(

1

F'~~

I

f

-~T

LEt·i<

A$

>

Figure

7-3.

LEN

Function

Example

The

result

ofrunning

the

above

program

would

be

5.

Format: Example:

STR$ (aexp)

A$=

STR$(65)

This

string

from

number

function

returns

the

string

form

of

the

number

in

parentheses. The

above

example

would

return

the

actual

number

65,

but

it

would

be

recognized

by

the

computer

as a

str

ing

.

Note:

There

can

only

be

one

STR$

and

only

one

CHR$

in

a logical

comparison.

F

or

exa

mple, A=

STR$(1) > STR$(2) is

not

valid

and

will

not

wor

k cor:rectly.

Format:

VAL(sexp)

Example:

100 A = V AL(A$)

This

function

returns a number

of

the

same

value

as

the

number

stored

as

a

string.

This

is

the

opposite

of

a STR$

function.

Usi

ng

this

function, the

computer

can

perform

arithmetic operations

on

strings

as show n

in the

following exam-

ple

program:

10

DH1

8$(5)

20

B:f.:

II

10(10(11!

30

E:=SG!~\

I..JAL(

B$) )

40

PRHH

11

THE

SQUAPE

POOT

OF

II ,

;8$

.;

II IS

II

jB

Figure

7-4.

VAL

Function

Program

Upon

execution,

the

screen

displays

THE SQUARE ROOT OF

B$

IS

100.

It

is

not

possible

to

use

the

VAL

function

with a string

that

does

not

start

with

a

number,

or

that

cannot

be

interpreted

by

the

computer

as a number.

It

can,

however,

intrepret

floating

point

numbers;

e.g.,VAL("1E9")would

return

the

number

1,000,000,000.

STRING

Strings

can

be

manipulated

in a variety

of

ways.

They

can

be

split,

concatenated,

MANIPULATIONS

rearranged,

and

sorted.

The

following

paragraphs

describe

the

different

manipulations.

String

Concatenation

means

putting

two

or

more

strings

together

to

form

one

large

string.

Each

string

to

be

included

in a larger

string

is

called a substring. Each

substring

must

be

dimensioned

(see

DIM).

In

Atari

BASIC, a

substring

can

con-

tain

up

to 99

characters

(including

spaces).

After

concatenation,

the

substrings

can

be

stored

in

another

string

variable,

printed,

or

used

in

later

sections

of

the

program.

Figure

7-5 is a

sample

program

demonstrating

string

concatenation.

In

this

program,

A$,

B$,

and

C$

are

concatenated

and

placed

in

A$.

10

D I

t1

A$(

1m;

) ,

8$(

100 ) ..

C$(

1 (u) )

:::.'0

A$=

II

sr~: I ~-lGS

::.:

suB:;rp

I

~-iGS

ARE

o I

~:cu:;sE

[I

II

30

E:$=

11

IN

'AT

A~:

I

BA:::IC--A

SELF-

TEACHmG

GUIDE

Ill

4~3

C$=~~---CHAPTE~:

9.

II

50

A$(

LEt-K

A$

H 1

)=B$

6£1

A$(

LHK

A$

)+

1

>=C$

70

F'k:HH

A$

Figure

7·5.

String

Concatenation

Example

String

Splitting

The

format

of a subscript

string

variable

is

as

follows:

svarname(aexp1[

,aexp2])

The

svarname

is

used

to

indicate

the

unsubscripted

string

variable

name

(with

$).

aexp1

indicates

the

starting

location

oft

he

substring

and

aexp2

(if

used)

in-

dicates

the

ending

location

of

the

substring.

If

no

aexp2

is

specified,

then

the

end

of

the

substring

is

the

current

end

of

the

string.

The

starting

location

cannot

be

greater

than

the

current

length

of

the

string. The

two

example

programs

in

Figure

7-6

illustrate

a split

string

with

no

end

location

indicated

and a split

string

with

an

ending

location

indicated.

10

DH1

~:$(

5)

20

S$="A8CD#"

3e

PRWT

S$(

2)

40

END

Result is

BCD.

(without

ending

location)

10

D m

:::$.::

2~::1

>

20

S$=11ATAPI

80(1

E:A:::IC

11

30

PR

I t·H

S$( 7 ..

9 >

40

END

Result

is 800.

(with ending

loc

ation

)

Figure

7·6.

Split

String

Examples

Strings

39

40

Strings

String

Comparisons

and

Sorts

In

string

comparisons,

the

logical

operators

are

used

exactly

the

way

they

are

with

numbers.

The

second

program

in

Appendix

His a simple

example

of

bub-

ble

sort.

In

using

logical

operators,

remember

that

each

letter,

number,

and symbol

is

assigned

an

ATASCII

code

number. A few

general

rules

apply

to

these

codes:

1.

AT

ASCII

codes

for

numbers

are

sized

in

order

of

the

numbers'

real

values

and

are

always

lower

than

the

codes

for

letters

(see

Appendix

C).

2.

Upper

case

letters

have

lower

numerical

values

than

the

lower

case let-

ters.

To

obtain

the

AT

ASCII code

for a lower

case

letter

if

you

know the

upper

case value,

add

32

to

the

upper

case code.

Note:

Atari

BASIC's

memory

management

system

moves

strings

around

in

memory

to

make

room

for

new

statements.

This

causes

the

string

address

to

vary

if a program

is

modified

or

Direct

mode

is

used.

DIM

(DI.)

8

ARRAYS

AND

MATRICES

An

array

is a one-dimensional

list

of

numb

ers

assigned

to

subscripted variables

;

e.g.,

A(O),

A(1), A(2).

Subscripts

range

from 0 to

the

dimensioned

value.

Figure

8-1

illustrates a 7-element

arra

y.

A(O) A(1) A(2) A(3) A(4) A(S) A(6)

Figure

8-1.

Example

of

an

Array

A

matrix,

in

this

context,

is a two-dimensional

table containing

rows

and

col-

umns.

Rows

run

horizontally

and

columns

run verticall

y.

Matrix

elements

are

stored

by

BASIC

in

row-ma

jor

order.

This

means

that all

the elem

ents

of

the

first

row

are

stored

first,

followed

by

all

the

elements

of

the

second

row,

etc

.

Figure

8-2

illustrates

a 7 x 4

matrix.

Columns

M(O,O)

M(0,1) M(0,2)

M(0,3)

M(1,0)

M(1

,1)

M(1,2 )

M(1,3)

M(2,

0)

M(2,1)

M(2,2)

M(2,3)

M(3,

0)

M(3,1)

M(3,2)

M(3,3) M(4,0) M(4,1) M(4,2) M(4,3) M(5,

0)

M(5,1) M(5,2) M(5,3)

M(6,0) M(6,1) M(6,2)

M(6,3)

Figure

8-2.

Example

of a Matrix

This

section

describes

the

two

commands

associated

with

arrays,

matrices,

and

strings, and

how

to

load

both

arrays

and

matrices.

The

com~a

nds

in

this sec-

tion

are:

DIM

CLR

Format:

D M {

svar(aexp)

}

1

mvar(aexp[

,aexp])

IJ{

,svar(aexp)

}tl

~

,mvar(aexp[

,aexp

... ] U

Examples:

DIM A(100) DIM M(6,3) DIM B$(20)

used with

STRINGS

Ana,v

s

and

Matr·ices

41

42

Arrays and

Matrices

A DIM

statement

is

used

to

reserve a certain

number

oflocations

in

memory

for

a

string,

array,

or

matrix. A character

in a string

takes

one

byte

in

memory

and

a

number

in

an

array

takes

six

bytes.

The

first

example

reserves

101 locations

for

an

array

designated

A.

The

second

example

reserves 7 rows

by 4 columns

for a two-dimensional

array

(matrix)

designated

M.

The

third

example

reserves

20

bytes

designated

B$.

All

strings,

arrays,

and

matrices

must

be

dimen-

sioned.

It

is a

good

habit

to

put

all DIM

statements

at

the

beginning

of

the

pro-

gram.

Notice

in

Figure

8-1

that

although

the

array

is

dimensioned

as DIM A(6),

there

are

actually 7 elements

in

the

array

because

of

the 0 element.

Although

Figure

8-2

is

dimensioned

as

DIM M(6,3), 28

locations

are

reserved.

Note:

The

ATARI

Personal

Computer

does

not

automatically

initialize

array

or

matrix

variables

to 0 at

the

start

of

program

execution.

To

initialize

array

or

matrix

elements

to

0,

use

the

following

program

steps:

250

orr·1

A(

100

>

300

FOR

E==0

TO

ll1l1

310

A(3

>=0

32f1

t·E·<T

E

Arrays

and

matrices

are

"filled"

with

data

by

using

FOR/NEXT

statements,

READIDA T A

statements

and

INPUT

commands.

Figure

8-3

illustrates

the

"building"

of

part

of

an

array

using

the

FOR/NEXT

loop

and

Figure

8-4

builds

an

array

using

the

READ/DATA

statements.

10

DH1

A<

we>

2f1

::·::=

1

(1

3(1

FO~:

E=1

TO

9(1

40

::-::=:~

=:+

1

50

A(E

)=>=:

60 t·4E>::T

E

70

FOP

E=1

TO

90

B(l

PF.:H-JT

E..

A(

E >

90

t·~E::-=:T

E

Figure

8-3.

Use

of

FOR/NEXT

to

Build

An

Array

10

DH1

A(3)

20

FOR

E=l

TO

3

30

F.:EAD

>=:

40

A(E>=>=:

50

PRHiT

A<E

).,

60

t·~E::-

=

:T

E

70

am

10(1

DATA

33

.. 45.,

12

Figure

8-4.

Use

of

R.EAD/DATA

to

Build

An

Array

CLR

Figure

8-5

shows

an

example

of

building

a 6 x 3

matrix.

10

Dit·1

t-1( 6 ..

3 >

20

FOP

Pm·l=0

TO

6

30

FOF.~

COL=l

TO

3

40 tl:

RC!l·J

..

COL

)=I

tH

(

~:t-~D

·::

0

/~::

1

00(1

)

50

t·~E~=:T

COL

=

t·~E>=:T

ROH

60

FO~:

F.:Ol·J=O

TO

6

70

FOF.:

COL=l

TO

3

:30

F'P I rH

t-1<

F.:Ol·J

·'

COL

>

90

t·~E:=<T

COL : F'P

I r·H =

t·~E>=:T

F.:O~·l

Figure

8-5.

Building A Matrix

Note

that

the

words

ROW

and

COLUMN

are

not

BASIC

commands,

statement

s,

functions,

or

keyword

s.

They

are

simply

variable

names

used

here

to

designate

which

loop

function

is first.

The

program

could

just

as easily have

been

written

with X and Y as

the

variable

names.

Format:

CLR

Example:

200

CLR

This

command

clears

the

memory

of

all

previously

dimensioned

strings,

arrays,

and

matrices

so

the

memory

and

variable

names

can

be

used

for

other

purposes.

It

also

clears

the

values

stored

in

undimensioned

var

iable

s.

If a matrix,

string,

or

array

is

needed

after a CLR

command,

it

must

be

redimensioned

with

a DIM

command.

Ar.,.ays

and

Matr·

ice

s

43

NOTES

44

Notes

9

GRAPHICS MODES

AND

COMMANDS

This

section

describes

the

Atari

BASIC

commands

and

the

different

graphics

modes

ofthe

ATARI

Personal

Computer.

Using

the

se

commands,

it

is

possible

to

create

graphics

for

game,

graphics, and

patterns

.

The

commands

to

be

described

in

this

section

are:

GRAPHICS COLOR

DRAWTO

LOCATE PLOT

POSITION

PUT/GET SETCOLOR

XIO

The

PUT/GET

and

XIO

commands

explained

in

this section

are

special

applica-

tions

of

the

same

commands

described

in

Section 5.

GRAPHICS (GR.)

Format: Example:

GRAPHICS

aexp

GRAPHICS 2

This

command

is

used

to

select

one

of

the

nine

graphics

modes.

Table

9-1

sum-

marizes

the

nine

modes and

the

characteristics

of

each. The

GRAPHICS

com-

mand

automatically

opens

the

screen

, S:(the

graphics windo

w),

as

device

116.

So

w

hen

printing

text

in

the

text window,

it

is

not

nece

ssary

to

specify

the

device

code.

The

aexp must

be

positive,

rounded

to

the

nearest

integer. Graphics

mode

0 is a full

-screen display

while

modes 1 through 8 are split

screen

displays. To

override

the split-screen,

add

the

characters

+ 16

to

the

mode

numb

er (aexp)

in

the

GRAPHICS

command.

Adding

32

prevents

the

graphics

comma

nd

from

clearing

the

scre

en.

To

return

to

graphics

mode 0 in

Dir

ect

mode,

pre

ss hiii@l;li@ii

or

type

GR.O

and press l;!jiii;Ui

TABLE

9.1-TABLE

OF

MODES

AND

SCREEN

FORMATS

SCREEN

FORMAT

Vert.

Number

Gr.

Mode

Horiz.

(Col)

Of

RAM

Mode

Type

(Rows)

Split

Full

Colors

Required

Screen

(Bytes)

0

TEXT

40

24

2

993

1

TEXT

20

24

5 513

2

TEXT

20

10

12

5 261

3 GRAPHICS

40

20

24

4 273

4 GRAPHICS

80

40

48

2 537

5 GRAPHICS

80

40

48

4 1017

6 GRAPHICS

160

80

96

2

2025

7 GRAPHICS

160 80

96

4

3945

8

GRAPHICS 320

160

192

1/2

7900

The

following

paragraphs

describe

the

nine

graphics

modes

.

Graph

ic Modes

and Cmnmand.

s

45

GRAPHICS

MODEO

GRAPHICS

MODES

1AND2

This

mode

is

the

1-color,

2-luminance

(brightness)

default

mode

for

the

AT

ARI

Personal

Computer.

It

contains a 24

by

40

character

screen

matrix. The

default

margin

settings

at 2 and

39

allow

38

characters

per

line.

Margins

may

be

chang-

ed

by

poking

LMARGN

and

RMARGN (82

and

83). See

Appendix

I.

~orne

syst_ems

have

different

margin

default

settings. The

color

ofthe

characters

IS

determmed

by

the

background

color.

Only

the

luminance

ofthe

characters

can

be

different.

This

full-screen

display

has a blue

display

area

bordered

in

black

(unless

the

border

is

specified

to

be

another

color).

To

display characters

at a specified

loca-

tion,

use

one

of

the

following

two

methods

.

Method

1.

lineno

POSITION aexp1,

aexp2

lineno

PRINT

sexp

Method

2

lineno

GR.

0

lineno

POKE 752,1

lineno

COLOR ASC(sexp)

lineno

PLOT

aexp1,aexp2

lineno

GOTO

lineno

Puts cursor

at

location

sp

ecified

by

aexp1

and

aexp2.

Specifies

gr

aphics

mode

.

Suppresses

cur

sor.

Specifies character

to

be printed. Specifies where

to

print

character.

Start

loop to prevent

READY

from

being

printed. (GOTO

same

linerw.J

Press

lll1D:I

to

terminat

e

loop.

GRAPHICS 0 is also

used

as a clear

screen

command

either

in

Direct

mode

or

Deferred

mode.

It

terminates

any

previously

selected

graphics

mode

and

returns

the

screen

to

the

default

mode

(GRAPHICS 0).

As

defined

in

Table

9-1,

these

two

5-color

modes

are

Text

modes.

However,

they

are

both

split-screen

(see

Figure

9-1)

modes.

Characters

printed

in

Graphics

mod

e 1 a

re

twice

the

width

of

those printed

in

Graphics

0,

but

are

the same

height.

Characters

printed

in

Graphics

mode 2 are

twice

the

width

and

height

of

those

in

Graphics

mode

0.

In

the

split-screen

mode,

a PRINT

command

is us

ed

to

display

characters

in

either

the

text

window

or

the

graphics window

. To

print

characters

in

the

graphics

window,

specify

device

#6

after

the

PRINT

com-

mand.

Example:

100

GR.

1

110 PRINT#6;"

ATARI"

The

default colors depend

on

the type

of

character

input.

Table

9-2

defines

the

default

color

and

color

register

used

for

each

type.

Table

9-2.

Default

Colors

for

Specific

Input

Types

Character

Type

Upper

case

alphabetical

Lower

case

alphabetical

Inverse

upper

case

alphabetical

Inverse

lower

case

alphabetical Numbers Inverse

numbers

Color

Register

0

1

2

3

0

2

Note:

See SETCOLOR

to

change

character

colors.

Default

Color

Orange

Light

Green

Dark

Blue

Red

Or

ange

Dark

Blue

46

Graphic Modes

and

Commands

GRAPHICS

MODES

3,

5,

AND

7

GRAPHICS

MODES

4AND6

GRAPHICS

MODE8

Unless

otherwise

specified, all

characters

are

displayed

in

upper

case

non-

inverse

form.

To

print

lower

case

letters

and

graphics

characters,

use

a

POKE

756,226.

To

return

to

upper

case,

use

POKE

756,224.

In

graphics

modes 1 and

2,

there

is

no

inverse

video,

but

it is

possible

to

get

all

the

rest

of

the

characters

in

four

different

colors

(see

end

of

section).

(X=Ol

(Y=O)

S:

Graphics

Window

(graphics

or

tt>xt)

E:

Text

Window

(4

lines)

border

(size

depends

on

individual

TV's

overscan)

Figure

9-1.

Split-Screen

Display

For

Graphics

Modes 1 and

2

The X and Y coordinates

start

at 0 (upper

left

of

screen).

The

maximum

values

are

the

numbers

of

rows

and

columns

minus

1 (see

Table

9-1).

This

split-screen

configuration

can

be

changed

to a full

screen

display

by

adding

the

characters

+ 16

to

the

mode

number.

Example:

GRAPHICS 1 + 16

These

three

4-color

graphics

modes

are

also

split-screen

displays

in

their

default

state,

but

may

be

changed

to

full

screen

by

adding

+ 16

to

the

mode

number.

Modes 3, 5,

and 7 are

alike

except

that

modes 5 and 7 use

more

points

(pixels)

in

plotting,

drawing,

and

positioning

the

cursor;

the

points

are

smaller,

thereby

giving a much

higher

resolution.

These

two

2-color

graphics

modes

are

split-screen

displays

and

can

display

in

only

two

colors

while

the

other

modes

can

display 4 and

5 colors.

The

advantage

of a two-color

mode

is

that

it

requires

less RAM

space

(see

Table

9-1).

Therefore,

it

is

used

when

only

two

colors

are

needed

and

RAM is

getting

crowded.

These

two

modes

also

have a higher

resolution

which

means

smaller

points

than

Graphics

mode

3.

This

graphics

mode

gives

the

highest

resolution

of

all

the

other

modes.

As

it

takes

a lot

of

RAM

to

obtain

this

kind

of

resolution,

it

can

only

accomodate

a

maximum

of

one

color

and

two

different

luminances.

Graphic Modes

and

Commands

47

COLOR (C.)

DRA

WTO

(DR.)

LOCATE (LOC.)

Format:

COLOR

aexp

Examples:

110 COLOR ASC("A") 110 COLOR 3

The

value

of

the

expression

in

the

COLOR

statement

determines

the

data

to

be

stored

in

the

display

memory

for

all

subsequent

PLOT

and

DRA

WTO

com-

mands

until

the

statement

is

executed. The

value

must

be

positive

and

is

usually

an

integer

from 0 through

255.

Non-integers

are

rounded

to

the

nearest

integer.

The

graphics

display

hardware

interprets

this

data

in

different

ways

in

the

different

graphics

modes. In

text

modes 0 through

2,

the

number

can

be

from 0 through

255 (8 bits)

and

determines

the

character

to

be

displayed

and

its

color. (The

two

most

significant

bits

determine

the

color. This

is

why

on-

ly

64

different

characters

are

available

in

these

modes

instead

of

the

full

256-character

set.)

Tables

9-6

and

9-7

at

the

end

ofthis

section

illustrate

the

internal

character

set

and

the

character/color

assignment.

Table

9-2

is a simplified

table

which allow

s

easy

generation

of

some

of

the

colors.

For

example,

COLOR

ASC("

A"):

PLOT

5,5

will

display

an

orange A character

in

graphics

modes 1 or 2 at

location

5,5.

Graphics

modes 3 through 8 are

not

text

modes,

so

the

data

stored

in

the

display

RAM

simply

determines

the

color

of

each

pixel.

Two-color

or

two-luminance

modes

require

either 0 or

1 (1-bit)

and

four-color

modes

require

0, 1, 2 ,

or

3.

(The

expression

in

the

COLOR

statement may

have a value

greater

than

3,

but

onl

y

one

or

two

bits

will

be

used.)

The

actual

color

which

is

displayed

depends

on

the

value

in

the

color

register

which

corresponds

to

the

data

of

0, 1,

2,

or 3 in

the

pa

rticular

graphi

cs

mode being used .

This· may be

dete

rmin

ed

by

looking

in

Table

9-5,

which

gives

the

default

colors

and

the

corresponding

register

numbers.

Colors

may

be

changed

by

using

SETCOLOR.

Note

that

when

BASIC is

first

powered

up,

the

color

data

is

0,

and when

a

GRAPHICS

command

(without

+ 32) is

executed

, all

of

the

pixels

are

set to 0.

Therefore,

nothing

seems

to

happen

to PLOT

and

DRA

WTO

in

GRAPHICS 3

through 7 when

no

COLOR statem e

nt

has bee

n execut

ed. Cor

rec

t b y

doing

a

COLOR 1

first

.

Fonnat: Example:

DRA

WTO

aexp1, aexp2

100 DRA

WTO

10, 8

This state

ment caus

es a line to

be draw

n fr

om the last po

int display

ed

by a PLOT

(see

PLOT)

to

the

location

specified

by

aexp1

and

aexp2.

The

first

expression

represents

the X coordinate

and

the second

represents the

¥-coordinate

(see

Fig

ur

e 9-1). The color

of the

lin

e is the sam e color

as th e point dis

played

by the

PLOT.

Format: Example:

LOCATE a

exp1, aexp2, va

r

150 LOCATE 1

2,

15, X

This

command

positions

the invisible

graphics

cursor

at

the

specified loc

ation

in

th

e graph

ics w

ind

ow,

retri

eves th

e data at that pixe

l, a

nd

stor

es

it

in the

specified

arithmetic variable

. T

his gives a

number

from 0 to

255

for

Graphics

mode

s 0

through

2;

0

or 1 for

the

2-color

graphics modes; and

0, 1, 2,

or 3 for

the

4-co

lor

modes. The tw o arithmetic expre

ssions specify

th e X a

nd

Y coo

rdinates

of the

point. LOCATE

is e

quivale

nt

to:

POSITION

aexp1

, a

exp

2:GET #6,av

ar

48

Graphic Modes a

nd Commwu

is

PLOT

(PL.)

Doing

a PRINT

after

a LOCATE

or

GET

from

the

screen

may

cause

the

data

in

the

pixel

which

was

examined

to

be

modified.

This

problem

is

avoided

by

repositioning

the

cursor

and

putting

the

data

that

was

read,

back

into

the

pixel

before

doing

the

PRINT.

The

following

program

illustrates

the

use

of

the

LOCATE

command.

10

GF.:AF'H

I

C::;

3+

16

;2€1

COLOP

1

30

::;ETCOLOF.: 2 ..

1

~3,

:3

40

PLOT

1~3

..

15

5€1

DPAl·nO

15

_,

15

6ft

LOCATE

12

..

15_,

i<

70

F'RH-H

;:.::

Figure

9-2.

Example

Program

Using

LOCATE

On

execution,

the

program

prints

the

data

(1)

determined

by

the

COLOR state-

ment

which

was

stored

in

pixel

12, 15.

Format: Example:

PLOT

aexp1,

aexp2

100 PLOT 5,5

The

PLOT

command

is

used

in

graphics

modes 3 through 8 to

display a point

in

the

graphics

window.

The

aexp1 specifies

the

X-coordinate

and

the

aexp2

the

Y-coordinate.

The

color

of

the

plotted

point

is

determined

by

the

hue

and

luminance

in

the

color

register

from

the

last

COLOR

statement

executed.

To

change

this

color

register,

and

the

color

of

the

plotted

point,

use

SET-

COLOR.

Points

that

can

be

plotted

on

the

screen

are

dependent

on

the

graphics

mode

being

used.

The

range

of

points

begins

at 1

and

extends

to

one

less

than

the

total

number

of

rows

(X-coordinate)

or

columns

(Y-coordinate)

shown

in

Table

9-1.

POSITION

(POS.)

Format:

POSITION

aexp1,

aexp2

100 POSITION

8,

12

PUT/GET (PU./GE.)

Example: The

POSITION

statement

is

used

to

place

the

invisible

graphics

window

cursor

at a specified

location

on

the

screen

(usually

precedes

a PRINT

statement).

This

statement

can

be

used

in

all modes.

Note

that

the

cursor

does

not

actually

move

until

an

I/0

command

which

involves

the

screen

is

issued.

Formats:

PUT

#aexp,

aexp

GET

#aexp,

avar

Examples:

100

PUT

#6, ASC("

A")

200 GET #1, X

In

graphics

work,

PUT

is

used

to

output

data

to

the

screen

display.

This

state-

ment

works

hand-in-hand

with

the

POSITION

statement.

After a PUT

(or GET),

the

cursor

is

moved

to

the

on

the

screen. Doing

a PUT

to

device

#6

causes

the

one-byte

input

(second

aexp)

to

be

displayed

at

the

cursor

position.

The

byte

is

either

an

AT

ASCII code

byte

for a particular

character

(modes

0-2)

or

the

color

data

(modes

3-8).

GET is

used

to

input

the

code

byte

of

the

character

displayed

at

the

cursor

posi-

tion,

into

the

specified

arithmetic

variable.

The

values

used

in

PUT

and

GET

cor-

respond

to

the

values

in

the

COLOR

statement.

(PRINT

and

INPUT

may

also

be

used.)

Graphic Modes

and

Commands

49

SETCOLOR (SE.)

Note:

Doing a PRINT

after a LOCATE

or

GET

from

the

screen

may

cause

the

data

in

the

pixel

which

was

examined

to

be

modified.

To

avoid

this

problem,

reposition

the

cursor

and

put

the

data

that

was

read,

back

into

the

pixel

before

doing

the

PRINT.

Format: Example:

SETCOLOR

aexp1,

aexp2,

aexp3

100 SETCOLOR 0, 1, 4

This

statement

is

used

to

choose

the

particular

hue

and

luminance

to

be

stored

in

the

specified

color

register.

The

parameters

of

the

SETCOLOR

statement

are

defined

below:

aexp1

aexp2

aexp3

=

Color

register

(0-4

depending

on

graphics

mode)

=

Color

hue

number

(0-15. See

Table

9-3)

Color

luminance

(must

be

an

even

number

between 0 and

14;

the

higher

the

number,

the

brighter

the

display.

14

is

almost

pure

white.)

TABLE

9.3-THE

ATARI

HUE

(SETCOLOR

COMMAND)

NUMBERS

AND

COLORS

GRAY

LIGHT

ORANGE

(GOLD)

ORANGE

RED-ORANGE PINK PURPLE-BLUE BLUE BLUE LIGHT BLUE TURQUOISE GREEN-BLUE GREEN YELLOW-GREEN ORANGE-GREEN LIGHT ORANGE

SETCOLOR

(aexp2)

NUMBERS

0

1

2

3

4

6

7

8

9

10

11 12 13 14 15

Note:

Colors

will

vary

with

type

and

adjustment

of

TV

or

monitor

used.

The

ATARI

display

hardware

contains

five

color

registers,

numbered

from 0 through

4.

The

Operating

System

(OS)

has

five

RAM

locations

(COLORO

through

COLOR4,

see

Appendix

I -

Memory

Locations)

where

it

keeps

track

of

the

current

colors.

The

SETCOLOR

statement

is

used

to

change

the

values

in

these

RAM

locations.

(The

OS

transfers

these

values

to

the

hardware

registers

every

television

frame.)

The

SETCOLOR

statement

requires a value

from 0 to

4

to

specify a color

register.

The

COLOR

statement

uses

different

numbers

because

it

specifies

data

which

only

indirectly

corresponds

to a color

register.

This

can

be

confusing,

so

careful

experimentation

and

study

of

the

various

tables

in

this

section

is

advised.

No

SETCOLOR

commands

are

needed

if

the

default

set

of

five

colors

is

used.

Although

128

different

color-luminance

combinations

are

possible,

not

more

than

five

can

be

displayed

at

any

one

time.

The

purpose

of

the

color

registers

and

SETCOLOR

statement

is

to

specify

these

five

colors.

50

Graphic Modes

and

Commands

TABLE

9.4-TABLE

OF

SETCOLOR

"DEFAULT"

COLORS*

Set

color

Defaults

To

Luminance

Actual

Color

(Color

Register)

Color

0

2

8

ORANGE

1

12

10

GREEN

2

9

4 DARK

BLUE

3

4

6

PINK OR RED

4

0

BLACK

*

"DEF

AULT"

occurs

if

not

SETCOLOR

statement

is

used.

Note:

Colors may

vary

depending

upon

the

television

monitor type,

condition,

and

adjustment.

A

program

illustrating

Graphics

mode 3 and

the

commands

explained

so

far

in

this section

is

shown

below:

10

GPAFHICS

3

2'€1

~:;ETCOLO

F 0

.~

2

_,

B = C

:OL!)P

1

30

PLOT

17

..

1 :

DF.'At.JTO

1 7

..

1 0 :

DPAl·JTO 9 ·' 1 ::

:

40

PLOT 19.'

1 :

DRAL·HO

19

..

1:::

50

PLOT

20

..

1 :

D~~AL.JTO

20

..

1 E

60

PLOT

22

..

1 :

DRA

~.JT

O

22

..

W:

D~:A~·lTO

30, 18

70

POKE

752

..

1

8(1

F'P

HH ; F'P

WT

II

AT

A~

: I FEF~:~~Gt

·

iAL

COi·1P

UTEP~:;"

9(1

I~OTO

9(1

The

SETCOLOR

and

COLOR

statements

set

the color

of

the

points

to

be plotted

(see

Table

9.5).

The

SETCOLOR co

mmand

loa

ds

col

or

regist

er

0 w i

th

hue

2

(orange)

and a luminan

ce

of 8 ("norma

l").

The

next 4 lines plot the

points

to

be

displayed.

Line

90

suppresses

the

cursor

and

line 100

prints

the

string

expres-

sion

ATARI

PERSONAL COMPUTERS

in

the text

window

(6

spaces

in).

Note th

at

the

background

color

was

never

set

because the

default

is

the desired

col

or

(black).

If the

program

is execut

ed, it

will

print

the

Atari

logo

in the

graphics

window

and

the

string

expression

in

the text window

as

in

Figure

9-3.

Graphic

Modes

and

Commands

51

0

~

0

~

'-'

fl.)

E-

z

...

0

C).

fl.)

...

~

I

...

0 1

2

3

4

5 6 7 8 9

10

11

12 13 14 15 16 17 18

19

1

2

3

4

0 1

2

3

4 5 6 7 8

X-AXIS

POINTS

(COLUMNS)

9

10

11

1213

1415

16

171819,20

2122

23

2425

26

27282930

31

32

33

3435

3637

38 39

ATARI PERSONAL COMPUTERS

Figure

9-3.

Atari

Logo

Program

Execution

DEVICE

CODE

"S."

Screen

(Graphics

or

Text)

/(TEXT

WINDOW)

Editor

DEVICE

CODE

"E."

(Text

Only)

"

~

;:r

c;·

~

"'

;:s

....

g

;3 ;3

"'

;:s

~

"'

Default

Colors

LIGHT

BLUE

DARK

BLUE

BLACK

ORANGE

LIGHT GREEN

DARK

BLUE

RED

BLACK

ORANGE

LIGHT GREEN

DARK

BLUE

BLACK

ORANGE

BLACK

LIGHT GREEN

DARK

BLUE

BLACK

Mode

or

Condition

MODE 0

and ALL TEXT WINDOWS

MODES 1

and

2

(Text Modes)

MODES 3, 5,

and

7

(Four-color

Modes)

MODES4

and

6

(Two-color

Modes)

4

MODE8

(1

Color

2

Luminances)

TABLE

9.5-MODE,

SETCOLOR, COLOR

TABLE

SETCOLOR

(aexpt)

Color

Register

No.

(aexp)

DESCRIPTION

AND

COMMENTS

0 COLOR

data

-

1

actually

Character

luminance

(same

color

as

background)

2

determines

Background

3

character

to

-

4

be

plotted

Border

0

COLOR

data

Character

1

actually

determines

Character

2

character

to

be

Character

3

plotted

Character

4

Background,

Border

0

1

Graphics

point

1

2

Graphics

point

2

3

Graphics

point

3

- -

4

0

Graphics

point

(background

default),

Border

0

1

Graphics

point

1 -

-

2

-

3 -

-

0

Graphics

point

(background

default),

Border

0

-

1

Graphics

point

luminance

(same

color

as

background)

2

0

Graphics

point

(background

default)

3

-

4

-

Border

--

-

~--

XIO

(X.)

SPECIAL FILL APPLICATION

Format: Example:

XIO 18,

#aexp,

aexp1,

aexp2,

filespec

100 XIO 18, #6, 0, 0,

"S:"

This

special

application

ofthe

XIO

statement

fills

an

area

on

the

screen

between

plotted

points

and

lines

with a non-zero

color

value.

Dummy

variables

(0)

are

used

for

aexp1

and

aexp2.

The

following

steps

illustrate

the

fill

process:

1.

PLOT

bottom

right

corner

(point 1).

2. DRA

WTO

upper

right

corner

(point

2).

This

outlines

the

right

edge

of

the

area

to

be

filled.

3.

DRA

WTO

upper

left

corner

(point

3).

4. POSITION

cursor

at

lower

left

corner

(point

4).

5.

POKE

address

765

with

the

fill

color

data

(1, 2,

or

3).

6.

This

method

is

used

to fill

each

horizontal

line

from

top

to

bottom

oft

he

spe-

cified

area. The

fill

starts

at

the

left

and

proceeds

across

the

line

to

the

right

until

it

reaches a pixel

which

contains

non-zero

data

(will

wraparound

if

necessary).

This

means

that

fill

cannot

be

used

to

change

an

area whi

ch h

as

been

filled

in

with a non-zero

value, as

the

fill

will

stop.

The

fill

command

will

go

into

an

infinite

loop

if

a fill

with

zero

(0)

data

is

attempted

on a line

which

has

no

non-zero

pixels

.

I:I;H!M

or

(ifjWI;I@§i

can

be

used

to

stop

the

fill

if

this

happens

.

The

following

program

creates a shape

and

fills it

with a data

(color)

of

3.

Note

that

the

XIO

command

draws

in

the

lines

of

the

left

and

bottom

of

the

figure.

10

GRAF'H

I

c:;

5+

16

2'0

COLOF.'

3

30

PLOT

70;

45

40

D~:A~-H

C!

50

.'

W

:-0

[tRA~~JT~J

3(t

..

10

60

F'0:3ITI0fi

10,45

70

F'OKE

765

.:

3.

8f1

::-no

1:::

, #6, o

..

o.,

":;

·"

9ff

GOTO

90

Figure

9-4.

Example

"FILL"

Program

Assigning

Colors

To

Characters

In

Text

Modes 1 and

2

This

procedure

describes

the

method

of

assigning

colors

to

the

Atari

character

set.

First,

look

up

the

character

numb

er

·in

Table

9-6.

Then,

see

Table

9-7

to

get

the

conversion

of

that

numb

er

required

to

ass

ign a co

lor

register

to

it.

Example:

Assign

SETCOLOR 0

to

lower

case "r"

in

mode

2

w

hose

color

is

determin

ed

by

register

0.

1.

In

Table

9-6,

find

the

column

and

number

for

" r "

(114-column

4).

2.

Using

Table

9-7,

locate

column

4.

Conversion

is

the

cha

racter

number

minu

s

32

(114-

32 = 82

).

54

Graphic

Modes

and

Commands

Table

9.6-INTERNAL

CHARACTER

SET

Column

1

Column

2

Column

3

Column

4

If

CHR

If

CHR

If

CHR

It

CHR

It

CHR

It

CHR

It

CHR

It

CHR

0

Spa

ce

16

0

32

@

48

p

64

c

80

g

96

D

112

p

1

!

17

1 33

A

49

Q

65

G

81

~

97

a

113

q

2

"

18

2

34

B

50

R

66

ll

82

=

98

b

114

r

3

It

19

3

35

c

51

s

67

g

83

c

99

c

115

s

4

$

20

4

36

D

52

T

68

a

84

c

100

d

116

t

5

%

21

5

37

E

53

u

69

Cl

85

~

101 e

117

u

6

&;

22

6

38

F

54

v

70

~

86

~

102

f

118

v

7

'

23

7

39

G

55

w

71

~

87

~

103

g

119

w

8

(

24

8

40

H

56

X

72

~

88

~

104

h

120

X

9 )

25

9 41

I

57

y

73

~

.

89

11

105 i

121

y

10

*

26

42

J

58

z

74

~

90

~

106

J

122

z

11

+

27

'

43

K

59

[

75

~

91

CD

~

107

k

123

D

12

'

28

<

44

L

60

\

76

Iii

92

0

108

I

124

I

13

-

29

-

45

M

61

J

77

Iii

93

D

109

m

125

CD

...

-

14

-

30

>

46

N

62

A

78

~

94

Q

110

n

126

<D

-4

15

I

31

?

47

0

63

-

79

~

95

Cl

111 0

127

CD

~

1.

In

mode 0 these characte

rs must be preceded w

ith

an escape,

CHR$(27),

to

be

print

ed.

MODEO

MODE1

OR

MODE2

Table

9.7-CHARACTER/COLOR

ASSIGNMENT

Conversion

1

Conversion

2

Conversion

3

Conversion

4

zSETCOLOR

2

#+32 #+32

#-32

NONE

POKE

756,224

POKE

756,226

SETCOLOR 0

_$32

#+32

#-32

SETCOLOR 1

NONE

#+64

#-64

NONE

SETCOLOR 2

#+160

#+96 #+96

SETCOLOR 3

#+128

#+192

#+64

#+128

Z.

Luminance

controlled

by

SETCOLOR

1,

0, LUM.

3. POKE

the

Character

Base

Address

(CHBAS)

with

226

to

specify

lower

case

let-

ters

or

special

graphics

characters

; e.g.,

POKE

756,226

or

CHBAS =

756

POKE CHBAS,

226

To

return

to

upper

case

letters, numbers,

and

punctuation

marks

, POKE CHBAS

with

224.

4. A PRINT

statement

using

the

converted

number

(82)

assigns

the

lower

case

"r"

to

SETCOLOR 0

in

mode

2 (see

Table

9-5).

Graphic

Control

Characters

These

characters

are

produced

when

the

&ml

key is

pressed

with

the

alphabetic

keys

shown

on

back

cover.

These

characters

can

be

used

to

draw

design,

pictures,

etc.,

in

mode 0 and

in

modes 1 and 2 if

CHBAS

is

changed

.

56

Graph

ic

Mod

es

and Commands

SOUND (SO.)

10

SOUNDS

AND

GAME

CONTROLLERS

This

section

describes

the

statement

used

to

generate

musical

notes

and

sounds

through

the

audio

system

ofthe

television

monitor.

Up

to

four

different

sounds

can

be

"played"

simultaneously

creating

harmony.

This

SOUND

statement

can

also

be

used

to

simulate

explosions,

whistles,

and

other

interesting

sound

ef-

fects.

The

other

commands

described

in

this

section

deal

with

the

functions

used

to

manipulate

the

keyboard,

joystick,

and

paddle

controllers.

These

func-

tions

allow

these

controllers

to

be

plugged

in

and

used

in

BASIC

programs

for

games,

etc.

The

command

and

functions

covered

in

this

section

are:

SOUND

Format: Example:

PADDLE

PTRIG

SOUND

aexp1,

aexp2,

aexp3,

aexp4

100 SOUND 2, 204, 10, 12

STICK

STRIG

The

SOUND

statement

causes

the

specified

note

to

begin

playing

as

soon

as

the

statement

is

executed.

The

note

will

continue

playing

until

the

program

en-

counters

another

SOUND

statement

with

the

same

aexp1

or

an

END

statement.

This

command

can

be

used

in

either

Direct

or

Deferred

modes.

The

SOUND

parameters

are

described

as follows:

aexp1

=

aexp2

aexp3

aexp4

Voice.

Can

be

0-3,

but

each

voice

requires a separate

SOUND state-

ment.

Pitch.

Can

be

any

number

between

0-255.

The

larger

the

number,

the

lower

the

pitch.

Table

10-1

defines

the

pitch

numbers

for

the

various

musical

notes

ranging

from

two octaves

above

middle C to

one

octavf'

below

middle

C.

Distortion. Can

be

even

numbers

between

0-14 .

Used

in

creating

sound

effects. A 10 is

used

to

created a "pure"

tone

whereas a 12

gives

an

interesting

buzzer

sound. A buzzing

sound

(like

engines

at

a

race

track)

can

be

produced

using

two

separate

SOUND

commands

with

the

distortion

value

(aexp3)

alternating

between 0 and

1.

A

value

of

1 is

used

to

force

output

to

the

speaker

using

the

specified

volume

(see aexp4).

The

rest

of

the

numbers

are

used

for

other

special effects,

noise

generation,

and

experimental

use.

Volume control. Can

be

between 1 and

15.

Using

a 1

creates a sound

barely

audible

whereas

a 15 is

loud. A value

of

B is

considered

nor-

mal.

If

more

than 1 sound

statement

is

being

used,

the

total

volume

should

not

exceed

32.

This

will

create

an

unpleasant

"clipped"

tone.

Sounds

and

Game Controllers

57

Using

the

note

values

in

Table

10-1,

the

following

example

demonstrates

how

to

write a program

that

will

"play"

the

C scale.

TABLE

10.1.

TABLE

OF PITCH

VALUES

FOR

THE

MUSICAL

NOTES

HIGH

NOTES

MIDDLE C

LOW

NOTES

10

F.:EAD

A

~

c

B A#

orB~

A G#

or

A~

G F#

or

G~

F E D#

orE D C#

or

D~

c

B A#

orB A G#

or

A~

G F#

or

G~

F E D#

orE~

D C#

or

D~

c

B A#

orB~

A G#

or

A~

G F#

G~

F D D#

or

I~

D C#

or

Db

c

20

IF

A=256

iHEt·i

HiD

30

SOUr·iD

~3

.'

A

..

1

(1

.•

1 0

40

FOP

~·J=1

TO

400:

r·iE>~T

~·J

50

PRWT

A

60

GOTO

10

70

END

29 31 33 35 37 40 42 45 47 50 53 57 60 64 68

72

76 81 85 91 96 102

108 114 121 128

136

144

153 162 173 182 193 204 217 230 243

80

DATA

~·9

..

31.·

35,

4f)

..

45

..

4 7

..

53

..

6(1, 64,

72

·'

:31

191.·

96.:

108.:

121

90

[lATA

12:3.~

144.~162

..

1:::2.~

193.:217)243

..

256

Figure

10-1.

Musical

Scale

Program

Note

that

the

DATA

statement

in

line

80

ends

with a 256,

which

is

outside

ofthe

designated

range.

The

256 is

used

as

an

end-of-data

marker.

58

Sounds

and

Game Controllers

GAME CONTROLLER

FUNCTIONS

PADDLE

PTRIG

STICK

Figure

10-2 is

an

illustration

of

the

three

controllers

used

with

the

Atari

Per-

sonal

Computers.

The

controllers

can

be

attached

directly

to

the

Atari

Per-

sonal

Computer

or

to

external

mechanical

devices

so

that

outside

events

can

be

fed

directly

to

the

computer

for

processing

and

control

purposes.

Format:

Example:

Figure

10-2.

Game

Controllers

P ADDLE(aexp) PRINT P ADDLE(3)

This

function

returns

the

status

of a particular

numbered

controller.

The

paddle

controllers

are

numbered

0-7

from

left

to

right.

This

function

can

be

used

with

other

functions

or

commands

to

"cause"

further

actions

like

sound,

graphics

controls,

etc.

For

example,

the

statement

IF

PADDLE(3) = 14

THEN

PRINT

"PADDLE

ACTIVE."

Note

that

the

PADDLE

function

returns a number

bet-

ween 1 and

228,

with

the

number

increasing

in

size

as

the

knob

on

the

con-

troller

is

rotated

counterclockwise

(turned

to

the

left).

Format:

PTRIG(aexp)

Example:

100

IF

PTRIG(4)"'0 THEN PRINT "MISSILES FIRED!"

The

PTRIG

function

returns a status

ofO

ifthe

trigger

button

ofthe

designated

controller

is

pressed. Otherwise,

it

returns a value

of

1.

The

aexp

must

be

a

number

between 0 and 7 as

it

designates

the

controller.

Format:

STICK(aexp)

Example:

100 PRINT

STICK(3)

This

function

works

exactly

the

same

way

as

the

PADDLE

command,

but

can

be

used

with

the

joystick

controller.

The

joystick

controllers

are

numbered

from

0-3

from

left to

right.

Controller

1 =

STICK(O)

Controller

2 = STICK(l)

Controller

3

==

STICK(2)

Controller

4 =

STICK(3)

Figure

10-3

shows

the

numbers

that

will

be

returned

when

the

joystick

con-

troller

is

moved

in

any

direction.

Sounds

and

Game Controllers

59

STRIG

14

13

Figure

10-3.

Joystick

Controller

Movement

Fonnat:

STRIG(aexp)

Example:

100

IF

STRIG(3) = 0

THEN

PRINT "FIRE TORPEDO"

The

STRIG

function

works the

same

way

as

the

PTRIG

function

.

It

can

be

used

with

both

the

joystick

and key

board controller

s.

GO

Sound.s

and Game

Contro

llers

MEMORY

CONSERVATION

11

ADVANCED

PROGRAMMING

TECHNIQUES

This

section

includes

hints

on

increasing

programming

efficiency,

conserving

memory,

and

combining

machine

language

programs

with

Atari

BASIC

pro-

grams.

This

section

does

not

include

an

instruction

set

for

the

6502

micro-

processor

chip

nor

does

it

give

instructions

on

programming

in

machine

language.

An

additional

purchase

of

the

Atari

Assembler

Editor

cartridge*

and

a

careful

study

of

Atari's

Assembler

Editor

Manual

are

strongly

recommended

.

These

hints

give

ways

of

conserving

memory

. Some

ofthese

methods

make

pro-

grams

less

readable

and

harder

to

modify,

but

there

are

cases

where

this

is

necessary

due

to

memory

limitations.

1.

In

many

small

computers,

eliminating

blank

spaces

between

words

and

characters

as

they

are

typed

into

the

keyboard

will

save

memory. This

is

not

true

of

the

ATARI

Personal

Computer

System,

which

removes

extra

spaces.

Statements

are

always

displayed

the

same

regardless

of

how

many

spaces

were

used

on

program

entry.

Spaces

should

be

used

Gust as

in

typing

on

a

conventional

typewriter)

between

successive

keywords

and

between

keywords

and

variable

names.

Here

is

an

example:

10

IF A

5 THEN PRINT A

Note

the

space

between

IF

and A and

between

THEN

and

PRINT.

In

most

cases, a

statement

will

be

interpreted

correctly

by

the

computer

even

if

all

spaces

are

left

out,

but

this

is

not

always

true.

Use

conventional

spacing.

2. Each

new

line

number

represents

the

beginning

of

what

is

called a new

"logical

line".

Each

logical

line

takes

6 bytes

of "overhead

",

whether

it

is

used

to

full

capacity

or

not.

Adding

an

additional

BASIC

statement

by

using

a

colon

(:)

to

separate

each

pair

of

statements

on

the

same

line

takes

only

3

bytes.

*Available

late

1980.

Advanced Programming Techniques

61

If

you

need

to

save

memory,

avoid

programs

like

this:

10

>{='r'+1

20

V=Y+1

3e

Z=X+"i'

40

PRI~H

Z

5e

GOTO

53

and

consolidate

lines

like

this:

10

>::=:~+l:Y='l+1:2=::·::+'-f

:

PRINT

Z:GOTO

10

This

consolidation saves

12

bytes.

3.

Variables

and

constants

should

be

"managed"

for

savings,

too. Each

time

a

constant

(4,5,16,3.14159, etc.) is used,

it

takes 7 bytes.

Defining a new

variable

requires 8 bytes

plus

the

length

of

the

variable

name

(in characters).

But

each

time

it

is

used

after

being

defined,

it

takes

only 1 byte,

regardless

of

its

length.

Thus,

if a constant

(such as 3.14159) is

used

more

than

once

or

twice

in a program,

it

should

be

defined

as a variable,

and

the

variable

name

used

throughout

the

program.

For

example:

10

PI=3 .

14159

20

PRINT

"AREA

OF

A

CIRCLE

IS

THE

RADIUS

SQUARED T It1ES

II

i

pI

4. Literal

strings

require 2 bytes

overhead

and 1 byte

for

each

character

(including

all spaces)

in

the

string.

5.

String

variables

take 9 bytes

each

plus

the

length

of

the

variable

name

(including

spaces)

plus

the

space

eaten

up

by

the

DIM

statement

plus

the

size

ofthe

string

itself(1

byte

per

character,

including

spaces)

when

it is

defined.

Obviously,

the

use

of

string

variables

is

very

costly

in

terms

of

RAM.

6. Definition

of a new

matrix

requires

15

bytes

plus

the

length

of

the

matrix

variable

name

plus

the

space

needed

for

the

DIM

statement

plus 6 times

the

size

of

the

matrix

(product

of

the

number

of

rows

and

the

number

of

col-

umns).

Thus,

a 25

row

by 4 column

matrix

would

require

15 +

approxi-

mately

3 (for

variable

name) + approximately

10

(for

the

DIM

statement)

+ 6

times

100 (the

matrix

size),

or

about

630

bytes.

82

Advanced Programming Techniques

PROGRAMMING

IN

MACHINE

LANGUAGE

7. Each

character

after

REM

takes

one

byte

of

memory.

Remarks

are

helpful

to

people

trying

to

understand a program,

but

sometimes

it

is

necessary

to

remove

remark

statements

to

save

memory.

8.

Subroutines

can

save

memory

because

one

subroutine

and

several

short

calls

take

less

memory

than

duplicating

the

code

several

times.

On

the

other

hand, a subroutine

that

is

only

called

once

takes

extra

bytes

for

the

GOSUB

and·

RETURN

statements.

9.

Parentheses

take

one

byte

each.

Extra

parentheses

are

a good

idea

in

some

cases

if

they

make

an

expression

more

understandable

to

the

programmer

.

However,

removing

unnecessary

parentheses

and

relying

on

operator

precedence

will

same a few

bytes.

Machine

language

is

written

entirely

in

binary

code.

The

AT

ARI

Personal

Com-

puter

contains

a 6502

microprocessor

and

it

is possible to call 6502

machine

code

subroutines

from

BASIC

using

the

USR

function. Short

routines may

then

be

entered

into a program

by

hand

assembly

(if

necessary).

Before it

returns

to

BASIC,

the

assembly

language

routine

must

do a pull

ac-

cumulator

(PLA)

instruction

to

remove

the

number

(N)

of

input

arguments

off

the

stack.

If

this

number

is

not

0,

then

all

ofthe

input

arguments

must

be

pop-

ped

off

the

stack

also

using

PLA. (See

Figure

6-1).

The

subroutine

should

end

by

placing

the

low

byte

of

its

result

in

location 212

(decimal),

and

then

return

to

BASIC

using

an

RTS

(Return

from

Subroutine)

in-

struction.

The

BASIC

interpreter

will

convert

the

2-byte

binary

number

stored

in

locations 212

and

213

into

an

integer

between 0 and

65535

in

floating-point

format

to

obtain

the

value

returned

by

the

USR

function.

The

ADR

function may

be

used

to

pass

data

that

is

stored

in

arrays

or

strings

to

a

subroutine

in

machine

language. Use

the

ADR

function

to

get

the

address

of

the

array

or

string,

and

then

use

this

address

as

one

of

the

USR

input

arguments.

The

following

program,

Hexcode Loader,

provides

the

means

of

entering

hexa-

decimal

codes, co

nverting

each

hexadecimal

number

to

decimal,

and

storing

the

decimal

number

into

an

array.

The

array

is

then

executed

as

an

assembly

language

subroutine.

(An

array

is

used

to

allocate space

in

memory

for

the

routine.)

Advanced Programming Techniques

63

1. To use

this

program,

first

enter

it.

After

entering

it, save

this

program

on

disk

or

cassette

for

future

use.

10

GRAPHICS

0,

PRINT

"rE:~~CODE

LOADER

PROG

RAI'1"

=PRINT

20

REM

STORES

OECit1AL

EQUILIALHHS

IN

ARR

A~t

A,

OUTPUTS

IN

PRINTED • DATA

STAT8·1ENT

S'

AT

21

REM

LI~E

NUMBER

1500.

30

REM

USEJ;.:

TI-H~

PLACES

CURSOR

ON

PR

It·ITE

0

OUTPUT

LINE,

HITS

"RETURHu, ~ ENTERS

31

REM

REST

OF

BASIC

PROGRAM

IOCLUDING

U

SR

STATEMENT.

43

DIM

A<

50)..

HE:)=:$(

5)

50

REM

INPUT,COt·MEF.:~3IOt

·

V:;TORAGE

OF

DATA.

60

N=0 = PRWT

"Et-HER

1

1-1)::

CODE

. IF

LAST

ONE

IS

IN}

EtHEF.:

I

DOHE

I •

II;

70

INPUT

1·£:=0::$

89

IF

HE:~=

II

DONE

II

THEN

N=999:

GOTO

130

90

FOR

1=1

TO

LEW

HE:~{$>

100

IF

HE:~<

I,

I ){="9"

H£t-~

N=t-t

=

~16+UAL<

HE

:~

I } I ) ) =

GOTO

120

110

N=~t=n6+ASC<

HE:);:$(

L I> >-Asu

11

A"

>+10

120

NE'I.T

I

13£1

PRit·IT

H =

C=C+1

140

A<

C

)=N

150

IF

N<>999

THEN

GOTO

60

190

REM

PRHIT

OUT

DATA

LWE

AT

1500

200

GRAPHICS

0=PRINT 111500

DATA

11

;

210

c=e

220

C=C+1

230

IF

A< C )=999

THEt-~

PRHH

"999

11

:STOP

240

PRINT

A(

C);

II}

II;

250

A<C

)=0

260

GOTO

220

300

PRIHT

"PUT

CORRECT

t-UMBER

OF

HE:=< BYT

ES

IH

Lit·E

1000.

":STOP : REt1

TRAP

LmE

999

f'E1

:r.~

E>;ECUT

I

Ot~

MODULE

:f.::;::

1000

CLR : BYTES=0

1910

TRAP

390:

DIM

E$(

1 ),

E( I NT<:

8\'TES . ...-6

)+1

)

1030

FOR

I=l

TO

B'lTES

1940

READ

A=

IF

A>255

TI·El~

GOTO

1060

1050

POKE

ADR<E$)+J,A

1060

NE:>n

I

1970

REM

BASIC

PART

OF

USER

Is

P~:OI;RAt1

FO

LLO~~S

Figure

11-1.

He.-rcode

Loader

Input

Program

64

Advanced

Programming

Techniques

2.

Now

add

the

BASIC

language

part

of

your

program

starting

at

line

1080 in-

cluding

the

USR

function

that

calls

the

machine

language

subroutine.

(See

example

below.)

3.

Count

the

total

number

of

hex

codes

to

be

entered

and

enter

this

number

on

line

1000

when

requested.

If

another

number

is

already

entered,

simply

replace

it.

4.

Run

the

program

and

enter

the

hexadecimal

codes

of

the

machine

level

subroutine

pressing

1Di1J

after

each

entry. After

the

last

entry,

type

DONE

and

press

IDiiJ.

5.

Now

the

DATA

line

(1500)

displays

on

the

screen.

It

will

not

be

entered

into

the

program

until

the

cursor

is

moved

to

the

DATA

line

and

fiiiim

is

pressed.

6.

Add a program

line

5 GOTO 1000 to

bypass

the

hexcode

loader

(or

delete

the

hexcode

loader

through

line

260).

Now

save

the

completed

program

by

using

CSA

VE

or

SAVE.

It

is

important

to

do

this

before

executing

the

part

of

the

program

containing

the

USR

calL A

mistake

in a machine

language

routine

may

cause

the

system

to

crash.

If

the

system

does

hang up,

press

(ftii@l;li!+ii

.

If

the

system

doe

sn't

respond,

turn

power

off

and

on

again,

reload

the

program,

and

correct

it.

Note:

This

method

only

works

with

relocatable

machine

language

routines.

The

following

two

sample

programs

can

each

be

entered

into the

Hexcode

Loader

program.

The

first

program

prints

NOTHING

IS

MOVING

while

the

machine

program

changes

the

colors.

The

second

sample

program

displays

a

BASIC

graphics

design,

then

changes

colors.

1980

GRAPHICS

1+16

1090

FOR

I=1

TO

6

1100

PRIHT

#6j

11

t10t.hir.s

is

t"II0

1v1

in::t!

11

1110

PF~INT

#6;

11

t~OTHH~

IS

t10UH~G!

II

1120

PRIHT

#6.:

11

not.hins

ls

mo

1

...

•ins!

11

1130

PRIHT

#6.:

11

NOTHit·~

IS

t101...!H~G!

II

1140

NE:)::T

I

1150

Q=USR(

ADR<

E$

)+

1 )

1160

FOR

I=1

TO

25: t·

E=<T

I =

GOTO

1150

After

entering

this

program,

check

that

line

1000 reads:

1000 CLR:BYTES

= 21

Type

RUN

liimmJ.

Ad

vanced

Progra

mmin

g Techn

iqu

es

65

Now

enter

the

hexadecimal

codes

as

shown

column

by

column.

68

2

A2

E8

0

EO

AC

3

C4

90

2

F5

BD

8C

cs

C7

2

9D

60

C4

BYTES=

21

When

completed,

type

DONE

and

press

&mJ.

Now

place

the

cursor

after

the

last

entry

(999)

on

the

DATA

line

and

pressiDmJ.

Now

run

the

program

by

typing

GOTO 1000

and

pressing

l;liilll;!ll,

or

if

line

5

has

been

added,

type

RUN

lilll!lmJ.

Press

illil1tito

stop

program

and

delete

line

5.

The

second

program,

which

follows,

should

be

entered

in

place

of

the

NOTHING

IS

MOVING

program. Be

sure

to

check

the

BYTES =

__

count

in

line

1000.

Follow

steps 2 through

6.

1080

GRAPHICS

7+16

1090

SET

COLO~~

€L

91

4

110(1

SETCOLOF.:

L 9 ..

E:

1110

SETCOLOR

2~9~4

1120

CR=1

1130

FOR

::-::=0

TO

159

1140

COLOR

INT<

CR)

115(1

PLOT

801

0

1160

~AL·JTO

:;

::

..

95

117(1

CR=CR+0

.

125

1180

IF

CR=4

THEN

CR=1

1190

NE:x:T

:<

1200

:~=US~'(

ADR(

E$

)+

1 )

121(1

FOR

1=1

TO

15=N£:;::T

I

1220

GOTO

1200

Type

RUN

lim!liJ3

Enter

the

hexadecimal

codes

for

this

program

column

by

column.

66

Advanced

Programming Techniques

68

A2

0

AC

C4

2

BD

C5

2

9D

-

CA

2

E8 EO

2 90 F5

8C C6

2

60

BYTES=

21

Address

Object

Code

02C4 02C5 02C6 02C7

6000 68

6001

A200

6003

ACC402

6006

BDC502

6009

9DC402

600C

E8

600D

E002

600F

90F5

6011 8CC602 6014 60

Assembler

Prints

This

11

Indicates

data

(source)

*

Routine

is

relocatable

When

completed,

type

DONE

and

press

lilii!lmJ.

Now

place

the

cursor

after

the

last

entry

(999)

on

the

DATA

line

and

press

lilii!lmJ.

Now

run

the

program

by

typing

GOTO 1000

and

pressing

limml3,or

add

line

5

GOTO 1000

and

type

RUN

lilii!lmJ.

Press

l!m!!:l

to

stop

program

and

delete

line

5.

Figure

11-2

illustrates

an

assembler

subroutine

used

to

rotate

colors

which

might

prove

useful.

It

is

included

here

for

the

information

of

the

user.

Assembler

Subroutine

to

Rotate

Colors

..

Line

No.

0100 0110 0120

0130 0140 0150 0160 0170 0175 0180 0190 0200 0210 0220 0230 0240

0250 0260

0270

0280 0290

Label

Mnemonic

Data

Routine

to

rotate

COLOR

data

From

one

register

to

another.

4

colors

are

rotated.

Operating

system

address COLOR 0 = $02C4 COLOR 1 = $02C5

COLOR 2 = $02C6 COLOR 3 = $02C7

*=

$6000

Machine

program

starting

address*

PLA

Pop

stack

(See

Chapter

4)

LDX

110

Zero

the X register

LDY

COLORO

Save COLOR 0

LOOP

LDA COLOR1,X

STA

COLORO,X

INX

Increment

the

X re.e;ister (add

one)

CPX

113

Compare

contents

of X register

with

2

BCC

LOOP Loop

if X register

contents

are

less

than

2

STY

COLOR3

Save COLOR 0

in

COLOR 3

RTS

Return

from

machine

level

sub-

routine

This

Portion

is

Source

Information

Programmer

Enters

Using

Atari

Assembler

Cartridge

$

Indicates a hexadecimal

number

Figure

11-2.

Assembler

Subroutine

To

Rotate

Colors

Advanced Programming Techniques

67

APPENDIX

A

ALPHABETICAL DIRECTORY

OF BASIC RESERVED

WORDS

Note:

The

period

is

mandatory

after

all

abbreviated key

word

s.

RESERVED

WORD:

ABS

ADR AND

ASC

ATN

BYE

CLOAD

CHR$

CLOG

CLOSE

CLR

COLOR

COM

CONT

cos

CSAVE

ABBREVIATION:

B.

CLOA.

CL.

c.

CON.

BRIEF

SUMMARY

OF

BASIC

STATEMENT

Function

returns abs

olute

value

(unsigned) of

the

va

riable

or e

xpr

essio

n.

Function

returns

memory

address

of

a s

tring.

Logical oper a

tor:

Expression

is

true only if

both subex-

pressions

joined

by

AND

are

true.

String

function

returns the

numeric value

of a single

string

character.

Function

returns

the

arctangent

of a number

or

expres-

sion

in

radi

ans

or

deg

rees.

Exit

from

BASIC

and

return

to

the res

ident

operating

system

or

console

processor

.

Loads

data

from

Program

Recorder

into

RAM.

String

function

returns a single

string

byte

equivalent

to a numeri

c v

alu

e be

twe

en 0

and 255

in

AT

ASC

II

cod

e.

Function

returns

the

base

10

logarithm

of

an

expres-

sio

n.

I/0

statement

used

to

close a file

at

the

conclusion

of

I/0

operations. The opposite

of

DIM:

Undimension

s all

string

s;

matrices. Chooses co

lor reg

ist

er

to

be used

in

color

graphi

cs

work

.

Sa

me

as DIM.

Continue. Causes a

program

to

restart

execution

on

the

following

use

of

the

i·l;it!M key

or

encounter-

ing

a

STOP

.

Function

returns

the

cosine

of

the

variable

or

expre

s-

sion

(degrees

or

radians).

Outpu

ts data f

rom

RAM

to the Prog

ram Rec

ord

er for

tape

storage.

Ap

pendix

A-1

RESERVED

WORD:

DATA

DEG

DIM

DOS

DRAWTO

END

ENTER

EXP

FOR

FRE

GET

GOSUB

GOTO

GRAPHICS

.

IF

INPUT

INT

LEN

A-2

Appendix

ABBREVIATION:

D.

DE.

DI.

DO.

DR.

E.

F.

GE.

GOS.

G.

GR.

I.

BRIEF

SUMMARY

OF

BASIC

STATEMENT

Part

ofREAD/DATA

combination.

Used

to

identify

the

succeeding

items

(which

must

be

separated

by

commas)

as

individual

data

items.

Statement

DEG

tells

computer

to

perform

trigonometric

functions

in

degrees

instead

of

radians.

(Default

in

radians.)

Reserves

the

specified

amount

of

memory

for

matrix,

array,

or

string.

All

string

variables,

arrays,

matrices

must

be

dimensioned

with a DIM

statement.

Reserved

word

for

disk

operators.

Causes

the

menu

to

be

displayed.

(See

DOS

Manual.)

Draws a straight

line

between a plotted

point

and

specified

point.

Stops

program

execution; closes files;

turns

off

sounds.

Program

may

be

restarted

using

CONT. (Note:

END

may

be

used

more

than

once

in a program.)

I/0

command

used

to

store

data

or

programs

in

un-

tokenized

(source)

form.

Function

returns

e (2.7182818)

raised

to

the

specified

power.

Used

with

establish

FOR/NEXT

loops. In-

troduces

the

range

that

the

loop

variable

will

operate

in

during

the

execution

of

loop.

Function

returns

the

amount

of

remaining

user

memory

(in bytes).

Used

mostly

with

disk

operations

to

input

a single

byte

of

data.

Branch

to a

subroutine

beginning

at

the

specified

line

number. Unconditional

branch

to

a specified

line

number.

Specifies

which

of

the

eight

graphics

modes

is to

be

used. GR.O

may

be

used

to

clear

screen.

Used

to

cause conditional

branching

or

to

execute

another

statement

on

the

same

line (only

ifthe

first ex-

pression

is

true).

Causes

computer

to

ask

for

input

from

keyboard.

Ex-

ecution

continues

only

when

i;i§ii@l

key

is

pressed

after

inputting

data.

Function

returns

the

whole

integer

below

the

specified value.

Rounding

is

always

downward,

even

when

number

is negative.

String

function

returns

the

length

of

the

specified

str-

ing

in

bytes

or

characters

(1

byte

contains 1 character).

RESERVED

WORD:

LET

LIST

LOAD

LOCATE

LOG

LPRINT

NEW

NOTE

ON

OPEN

OR

PADDLE

PEEK

PLOT

POINT

POKE

POP

POSITION

PRINT

ABBREVIATION:

LE.

L.

LO.

LOC.

LP.

N.

NO.

o.

PL.

P.

POK.

POS.

PR.

or?

BRIEF

SUMMARY

OF

BASIC

STATEMENT

Assigns a value

to

a specific

variable

name.

LET is op-

tional

in

Atari

BASIC,

and

may

be

simply

omitted.

Display

or

otherwise

output

the

program

list.

Input

from

disk,

etc.

into

the

computer.

Graphics: Stores,

in

a specified

variable,

the

value

that

controls

a specified

graphics

point.

Function

returns

the

natural

logarithm

of a number.

Command

to

line

printer

to

print

the

specified message.

Erases all

contents

of

user

RAM.

Causes a

FOR/NEXT

loop

to

terminate

or

continue

defending

on

the

particular

variables

or

expressions.

Al

loops

are

executed

at

least

once

.

A "

1"

is

returned

only

if

the

expression

is NOT

true.

If

it is

true,

a

"0"

is

returned.

See DOSIFMS

Manual

...

used

only

in

disk

operations.

Used

with

GOTO

or

GOSUB

for

branching

purposes.

Multiple

branches

to

different

line

numbers

are

possible

depending

on

the

value

of

the

ON

variable

or

expres-

sion. Opens

the

specified file for

input

of

output

operations.

Logical

operator

used

between

two

expressions.

If

either

one

is

true,

a

"1"

is evaluated. A

"0

'

results

only

if

both

are

false.

Function

returns

position

of

the

paddle

game

controller.

Function

returns

decimal

form

of

contents

of

specified

memory

location (RAM

or

ROM).

Causes a

single

point

to

be

plotted

at

the

X, Y location

specified. Used

with

disk

operations

only.

Insert

the

specified

byte

into

the

specified

memory

loca-

tion

. May

be

used

only

with

RAM.

Don't

try

to

POKE

ROM

or

you'll

get

an

error.

Removes

the

loop variable

from

the

GOSUB stack. Used

when

departure

from

the

loop is

made

in

other

than

normal

manner.

Sets

the

cursor

to

the

specified

screen

position.

I/0

command

causes

output

from

the

computer

to

the

specified

output

device.

Appendix

A-3

RESERVED

WORD:

PTRIG

PUT

RAD

READ

REM

RESTORE

RETURN

RND

RUN

SAVE

SETCOLOR

SGN

SIN

SOUND

SQR

STATUS

STEP

STICK STRIG

STOP

A-4

Appendix

ABBREVIATION:

PU.

REA.

R.

or

•

lffilS'J

RES. RET.

RU.

s.

SE.

so.

ST.

STO.

BRIEF

SUMMARY

OF

BASIC

STATEMENT

Function

returns

status

of

the

trigger

button

on

game

controllers. Causes

output

of a single

byte

of

data

from

the

computer

to

the

specified device.

Specifies

that

information

is

in

radians

rather

than

degrees

when

using

the

trigonometric

functions.

Default is to

RAD.

(See DEG.)

Read

the

in

the

DATA

list

and

assign

to

specified

variables.

Remarks.

This

statement

does

nothing,

but

comments

may

be

printed

within

the

program

list

for

future

reference

by

the

programmer.

Statements

on a line

that

starts

with

REM

are

not

executed.

Allows

DATA

to

be

read

more

than

once.

RETURN

from

subroutine

to

the

statement

immediate-

ly

following

the

one

in

which

GOSUB

appeared.

Function

returns a random

number

between 0 and

1,

but

never

1.

Execute

the

program.

Sets

normal

variables

to

0,

un-

dims

arrays

and

string.

I/0

statement

causes

data

or

program

to

be

recorded

on

disk

under

filespec

provided

with

SAVE.

Store

hue

and

luminance

color

data

in a particular

color

register. Function

returns

+ 1

if

value

is

positive, 0 if

zero,

- 1

if

negative. Function

returns

trigonometric

sine

of

given

value

(DEG

or

RAD).

Controls

register,

sound

pitch,

distortion,

and

volume

of

a

tone

or

note.

Function

returns

the

square

root

of

the

specified

value.

Calls

status

routine

for

specified

device.

Used

with

FOR/NEXT.

Determines

quality

to

be

skipped

between

each

pair

of

loop

variable

values.

Function

returns

position

of

stick

game

controller.

Function

returns 1 if

stick

trigger

button

not

pressed,

0

if

pressed.

Causes

execution

to stop,

but

does

not

close files

or

turn

off

sounds.

RESERVED

WORD:

STR$

THEN

TO

TRAP

USR

VAL

XIO

ABBREVIATION:

T.

X.

BRIEF

SUMMARY

OF

BASIC

STATEMENT

Function

returns a character

string

equal

to

numeric

value

given. For example:

STR$(65)

returns

65

as a

string.

Used

with

IF:

If

expression

is

true,

the

THEN

statements

are

executed.

If

the

expression

is false, con-

trol

passes

to

Used

with

FOR

as

in

"FOR X = 1

TO

10".

Separates

the

loop

range

expressions.

Takes

control

of

program

in

case

of

an

INPUT

error

and

directs

execution

to

a specified

line

number.

Function

returns

results

of

a

machine-language

subroutine.

Function

returns

the

equivalent

numeric

value

of

a

string. General I/0

statement

used

with

disk

operations

(see

DOSIFMS

Manual)

and

in

graphics

work

(Fill).

App

endix

A-5

ERROR

CODE

NO.

2

3

4

5

6

7

8

9

10

11

12

13

14

15

ERROR

CODE

MESSAGE

APPENDIX

B

ERROR

MESSAGES

Memory

insufficient

to

store

the

statement

or

the

new

variable

name

or

to

DIM a

new

string

variable.

Value

Error: A value

expected

to

be a positive

integer

is

negative, a value

ex-

pected

to

be

within

a specific

range

is

not.

Too

Many

Variables: A maximum

of

128

different

variable

names

is

allowed.

(See

Variable

Name

Limit.)

String

Length

Error:

Attempted

to

store

beyond

the

DIMensioned s

tring

length.

Out

of

Data

Error: READ

statement

requires

more

data

items

than

supplied

by

DATA

statement(s).

Number

greater

than

32767:

Value

is

not a positive

integer

or

is

greater

than

32767.

Input

Statement

Error:

Attempted

to

INPUT a non-numeric

value

into

a

numeric

variable.

Array

or

String

DIM

Error:

DIM

size

is

greater

than

32767

or

an

array/martix

reference

is

out

of

the

range

of

the

dimensioned

size, or

the

array/matrix

or

string

has

been

already

DIMensi

oned,

or a reference

has

been

made

to

an

undimensioned

array

or

string.

Argument

Stack

Overflow:

There

are

too

many

GOSUBs

or

too

large

an

expres-

sion.

Floating

Point

Overflow/Underflow

Error:

Attempted

to

divide

by

zero

or

refer

to a number

larger

than

1 x

10

96

or

smaller

than

1 x

10-

99

•

Line

Not

Found:

A GOSUB, GOTO,

or

THEN

referenced a non-existent

line

number

.

No

Matching

FOR

Statement:

A NEXT

was

encountered

without a previous

FOR,

or

nested

FOR/NEXT

statements

do

not

match

properly.

(Error

is

reported

at

the

not

at

FOR).

Line

Too

Long

Error:

The

statement

is

too

complex

or

too

long

for

BASIC

to

handle.

GOSUB

or

FOR

Line

Deleted:

A NEXT

or

RETURN

statement

was

encountered

and

the

corresponding

FOR

or

GOSUB

has

been

deleted

since

the

last RUN.

App

endix

B-1

ERROR

CODE

NO.

16

17

18

Note:

19

20 21

128

129

130 131

132

133 134

135

136

137

138

139

140 141 142

ERROR

CODE

MESSAGE

RETURN

Error:

A RETURN

was

encountered

without a matching

GOSUB.

Garbage

Error:

Execution

of"garbage"

(bad RAM bits)

was

attempted.

This

error

code

may

indicate a hardware

problem,

but

may

also

be

the

result

of

faulty

use

of

POKE.

Try

typing

NEW

or

powering

down,

then

re-enter

the

program

without

any

POKE

commands.

Invalid

String

Character:

String

does

not

start

with a valid

character,

or

string

in

VAL

statement

is

not a numeric

string.

The

following

are

INPUT

/OUTPUT

errors

that

result

during

the

use

of

disk

drives,

printers,

or

other

accessory

devices.

Further

information

is

pro-

vided

with

the

auxiliary

hardware.

LOAD

program

Too

Long:

Insufficient

memory

remains

to

complete

LOAD.

Device

Number

Larger

than 7 or

Equal

to 0.

LOAD

File

Error:

Attempted

to LOAD a non-LOAD file.

BREAK

Abort:

User

hit

M,!;@M

key

during

I/0

operation.

IOCB

1

already

open.

Nonexistent

Device

specified.

IOCB

Write

Only.

READ

command

to a

write-only

device

(Printer).

Invalid

Command:

The

command

is

invalid

for

this

device.

Device

or

File

not

Open:

No OPEN specified

for

the

device.

Bad

IOCB

Number:

Illegal

device

number.

IOCB

Read

Only

Error: WRITE

command

to a

read-only

device.

EOF:

End

of

File

read

has

been

reached.

(NOTE:

This

message

may

occur

when

using

cassette files.)

Truncated

Record:

Attempt

to

read a record

longer

than

256

characters.

Device

Timeout.

Device

doesn't

respond.

Device

NAK:

Garbage

at

serial

port

or

bad

disk

drive.

Serial

bus

input

framing

error.

Cursor

out

of

range

for

particular

mode.

Serial

bus

data

frame

overrun.

1

IOCB

refers

to

Input/Output

Control

Block.

The

device

number

is

the

same

as

the

IOCB

number.

B-2

Appendix

ERROR

CODE

NO.

143

144

145

146 147 160 161 162 163 164 165 166 167 168 169

170 171

ERROR

CODE

MESSAGE

Serial

bus

data

frame

checksum

error.

Device

done

error

(invalid "done"

byte):

Attempt

to

write

on a write-protected

diskette.

Read

after

write

compare

error

(disk

handler)

or

bad

screen

mode

handler.

Function

not

implemented

in

handler.

Insufficient

RAM

for

operating

selected

graphics

mode.

Drive

number

error.

Too

many

OPEN

files

(no

sector

buffer

available).

Disk

full

(no

free

sectors).

Unrecoverable

system

data

I/0

error.

File

number

mismatch:

Links

on

disk

are

messed up.

File

name

error.

POINT

data

length

error.

File

locked.

Command

invalid

(special

operation

code).

Atari 400, 800 Basic Reference Manual

Specifications and Main Features

Frequently Asked Questions

User Manual