Commodore 1581 User Manual

COMMODORE

n

DISK

DRIVE

useris

guide

v

■

USER'S

MANUAL

STATEMENT

WARNING:

This

equipment has

been

certified

to

comply

with

the

limits

for

a

ClassBcomputing

device,

pursuant

to

subpartJof

Part

15

of

the

Federal

Communications

Commission's

rules,

which

are

designed

to

pro

vide

reasonable

protection

against

radio

and

television

interference

in

a

residential

installation.

If

not

installed

properly,

in

strict

accordance

with

the

manufacturer's

instructions,

it

may

cause

such

interference.

If

you

suspect

interference,

you

can

test

this

equipment

by

turning

it

off

and

on.

If

this

equipment

does

cause

interference,

correct

it

by

doing

any

of

the

following:

•

Reorient

the

receiving

antenna

or

AC

plug.

•

Change

the

relative

positions

of

the

computer

and

the

receiver.

•

Plug

the

computer

intoadifferent

outlet

so

the

computer

and

receiver

are

on

different

circuits.

CAUTION:

Only

peripherals

with

shield-grounded cables

(computer

input-

output

devices,

terminals,

printers,

etc.),

certified

to

comply

with

Class

B

limits,

can

be

attached

to

this

computer.

Operation

with

non-certified

peripherals

is

likely

to

result

in

communications

interference.

Your

house

AC

wall

receptacle

must beathree-pronged

type

(AC

ground).

If

not,

contact

an

electrician

to

install

the

proper

receptacle.

If

a

multi-connector

box

is

used

to

connect

the

computer

and

peripherals

to

AC,

the

ground

must

be

common

to

all

units.

If

necessary,

consult

your

Commodore

dealer

or

an

experienced

radio-

television

technician

for

additional

suggestions.

You

may

find

the

following

FCC

booklet

helpful:

"How

to

Identify

and

Resolve

Radio-TV

Interference

Problems."

The

booklet

is

available

from

the

U.S.

Government

Printing

Office,

Washington,

D.C.

20402,

stock

no.

004-000-00345-4.

1581

Disk

Drive

User's

Guide

Copyright

©

1987

by

Commodore

Electronics

Limited

All

rights

reserved

This

manual

contains

copyrighted

and

proprietary

information.

No

part

of

this

publication

may

be

reproduced,

stored

inaretrieval

system,

or

transmitted

in

any

form

or

by

any means,

electronic,

me

chanical,

photocopying,

recording

or

otherwise,

without

the

prior

written

permissibn

of

Commodore

Electronics

Limited.

COMMODORE64isaregistered

trademarkofCommodore

Electronics

Limited

COMMODORE

128,

Plus4,and VIC20are

trademarks

of

Commodore

Electronics

Limited

CONTENTS

INTRODUCTION

1

HOW

THIS

GUIDE

IS

ORGANIZED

1

PART

ONE:

BASIC

OPERATING

INFORMATION

CHAPTER

1:

UNPACKING,

SETTING

UP

AND

USING

THE

1581

3

step-by-step

instructions

3

troubleshooting

guide

5

tips

for

maintenance

and

care

7

inserting

a

diskette

8

using

pre-programmed

(software)

diskettes

8

how

to

prepareanew

diskette

10

diskette

directory

11

selective

directories

12

printing

a

directory

13

pattern

matching.

13

splat

files

14

CHAPTER

2:

BASIC

2.0

COMMANDS

15

error

checking

16

BASIC

hints

17

save

17

save

with

replace

18

verify

19

scratch

20

more

about

scratch.

21

rename

22

renaming

and

scratching

troublesome

files....

23

copy

24

validate

25

initialize

26

CHAPTER

3:

BASIC

7.0

COMMANDS

27

error

checking

27

save

27

save

with

replace

28

verify

'.

29

copy

29

concat

30

scratch

30

more

about

scratch

31

rename

32

renaming

and

scratching

troublesome

files

33

collect

34

dclear

35

|

PART

TWO:

ADVANCED

OPERATION

AND

PROGRAMMING

|

CHAPTER

4:

SEQUENTIAL

DATA

FILES

37

openingafile

38

closing

a

file

43

reading

file

data:

using

input#

44

more

about

input#

45

numeric

data

storage

on

diskette

47

reading

file

data:

using

get#

48

demonstration

of

sequential

files

51

CHAPTER

5:

RELATIVE

DATA

FILES

53

files,

records,

and

fields

53

file

limits

54

creating

a

relative

file

54

using

relative

files:

record#

command

56

completing

relative

file

creation

58

expanding

a

relative

file

60

writing

relative

file

data

60

designing

a

relative

record

60

writing

the

record

61

reading

a

relative

record

64

the

value

of

index

files

67

CHAPTER

6:

DIRECT

ACCESS

COMMANDS

69

openingadata

channel

for

direct

access

69

block-read

70

block-write

71

the

original

block-read

and

block-write

commands

72

the

buffer

pointer

74

allocating

blocks

75

freeing

blocks

76

partitions

and

sub-directories

77

using

random

files

79

CHAPTER

7:

INTERNAL

DISK

COMMANDS

81

memory-read.

82

memory-write

84

memory-execute

85

block-execute

85

user

commands

86

utility

loader

87

auto

boot

loader

88

CHAPTER

8:

MACHINE

LANGUAGE

PROGRAMS

89

disk-related

kernal

subroutines

89

CHAPTER

9:

BURST

COMMANDS

91

cmdl-read

91

cmd2-write

92

cmd3-inquire

disk

92

cmd4-format

93

cmd6-query

disk

format

94

cmd7-inquire

status

94

cmd8-dump

track

cache

buffer

95

chgutl

utility

95

fastload

utility

96

status

byte

breakdown

96

burst

transfer

protocol

97

explanation

of

procedures

98

CHAPTER

10:1581

INTERNAL

OPERATION

101

logical

versus

physical

disk

format

101

track

cache

buffer

101

controller

job

queue

102

vectored

jump

table

108

APPENDICES:

A:

changing

the

device

number

Ill

B:

dos

error

messages

113

C:

dos

diskette

format

119

D:

disk

command

quick

reference

chart

123

E:

specifications

of

the

1581

disk

drive

125

F:

serial

interface

information

127

USER'S

MANUAL

STATEMENT

inside

back

cover

INTRODUCTION

The

Commodore

1581

isaversatile

3.5"

disk

drive

that

can

be

used

withavariety

of

computers,

including

the

COMMODORE

128™,

the

COMMODORE

64®,

the

Plus

4™,

COMMODORE

16™,

and

VIC

20.™

Also,

in

addition

to

the

convenience

of

3.5"

disks,

the

1581

offers

the

following

features:

•

Standard

and

fast

serial

data

transfer

rates—The

1581

auto

matically

selects

the

proper

data

transfer

rate

(fast

or

slow)

to

match

the

operating

modes

available

on

the

Commodore

128

computer.

•

Double-sided,

double-density

MFM

data

recording—Provides

more

than

800K

formatted

storage

capacity

per

disk

(400K

+

per

side).

•

Special

high-speed

burst

commands—These

commands,

used

for

machine

language

programs,

transfer

data

several

times

faster

than

the

standard

or

fast

serial

rates.

HOW

THIS

GUIDE

IS

ORGANIZED

This

guide

is

divided

into

two

main

parts

and

seven

appendices,

as

described below:

PART

ONE:

BASIC

OPERATING

INFORMATION—includes

all

the

information

needed

by

novices

and

advanced

users

to

set

up

and

begin

using

the

1581

disk

drive.

PART

ONE

is

subdivided

into

three

chapters:

•

Chapter

1,

Unpacking,

Setting

Up

and

Using

the

1581,

tells

you

how

to

use

disk

software

programs

that

you

buy.

These

pre

written

programs

help

you

performavariety

of

activities

in

fields

such

as

business,

education,

finance,

science,

and

recrea

tion.

If

you're

interested

only

in

loading

and

running

pre

packaged

disk

programs,

you

need

read

no

further

than

this

chapter.

If

you

are

also

interested

in

saving,

loading,

and

run

ning

your

own

programs,

you

will

want

to

read

the

remainder

of

the

guide.

•

Chapter

2,

Basic

2.0

Commands,

describes

the

use

of

the

BASIC

2.0

disk

commands

with

the

Commodore

64

and

Com

modore

128

computers.

•

Chapter

3,

Basic

7.0

Commands,

describes

the

use

of

the

BASIC

7.0

disk

commands

with

the

Commodore

128.

PART

TWO:

ADVANCED

OPERATION

AND

PROGRAMMING—is

primarily

intended

for

users

familiar

with

computer

program

ming.

PART

TWO

is

subdivided

into

six

chapters:

•

Chapter

4,

Sequential

Data

Files,

discusses

the

concept

of

data

files,

defines

sequential

data

files,

and

describes

how

sequen

tial

data

files

are

created

and

used

on

disk.

•

Chapter

5,

Relative

Data

Files,

defines

the

differences

between

sequential

and

relative

data

files,

and

describes

how

relative

data

files

are

created

and

used

on

disk.

•

Chapter

6,

Direct

Access

Commands,

describes

direct

access

disk

commands

asatool

for

advanced

users

and

illustrates

their

use.

•

Chapter

7,

Internal

Disk

Commands,

centers

on

internal

disk

commands.

Before

using

these

advanced

commands,

you

should

know

how

to

programa6502

chip

in

machine

lan

guage.

•

Chapter

8,

Machine

Language

Programs,

provides

a

list

of

disk-related

kernal

ROM

subroutines

and

givesapractical

ex

ample

of

their

use

inaprogram.

•

Chapter

9,

Burst

Commands,

gives

information

on

high-speed

burst

commands.

•

Chapter

10,1581

Internal

Operations,

describes

how

the

1581

operates

internally.

APPENDICES

ATHROUGH

F—provide

various

reference

information;

for

example,

AppendixAtells

you

how

to

set

the

device

number

through

use

of

two

switches

on

the

back

of

the

drive.

PART

ONE

BASIC

OPERATING

INFORMATION

CHAPTER

1

HOW

TO

UNPACK,

SET

UP

AND

BEGIN

USING

THE

1581

STEP-BY-STEP

INSTRUCTIONS

1.

Inspect

the

shipping

carton

for

damage.

If

you

find

any

damage

to

the

shipping

carton

and

suspect

that

the

disk

drive

may

have

been

affected,

contact

your

dealer.

2.

Check

the

contents

of

the

shipping

carton.

Packed

with

the

1581

and

this

book,

you

should

find

the

following:

electrical

power

supply,

interface

cable,

Test/Demo

diskette,

and

a

warranty

card

to

be

filled

out

and

returned

to

Commodore.

3.

Remove

the

shipping

spacer

from

the

disk

drive.

The

spacer

is

there

to

protect

the

inside

of

the

drive

during

shipping.

To

remove

it,

push

the

button

on

the

front

of

the

drive

(see

Figure

1)

and

pull

out

the

spacer.

Figure1.Frontof1581

Disk

Drive

H

■

commodore

1581

^H

1

FLOPPY

DISK

DRIVE

■

V

THE

PRODUCT

DOES

NOT

NECESSARILY

RESEMBLE

THE

PICTURE

INSIDE

THE

USER'S

MANUAL

3

4.

Connect

the

power

cord.

Check

the

ON/OFF

switch

on

the

back

of

the drive

(see

Figure

2)

and

make

sure

it's

OFF.

Connect

the

power

supply

where

indicated

in

Figure

2.

Plug

the

other

end

into

an

electrical

outlet.

Don't

turn

the

power

on

yet.

Figure2.ConnectionofPower

Cord

and

Interface

Cablesto1581

BACK

OF

C128

SERIAL

PORT

CONNECTOR

ON

C128

POWER

CORD

SOCKET

BACK

OF

1581

SERIAL

PORT

CONNECTORS

FOR

INTERFACE

CABLES

DIP

SWITCHES

FOR

CHANGING

DEVICE

NUMBER

ON/OFF

SWITCH

POWER

OUTLET

5.

Connect

the

interface

cable.

Make

sure

your

computer

and

any

other

peripherals

are

OFF.

Plug

either

end

of

the

interface

cable

into

either

serial

port

on

the

back

of

the

drive

(see

Figure

2).

Plug

the

other

end

of

the

cable

into

the

back

of

the

computer.

If

you

have

another

peripheral

(printer

or

extra

drive),

plug

its

interface

cable

into

the

remaining

serial

port

on

the

drive.

6.

Turn

ON

the

power.

With

everything

hooked

up

and

the

drive

empty,

you

can

turn

on

the

power

to

the

peripherals

in

any

order,

but

turn

on

the

power

to

the

computer

lasfe

When

everything

is

on,

the

drive

goes

through

a

self

test.

If

all

is

well,

the

green

light

will

flash

once

and

the

red

power-on

light

will

glow

continuously.

If

the

red

light

continues

to

flash,

there

may

beaproblem.

In

that

case,

refer

to

the

Trouble

shooting

Guide.

TROUBLESHOOTING

GUIDE

Problem

Red

power-on

indicator

not

lit

Red

light

flashing

e

Possible

Cause

Power

not

ON

Power

cable

not

plugged

in

Power

offtowall

outlet

Drive

failing

its

self

test

Solution

Make

sure

ON/OFF

switchisON

Check

both

ends

of

power

cabletobe

sure

they

are

fully

inserted

Replace

fuseorreset

circuit

breakerinhouse

Turn

the

system

off

for

a

moment

then

try

again.

If

the

light

still

flashes,

turn

the

drive

off

and

on

again

with

the

interface

cable

disconnected.

If

the

problem

persists,

contact

your

dealer.

If

unplugging

the

interface

cable

made

a

difference,

make

sure

the

cableisproperly

connectedIfthat

doesn't

work,

the

problemisprobably

in

the

cable

itself

or

somewhere

elseinthe

system

TROUBLESHOOTING

GUIDE

(Cont.)

Programs

won't

load

and

the

computer

says

"DEVICE

NOT

PRESENT

ERROR"

Programs

won't

load,

but

the

computer

and

disk

drive

givenoerror

message

Interface

cable

not

well

connectedordrive

not

ON

Switchesonback

of

drive

may

notbeset

for

correct

device

number

Another

panofthe

system

may

be

interfering

Be

sure

the

cable

is

properly

connected

and

the

driveisON

Check

AppendixAfor

correct

settingtomatch

LOAD

command

Unplug

all

other

^machinesonthe

computer.Ifthat

cures

it,

plug

theminoneata

time.

The

one

just

added

when

the

trouble

repeatsismost

likely

the

problem

Tryingtoload

a

machine

language

program

into

BASIC

space

will

cause

this

problem

Programs

won't

load

and

red

light

flashes

Disk

error

Check

the

error

channel

to

determine

the

error,

then

follow

the

advice

in

AppendixBto

correct

it.

The

error

channel

is

explainedinChapters

2

and3

o

(Be

suretospell

program

names

correctly

and

include

the

exact

punctuation

when

loading

the

programs)

Your

programs

load

OK,

but

commercial

programs

and

those

from

other

1581s

don't

Either

the

diskette

is

faulty,oryour

disk

drive

is

misaligned

Try

another

copyofthe

program.Ifseveral

programs

from

several

sources

failtoload,

have

your

dealer*align

your

disk

drive

Your

programs

that

usedtoload,

won't

anymore,

but

programs

savedonnewly-

formatted

diskettes

will

Older

diskettes

have

been

damaged

The

disk

drive

has

gone

outofalignment

Recopy

from

backups

Have

your

dealer

align

your

disk

drive

TIPS

FOR

MAINTENANCE

AND

CARE

1.

Keep

the

drive

well

ventilated.

A

couple

of

inches

of

space

to

allow

air

circulation

on

all

sides

will

prevent

heat

from

building

up

inside

the

drive.

2.

The

1581

should

be

cleaned

onceayear

in

normal

use.

Several

items

are

likely

to

need

attention:

the

two

read/write

heads

may

need

cleaning

(with

91%

isopropyl

alcohol

onacotton

swab).

Tjfcte

rails

along

which

the

head

moves

may

need

lubrication

(with

a

special

molybdenum

lubricant,

not

oil),

and

the

write

protect

sen

sor

may

need

to

be

dusted.

Since

these

chores

require

special

materials

or

parts,

it

is

best

to

leave

the

work

to

an

authorized

Commodore

service

center.

If

you

want

to

do

the

work

yourself,

ask

your

dealer

for

the

appropriate

materials.

IMPORTANT:

Home

repair

of

the

1581

will

void

your

warranty.

3.

Use

good

quality

diskettes.

Badly-made

diskettes

can

cause

increased

wear

on

the

drive's

read/

write

head.

If

you're

usingadiskette

that

is

unusually

noisy,

it

could

be

causing

added wear

and

should

be

replaced.

4.

Keep

diskettes

(and

disk

drive)

away from

magnets.

That

includes

the

electromagnets

in

telephones,

televisions,

desk

lamps,

and

calculator

cords.

Keep

smoke,

moisture,

dust,

and

food

off

the

diskettes.

5.

Removeadiskette

before

turning

the

drive

off.

If

you

don't,

you

might

lose

part

or

all

the

data

on

the

diskette.

6.

Don't

removeadiskette

from

the

drive

while

the

green

light

is

glowing

and

the

drive

motor

is

turning.

If

you

remove

the

diskette

then,

you

might

lose

the

information

currently

being

written

to

the

diskette.

INSERTINGADISKETTE

Grasp

the

diskette

by

the

side

opposite

the

metal

shutter.

Hold

it

with

the

label

up

and

the

write-protect

notch

down

and

to

the

left

(See

Figure

3).

Insert

the

diskette

by

pushing

it

straight

into

the

drive

with

the

access

slot

going

in

first

and

the

label

last.

Be

sure

the

diskette

goes

in

until

it

drops

into

place;

you

shouldn't

have

to

force

it.

WRITE

PROTECT

TAB—g[

V

INSERTTHIS

EDGE

FIRST

.

CENTER

HUB

SHUTTER

Figure3.Inserting

a

Diskette

When

the

write/protect

notch

is

open,

the

contents

of

the

diskette

cannot

be

altered

or

added

to.

That

prevents

accidental

erasing

of

information

you

want

to

preserve.

Blank

diskettes

may

not

havealabel

on

them

when

you

purchase

them.

USING

PRE-PROGRAMMED

(SOFTWARE)

DISKETTES

Your

software

user's

guide

should

list

the

procedure

for

loading

the

program

into

your

computer.

Nevertheless,

we've

included

the

following

procedure

asageneral

guide.

You'll

also

use

this

procedure

to

load

programs

or

files

from

your

own

diskettes.

For

purposes

of

demonstration,

use

the

Test/Demo

diskette

included

with

the

disk

drive.

1.

Turn

on

system.

2.

Insert

diskette.

3.

If

you

are

usingaVIC

20,

Commodore

64,

oraCommodore

128

computer

in

C64

mode,

type:

LOAD

"HOW

TO

USE",8

If

you

are

usingaPlus/4

or

Commodore

128

in

C128

mode,

type:

DLOAD

"HOW

TO

USE"

4.

Press

the

RETURN

key.

5.

The

following

will

then

appear

on

the

screen:

SEARCHING

FOR

0:HOW

TO

USE

LOADING

READY

I

6.

Type:

RUN

7.

Press

the

RETURN

key.

To

loadadifferent

program

or

file,

simply

substitute

its

name

in

place

of

HOW

TO

USE

inside

the

quotation

marks.

-NOTE

The

HOW

TO

USE

program

is

the

key

to

the

Test/

Demo

diskette.

When

you

LOAD

and

RUN

it,

it

provides

instructions

for

using

the

rest

of

the

programs

on

the

dis

kette.

To

find

out

what

programs

are

on

your

Test/Demo

diskette,

refer

to

the

section

entitled

"DIRECTORIES"

later

in

this

chapter.

Ifaprogram

doesn't

load

or

run

properly

using

the

above

meth

od,

it

may

be

that

it

isamachine

language

program.

But

unless

you'll

be

doing

advanced

programming,

you

need

not

know

anything

about

machine

language.

A

program's

user's

guide

should

tell

you

if

it

is

written

in

machine

language.

If

it

is,

or

if

you

are

having

trouble

loadingaparticular

program,

simply

adda;1

(comma

and

number

1)

at

the

end

of

the

command.

NOTE

Throughout

this

manual,

when

the

format

foracom

mand

is

giv^n,

it

will

followaparticular

style.

Anything

that

is

capitalized

must

be

typed

in

exactly

as

it

is

shown

(these

commands

are

listed

in

capital

letters

for

style

purposes,

DO

NOT

use

the

SHIFT

key

when

entering

these

com

mands).

Anything

in

lower

case

is

more

or

lessadefinition

of

what

belongs

there.

Anything

in

brackets

is

optional.

For

instance,

in

the

format

for

the

HEADER

command

given

on

the

following

page,

the

word

HEADER,

the

capital

I

in

lid,

the

capitalDin

Ddrive#,

and

the

capitalUin

Ude*-

vice#

must

all

be

typed

in

as

is

(Ddrive#

and

Udevice#

are

optional).

On

the

other

hand,

diskette

name

tells

you

that

you

must

enteraname

for

the

diskette,

but

it

is

up

to

you

to

decide

what

that

name

will

be.

Also,

the

id in

lid

is

left

to

your

discretion,

as

is

the

device#

in

Udevice#.

The

drive#

in

Ddrive#

is

always0on

the

1581,

but

could

be0or1on

a

dual

disk

drive.

Be

aware,

however,

that

there

are

certain

limits

placed

on

what

you

can

use.

In

each

case,

those

limits

are

explained

immediately

following

the

format

(for

in

stance,

the

diskette

name

cannot

be

more

than

sixteen

characters

and

the

device#

is

usually

8).

Also

be

sure

to

type

in

all

punctuation

exactly

where

and

how

it

is

shown

in

the

format.

Finally,

press

the

RETURN

key

at

the

end

of

each

command.

HOW

TO

PREPAREANEW

DISKETTE

A

diskette

needsapattern

of

circular

magnetic

tracks

in

order

for

the

drive's

read/write

head

to

find

things

on

it.

This

pattern

is

not

on

your

diskettes

when

you

buy

them,

but

you

can use

the

HEADER

command

or

the

NEW

command

to

add

it

toadiskette.

That

is

known

as

formatting

the

disk.

This

is

the

command

to

use

with

the

C128

in

C128

mode

or

Plus/4:

HEADER

"diskette

name",Iid,Ddrive#[,Udevice#]

Where:

"diskette

name"

is

any

desired

name

for

the

diskette,

up

to

16

charac-

10

ters

long

(including

spaces),

"id"

can

be

any

two

characters

as

long

as

they

don't

formaBASIC

keyword

(such

as

IF

or

ON)

either

on

their

own

or

with

the

capital

I

before

them.

"drive#"

is0.

"device#"

is

8,

unless

you

have

changed

it

as

per

instructions

in

AppendixA(the

1581

assumes8even

if

you

don't

type

it

in).

The

command

for

the

C64,

VIC

20,

or

C128

in

C64

mode

is

this:

OPEN

15,device#,15,"NEWdrive#:diskette

name,id"

CLOSE

15

The

device#,

drive#,

diskette

name,

and

id

are

the

same

as

described

above.

The

OPEN

command

is

explained

in

the

next

chapter.

For

now,

just

copy

it

as

is.

-NOTE

FOR

ADVANCED

USERS

If

you

want

to

use

variables

for

the

diskette

name

or

id,

the

format

is

as

follows:

C128,

Plus/4:

HEADER

(A$),I(B$),D0

C64:

OPEN

15,8,15:PRINT#15,"N0:"

+A$+","+B$:

CLOSE15

Where:

A$

contains

the

diskette

name

(16

character

limit)

B$

contains

the

id

(2

characters

long)

After

you

formataparticular

diskette,

you.

can

reformat

it

at

any

time.

You

can

change

its

name

and

erase

its

files

faster

by

omitting

the

id

number

in

the

HEADER

command.

DISKETTE

DIRECTORY

A

directory

isalist

of

the

files

onadiskette.

To

view

the

directory

on

the

C128

or

Plus/4,

type

the

word

DIRECTORY

onablank

line

and

press

the

RETURN

key

or

simply

press

the

F3

key

on

the

C128.

That

doesn't

erase

anything

in

memory,

so

you

can

call

upadirectory

11

anytime—even

from

withinaprogram.

The

C64

directory

command,

LOAD

"$",8

(press

RETURN)

LIST

(press

RETURN),

does

erase what's

in

memory.

Ifadirectory

doesn't

all

fit

on

the

screen,

it

will

scroll

up

until

it

reaches

the

last

line.

If

you

want

to

pause,

stop,

or

slow

down

the

scrolling,

refer

to

your

particular

computer's

user's

manual

for

instructions

as

to

which

keys

to

use.

To

get

an

idea

of

whatadirectory

looks

like,

load

the

directory

from

the

Test/Demo

diskette.

The0on

the

left-hand

side

of

the

top

line

is

the

drive

number

of

the

1581.

The

diskette

name

is

next,

followed

by

the

diskette

id—both

of

which

are

determined

when

the

diskette

is

formatted.

The

3D

at

the

end

of

the

top

line

means

the

1581

uses

Version

3D

of

Commodore's

disk

operating

system

(DOS).

Each

of

the

remaining

lines

provides

three

pieces

of

information

about

the

files

on

the

diskette.

At

the

left

end

of

each

line

is

the

size

of

the

file

in

blocks of

254

characters.

Four

blocks

are

equivalent

to

almost

IK

of

memory

inside

the

computer.

The

middle

of

the

line

contains

the

name

of

the

file

enclosed

in

quotation

marks.

All

charac

ters

within

the

quotation

marks

are

part

of

tfie

filename.

The

right

side

of

each

line

contains

a

three-letter

abbreviation

of

the

file

type.

The

types

of

files

are

described

in

later

chapters.

The

bottom

line

ofadirectory

shows

how

many

blocks

are

available

for

use.

This

number

ranges

from

3160

onanewly

formatted

diskette

to0on

one

that

is

completely

full.

SELECTIVE

DIRECTORIES

By

altering

the

directory

LOAD

command,

you

can

createasub

directory

that

lists

a

single

selected

type

of

file.

For

example,

you

could

requestalist

of

all

sequential

data

files

(Chapter

4),

or

one

of

all

the

relative

data

files

(Chapter

5).

The

format

for

this

command

is:

LOAD"$0:pattern

=

filetype",8

(for

the

C64)

where

pattern

specifies

a

particular

group

of

files,

and

filetype

is

the

one-letter

abbreviation

for

the

types

of

files

listed

below:

P=Program

S=Sequential

R=Relative

U

=

User

12

The

command

for

the

C128

and

Plus/4

is

this:

DIRECTORY"pattern

=

filetype"

Some

examples:

LOAD"$0:*

=

R",8

and

DIRECTORY"*

=

R"

display

all

relative

files.

LOAD"$0:Z*

=

R",8

and

DIRECTORY"Z*

=

R"

display

a

sub-directo

ry

consisting

of

all

relative

files

that

start

with

the

letterZ(the

asterisk

(*)

is

explained

in

the

section

entitled

"Pattern

Matching."

PRINTINGADIRECTORY

To

printout

a

directory,

use

the

following:

LOAD'T',8

OPEN4,4:CMD4:LIST

PRINT#4:CLOSE4

PATTERN

MATCHING

You

can

use

special

pattern-matching

characters

to

loadapro

gram

fromapartial

name

or

to

provide

the

selective

directories

described

earlier.

The

two

characters

used

in

pattern

matching

are

the

asterisk

(*)

and

the

question

mark

(?).

They

act

something

likeawild

card

in

a

game

of

cards.

The

difference

between

the

two

is

that

the

asterisk

makes

all

characters

in

and

beyond

its

position

wild,

while

the

ques

tion

mark

makes

only

its

own

position

wild.

Here

are

some

examples

and

their

results:

LOAD

"A*",8

loads the

first

file

on

disk

that

begins

with

an

A,

regardless

of

what

follows

DLOAD"SM?TH"

loads

the

first

file

that

starts

with

SM,

ends

with

TH,

and

one

other

character

between

DIRECTORY"Q*"

loadsadirectory

of

files

whose

names

begin

withQ

LOAD"*",8

isaspecial

case.

When

an

asterisk

is

used

alone

as

a

name,

it

matches

the

last

file

used

(on

the

C64

and

C128

in

C64

mode).

13

LOAD

"0:*",8

loads the

first

file

on

the

diskette

(C64

and

C128

in

C64

mode).

DLOAD

"*"

loads

the

first

file

on

the

diskette

(Plus/4

and

C128

in

C128

mode).

SPIAT

FILES

One

indicator

you

may

occasionally

notice

onadirectory

line,

after

you

begin

saving

programs

and

files,

is

an

asterisk

appearing

just

before

the

file

type

ofafile

that

is0blocks

long.

This

indicates

the

file

was

not

properly

closed

after

it

was

created,

and

that

it

should

not

be

relied

upon.

These

"splat"

files

normally

need

to

be

erased

from

the

diskette

and

rewritten.

However,

do

not

use

the

SCRATCH

command

to

get

rid

of

them.

They

can

only

be

safely

erased

by

the

VALIDATE

or

COLLECT

commands.

One

of

these

should

normally

be

used

when

everasplat

file

is

noticed

onadiskette.

All

of

these

commands

are

described

in

the

following

chapters.

There

are

two

exceptions

to

the

above

warning:

one

is

that

VALIDATE

and

COLLECT

cannot

be

used

on

some

diskettes

that

in

clude

direct

access

(random)

files

(Chapter

6).

The

other

is

that

if

the

information

in

the

splat

file

was

crucial

and

can't

be

replaced,

there

is

a

way

to

rescue

whatever

part

of

the

file

was

properly

written.

This

option

is

described

in

the

next

chapter.

14

CHAPTER

2

BASIC

2.0

COMMANDS

This

chapter

describes

the

disk

commands

used

with

the

VIC

20,

Commodore

64

or

the

Commodore

128

computer

in

C64

mode.

These

are

Basic

2.0

commands.

You

send

command

data

to

the

drive

through

something

called

the

command

channel.

The

first

step

is

to

open

the

channel

with

the

following

command:

OPEN15,8,15

The

first

15

isafile

number

or

channel

number.

Although

it

could

be

any

number

from1to

255,

we'll

use

15

because

it

is

used

to

match

the

secondary

address

of

15,

which

is

the

address

of

the

command

channel.

The

middle

number

is

the

primary

address,

better

known

as

the

device

number.

It

is

usually

8,

unless

you

change

it

(see

Appendix

A).

Once

the

channel

has

been

opened,

use

the

PRINT#

command

to

send

information

to

the

disk

drive

and

the

INPUT#

command

to

receive

information

from

the

drive.

You

must

close

the

channel

with

the

CLOSE15

command.

The

following

examples

show

the

use

of

the

command

channel

to

NEW

an

unformatted

disk:

OPEN15,8,15

PRINT#15,"NEWdrive#:diskname,id"

CLOSE15

You

can

combine

the

first

two

statements

and

abbreviate

the

NEW

command

like

this:

OPEN15,8,15,"Ndrive#

:diskname,id"

If

the

command

channel

is

already

open,

you

must

use

the

following

format

(trying

to

openachannel

that

is

already

open

results

ina"FILE

OPEN"

error):

PRINT#15,uNdrive#:diskname,id"

15

ERROR

CHECKING

In

Basic

2.0,

when

the

red

drive

light

flashes,

you

must

write

a

small

program

to

find

out

what

the

error

is.

This

causes

you

to

lose

any

program

variables

already

in

memory.

The

following

is

the

error

check

program:

10OPEN15,8,15

20

INPUT#15,EN,EM$,ET,ES

30

PRINT

EN,

EM$,ET,ES

40

CLOSE15

This

little

program

reads

the

error

channel

into

four

BASIC

variables

(described below),

and

prints

the

results

on

the

screen.

A

message

is

displayed

whether

there

is

an

error

or

not,

but

if

there

was

an

error,

the

program

clears

it

from

disk

memory

and

stops

the

error

light

from

blinking.

Once

the

message

is

on

the

screen,

you

can

look

it

up

in

Appen

dixBto

see

what

it

means,

and

what

to

do

about

it.

For

those

of

you

who

are

writing

programs,

the

following

is

a

small

error-checking

subroutine

you

can

include

in

your

programs:

59980

REM

READ

ERROR

CHANNEL

59990

INPUT#15,EN,EM$,ET,ES

60000

IF

EN>1

THEN

PRINT

EN,EM$,ET,ES:STOP

60010

RETURN

This

assumes

file

15

was

opened

earlier

in

the

program,

and

that

it

will

be

closed

at

the

end

of

the

program.

The

subroutine

reads

the

error

channel

and

puts

the

results

into

the

named

variables—EN

(Error

Number),

EM$

(Error

Message),

ET

(Error

Track),

and

ES

(Error

Sector).

Of

the

four,

only

EM$

has

to

be

a

string.

You

could

choose

other

variable

names,

although

these

have

become

traditional

for

this

use.

Two

error

numbers

are

harmless—0

means

everything

is

OK,

and

1

tells

how

many

files

were

erased

byaSCRATCH

command

(de

scribed

later

in

this

chapter).

If

the

error

status

is

anything

else,

line

60000

prints

the

error

message

and

halts

the

program.

Because

this

isasubroutine,

you

access

it

with

the

BASIC

GOSUB

command,

either

in

immediate

mode

or

fromaprogram.

The

RETURN

statement

in

line

60010

will

jump

back

to

immediate

mode

or

the

next

statement

in

your

program,

whichever

is

appropriate.

16

BASIC

HINTS

h

It

is

best

to

open

file

15

once

at

the

very

start

ofaprogram,

and

only

close

it

at

the

end

of

the

program,

after

all

other

files

have

already

been

closed.

By

opening

it

once

at

the

start,

the

file

is

open

whenever

needed

for

disk

commands

elsewhere

in

the

program.

2.

If

BASIC

halts

with

an

error

when

you

have

files

open,

BASIC

aborts

them

without

closing

them

properly

on

the

disk.

To

close

them

properly

on

the

disk,

you

must

type:

CLOSE

15:OPEN

15,8,15,'T':CLOSE

15

This

opens

the

command

channel

and

immediately

closes

it,

along

with

all

other

disk

files.

Failure

to

closeadisk

file

properly

both*

in

BASIC and

on

the

disk

may

result

in

losing

the

entire

file.

3.

One

disk

error

message

is

not

always

an

error.

Error

73,

"COPY

RIGHT

CBM DOS

V10

1581"

will

appear

if

you

read

the

disk

error

channel

before

sending

any

disk

commands

when

you

turn

on

your

computer.

This

isahandy

way

to

check

which

version

of

DOS

you

are

using.

However,

if

this

message

appears

later,

after

other

disk

com

mands,

it

means

there

isamismatch

between

the

DOS

used

to

format

your

diskette

and

the

DOS

in

your

drive.

DOS

is

Disk

Operating

System.

4.

To

reset

drive,

type:

OPEN

15,8,15,"UJ":CLOSE

15.

SAVE

The

SAVE

command

preserves

a

program

or

file

onaformatted

diskette

for

later

use.

FORMAT FOR

THE

SAVE

COMMAND

SAVE

"drive

#:file

name",device

#

where

"file

name"

is

any

string

expression

of

up

to

16

characters,

preceded by

the

drive

number

andacolon,

and

followed

by

the

device

number

of

the

disk,

normally

8.

However,

the

SAVE

command

will

not

work

in

copying

programs

that

are

not

in

the

BASIC

text

area,

such

as

"DOS

5.1"

for

the

C64.

To

copy

it

and

similar

machine-language

programs,

you

will

need

a

machine-language

monitor

program,

such

as

the

one

resident

in

the

C128.

17

FORMAT FORAMONITOR

SAVE

S "drive

#:file

name",device

#,starting

address,ending

ad

dress

+1

where

"drive

#:"

is

the

drive

number,0on

the

1581;

"file

name"

is

any

valid

file

name

up

to

14

characters

long

(leaving

two

for

the

drive

number

and

colon);

"device

#"

isatwo

digit

device

number,

normally

08

(the

leading0is

required);

and

the

addresses

to

be

saved

are

given

in

Hexadecimal

but

withoutaleading

dollar

sign

($).

Note

the

ending

address

listed

must

be

one

location

beyond

the

last

location

to

be

saved.

EXAMPLE:

Here

is

the

required

syntax

to

SAVEacopy

of

"DOS

5.1"

S

"0:DOS

5.r,08,CC00,D000

SAVE

WITH

REPLACE

Ifafile

already

exists,

it

can't

be

saved

again

with

the

same

name

because

the

disk

drive

only

allows

one

copy

of

any

given

file

name

per

diskette.

It is

possible

to

get

around

this

problem

using

the

RENAME

and

SCRATCH

commands

described

later.

However,

if

all

you

wish

to

do

is

replaceaprogram

or

data

file

witharevised

version,

another

command

is

more

convenient.

Known

as

SAVE-WITH-REPLACE,

or

@SAVE,

this

option

tells

the

disk

drive

to

replace

any

file

it

finds

in

the

diskette

directory

with

the

same

name,

substituting

the

new

file

for

the

old

version.

FORMAT

FOR

SAVE

WITH

REPLACE:

SAVE"@Drive

#:file

name",

device

#

where

all

the

parameters

are

as

usual

except

for

addingaleading

"at"

sign

(@.)

The

"drive

#:"

is

required

here.

EXAMPLE:

SAVE"@0:REVISED

PROGRAM",8

The

actual

procedure

is

that

the

new

version

is

saved

completely,

then

the

old

version

is

erased.

Because

it

works

this

way,

there

is little

18

dangeradisaster

such

as

losing

power

midway

through

the

process

would

destroy

both

the

old

and

hew

copies

of

the

file.

Nothing

happens

to

the

old

copy

until

after

the

new

copy

is

saved

properly.

VERIFY

The

VERIFY

command

can

be

used

to

make

certain

thatapro

gram

file

was

properly

saved

to

disk.

It

works

much

like

the

LOAD

command,

except

that

it

only

compares

each

character

in

the

program

against

the

equivalent

character

in

the

computer's

memory,

instead

of

actually

being

copied

into

memory.

If

the

disk

copy

of

the

program

differs

evenatiny

bit

from

the

copy

in

memory,

"VERIFY

ERROR"

will

be

displayed,

to

tell

you

that

the

copies

differ.

This

doesn't

mean

either

copy

is

bad,

but

if

they

were

supposed

to

be

identical,

there

isaproblem.

Naturally,

there's

no

point

in

trying

to

VERIFYadisk

copy,

of

a

program

after

the

original

is

no

longer

in

memory.

With

nothing

to

compare

to,

an

apparent

error

will

always

be

announced,

even

though

the disk

copy

is

automatically

verified

as

it

is

written

to

the

diskette.

FORMAT

FOR THE

VERIFY

COMMAND:

VERIFY

"drive#:pattern",device#,relocate

flag

where

"drive#:"

is

an

optional

drive

number,

"pattern".is

any

string

expression

that

evaluates

toafile

name,

with

or

without

pattern-

matching

characters,

and

"device#"

is

the

disk

device

number,

nor

mally

8.

If

the

relocate

flag

is

present

and

equals

1,

the

file

will

be

verified

where

originally

saved,

rather

than

relocated

into

the

BASIC

text

area.

A

useful

alternate

form

of

the

command

is:

VERIFY"*",device

#

It

verifies

the

last

files

used

without

having

to

type

its

name

or

drive

number.

However,

it

won't

work

properly

after

SAVE-WITH-REPLACE,

because

the

last

file

used

was

the

one

deleted,

and

the

drive

will

try

to

compare

the

deleted

file

to

the

program

in

memory.

No

harm

will

result,

but

"VERIFY

ERROR"

will

always

be

announced.

To

use

VERIFY

after

@SAVE,

include

at

least

part

of

the

file

name

that

is

to

be

verified

in

the

pattern.

19

One

other

note

about

VERIFY—when

you

VERIFYarelocated

BASIC

file,

an

error

will

nearly

always

be

announced,

due

to

changes

in

the

link

pointers

of

BASIC

programs

made

during

relocation.

It

is

best

to

VERIFY

files

saved

from

the

same

type

of

machine,

and

identi

cal

memory

size.

For

example,

a

BASIC

program

saved

fromaPlus/4

can't

be

verified

easily

withaC64,

even

when

the

program

would

work

fine

on

both

machines.

This

shouldn't

matter,

as

the

only

time

you'll

be

verifying

files

on

machines

other

than

the

one

which

wrote

them

is

when

you

are

comparing

two

disk

files

to

see

if

they

are

the

same.

This

is

done

by

loading

one

and

verifying

against

the

other,

and

can

only

be

done

on

the

same

machine

and

memory

size

as

the

one

on

which

the

files

were

first

created.

SCRATCH

The

SCRATCH

command

allows

you

to

erase

unwanted

files

and

free

the

space

they

occupied

for

use

by

other

files.

It

can

be

used

to

erase

eitherasingle

file

or

several

files

at

once

via

pattern-matching.

FORMAT

FOR

THE

SCRATCH

COMMAND:

PRINT#15,"SCRATCH0:pattern"

or

abbreviate

it

as:

PRINT#15,"S0:pattern"

"pattern"

can

be

any

file

name

or

combination

of

characters

and

wild

card

characters.

As

usual,

it

is

assumed

the

command

channel

has

already

been

opened

as

file

15.

Although

not

absolutely

necessary,

it

is

best

to

include

the

drive

number

in

SCRATCH

commands.

If

you

check

the

error

channel

afteraSCRATCH

command,

the

value

for

ET

(error

track)

will

tell

you

how

many

files

were

scratched.

For

example,

if

your

diskette

contains

program

ftles

named

"TEST,"

"TRAIN,"

"TRUCK,"

and

"TAIL,"

you

may

SCRATCH

all

four,

along

with

any

other

files

beginning

with

the

letter

"T,"

by

using

the

command:

PRINT#15/S0:T*'

Then,

to

prove

they

are

gone,

you

can

type:

GOSUB

59990

20

to

call

the

error

checking

subroutine

given

earlier

in

this

chapter.

If

the

four

listed

were

the

only

files

beginning

with

"T",

you

will see:

01,FILES

SCRATCHED,04,00

READY.

The

"04"

tells

you4files

were

scratched.

MORE

ABOUT

SCRATCH

SCRATCH

isapowerful

command

and

should

be

used

with

caution

to

be

sure

you

delete

only

the

files

you

really

want

erased.

When

using

it

withapattern,

we

suggest

you

first

use

the

same

pattern

inaDIRECTORY

command,

to

be

sure

exactly

which

files

will

be

deleted.

That

way

you'll

have

no

unpleasant

surprises

when

you

use

the

same

pattern

in

the

SCRATCH

command.

If

you

accidentally

SCRATCHafile

you

shouldn't

have,

there

is

stillachance

of

saving

it

by

using

the

"Unscratch"

program

on

your

Test/Demo

diskette.

More

about

Splats

Never

scratch a

splat

file.

These

are

files

that

show

up

in

a

directory

listing

with

an

asterisk

(*)

just

before

the

file

type

for

an

entry.

The

asterisk

(or

splat)

means

that

file

was

never,

properly

closed,

and

thus

there

is

no

valid

chain

of

sector

links

for

the

SCRATCH

command

to

follow

in

erasing the

file.

If

you

SCRATCH

suchafile,

odds

are

you

will

improperly

free

up

sectors

that

are

still

needed

by

other

programs

or

files

and

cause

permanent

damage

to

those

later

when

you

add

more

files

to

the

diskette.

If

you

findasplat

file,

or

if

you

discover

too

late

that

you

have

scratched

suchafile,

immediately

validate

the

diskette

using

the

VALIDATE

command

described

later

in

this

chapter.

If

you

have

added

any

files

to

the

diskette

since

scratching

the

splat

file,

it

is

best

.to

immediately

copy

the

entire

diskette

onto

another

fresh

diskette,

but

do

this

withacopy

program

rather

than

withabackup

programs

Otherwise,

the

same

problem

will

be

recreated

on

the

new

diskette.

When

the

new

copy

is

done,

compare

the

number

of

blocks

free

in

its

directory

to

the

number

free

on

the

original

diskette.

If

the

numbers

match,

no

damage

has

been

done.

If

not,

very

likely

at

least

one

file

on

the

diskette

has

been

corrupted,

and

all

should

be

checked

immedi

ately.

21

Locked

Files

Occasionally,

a

diskette

will

containalocked

file;

one

which

cannot

be

erased

with

the

SCRATCH

command.

Such

files

may

be

recognized

by

the

"<"

character

which

immediately

follows

the

file

type

in

their

directory

entry.

If

you

wish

to

erase a

locked

file,

you

will

have

to

useasector

editor

program

to

clear

bit6of

the

file-type

byte

in

the

directory

entry

on

the

diskette.

Conversely,

to

lockafile,

you

would

set

bit6of

the

same

byte.

RENAME

The

RENAME

command

allows

you

to

alter

the

name

ofaprogram

or

other

file

in

the

diskette

directory.

Since

only

the

directory

is

affected,

RENAME

works

very

quickly.

FORMAT

FOR

RENAME

COMMAND:

PRINT#15,"RENAME0:new

name=old

name"

or

it

may

be

abbreviated

as:

PRINT#15,"R0:new

name=old

name"

where

"new

name"

is

the

name

you

want

the

file

to

have,

and

"old

name"

is

the

name

it

has

now.

"new name"

may

be

any

valid

file

name,

up

to

16

characters

in

length.

It

is

assumed

you

have

already

opened

file

15

to

the

command

channel.

One

caution—be

sure

the

file

you

are

renaming

has

been

proper

ly

closed

before

you

rename

it.

EXAMPLES:

Just

before

saving a

new

copy

ofa"calendar"

program,

you

might

type:

PRINT#15,"R0:CALENDAR/BACKUP

=

CALENDAR"

Or

to

moveaprogram

called

"BOOT,"

currently

the

first

program

on

a

diskette

to

someplace

else

in

the

directory,

you

might

type:

PRINT#15,"R0:TEMP

=

BOOT"

followed

byaCOPY

command

(described

later),

which

turns

"TEMP"

intoanew

copy

of

"BOOT,"

and

finishing

withaSCRATCH

command

to

get

rid

of

the

original

copy

of

"BOOT."

22

RENAMING

AND

SCRATCHING

TROUBLESOME

FILES

Eventually,

you

may

run

acrossafile

which

has

an

odd

filename,

such

asacomma

by

itself

(",")

or

one

that

includes

a

Shifted

Space

(a

Shifted

Space

looks

the

same

asaregular

space,

but

ifafile

with

a

space

in

its

name

won't

load

properly

and

all

else

is

correct,

it's

probably

a

Shifted

Space).

Or

perhaps

you

will

find

one

that

includes

nonprinting

characters.

Any

of

these

can

be

troublesome.

Comma

files,

for

instance,

are

an

exception

to

the

rule

that

no

two

files

can

have

the

same

name.

Since

it

shouldn't

be

possible

to

makeafile

whose

name

is

onlyacomma,

the

disk

never

expects

you

to

do

it

again.

Files

withaShifted

Space

in

their

name

can

also

be

troublesome,

because

the

disk

interprets

the

Shifted

Space

as

signaling

the

end

of

the

file

name,

and

prints

whatever

follows

after

the

quotation

mark

that

marks

the

end

ofaname

in

the

directory.

This

technique

can

be

useful

by

allowing

you

to

havealong

file

name,

and

making

the

disk

recognize

a

small

part

of

it

as

being

the

same

as

the

whole

thing

without

using

pattern-matching

characters.

In

any

case,

if

you

haveatroublesome

filename,

you

can

use

the

CHR$()

function

to

specify

troublesome

characters

without

typing

them

directly.

This

may

allow

you

to

build

them

intoaRENAME

command.

If

this

fails,

you

may

also

use

the

pattern-matching

charac

ters

inaSCRATCH

command.

This

gives

youaway

to

specify

the

name

without

using

the

troublesome

characters

at

all,

but

also

means

loss

of

your

file.

For

example,

if

you

have

managed

to

createafile

named

""MOV

IES",

with

an

extra

quotation

mark

at

the

front

of

the

file

name,

you

can

rename

it

to

"MOVIES"

using

the

CHR$()

equivalent

of a

quotation

mark

in

the

RENAME

command:

I

PRINT#15,uR0:MOVIES

="+

CHR$(34)

+"MOVIES"

The

CHR$(34)

forcesaquotation

mark

into

the

command

string

without

upsetting

BASIC.

The

procedure

forafile

name

that

includes

a

Shifted

Space

is

similar,

but

uses

CHR$(l60).

In

cases

where

even

this

doesn't

work,

for

example,

if

your

diskette

contains

a

comma

file,

(one

named

",")

you

can

get

rid

of

it

this

way:

PRINT#15,"S0:?"

This

example

deletes

all

files

with

one

character

names.

23

Depending

on

the

exact

problem,

you

may

have

to

be

very

creative

in

choosing

pattern-matching

characters

that will

affect

only

the

desired

file,

and

may

have

to

rename

other

files

first

to

keep

them

from

being

scratched.

In

some

cases,

it

may

be

easier

to

copy

desired

files

toadifferent

diskette

and

leave

the

troublesome

files

behind.

COPY

The

COPY

command

allows

you

to

makeaspare

copy

of

any

program

or

file

onadiskette.

Onasingle

drive

like

the

1581,

the

copy

must

be

on

the

same

diskette,

which

means

it

must

be

givenadifferent

name

from

the

file

copied.

It's

also

used

to

combine

up

to

four

sequential

data

files

(linking

the

files

one

to

another,

end

to

end

in

a

chain).

Files

are

linked

in

the

order

in

which

they

appear

in

the

command.

The

source

files

and

other

files

on

the

diskette

are

not

changed.

Files

must

be

closed

before

they

are

copied

or

linked.

FORMAT

FOR

THE

COPY

COMMAND

PRINT#15,"COFYdrive

#:new

file=old

file"

EXAMPLES:

PRINT#15,uCOPY0:BACKUP

=

ORIGINAL"

or

abbreviated

as

PRINT#15,"Cdrive

#:new

file=old

file"

PRINT#15,"C0:BACKUP

=

ORIGINAL"

where

"drive

#"

is

the

drive

number

"new

file"

is

the

copy

and

"old

file"

is

the

original.

FORMAT

FOR

THE

COMBINE

OPTION

PRINT#15,"Cdrive

#:new

file=file

l,file

2,file

3,

file

4"

where

"drive

#"

is

always

0,

NOTE

The

length

ofacommand

string

(command

and

filenames)

is

limited

to

41

characters.

24

EXAMPLES:

After

renamingafile

named

"BOOT"

to

"TEMP"

in

the

last

section's

example,

you

can

use

the

COPY

command

to

makeaspare

copy

of

the

program

elsewhere

on

the

diskette,

under

the

original

name:

PRINT#15,"C0:BOOT

=

TEMP"

After

creating

several

small

sequential

files

that

fit

easily

in

mem

ory

along

withaprogram

we

are

using,

you

can

use

the

concatenate

option

to

combine

them

inamaster

file,

even

if

the

result

is

too

big

to

fit

in

memory.

(Be

sure

it

will

fit

in

remaining

space

on

the

diskette—it

will

be

as

big

as

the

sum

of

the

sizes

of

the

files

in

it.)

PRINT#15,"C0:A-Z=A-G,H-M,N-Z"

EXAMPLES:

After

renamingafile

named

"BOOT"

to

"TEMP"

in

the

last

section's

example,

you

can

use

the

COPY

command

to

makeaspare

copy

of

the

program

elsewhere

on

the

diskette,

under

the

original

name:

PRINT#15/'C0:BOOT

=

TEMP"

After

creating

several

small

sequential

files

that

fit

easily

in

mem

ory

along

withaprogram

we

are

using,

you

can

use

the

concatenate

option

to

combine

them

inamaster

file,

even

if

the

result

is

too

big

to

fit

in

memory.

(Be

sure

it

will

fit

in

remaining

space

on

the

diskette—it

will

be

as

big

as

the

sum

of

the

sizes

of

the

files

in

it.)

PRINT#15,"C0:A-Z=A-G,H-M,N-Z"

VALIDATE

The

VALIDATE

command

recalculates

the

Block

Availability

Map

(BAM)

of

the

current

diskette,

allocating

only

those

sectors

still

being

used

by

valid,

properly-closed

files

and

programs.

All

other

sectors

(blocks)

are

left

unallocated

and

free

for

re-use,

and

all

improperly

closed

files

are

automatically

scratched.

This

brief

description

of

its

workings

doesn't

indicate

either

the

power

or

the

danger

of

the

25

VALIDATE

command.

Its

power

is

in

restoring

to

good

health

many

diskettes

whose

directories

or

block

availability

maps

have

become

muddled.

Any

time

the

blocks

used

by

the

files

onadiskette

plus

the

blocks

shown

as

free

don't

add

up

to

the

3160

available

onafresh

diskette,

VALIDATE

is

needed,

with

one

exception

below.

Similarly,

any

timeadiskette

contains

an

improperly-closed

file

(splat

file),

indicated

by

an

asterisk

(*)

next

to

its

file

type

in

the

directory,

that

diskette

needs

to

be

validated.

In

fact,

but

for

the

one

exception,

it

is

a

good

idea

to

VALIDATE

diskettes

whenever

you

are

the

least

bit

concerned

about

their

integrity.

The

exception

is

diskettes

containing

direct

access

files,

as

de

scribed

in

Chapter

6.

Most

direct

access

(random)

files

do

not

allocate

their

sectors

inaway

the

VALIDATE

command

can

recognize.

Thus,

using

VALIDATE on

suchadiskette

may

result

in

un-allocating

all

direct

access

files,

with

loss

of

all

their

contents

when

other

files

are

added.

Unless

specifically

instructed

otherwise,

never

use

VALIDATE

onadiskette

containing

direct

access

files.

FORMAT

FOR

THE

VALIDATE

COMMAND

PRINT#15,"VALIDATE0"

or

.abbreviated

as

PRINT#15,"V0"

where

"0"

is

the

drive

number.

As

usual,

it

is

assumed

file

15

has

been

opened

to

the

command

channel

and

will

be

closed

after

the

com

mand

has

been

executed.

INITIALIZE

Whenadiskette

is

inserted

into

the

drive,

its

directory

is

auto

matically

re-read

intoadisk

buffer.

You

would

use

the

command

only

if

that

information

became

unreliable.

FORMAT

FOR

THE

INITIALIZE

COMMAND

PRINT#15,"INITIALIZEdrive#"

or

it

may

be

abbreviated

to

PMNT#15,"Idrive#"

26

CHAPTER

3

BASIC

7.0

COMMANDS

This

chapter

describes

the

disk

commands

used

with

the

Com

modore

128

computer

(in

C128

mode).

This

is

BASIC

7.0,

which

includes

BASIC

2.0,

BASIC

3.5,

and

BASIC

4.0

commands,

all

of

which

can

be

used.

ERROR

CHECKING

When

the

drive

light

(red

light)

flashes,

you must

use

the

follow

ing

command

to

find

out

what

the

error

is:

PRINT

DS$

A

message

is

displayed

whether

there

is

an

error

or

not.

If

there

was

an

error,

this

command

clears

it

from

disk

memory

and

turns

off

the

error

light

on

the

disk

drive.

Once

the

message

is

on

the

screen,

you

can

look

it

up

in

Appen

dixBto

see

what

it

means,

and

what

to

do

about

it.

For

those

of

you

who

are

writing

programs,

the

following

is

a

small

error-checking

subroutine

you

can

include

in

your

programs:

59990

REM

READ

ERROR

CHANNEL

60000

IF

DS>1

THEN

PRINT

DS$:STOP

60010

RETURN

The

subroutine

reads

the

error

channel

and

puts

the

results

into

the

reserved

variables

DS

and

DS$.

They

are

updated

automatically

by

BASIC.

Two

error

numbers

are

harmless—0

means

everything

is

OK,

and

1

tells

how

many

files

were

erased

byaSCRATCH

command

(de

scribed

later

in

this

chapter).

If

the

error

status

is

anything

else,

line

60000

prints

the

error

message

and

halts

the

program.

Because

this

isasubroutine,

you

access

it

with

the

BASIC

GOSUB

command,

either

in

immediate

mode

or

fromaprogram.

The

RETURN

statement

in

line

60010

will

jump

back

to

immediate

mode

or

the

next

statement

in

your

program,

whichever

is

appropriate.

SAVE

This

command

will

saveaprogram

or

file

so

you

can

reuse

it.

The

diskette

must

be

formatted

before

you

can

save

it

to

that

diskette.

27

FORMAT

FOR THE

SAVE

COMMAND

DSAVE

"file

name"

[,Ddrive#]

[,Udevice#]

This

command

will

not

work

in

copying

programs

that

are

not

written

in

BASIC.

To

copy

these

machine

language

programs,

you

can

use

the

BSAVE

command

or

the

built-in

MonitorScommand.

FORMAT

FOR

THE

BSAVE

COMMAND

BSAVE

"file

name"

[,Ddrive#]

[,Udevice#]

[Bbank#]

[,Pstarting

address]

[TO

Pending

address

+1]

where

the

usual

options

are

the

same

and

bank#

is

one

of

the

16

banks

of

the

C128.

The

addresses

to

be

saved

are

given

in

decimal.

Note

that

the

ending

address

must

be1location

beyond

the.

last

location

to

be

saved.

To

accessabuilt-in

monitor,

type

MONITOR.

To

exitamonitor,

typeXalone

onaline.

FORMAT

FORAMONITOR

SAVE

S"drive

#:file

name",device

#,starting

address,ending

address

+1

where

"drive

#:"

is

the

drive

number,0on

the

1581;

"file

name"

is

any

valid

file

name

up

to

14

characters

long

(16

if

you

leave

outjthe

drive

#

and

the

colon

that

follows

it);

"device

#"

isatwo

digit

device

number,

normally

08

on

the

1581

(the

leading0is

required);

and

the

addresses

to

be

saved

are

given

in

Hexadecimal

(base

16,)

but

withoutaleading

dollar

sign

(for

the

Plus/4).

On

the

C128,

the

addresses

need

not

be

in

Hexidecimal.

Note

that

the

ending

address

listed

must be1location

beyond

the

last

location

to

be

saved.

SAVE

WITH

REPLACE

Ifafile

already

exists,

it

can't

be

saved

again

with

the

same

name

because

the

disk

drive

allows

only

one

copy

of

any

given

file

name

per

diskette.

It

is

possible

to

get

around

this

problem

using

the

RENAME

and

SCRATCH

commands

described

later

in this

chapter.

If

all

you

wish

to

do

is

replaceaprogram

or

data

file

witharevised

version,

another

command

is

more

convenient.

Known

as

SAVE

WITH

RE

PLACE, or

@SAVE

this

option

tells

the

disk

drive

to

replace

any

file

it

finds

in

the

diskette

directory

with

the

same

name,

substituting

the

new

file

for

the

old

version.

28

FORMAT

FOR

SAVE

WITH

REPLACE

DSAVE

"@file

name"

[,Ddrive#]

[,Udevice#]

The

actual

procedure

is

this—the

new

version

is

saved

complete

ly,

then

the

old

version

is

scratched

and

its

directory

entry

altered

to

point

to

the

new

version.

Because

it

works

this

way,

there

is

little

dangeradisaster

such

as

having

the

power

going

off

midway

through

the

process

would

destroy

both

the

old

and

new

copies

of

the

file.

Nothing

happens

to

the

old

copy

until

after

the

new

copy

is

saved

properly.

VERIFY

This

command

makesabyte-by-byte

comparison

of

the

program

currently

in

memory

against

a

program

on

diskette.

This

comparison

includes

the

BASIC

line

links,

which

may

be

different

for

different

types

of

memory

configurations.

What

this

means

is

thataprogram

saved

to

disk

onaC64

and

reloaded

intoaC128

wouldn't

verify

properly

because

the

line

links

point

to

different

memory

locations.

If

the

disk

copy

of

the

program

differs

at

all

from

the

copy

in

memory,

a

"VERIFY

ERROR"

will

be

displayed.

This

doesn't

mean

either

copy

is

bad,

but

if

they

were

supposed

to

be

identical,

there

isaproblem.

FORMAT

FOR THE

DVERIFY

COMMAND

DVERIFY

"file

name"

[,Ddrive#]

[,Udevice#]

The

following

version of

the

command

verifies

a

file

that

was

just

saved:

DVERIFY

"*"

This

command

won't

work

properly

after

SAVE-WITH-REPLACE,

because

the

last

file

used

was

the

one

deleted

and

the

drive

will

try

to

compare

the

deleted

file

to

the

program

in

memory.

No

harm

will

result,

but

"VERIFY

ERROR"

will

always

be

announced.

To

use

DVER

IFY

after

@SAVE,

include

at

least

part

of

the

file

name

that

is

to

be

verified

in

the

pattern.

COPY

The

COPY

command

allows

you

to

makeaspare

copy

of

any

program

or

file

onadiskette.

However,

onasingle

drive

like

the

1581,

29

the

copy

must

be

on

the

same

diskette,

which

means

it

must

be

given

a

different

name

from

the

file

copied.

The

source

file

and

other

files

on

the

diskette

are

not

changed.

Files

must

be

closed

before

they

can

be

copied

or

concatenated.

FORMAT

FOR

THE

COPY

COMMAND

COPY

[Ddrive#,]

"old

file

name"

TO

[Ddrive#,]

"new

file

name"

[,Udevice#]

Where

both

drive#s

would

be0if

included.

CONCAT

The

CONCAT

command

allows

you

to

concatenate

(combine)

two

sequential

files.

FORMAT

FOR

THE

CONCAT

COMMAND

CONCAT

[Ddrive#,]

"add

file"

TO

[Ddrive#,]

"master

file"

[,Udevice#]

Where

the

optional

drive#

would

be0in

both

cases.

The

old

"master

file"

is

deleted

and

replaced

withanew

"master

file"

which

is

the

concatenation

of

the

old

"master

file"

and

"add

file".

-NOTE

The

length

ofacommand

string

(command

and

filenames)

is

limited

to

41

characters.

SCRATCH

The

SCRATCH

command

allows

you

to

erase

unwanted

programs

and

files

from

your

diskettes,

and

free

up

the

space

they

occupied

Jor

use

by

other

files

and

programs.

It

can

be

used

to

erase

eitherasingle

file,

or

several

files

at

once

via

pattern-matching.

FORMAT

FOR THE

SCRATCH

COMMAND

SCRATCH

"pattern"

[,Ddrive#]

[,Udevice#]

Where,

"pattern"

is

any

valid

file

name

or

pattern-matching

character.

30

You

will

be

asked

asaprecaution:

ARE

YOU

SURE?"

If

you

ARE

sure,

simply

pressYand

RETURN.

If

not,

press

RETURN

alone

or

type

any

other

answer,

and

the

command

will

be

canceled.

The

number

of

files

that

were

scratched

will

be

automatically

displayed.

For

example,

if

your

diskette

contains

program

files

named

"TEST,"

"TRAIN,"

"TRUCK,"

and

"TAIL,"

you

may

scratch

all

four,

along

with

any

other

files

beginning

with

the

letter

"T,"

by

using

the

command:

SCRATCH

"T*"

and

if

the

four

listed

were

the

only

files

beginning

with

"T",

you

will

see:

01,FILES

SCRATCHED,04,00

READY

The

"04"

tells

you4files

were

scratched.

You

can

performaSCRATCH

withinaprogram,

but

there

will

be

no

prompt

message

displayed.

MORE

ABOUT

SCRATCH

SCRATCH

isapowerful

command

and

should

be

used

with

caution

to

be

sure

you

delete

only

the

files

you

really

want

erased.

When

using

it

withapattern,

we

suggest

you

first

use

the

same

pattern

inaDIRECTORY

command,

to

be

sure

exactly

which

files

will

be

deleted.

That

way

you'll

have

no

unpleasant

surprises

when

you

use

the

same

pattern

in

the

SCRATCH

command.

If

you

accidentally

SCRATCHafile

you

shouldn't

have,

there

is

still

a

chance

of

saving

it

by

using

the

"Unscratch"

program

on

your

Test/Demo

diskette.

More

about

Splat

Files

Never

SCRATCHasplat

file.

These

are

files

that

show

up

in

a

directory

listing

with

an

asterisk

(*)

just

before

the

file

type

for

an

entry.

The

asterisk

(or

splat)

means

that

file

was

never

properly

closed,

and

thus

there

is

no

valid

chain

of

sector

links

for

the

SCRATCH

command

to

follow

in

erasing

the

file.

If

you

SCRATCH

suchafile,

31

odds

are

you

will

improperly

free

up

sectors

that

are

still

needed

by

other

programs

or

files,

and

cause

permanent

damage

to

those

other

programs

or

files

later

when

you

add

more

files

to

the

diskette.

If

you

findasplat

file,

or

if

you

discover

too

late

that

you

have

scratched

suchafile,

immediately

validate

the

diskette

using

the

COLLECT

command

described

later

in

this

chapter.

If

you

have

added

any

files

to

the

diskette

since

scratching

the

splat

file,

it

is

best

to

immediately

copy

the

entire

diskette

onto

another

fresh

diskette,

but

do

this

withacopy

program

rather

than

withabackup

program.

Otherwise,

the

same

problem

will

be

recreated

on

the

new

diskette.

When

the

new

copy

is

done,

compare

the

number

of

blocks

free

in

its

directory

to

the

number

free

on

the

original

diskette.

If

the

numbers

match,

no

damage

has

been

done.

If

not,

very

likely

at

least

one

file

on

the

diskette

has

been

corrupted,

and

all

should

be

checked

immedi

ately.

Locked

Files

Occasionally,

a

diskette

will

containalocked

file;

one

which

cannot

be

erased

with

the

SCRATCH

command.

Such

files

may

be

recognized

by

the

"<"

character

which

immediately

follows

the

file

type

in

their

directory

entry.

If

you

wish

to

erasealocked

file,

you

will

have

to

useadisk

monitor

to

clear

bit6of

the

file-type

byte

in

the

directory

entry

on

the

diskette.

Conversely,

to

lockafile,

you

would

set

bit6of

the

same

byte.

RENAME

The

RENAME

command

allows

you

to

alter

the

name

ofapro

gram

or

other

file

in

the

diskette

directory.

Since

only

the

directory

is

affected,

RENAME

works

very

quickly.

If

you

try

to

RENAMEafile

by

usingafile

name

already

in

the

directory,

the

computer

will

respond

witha"FILE

EXISTS"

error.Afile

must

be

properly

closed

before

it

can

be

renamed.

FORMAT

FOR

RENAME

COMMAND:

RENAME

[Ddrive#,]

"old

name"

TO

[Ddrive#,]

"new

name"

[,Udevice#]

where

both

drive#s,

if

included,

would

be

0

32

RENAMING

AND

SCRATCHING

TROUBLESOME

FILES

Eventually,

you

may

run

acrossafile

which

hasacrazy

filename,

such

asacomma

by

itself

(",")

or

one

that

includes

a

Shifted

Space.

Or

perhaps

you

will

find

one

that

includes

nonprinting

characters.

Any

of

these

can

be

troublesome.

Comma

files,

for

instance,

are

an

exception

to

the

rule

that

no

two

files

can

have

the

same

name.

Since

it

shouldn't

be

possible

to

makeafile

whose

name

is

onlyacomma,

the

disk

never

expects

you

to

do

it

again.

Files

withaShifted

Space

in

their

name

can

also

be

troublesome,

because

the

disk

interprets

the

Shifted

Space

as

signaling

the

end

of

the

file

name,

and

prints

whatever

follows

after

the

quotation

mark

that

marks

the

end

ofaname

in

the

directory.

This

technique

can

be

useful

by

allowing

you

to

havealong

file

name,

and making

the

disk

recognize

a

small

part

of

it

as

being

the

same

as

the

whole

thing

without

using

pattern-matching

characters.

In

any

case,

if

you

haveatroublesome

filename,

you

can

use

the

CHR$()

function

to

specify

troublesome

characters

without

typing

them

directly.

This

may

allow

you

to

build

them

intoaRENAME

command.

If

this

fails,

you

may

also

use

the

pattern-matching

charac

ters

discussed

foraSCRATCH

command.

This

gives

youaway

to

specify

the

name

without

using

the

troublesome

characters

at

all,

but

also

means

loss

of

your

file.

For

example,

if

you

have

managed

to

createafile

named""MOV

IES",

with

an

extra

quotation

mark

at

the

front

of

the

file

name,

you

can

rename

it

to

"MOVIES"

using

the

CHR$()

equivalent

ofaquotation

mark

in

the

RENAME

command:

EXAMPLE:

RENAME(CHR$(34)

+

"MOVIES")

TO

"MOVIES"

The

CHR$(34)

forcesaquotation

mark

into

the

command

string

without

upsetting

BASIC.

The

procedure

forafile

name

that

includes

a

Shifted

Space

is

similar,

but

uses

CHR$(l60).

In

cases

where

even

this

doesn't

work,

for

example,

if

your

diskette

contains

a

comma

file,

(one

named

",")

you

can

get

rid

of

it

this

way:

SCRATCH"?"

33

This

example

deletes

all

files

with

one-character

names.

Depending

on

the

exact

problem,

you

may

have

to

be

very

creative

in

choosing

pattern-matching

characters

that will

affect

only

the

desired

file,

and

may

have

to

rename

other

files

first

to

keep

them

from

being

scratched.

In

some

cases,

it

may

be

easier

to

copy

desired

files

toadifferent

diskette

and

leave

the

troublesome

files

behind.

COLLECT

The

COLLECT

command

recalculates

the

Block

Availability

Map

(BAM)

of

the

current

diskette,

allocating

only

those

sectors

still

being

used

by

valid,

properly

closed

files

and

programs.

All

other

sectors

(blocks)

are

left

unallocated

and

free

for

reuse,

and

all

improperly

closed

files

are

automatically

scratched.

However,

this

brief

descrip

tion

of

COLLECT

doesn't

indicate

either

the

power

or

the

danger

of

the

command.

Its

power

is

in

restoring

to

good

health

many

diskettes

whose

directories

or

Block

Availability

Maps

have

become

muddled.

Any

time

the

blocks

used

by

the

files

onadiskette

plus

the

blocks

shown

as

free

don't

add

up

to

the

3160

available

onafresh

diskette,

COLLECT

is

needed

(with

one

exception

below).

Similarly,

any

time

a

diskette

contains

an

improperly

closed

file

(splat

file),

indicated

by

an

asterisk

(*)

next

to

its

file

type

in

the

directory,

that

diskette

needs

to

be

collected.

In

fact,

but

for

the

one

exception

below,

it

isagood

idea

to

COLLECT

diskettes

whenever

you

are

concerned

about

their

integ

rity.

Just

note

the

number

of

blocks

free

in

the

diskette's

directory

before

and

after

using

COLLECT.

If

the

totals

differ,

there

was

indeed

a

problem,

and

the

diskette

should

probably

be

copied

ontoafresh

diskette

file-by-file,

using

the

COPY

command

described

in

the

pre

vious

section,

rather

than

usingabackup

command

or

program.

The

exception

is

diskettes

containing

direct

access

files,

as

de

scribed

in

Chapter

6.

Most

direct

access

(random)

files

do

not

allocate

their

sectors

inaway

COLLECT

can

recognize.

Thus,

collecting

such

a

diskette

may

result

in

unallocating

all

direct

access

files,

with

loss

of

all

their

contents

when

other

files

are

added.

Unless

specifically

instruct

ed

otherwise,

never

collectadiskette

containing

direct

access

files.

(Note:

these

are

not

the

same

as

the

relative

files

described

in

Chapter

5.

COLLECT

may

be

used

on

relative

files

without

difficulty.)

FORMAT

FOR

THE

COLLECT

COMMAND

COLLECT

[Ddrive#]

[,Udevice#]

34

DCLEAR

One

command

that

should

not

often

be

needed

on

the

1581,

but

is

still

of

occasional

value

is

DCLEAR.

On

the

1581,

and

nearly

all

other

Commodore

drives,

this

function

is

performed

automatically,

when

everanew

diskette

is

inserted.

The

result

of

an

DCLEAR,

whether

forced

byacommand,

or

done

automatically

by

the

disk,

isare-reading

of

the

current

diskette's

BAM

intoadisk

buffer.

This

information

must

always

be

correct

in

order

for

the

disk

to

store

new

files

properly.

However,

since

the

chore

is

handled

automatically,

the

only time

you'd

need

to

use

the

command

is if

something

happened

to

make

the

information

in

the

drive

buffers

unreliable.

FORMAT FOR THE

DCLEAR

COMMAND

PRINT#15,uDCLEARdrive

#"

EXAMPLE:

PRINT#15,"DCLEAR

0"

or

it

may

be

abbreviated

to

PRINT#15,"Idrive

#"

PRINT#15,"I0"

where

the

command

channel

is

assumed

to

be

opened

by

file

15,

and

"drive

#"

is

0.

35

PART

TWO

ADVANCED

OPERATION

AND

PROGRAMMING

CHAPTER

4

SEQUENTIAL

DATA

FILES

A

file

onadiskette

is

just

likeafile

cabinet

in

your

office^—an

organized

place

to

put

things.

Nearly

everything

you

put

onadiskette

goes

in

one

kind

of

file

or

another.

So

far

all

you've

used

are

program

files,

but

there

are

others.

In

this

chapter

you'll

learn

about

sequential

data

files.

The

primary

purpose

ofadata

file

is

to

store

the

contents

of

program

variables,

so

they

won't

be

lost

when

the

program

ends.

A

sequential

data

file

is

one

in

which

the

contents

of

the

variables

are

stored

"in

sequence,"

one

right

after

another.

You

may

already

be

familiar

with

sequential

files

from

usingaDATASSETTE™,

because

sequential

files

on

diskette

are

just

like

the

data

files

used

on

cassettes.

Whether

on

cassette

or

diskette,

sequential

files

must

be

read

from

beginning

to

end.

When

sequential

files

are

created,

information

(data)

is

trans

ferred

byte-by-byte,

throughabuffer,

onto

the

magnetic

media.

Once

in

the disk

drive,

program

files,

sequential

data

files,

and

user

files

all

work

sequentially.

Even

the

directory

acts

likeasequential

file.

To

use

sequential

files

properly,

we

will

learn

some

more

BASIC

words

in

the

next

few

pages.

Then

we'll

put

them

together

inasimple

but

useful

program.

37

NOTE

Besides

sequential

data

files,

two

other

file

types

are

recorded

sequentially

onadiskette.

They

are

program

files,

and

user

files.

When

you

saveaprogram

onadiskette,

it

is

saved

in

order

from

beginning

to

end,

just

like

the

informa

tion

inasequential

data

file.

The

main

difference

is

in

the

commands

you

use

to

access

it.

User

files

can

be

even

more

similar

to

sequential

data

files.

User

files

are

almost

never

used,

but

like

program

files,

they

could

be

treated

as

though

they

were

sequential

data

files

and

some

can

be

accessed

with

the

same

commands.

For

the

advanced

user,

the

similarity

of

the

various

file

types

offers

the

possibility

of readingaprogram

file

into

the

computerabyte

(character)

atatime

and

rewriting

it

to

the

diskette

inamodified

form.

OPENINGAFILE

One

of

the

most

powerful

tools

in

Commodore

BASIC

is

the

OPEN

statement.

With

it,

you

may

send

data

almost

anywhere,

much

likeatelephone

switchboard.

As

you

might

expect,

a

command

that

can

do

this

much

is

fairly

complex.

You

have

already

used

OPEN

statements

regularly

in

some

of

your

diskette

commands.

Before

you

study

the

format

of

the

OPEN

statement,

let's

review

some

of

the

possible

devices

inaCommodore

computer

system:

Device#:

Name;

Used

for;

0

Keyboard

Receiving

input

from

the

computer

operator

1

DATASSETTE™

Sending

and

receiving

information

from

cassette

2

RS232

Sending

and

receiving

information

fromamodem

3

Screen

Sending

outputtoa

video

display

4,5

Printer

Sending

output

toahard

copy

printer

8,9,10,11

Diskdrive

Sending

and

receiving

information

from

diskette

Because

of

the

flexibility

of

the

OPEN

statement,

it

is

possible

for

a

single

program

statement

to

contact

any

one

of

these

devices,

or

even

others,

depending

on

the

value

ofasingle

character

in

the

command.

If

the

character

is

kept

inavariable,

the

device

can

even

change

each

time

that

part

of

the

program

is

used,

sending

data

alternately

and

with

equal

ease

to

diskette,

cassette,

printer

and

screen.

38

NOTE

In

the

last

chapter

you

learned

how

to

check

for

disk

errors

after

disk

commands

inaprogram.

It

is

equally

important

to

check

for

disk

errors

after

using

file-handling

statements.

Failure

to

detect

a disk

error

before

using

an

other

file-handling

statement

could

cause

loss

of

data,

and

failure

of

the

BASIC

program.

The

easiest

way

to

check

the disk

is

to

follow

all

file-

handling

statements

withaGOSUB

statement

to

an

error

check

subroutine.

EXAMPLE:

BASIC

7.0

840

DOPEN#4,"DEGREE

DAY

DATA",D0,U8,W

850

GOSUB

59990:

REM

CHECK

FOR

DISK

ERRORS

BASIC

2.0

840

OPEN

4,8,4,"0:DEGREE

DAY

DATA,S,W"

850

GOSUB

59990:REM

CHECK

FOR

DISK

ERRORS

FORMAT

FOR THE

DISK

OPEN

STATEMENT

FOR

SEQUENTIAL

FILES:

BASIC

7.0

DOPEN#file#,

"file

name"

[,Ddrive#]

[,Udevice#]

[,W]

BASIC

2.0

OPEN

file

#,

device

#,

channel

#,"drive

#:file

name,file

type,-

direction"

where:

"file

#"

is

an

integer

(whole

number)

between1and

255.

Do

not

openadisk

file

withafile

number

greater

than

127

it

will

cause

severe

problems.

After

the

file

is

open,

all

other

file

commands

will

refer

to

it

by

the

number

given

here.

Only

one

file

can

use

any

given

file

number

atatime.

"device

#"

is

the

number,

or

primary

address,

of

the

device

to

be

used.

This

number

is

an

integer

in

the

range

8-11,

and

is

normally

8

on

the

1581.

"channel

#"

isasecondary

address,

giving

further

instructions

to

the

selected

device

about

how

further

commands

are

to

be

obeyed.

In

disk

files,

the

channel

number

selects

a

particular

channel

along

which

39

communications

for

this

file

can

take

place.

The

possible

range

of

disk

channel

numbers

is

0-15,

but0is

reserved

for

program

loads,1for

program

saves,

and

15

for

the

disk

command

channel.

Also

be

sure

that

no

two

disk

files

have

the

same

channel

number

unless

they

will

never

be

open

at

the

same

time.

(One

way

to

do

this

is

to

make

the

channel

number

for

each

file

the

same

as

its

file

number.)

"drive

#"

is

the

drive

number,

always0on

the

1581.

Do

not

omit

it,

or

you

will

only

be

able

to

use

two

channels

at

the

same

time

instead

of

the

normal

maximum

of

three.

If

any

pre-existing

file

of

the

same

name

is

to

be

replaced,

precede

the

drive

number

with

the

"at"

sign

(@)

to

request

OPEN-WITH-REPLACE.

"file

name'1

is

the

file

name,

maximum

length

16

characters.

Pattern

matching

characters

are

allowed

in

the

name

when

accessing

existing

files,

but

not

when

creating

new

ones.

"file

type"

is

the

file

type

desired:

S=sequential,

P=program,

U=user,

A=append

andL=

length

ofarelative

file.

"direction"

is

the

type

of

access

desired.

There

are

three

possi

bilities:

R=read,

W=write,

andM=

modify.

When

creating

a

file,

use

"W"

to

write

the

data

to

diskette.

When

vie\^ing

a

completed

file,

use

"R"

to

read

the

data

from

diskette.

Only

use

the

"M"

(modify)

option

asalast

ditch

way

of

reading

back

data

from

an

improperly

closed

(Splat)

file.

If

you

try

this,

check

every

byte

as

it

is

read

to

be

sure

the

data

is

still

valid,

as

such

files

always

include

some

erroneous

data,

and

have

no

proper

end.

"file

type"

and

"direction"

don't

have

to

be

abbreviated.

They

can

be

spelled

out

in

full

for

clarity

in

printed

listings.

"file

#",

"device

#"

and

"channel

#"

must

be

valid

numeric

constants,

variables

or

expressions.

The

rest

of

the

command

must be

a

valid

string

literal,

variable

or

expression.

"w"

is

an

option

that

must be

specified

to

write

the

sequential

file,

or

the

file

will

be

opened

to

read.

The

maximum

number

of

files

that

may

be

open

simultaneously

is

10,

including

all

files

to

all

devices.

The

maximum

number

of

sequential

disk

files

that

can

be

open

at

once

is

three

(or

two

if

you

neglect

to

include

the

drive

number

in

your

OPEN

statement),

plus

the

command

channel.

EXAMPLES

OF

OPENING

SEQUENTIAL

FILES:

To

createasequential

file

of

phone

numbers,

you

could

use:

BASIC

7.0:

DOPEN#2,"PHONES",D0,U8,W

BASIC

2.0:

OPEN

2,8,2,"0:PHONES,SEQUENTIAL,WRITE"

or

OPEN

2,8,2,"0:PHONES,S,W"

40

On

the

chance

you

Ve

already

gota"PHONES"

file

on

our

diskette,

you

can

avoid

a "FILE

EXISTS"

error

message

by

doing

an

@OPEN

BASIC

7.0:

DOPEN#2,

"©PHONES",

D0,U8,W

BASIC

2.0:

OPEN

2,8,2,"@0:PHONES,S,W"

This

erases

all

your

old

phone

numbers,

so

make

sure

that

any

information

that

may

be

deleted

is

of

no

importance.

After

writing

our

phone

file,

remove

the

diskette

and

turn

off

the

system.

To

recall

the

data

in

the

file,

reopen

it

with

something

like:

BASIC

7.0:

DOPEN#8,"PHONES",D0,U8

BASIC

2.0:

OPEN

8,8,8,"0:PHONES,S,R"

It

doesn't

matter

whether

the

file

and

channel

numbers

match

the

ones

we

used

before,

but

the

file

name

does

have

to

match.

It's

possible

to

use

an

abbreviation

form

of

the

file

name,

if

there

are

no

other

files

that

would

have

the

same

abbreviation:

BASIC

7.0:

DOPEN#10,"PH*",D0,U8

BASIC

2.0:

OPEN

10,8,6,"0:PH*,S,R"

If

you

have

too

many

phone

numbers,

they

might

not

fit

in

one

file.

In

that

case,

use

several

similar

file

names

and

letaprogram

choose

the

correct

file.

BASIC

7.0:

100

INPUT

"WHICH

PHONE

FILE

(1-3)";PH

110

IF

PHO1

AND

PHO2

AND

PH<>3

THEN

100

120

DOPEN#4,"PHONE"

+

STR$(PH),D0,U8

BASIC

2.0:

100

INPUT

"WHICH

PHONE

FILE

(1-3)";PH

110

IF

PHO1

AND

PHO2

AND

PH<>3

THEN

100

120

OPEN

4,8,2,"PHONE"

+

STR$(PH)+",S,R"

You

can

omit

the

drive

number

on

an

OPEN

command

to

readafile.

Doing

so

allows

those

with

dual

drives

to

search

both

diskettes

for

the

file.

FORMAT

FOR THE

PRINT#

COMMAND:

PRINT#file

#,data

list

41

where

"file

#"

is

the

same

file

number

given

in

the

desired

file's

current

OPEN

statement.

During

any

given

access

of a

particular

file,

the

file

number

must

remain

constant

because

it

serves

asashorthand

way

of

relating

all

other

file-handling

commands

back

to

the

correct

OPEN

statement.

Givenafile

number,

the

computer

can

look

up

everything

else

aboutafile

that

matters.

The

"data

list"

is

the

same

as

foraPRINT

statement

-alist

of

constants,

variables

and/or

expressions,

including

numbers,

strings

or

both.

However,

it's

better

if

each

PRINT#

statement

to

disk

include

only

one

data

item.

If

you

wish

to

include

more

items,

they

should

be

separated

byacarriage

return

character,

notacomma.

Semicolons

are

permitted,

but

not

recorded

in

the

file,

and

do

not

result

in

any

added

spaces

in

the

file.

Use

them

to

separate

items

in

the

list

that

might

otherwise

be

confused,

such

asastring

variable

immediately

following

a

numeric

variable.

-NOTE

Do

not

leaveaspace

between

PRINT

and

#,

and

do

not

abbreviate

the

command

as

?#.

The

correct

abbreviation

for

PRINT#

is

pR.

EXAMPLES:

To

recordafew

grades

for

John

Paul

Jones,

usingasequential

disk

file

#1

previously

opened

for

writing,

use:

200

FOR

CLASS=1

TO

COURSES

210

PRINT#1,GRADE$(CLASS)

220

GOSUB

59990:REM

CHECK

FOR

DISK

ERRORS

320

NEXT

CLASS

assuming

your

program

includes

an

error

check

subroutine

like

the

one

in

the

last

chapter.

In

using

PRINT#,

there

is

an

exception

to

the

requirement

to

check

for

disk

errors

after

every

file-handling

statement.

When

using

PRINT#,asingle

check

after

an

entire

set

of

data

has

been

written

will

still

detect

the

error,

so

long

as

the

check

is

made

before

any

other

file-handling

statement

or

disk

command

is

used.

You

may

be

familiar

with

PRINT

statements

in

which

several

items

follow

each

other:

400

PRINT

NAME$,STREET$,CITY$

42

To

get

those

same

variables

onto

sequential

disk

file

number5instead

of

the

screen,

the

best

approach

would

be

to

use

three

separate

PRINT#

statements,

as

follows:

400

PRINT#5,NAME$

410

PRINT#5,STREET$

420

PRINT#5,CITY$

If

you

need

to

combine

them,

here

isasafe

way

to

do

it:

400PRINT#5,NAME$;CHR$(13);STREET$;CHR$(13);CITY$

CHR$(13)

is

the

carriage

return

character,

and

has

the

same

effect

as

putting

the

print

items

in

separate

lines.

If

you

do

this

often,

some

space

and

time

may

be

saved

by

previously

defining

a

variable

as

equal

to

CHR$(13):

10CR$=CHR$(13)

400PRINT#5,NAME$;CR$;STREET$;CR$;CITY$

The

basic

idea

is

thataproper

sequential

disk-file

write,

if

redir

ected

to

the

screen,

will

display

only

one

data

item

per

line,

with

each

succeeding

item

on

the

next

line.

CLOSINGAFILE

After

you

finish

usingadata

file,

it

is

extremely

important

that

you

CLOSE

it.

During

the

process

of

writing

a

file,

data

is

accumulated

in

a

memory

buffer,

and

only

written

out

to

the

diskette

when

the

buffer

fills.

Working

this

way,

there

is

almost

alwaysasmall

amount

of

data

in

the

buffer

that

has not

been

written

to

diskette

yet,

and

which

would

simply

be

lost

if

the

computer

system

were

turned

off.

Similarly,

there

are

diskette

housekeeping

matters,

such

as

updating

the

BAM

(Block

Availability

Map)

of

sectors

used

by

the

current

file,

which

are

not

per

formed

during

the

ordinary

course

of

writing

a

file.

This

is

the

reason

for

havingaCLOSE

statement.

When

you

are

done

withafile,

the

CLOSE

statement

will

write the

rest

of

the

data

buffer

out

to

diskette,

update

the

BAM,

and

complete

the

file's

entry

in

the

directory.

Always

closeadata

file

when

you

are

done

using

it.

Failure

to

do

so

may

cause

loss

of

the

entire

file.

However,

do

not

close

the

disk

command

channel

until

all

other

files

have

been

closed.

The

command

channel

should

be

the

first

file

opened,

and

the

last

file

closed

in

any

program.

43

FORMAT

FOR

THE

CLOSE

STATEMENT

BASIC

7.0:

DCLOSE#file#

[,Udevice#]

BASIC

2.0:

CLOSE

file

#

where

"file

#"

is

the

same

file

number

given

in

the

desired

file's

cur

rent

OPEN

statement.

EXAMPLES:

To

close

the

data

file

#5

used

as

an

example

on

the

previous

page,

use:

BASIC

7.0:

DCLOSE#5

BASIC

2.0:

CLOSE

5

In

BASIC

7.0,

when

the

DCLOSE

statement

is

used

alone

(no#

or

file#

parameters),

it

closes

all

disk

files

at

once.

Withabit

of

planning,

the

same

can

be done

viaaprogram

loop.

Since there

is

no

harm

in

closing

a

file

that

wasn't

open,

close

every

file

you

even

think

might

be

open

before

endingaprogram.

If

you

always

gave

your

files

numbers

between1and

5,

you

could

close

them

all

with

9950

FOR1=1TO

5

9960

CLOSE

I

9970

GOSUB

59990:REM

CHECK

FOR

DISK

ERRORS

9980

NEXT

I

assuming

your

program

includes

an

error

check

subroutine

like

the

one

in

the

last

chapter.

READING

FILE

DATA:

USING

INPUT#

Once

information

has

been

written

properly

toadiskette

file,

it

may

be

read

back

into

the

computer

with

an

INPUT#

statement.

Just

as

the

PRINT#

statement

is

much

like

the

PRINT

statement,

INPUT#

is

nearly

identical

to

INPUT,

except

that

the

list

of

items

following

the

command

word

comes

fromaparticular

file

instead

of

the

keyboard.

Both

statements

are

subject

to

the

same

limitations—halting

input

after

a

comma

or

colon,

not

accepting

data

items

too

large

to

fit

in

BASIC'S

input

buffer,

and

not

accepting

non-numeric

data

intoanumeric

vari

able.

44

FORMAT

FOR

THE

INPUT#

STATEMENT

INPUT#file

#,variable

list

where

"file

#"

is

the

same

file

number

given

in

the

desired

file's

cur

rent

OPEN

statement,

and

"variable

list"

is

one

or

more

valid

BASIC

variable

names.

If

more

than

one

data

element

is

to

be

input

by

a par

ticular

INPUT#

statement,

each

variable

name

must

be

separated

from

others

byacomma.

EXAMPLES:

To

read

back

in

the

grades

written

with

the

PRINT#

example,

use:

300

FOR

CLASS=1

TO

COURSES

310

INPUT#1,GRADE$(CLASS)

320

GOSUB

59990:REM

CHECK

FOR

DISK

ERRORS

330

NEXT

CLASS

assuming

your

program

includes

an

error

check

subroutine

like

the

one

in

the

last

chapter.

To

read

back

in

the

address

data

written

by

another

PRINT#

ex

ample,

it

is

safest

to

use:

800

INPUT#5,NAME$

810

GOSUB

59990:REM

CHECK

FOR

DISK

ERRORS

820

INPUT#5,STREET$

830

GOSUB

59990:REM

CHECK FOR

DISK

ERRORS

840

INPUT#5,CITY$

850

GOSUB

59990:REM

CHECK FOR

DISK

ERRORS

but

many

programs

cheat

on

safetyabit

and

use

800

INPUT#5,NAME$,STREET$,CITY$

810

GOSUB

59990:REM

CHECK

FOR

DISK

ERRORS

This

is

done

primarily

when

top

speed

in

the

program

is

essential,

and

there

is

little

risk

of

reading

improper

data

from

the

file.

MORE

ABOUT

INPUT#

After

you

begin

using

data

files

regularly,

you

may

encounter

two

BASIC

error

messages.

They

are

"STRING

TOO

LONG

ERROR"

and

"FILE

DATA

ERROR".

Both

are

likely

to

halt

your

program

at

an

45

INPUT#

statement,

but

may

also

have

been

caused

by

errors

in

a

PRINT#

statement

when

the

file

was

written.

"String

Too

Long"

Error

A

BASIC

string

may

be

up

to

255

characters

long,

although

the

longest

string

you

can

enter

viaasingle

Input

statement

is

just

under

two

lines

of

text.

This

lower

limitation

is

due

to

the

size

of

the

input

buffer

in

Commodore's

serial

bus

computers.

The

same

limit

applies

to

INPUT#

statements.

Ifasingle

data

element

(string

or

number)

being

read

fromadisk

file

into

an

INPUT#

statement

contains

more

than

88

(BASIC

2)

and

160

(BASIC

7)

characters,

BASIC

will

halt

with

a

"STRING

TOO

LONG

ERROR."

"File

Data" Error

The

other

error

message

"FILE

DATA

ERROR"

is

caused

by

at

tempting

to

readanon-numeric

character

intoanumeric

variable.

To

a

computer,

a

number

is

the

characters

0

through

9,

the"+"and"-

"

signs,

the

decimal

point

(.),

the

SPACE

character,

and

the

letter

"E"

used

in

scientific

notation.

If

any

other

character

appears

in

an

IN-

PUT#

toanumeric

variable,

"FILE

DATA

ERROR"

will

be

displayed

and

die

program

will

halt.

The

usual

causes

of

this

error

areamis

match

between

the

order

in

which

variables

are

written

to

and

read

fromafile,amissing

carriage

return

withinaPRINT#

statement

that

writes

more

than

one

data

item,

oradata

item

that

includes

either

a

comma

oracolon

withoutapreceding

quotation

mark.

Onceafile

data

error

has

occurred,

you

should

correct

it

by

reading

the

data

item

intoastring

variable,

and

converting

it

back

toanumber

with

the

BASIC

VAL()

statement

after

removing

non-numeric

characters

with

the

string

functions

described

in

your

computer

user's

manual.

Commas

(,)

and

Colons

(:)

As

suggested

before,

commas

and

colons

can

cause

trouble

in

a

file,

because

they

delimit

(end)

the

data

element

in

which

they

appear

and

cause

any

remaining

characters

in

the

data

element

to

be

read

into

the

next

INPUT#

variable.

They

have

the

same

effect

in

an

INPUT

statement,

causing

the

common

"EXTRA

IGNORED"

error

message.

However,

sometimes

you

really

needacomma

or

colon

withinadata

element,

such

asaname

written

as

"Last,

First."

The

cure

is

to

precede

such

data

elements

withaquotation

mark.

Afteraquotation

mark,

in

either

an

INPUT

or

INPUT#

statement,

all

other

characters

except

a

carriage

return

or

another

quotation

mark

are

accepted

as

part

of

the

current

data

element.

46

EXAMPLES:

To

forceaquotation

mark

into

a data

element

going

toafile,

appendaCHR$(34)

to

the

start

of

the

data

element.

For

example:

PRINT#2,CHR$(34)

+

"DOE,

JOHN"

or

PRINT#2,CHR$(34);"DOE,

JOHN"

If

you

do

this

often,

some

space

and

time

may

be

saved

by

previously

definingavariable

as

equal

to

CHR$(34)

as

we

did

earlier

with

CHR$(13):

20QT$=CHR$(34)

400

PRINT#5,QT$+NAME$

In

each

case,

the

added

quotation

mark

will

be

stripped

from

the

data

by

the

INPUT

or

INPUT#

statement,

but

the

comma

or

colon^vill

remain

part

of

the

data.

NUMERIC

DATA

STORAGE

ON

DISKETTE

Up

to

this

point

we

have

discussed

string

data

storage,

now

let's

look

at

numeric

storage.

Inside

the

computer,

the

space

occupied

byanumeric

variable

depends

only

on

its

type.

Simple

numeric

variables

use

seven

bytes

(character

locations)

of

memory.

Real

array

variables

use

five

bytes

per

array

element,

and

integer array

elements

use

two

bytes

each.

In

contrast,

whenanumeric

variable

or

any

type

is

written

toafile,

the

space

it

occupies

depends

entirely

on

its

length,

not

its

type.

This

is

because

numeric

data

is

written

toafile

in

the

form

ofastring,

as

if

the

STR$()

function

had

been

performed

on

it.

The

first

character

will

be

a

blank

space

if

the

number

is

positive,

andaminus

sign

(-)if

the

number

is

negative.

Then

comes

the

number,

digit-by-digit.

The

last

character

isacursor

right

character.

This

format

allows

the

disk

data

to

be

read

back

intoastring

or

numeric

variable

later.

It

is,

however,

wasteful

of

disk

space,

and

it

can

be

difficult

to

anticipate

the

space

required

by

numbers

of

unknown

length.

For

this

reason,

some

programs

convert

all

numeric

variables

into

strings

before

writing

them

to

diskette,

and

use

string

functions

to

remove

any

unneeded

characters

in

advance.

Doing

so

still

allows

47

those

data

elements

to

be

read

back

intoanumeric

variable

by

INPUT#

later,

although

file

data

errors

may

be

avoided

by

reading

all

data

in

as

strings,

and

converting

to

numbers

using

the

VAL

()

function

after

the

information

is

inside

the

computer.

For

example,

"N$=RIGHT$(STR$(N)J£N(STR$(N))-1)"

will

convertapositive

numberNintoastring

N$

without

the

usual

leading

space

for

its

numeric

sign.

Then

instead

of

writing

PRINT#5,N,

you

would

use

PRINT#5,N$.

READING

FILE

DATA:

USING

GET#

The

GET#

statement

retrieves

data

from

the

disk

drive,

one

character

atatime.

Like

the

similar

keyboard

GET

statement

in

BASIC,

it

only

accepts

a

single

character

intoaspecified

variable.

However,

unlike

the

GET

statement,

it

doesn't

just

fall

through

to

the

next

statement

if

there

is

no

data

to

be

gotten.

The

primary

use

of

GET#

is

to retrieve

from

diskette

any

data

that

cannot

be

read

into

an

INPUT#

statement,

either

because

it

is

too

long

to

fit

in

the

input

buffer

or

because

it

includes

troublesome

characters.

FORMAT

FOR

THE

GET#

STATEMENT:

GET#file#,variable

list

where

"file

#"

is

the

same

file

number

given

in

the

desired

file's

current

OPEN

statement,

and

'Variable

list"

is

one

or

more

valid

BASIC

variable

names.

If

more

than

one

data

element

is

to

be

input

by

a

particular

GET#

statement,

each

variable

name

must

be

separated

from

others

byacomma.

In

practice,

you

will

almost

never

seeaGET

or

GET#

statement

containing

more

than

one

variable

name.

If

more

than

one

character

is

needed,aloop

is

used

rather

than

additional

variables.

Also

as

in

the

INPUT#

statement,

it

is

safer to

use

string

variables

when

the

file

to

be

read

might

containanon-numeric

character.

Data

inaGET#

statement

comes

in

byte-by-byte,

including

such

normally

invisible

characters

as

the

Carriage

Return,

and

the

various

cursor

controls.

All

but

one

will

be

read

properly.

The

exception

is

CHR$(0),

the

ASCII

Null

character.

It

is

different

from

an

empty

string

(one

of

the

form

A$=""),

even

though

empty

strings

are

often

re

ferred

to

as

null

strings.

Unfortunately,

inaGET#

statement,

CHR$(0)

is

converted

into

an

empty

string.

The

cure

is

to

test

for

an

empty

string

afteraGET#,

and

replace

any

that

are

found

with

CHR$(0)

instead.

The

first

example

below

illustrates

the

method.

48

EXAMPLES:

To

readafile

that

may

containaCHR$(0),

such

asamachine

language

program

file,

you

could

correct

any

CHR$(0)

bytes

with

1100

GET#3,G$:IF

G$=""

THEN

G$=CHR$(0)

If

an

overlong

string

has

managed

to

be

recorded

inafile,

it

may

be

read

back

safely

into

the

computer

with

GET#,

usingaloop

such

as

this

3300

B$=""

,

3310

GET#1

A$

3320

IF

A$OCHR$(13)

THEN

B$=B$+A$:GOTO

3310

The

limit

for

suchatechnique

is

255

characters.

It

will

ignore

CHR$(0),

but

that

may

be

an

advantage

in

building

a

text

string.

If

CHR$

(0)

is

required

in

the

file,

then

add

the

following

line:

3315

If

A$=""

THEN

A$=CHR$(0T

GET#

may

be

useful

in

recovering

damaged

files,

or

files

with

unknown

contents.

The

BASIC

reserved

variable

ST

(the

file

STatus

variable)

can

be

used

to

indicate

when

all

ofaproperly

closed

file

has

been

read.

500

GET#2,S$

510

SU=ST:REM

REMEMBER

FILE

STATUS

520

PRINT

S$;

530

IF

SU=0

THEN

500.REM

IF

THERE'S

MORE

TO

BE

READ

540

IF

SUO64

THEN

PRINT

"STATUS

ERROR:

ST=";SU

Copying

ST

into

SU

is

often

an

unneccessary

precaution,

but

must

be

done

if

any

other

file-handling

statement

appears

between

the

one

which

read

from

the

file

and

the

one

that

loops

back

to

read

again.

For

example,

it

would

be

required

if

line

520

was

changed

to

520

PRINT#1,S$;

Otherwise,

the

file

status

checked

in

line

530

would

be

that

of

the

write

file,

not

the

read

file.

The

following

table

applies

to

single

errors

oracombination

of

two

or

more

errors.

49

POSSIBLE

VALUES

OF

THE

FILE

STATUS

VARIABLE

IFST

=

0

1

2

4

8

16

32

64

128

"ST,"

AND

THEIR

MEANINGS

THEN

All

is

OK

Receiving

device

was

not

available

(time

out

on

talker)

Transmitting device

was

not

available

(time

out

on

listener)

Cassette

data

file

block

was

too

short

Cassette

data

file

block

was

too

long

Unrecoverable

read

error

from

cassette,

verify

error

Cassette

checksum

error—one

or

more

faulty

characters

were

read

End

of

file

reached

(EOI

detected)

Device

not

present,

or

end

of

tape

mark

found

on

cassette

50

DEMONSTRATIONOFSEQUENTIAL

FILES

(BASIC

7.0)

Use

the

following

program

for

your

first

experiments

with

sequen

tial files.

Comments

have

been

addedtohelp

you

better

understand

it.

150CR$=CHR$(13)

170

PRINT

CHR$(147):REM

CLEAR

SCREEN

190

PRINT

"**

WRITEAFILE

**"

210

PRINT

220

DOPEN

#2,"@SEQ

FILE",W

230

GOSUB

500

240

PRINT'ENTERAWORD,

THENANUMBER"

250

PRINT'OR

'END,0'TOSTOP"

260

PRINT

270

INPUT

A$,B

280

PRINT#2A$;CR$;B

290

GOSUB

500

300IFA$O"END"

THEN

270

310

PRINT

320

DCLOSE

#2

340

PRINT

"**

READ SAME

FILE

BACK

**"

360

PRINT

370

DOPEN

#2,"SEQ

FILE"

380

GOSUB

500

390

INPUT#2A$3

400RS=ST

410

GOSUB

500

420

PRINT

A$,B

430IFRS=0

THEN

390

440IFRSO64

THEN

PRINT"STATUS

=

";RS

450

DCLOSE

#2

460

END

480

REM**ERROR

CHECK

S/R

**

500IFDS>0

THEN

PRINT

DS$:STOP

510

RETURN

Makeacarriage

return

variable

Open

demo

file

with

replace

Check

for

disk

errors

Acceptastring&number

from

keyboard

Write

themtothe

disk

file

Until

finished

Tidy

up

Reopen

same

file

for

reading

Read

next

string&number

from

file

Remember

file

status

Display

file

contents

until

done,

unless

there'sanerror

Then

quit

51

CHAPTERS

RELATIVE

DATA

FILES

Sequential

files

are

very

useful

when

you're

just

working

with

a

continuous stream

of

data—i.e.,

information

that

can

be

fead

or

written

all

at

once.

However,

sequential

files

are

not

useful

in

some

situations.

For

example,

after

writingalarge

list

of

mail

labels,

you

wouldn't

want

to

have

to

reread

the

entire

list

each

time

you

need

a

person's

record.

Instead,

you need

some

kind

of

random

access,

a

way

to

get

toaparticular

label in

your

file

without

having

to

read

through

all

those

preceding

it.

As

an

example,

comparearecord

turntable

withacassette

re

corder.

You

have

to

listen

toacassette

from

beginning

to

end,

but

a

turntable

needle

can

be

picked

up

at

any

time,

and

instantly

moved

to

any

spot

on

the

record.

Your

disk

drive

works

likeaturntable

in

that

respect.

In

this

chapter

you

will

learn

aboutatype

of

file

that

reflects

this

flexibility.

Actually,

two

different

types

of

random

access

files

may

be

used

on

Commodore

disk

drives:

relative

files

and

random

files.

Relative

files

are

much

more

convenient

for

most

data

handling

operations,

but

true

random

access

file

commands

are

also

available

to

advanced

users,

and

will

be

discussed

in

the

next

chapter.

FILES,

RECORDS,

AND

FIELDS

When

learning

about

sequential

files,

you

did

not

worry

about

the

organization

of

data

withinafile,

so

long

as

the

variables

used

to

write

the

file

matched

up

properly with

those

which

read

it

back

into

the

computer.

But

in

order

for

relative

access

to

work,

you

needamore

structured

and

predictable

environment

for

our

data.

The

structure

you

will

use

is

similar

to

that

used

in

the

traditional

filing

cabinet.

Inatraditional

office,

all

customer

records

might

be

kept

inasingle

file

cabinet.

Within

this

file,

each

customer

has

a

personal

record

inafile

folder

with

their

name

on

it,

that

contains

everything

the

office

knows

about

that

person.

Likewise,

within

each

file

folder,

there

may

be

many

small

slips

of

paper,

each

containing

one

bit

of

information

about

that

customer,

such

asahome

phone

number

or

the

date

of

the

most

recent purchase.

Inacomputerized

office,

the

file

cabinet

is

gone,

but

the

concept

ofafile

containing

all

the

information

aboutagroup

or

topic

remains.

The

file

folders

are

gone

too,

but

the

notion

of

subdividing

the

file

into

individual

records

remains.

The

slips

of

paper

within

the

personal

53

records

are

gone

too,

replaced

by

subdivisions

within

the

records,

called

fields.

Each

field

is

large

enough

to

hold

one

piece

of

informa

tion

about

one

record

in

the

file.

Thus, within

each

file

there

are

many

records,

and

within

each

record

there are

typically

many

fields.

A

relative

file

takes

care

of

organizing

the

records

for

you,

num

bering

them

from1to

the

highest

record

number,

by

ones,

but

the

fields

are

up

to

you

to

organize.

Each

record

will

be

of

the

same

size,

but

the

1581

won't

insist

that

they

all

be

divided

the

same

way.

On

the

other

hand,

they

normally

will

be

subdivided

the

same

way,

and

if

it

can

be

known

in

advance

exactly

where

each

field

starts

within

each

record,

there

are

even

fast

ways

to

accessadesired

field

within

a

record

without

reading

through

the

other

fields.

As

all

of

this

implies,

access

speed

isaprimary

reason

for

putting

information

intoarelative

disk

file.

Some

well-written

relative

file

programs

are

able

to

find

and

read

the

record

of

one

desired

person

out

of a

thousand

in

under

15

seconds,

a

feat

no

sequential

file

program

could

match.

FILE

LIMITS

With

relative

files,

you

don't

have

to

worry

about

exactly

where

on

the

diskette's

surface

a

given

record

will

be

stored,

or

whether

it

will

fit

properly

within

the

current

disk

sector,

or

need

to

be

extended

onto

the

next

available

sector.

DOS

takes

care

of

all

that

for

you.

All

you

need

to

do

is

specify

how

long

each

record

is,

in

bytes,

and

how

many

records

you

will

need.

DOS

will

do

the

rest,

and

organize

things

in

suchaway

that

it

can

quickly

find

any

record

in

the

file,

as

soon

as

it

is

given

the

record

number

(ordinal

position

within

the

file).

The

only

limit that

will

concern

you

is

that

each

record

must be

the

same

size,

and

the

record

length

you

choose

must

be

between

2

and

254

characters.

Naturally

the

entire

file

also

has

to

fit

on

your

diskette,

along

with

any

other

existing

file(s).

CREATINGARELATIVE

FILE

Whenarelative

file

is

to

be

used

for

the

first

time,

its

Open

statement

will

create

the

file;

after

that,

the

Open

statement

is

used

to

reopen

the

file

for

both

reading

and

writing.

FORMAT

STATEMENT

TO

OPENARELATIVE

FILE:

BASIC

7.0:

DOPEN#file

#,

"file

name",

L record

length

[JDdrive

#]

[,Udevice

#]

BASIC

2.0:

OPEN

file

#,

device

#,

channel

#,

"drive

#:

file

name,

L,"+CHR$

(record

length)

54

where

"file

#"

is

the

file

number,

normally

an

integer

between1and

127;

"device

#"

is

the

device

number

to

be

used,

normally

8

on

the

1581;

"channel

#"

selects

a

particular

channel

along

which

communi

cations

for

this

file

can

take

place,

normally

between2and

14;

"drive

#"

is

the

drive

number,

always0on

the

1581;

and

"file

name"

is

the

name

of

the

file,

withamaximum

length

of

16

characters.

Pattern

matching

characters

are

allowed

in

the

name

when

accessing

an

existing

file,

but not

when

creating a

new

one.

The

record

length

is

the

size

of

each

record

within

the

file

in

bytes

used,

including

carriage

returns,

quotation

marks

and

other

special

characters.

-NOTE

•

Do

not

precede

the

file

name

(in

BASIC

7.0)

or

the

drive

number

(in

BASIC

2.0)

with

the

"at"

sign

(@);

there

is

no

reason

to

replacearelative

file.

•Lrecord

length

(in

BASIC

7.0)

or,L,"+CHR$(rec-

ord

length)

(in

BASIC

2.0)

is

only

required

whenarelative

file

is

first

created,

though

it

may

be

used

later,

so long

as

the

record

length

is

the

same

as

when

the

file

was

first

created.

Since

relative

files

may

be

read

from

or

written

to

alternately

and

with

equal

ease,

there

is

no

need

to

specify

Read

or

Write

mode

when

openingarelative

file.

•

"file

#",

"device

#"

and

"channel

#"

must

be

valid

numeric

constants,

variables

or

expressions.

The

rest

of

the

command

must

beavalid

string

literal,

variable

or

expres

sion.

In

BASIC

7.0

DOPEN,

wheneveravariable

or

expres

sion

is

used

asafile

name

it

must

be

surrounded

by

parentheses.

EXAMPLES:

To

create

or

reopenarelative

file

named

"GRADES",

of

record

length

100,

use:

N

BASIC

7.0:

DOPEN#2,"GRADES",L100,D0,U8

BASIC

2.0:

OPEN

2,8,2,"GRADES,L,"

+

CHR$(100)

To

reopen

an

unknown

relative

file

of

the

user's

choice

that

has

already

been

created,

use:

BASIC

7.0:

200

INPUT"WHICH

FILE";FI$

210

DOPEN#5,(FI$),D0,U8

55

BASIC

2.0:

200

INPUT'WHICH

FILE";FI$

210

OPEN

5,8,5,FI$

USING

RELATIVE

FILES:

RECORD#

COMMAND

Whenarelative

file

is

opened

for

the

first

time,

it

is

not

quite

ready

for

use.

Both

to

save

time

when

using

the

file

later,

and

to

assure

that

the

file

will

work

reliably,

it

is

necessary

to

create

several

records

before

closing

the

file

for

the

first

time.

At a

minimum,

enough

records

to

fill

more

than

two

disk

sectors

(512

bytes)

should

be

written.

In

practice,

most

programs

go

ahead

and

create

as

many

records

as

the

program

is

eventually

expected

to

use.

That

approach

has

the

additional

benefit

of avoiding

such

problems

as

running

out

of

room

on

the

diskette

before

the

entire

file

is

completed.

If

you

simply

begin

writing

data

toajust-opened

relative

file,

it

will

act

much

likeasequential

file,

putting

the

data

elements

written

by

the

first

PRINT#

statement

in

Record

#1,

those

written

by

the

second

PRINT#

statement

in

record

#2

and

so

on.

This

means

each

record

must

be

written

byasingle

PRINT#

statement,

using

embed

ded

carriage

returns

within

the

data

to

separate

fields

that

will

be

read

in

via

one

or

more

INPUT#

statements

later.

However,

it

is

far

better

to

explicitly

specify

which

record

number

is

desired

viaaRECORD#

command

to

the

disk.

This

allows

you

to

access

records

in

any

desired

order,

hopping

anywhere

inafile

with

equal

ease.

FORMAT

FOR

THE

RECORD#

COMMAND:

BASIC

7.0:

RECORD#file

#,

record

number

[,offset]

BASIC

2.0:

PRINT#15,

"P"+CHR$

(channel#+

96)+CHR$

(<record

#)+CHR$(>record

#)+CHR$(offset)

where

"file

#"

is

the

file#specified

in

the

current

DOPEN

statement

for

the

specified

file,

"record

number"

is

the

desired

record

number,

"channel

#"

is

the

channel

number

specified

in

the

current

OPEN

statement

for

the

specified

file,

"<record

#"

is

the

low

byte

of

the

desired

record

number,

expressed

asatwo-byte

integer,

">record

#"

is

the

high

byte

of

the

desired

record

number,

and

an

optional

"offset"

value,

if

present,

is

the

byte

within

the

record

at

whichafollowing

Read

or

Write

should

begin.

To

fully

understand

this

command,

you

must

understand

how

most

integers

are

stored

in

computers

based

on

the

6502

and

related

microprocessors.

In

the

binary

arithmetic

used

by

the

microprocessor,

it

is

possible

to

express

any

unsigned

integer

from

0-255

inasingle

56

byte.

It

is

also

possible

to

store

any

unsigned

integer

from

0-65535

in

two

bytes,

with

one

byte

holding

the

part

of

the

number

that

is

evenly

divisible

by

256,

and

any

remainder

in

the

other

byte.

In

machine

language,

such

numbers

are

written

backwards,

with

the

low-order

byte

(the

remainder)

first,

followed

by

the

high-order

byte.

In

assem

bly

language

programs

written

with

the

Commodore

Assembler,

the

low

part

ofatwo-byte

number

is

indicated

by

preceding

its

label

with

the

less-than

character

(<).

Similarly,

the

high

part

of

the

number

is

indicated

by

greater-than

(>).

-NOTE

To

avoid

the

remote

possibility

of

corrupting

relative

file

data,

it

is

necessary

to

give

RECORD#

command

once

before

the

Read

or

Write

access

and

once

after

the

access.

Although

this

is

not

necessary

for

the

1581,

other

Com

modore

drives

require

it.

To

make

your

programs

compati

ble

with

those

other

drives,

it'sagood

idea

to

use

it.

EXAMPLES:

In

BASIC

7.0,

to

position

the

record

pointer

for

file

#2

to

record

number

3,

type:

RECORD#2,3

In

BASIC

2.0,

to

position

the

recQrd

pointer

for

channel

#2

to

record

number

3,

type:

PRINT

#15,

"P"

+CHR$(98)

+CHR$(3)+CHR$(0)

The

CHR$(98)

comes

from

adding

the

constant

(96)

to

the

desired

channel

number

(2).

(96+2=98)

Although

the

command

appears

to

work

even

when

96

is

not

added

to

the

channel

number,

the

constant

is

normally

added

to

maintain

compatibility

with

the

way

RECORD#

works

in

BASIC

7.0.

Since3is

less

than

256,

the

high

byte

of

its

binary

representation

is

0,

and

the

entire

value

fits

into

the

low

byte.

Since

you

want

to

read

or

write

from

the

beginning

of

the

record,

no

offset

value

is

needed.

Since

these

calculations

quickly

become

tedious,

most

programs

are

written

to

do

them

for

you.

Here

is

an

example

ofaprogram

which

57

inputsarecord

number

and

converts

it

into

the

required

low-byte/

high-byte

form:

450

INPUTRECORD

NUMBER

DESIRED";RE

460

IF

RE<1

OR

RE>65535

THEN

450

470RH=INT(RE/256)

480RL=RE-256*RH

490

PRINT#15,

"P"

+CHR$(98)+CHR$(RL)+CHR$(RH)

Assuming

RH

and

RL

are

calculated

as

in

the

previous

example,

programs

may

also

use

variables

for

the

channel,

record,

and

offset

required:

570

INPUT

"CHANNEL,

RECORD,&OFFSET

DESIRED";CH,RE,OF

630

PRINT#15,

"P"

+

CHR$

(CH+96)+CHR$(RL)+CHR$(RH)+CHR$(OF)

COMPLETING

RELATIVE

FILE

CREATION

Now

that

you

have

learned

how

to

use

both

the

Open

and

Re-

cord#

commands,

you

are

almost

ready

to

properly

createarelative

file.

The

only

additional

fact

you

need

to

know

is

that

CHR$(255)

is

a

special

character

inarelative

file.

It

is

the

character

used

by

the

DOS

to

fill

relative

records

as

they

are

created,

beforeaprogram

fills

them

with

other

information.

Thus,

if

you

want

to

write

the

last

record,

you

expect

to

need

in

your

file

with

dummy

data

that

will

not

interfere

with

your

later

work,

CHR$(255)

is

the

obvious

choice.

Here

is

how

it

works

in

an

actual

program

which you

may

copy

for

use

in

your

own

relative

file

programs.

BASIC

2.0:

1020

OPEN

15,8,15

Open

command

channel

1380

INPUT'ENTER

RELATIVE

FILE

NAME";FI$

Select

file

parameters

1390

INPUT'ENTER

MAX.#OF

RECORDS";NR

1400

INPUT'ENTER

RECORD

LENGTH";RL

1410

OPEN

l,8,2,"0:"

+

FI$+"JL,"+CHR$(RL)

Begintocreate

desired

file

1420

GOSUB

59990

Check

for

disk errors

1430RH=

INT(NR/256)

Calculate

length

values

144ORL=NR-256*RH

1450

PRINT#15,"P"

+

CHR$(96+2)

+

CHR$(RL)+CHR$(RH)

Positiontolast

record

number

1455

PRINT#15,"P"

+

CHR$(96+2)

+

Re-position

for

safety

CHR$(RL)+CHR$(RH)

1460

GOSUB

59990

1470

PRINT#1

,CHR$(255);

Send

default

character

to

it

58

1480

GOSUB

59990

1500

GOSUB

59990

1510

CLOSE

1

1520

GOSUB

59990

9980

CLOSE

15

9990

END

59980

REM

CHECK

DISK

SUBROUTINE

59990

INPUT#15,EN,EM$,ET,ES

60000IFEN>1

AND EN<>50

THEN

PRINT

EN,EM$,ET,ES:STOP

60010

RETURN

BASIC

7.0:

1380

INPUT'ENTER

RELATIVE

FILE

NAME";FI$

1390

INPUT'ENTER

MAX.#OF

RECORDS";NR

1400

INPUT'ENTER

RECORD

LENGTH";RL

1410

DOPEN#1,(FI$),L(RL)

1420

GOSUB

60000

1450

RECORD#1,(NR)

1455

RECORD#1,(NR)

1460

GOSUB

60000

1470

PRINT#1,CHR$(255);

1480

GOSUB

60000

1500

GOSUB

60000

1510

CLOSE

1

1520

GOSUB

60000

9980

CLOSE

15

9990

END

59980

REM

CHECK

DISK

SUBROUTINE

60000IFDS>1

AND

DSO50

THEN

PRINT

DS,DS$:STOP

60010

RETURN

Now

the

file

canbesafely

closed

And

the

command

chan

nel

closed

Beforeweend

the

pro

gram

Error

check

subroutine

Ignore

"RECORD

NOT

PRESENT11

Select

file

parameters

Begintocreate

desired

file

Check

for

disk

errors

Calculate

length

values

Positiontolast

record

number

Send

default

character

to

it

Now

the

file

canbesafely

closed

And

the

command

chan

nel

closed

Beforeweend

the

pro

gram

Error

check

subroutine

Ignore

"RECORD

NOT

PRESENT'1

Two

lines

require

additional

explanation.

When

line

1470

executes,

the

disk

drive

will

operate

for

up

to

several

minutes,

creating

all

the

re

cords

in

the

file,

up

to

the

maximum

record

number

you

selected

in

line

1390.

This

is

normal,

and

only

needs

to

be

done

once.

During

the

process

you

may

hear

the

drive

motor

turning

and

an

occasional

slight

click

as

the

head

steps

from

track

to

track.

Second,

line

60000

above

is

59

different

from

the

equivalent

line

in

the

error

check

subroutine

given

earlier.

Here

disk

error

number

50

is

specifically

ignored,

because

it

will

be

generated

when

the

error

channel

is

checked

in

line

1460.

Ig

nore

it

because

not

havingarequested

record

would

only

be

an

error

if

that

record

had

been

created

previously.

EXPANDINGARELATIVE

FILE

If

you

underestimate

your

needs

and

want

to

expandarelative

file

later,

simply

request

the

record

number

you

need,

even

if

it

doesn't

currently

exist

in

the

file.

If

there

is

no

such

record

yet,

DOS

will

create

it

as

soon

as

you

try

to

write

information

in

it,

and

also

automatically

create

any

other

missing

records

below

it

in

number.

When

the

first

record

beyond

the

current

end

record

is

written,

the

DOS

returns

"50,

RECORD

NOT

PRESENT"

error.

This

is

expected

and

correct.

WRITING

RELATIVE

FILE

DATA

The

commands

used

to

read

and

write

relative

file

data

are the

same

PRINT#,

INPUT#,

and

GET#

commands

used

in

the

preceding

chapter

on

Sequential

files.

Each

command

is

used

as

described

there.

However,

some

aspects

of

relative

file

access

do

differ

from

sequential

file

programming,

and

we

will

cover

those

differences

here.

DESIGNINGARELATIVE

RECORD

As

stated

earlier

in

this

chapter,

each

relative

record

hasafixed

length,

including

all

special

characters.

Within

that

fixed

length,

there

are

two

popular

ways

to

organize

various

individual

fields

of

informa

tion.

One

is

free-format,

with

individual

fields

varying

in

length

from

record

to

record,

and

each

field

separated

from

the

next

byacarriage

return

character

(each

of

which

does

take

up

one

character

space

in

the

record).

The

other

approach

is

to

use

fixed-length

fields,

that

may

or

may

not

be

separated

by

carriage

returns.

If

fixed

length

fields

are

not

all

separated

by

carriage

returns,

you

will

either

need

to

be

sure

a

carriage

return

is

included

within

each

88-character

portion

of

the

record

(88

is

for

BASIC

2,160

is

for

BASIC

7).

If

this

is

not

done,

you

will

have

to

use

the

GET#

command

to

read

the

record,

atasignificant

cost

in

speed.

Since

each

relative

record

is

most

easily

written

byasingle

PRINT#

statement,

the

recommended

approach

is

to

buildacopy

of

the

current

record

in

memory

before

writing

it

to

disk.

It

can

be

collected

intoasingle

string

variable

with

the

help

of

BASIC'S

many

60

string-handling

functions,

and

then

all

written

out

at

once

from

that

variable.

Here

is

an

example.

If

we

are

writing

a

4-line

mail

label,

consist

ing

of4fields

named

"NAME,"

"STREET,"

"CITY&STATE,"

and

"ZIP

CODE,"

and

haveatotal

record

size

of

87

characters,

we

can

organize

it

in

either

of

two

ways:

WITH

FIXED

LENGTH

FIELDS

Field

Name

NAME

STREET

CITY&STATE

ZIP

CODE

Total

length

Length

27

characters

27

characters

23

characters

10

characters

87

characters

WITH

VARIABLE

LENGTH

FIELDS

Field

Name

NAME

STREET

CITY&STATE

ZIP

CODE

Potential

length

Edited

length

Length

31

characters

31

characters

26

characters

11

characters

99

characters

87

characters

With

fixed

length

records,

the

field

lengths

add

up

to

exactly

the

record

length.

Since

the

total

length

is

just

within

the

Input

buffer

size

limitation,

no

carriage

return

characters

are

needed.

With

variable

length

records,

you

can

take

advantage

of

the

variability

of

actual

address

lengths.

While

one

name

contains

27

letters,

another

may

have

only

15,

and

the

same

variability

exists

in

street

and

city

lengths.

Although

variable

length

records

lose

one

character

per

field

for

carriage

returns,

they

can

take

advantage

of

the

difference

between

maximum

field

length

and

average

field

length.

A

program

that

uses

variable

record

lengths

must

calculate

the

total

length

of

each

record

as

it

is

entered,

to

be

sure

the

total

of

all

fields

doesn't

exceed

the

space

available.

WRITING

THE

RECORD

Here

is

an

example

of

program

lines

to

enter

variable

length

fields

for

the

above

file

design,

build

them

intoasingle

string,

and

send

them

to

record

number

RE

in

file

number3(assumed

to

be

a

relative

file

that

uses

channel

number

3).

BASIC

7.0:

100

INPUT'ENTER

RECORD

NUMBER";RE

110:

120

DOPEN#3,"MYRELFILE",L88

130CR$=CHR$(13)

140

INPUTNAME";

NA$

150IFLEN(A$)>30

THEN

140

160

INPUT'STREET";SA$

170IFLEN(SA$)>30

THEN

160

61

180

INPUTCITY&STATE";

CS$

190IFLEN(CS$)>25

THEN

180

200

INPIITZIP

CODE";ZP$

210IFLEN(ZP$)>10

THEN

200

220

DA$=NA$+CR$+SA$+CR$+CS$+CR$;ZP$

230IFLEN(DA$)<88

THEN

260

240

PRINT'RECORD

TOO

LONG"

250

GOTO

140

260:

270:

280

RECORD#3,(RE),1

290

IFDS=50THENPRINT#3,CHR$(255):GOSUB1000:GOTO280

300

GOSUB1000

310

PRINT#3,DA$

320

GOSUB1000

330

RECORD#3,(RE),1

340

GOSUB1000

350

DaOSE3:END

1000

IFDS<20

THEN

RETURN

1002:

1010

PRINTDS$:DCLOSE3:END

BASIC

2.0:

100

INPUT'ENTER

RECORD

NUMBER";RE

110

OPEN

15,8,15

120

OPEN3,8,3,UMYRELFILE,L,"

+

CHR$(88)

130CR$=CHR$(13)

140

INPUT'NAME";

NA$

150IFLEN(A$)>30

THEN

140

160

INPUrSTREET";SA$

170IFLEN(SA$)>30

THEN

160

180

INPUT"CITY&STATE";

CS$

190IFLEN(CS$)>25

THEN

180

200

INPUT"ZIP

CODE";ZP$

210IFLEN(ZP$)>10

THEN

200

220

DA$=NA$+CR$+SA$+CR$+CS$+CR$;ZP$

230IFLEN(DA$)<88

THEN

260

240

PRINT"RECORD

TOO

LONG"

250

GOTO

140

260RH=INT(RE/256)

270RL=RE-256*RH

280

PRINT#15,"P"

+

CHR$(96+3)+CHR$(RL)

+

CHR$(RH)+CHR$(1)

290

GOSUB1000:IFEN=

50THENPRINT#3,CHR$(255):GOSUB1000:GOTO280

300

GOSUB1000

310

PRINT#3,DA$

320

GOSUB1000

330

PRINT#15,<<P"

+

CHR$(96+3)+CHR$(RL)+CHR$(RH)+CHR$(1)

340

GOSUB1000

350

CLOSE3:CLOSE15:END

1000

INPUT#15,EN,EM$,ET,ES

1002IFEN<20

THEN

RETURN

1010

PRINTEM$:CLOSE3:CLOSE15:END

62

To

use

the

above

program

lines

for

the

version

with

fixed

length

fields,

we

would

alterafew

lines

as

follows:

BASIC

7.0:

100

INPUT'ENTER

RECORD

NUMBER";RE

110:

120

DOPEN#3,"MYRELFILE",L88

130

BL$="(27

shifted

space

chars)"

140

INPUT'NAME";

NA$

145LN=LEN(NA$)

150IFLEN>27

THEN

140

155

NA$=NA$+LEFT$(BL$,27

-

IN)

160

INPUT"STREET";SA$

165LN=LEN(SA$)

170IFLEN>27

THEN

160

175

SA$=SA$+LEFT$(BL$,27

-

LN)

180

INPUrCITY&STATE";

CS$

185LN=LEN(CS$)

190IFLEN>23

THEN

180

195

CS$=CS$+LEFT$(BL$,23

-

LN)

200

INPUTZIP

CODE";ZP$

205LN=LEN(ZP$)

210IFLN>10THEN200

215

ZP$=ZP$+LEFT$(BL$,10-LN)

220

DA$=NA$+SA$+CS$+ZP$

260:

270:

280

RECORD#3,(RE),1

290

IFDS=50THENPRINT#3,CHR$(255):GOSUB1000:GOTO280

300

GOSUB1000

310

PRINT#3,DA$

320

GOSUB1000

330

RECORD#3,(RE),1

340

GOSUB1000

350

DCLOSE#3:END

1000

IFDS<20

THEN

RETURN

1002:

1010

PRINT'ERROR:"DS$:DCLOSE#):END

BASIC

2.0:

100

INPUT'ENTER

RECORD

NUMBER";RE

110

OPEN

15,8,15

120

OPEN#3,8,3,"MYRELFILE>L,"

+

CHR$(88)

130

BL$="(27

shifted

space

chars)"

140

INPUT"NAME";

NA$

145LN=LEN(NA$)

15OIFLEN>27THEN14O

155

NA$=NA$+LEFT$(BL$,27

-

LN)

160

INPUT"STREET";SA$

165LN=LEN(SA$)

63

170IFLEN>27

THEN

160

175

SA$=SA$+LEFT$(BL$,27

-

LN)

180

INPUT'CITY&STATE";

CS$

185LN=LEN(CS$)

190IFLN>23THEN180

195

CS$=CS$+LEFT$(BL$,23

-

LN)

200

INPtTTZIP

CODE";ZP$

205LN=LEN(ZP$)

210IFLN>10THEN200

215

ZP$=ZP$+LEFT$(BL$,10

-

LN)

220

DA$=NA$+SA$+CS$+ZP$

260RH=INT(RE/256)

270RL=RE-256*RH

280

PRINT#15,"P"

+

CHR$(96+3)+CHR$(RL)+CHR$(RH)+CHR$(1)

290

GOSUB1000:IFEN=

50THENPRINT#3)CHR$(255):GOSUB1000:GOTO280

300

GOSUB1000

310

PRINT#3,DA$

320

GOSUB1000

330

PRINT#15,"P"

+

CHR$(96+3)+CHR$(RL)

+

CHR$(RH)+CHR$(1)

340

GOSUB1000

350

GOSUB1000:aOSE3:aOSE15:END

1000

INPUT#15,EN,EM$,ET,E

1002IFEN<20

THEN

RETURN

1010PRINT"ERROR;"EM$:aOSE3:aOSE15:END

If

field

contents

vary

in

length,

variable

field

lengths

are

often

preferable.

On

the

other

hand,

if

the

field

lengths

are

stable,

fixed

field

lengths

are

preferable.

Fixed

length

fields

are

also

required

if

you

want

to

use

die

optional

offset

parameter

of

the

RECORD#

command

to

point

ataparticular

byte

withinarecord.

However,

when

any

part

of

a

record

is

written,

DOS

overwrites

any

remaining

spaces

in

the

record.

Thus,

if

you

must

use

the

offset

option,

never

update

any

field

inarecord

other

than

the

last

one

unless

all

succeeding

fields

will

also

be

updated

from

memory

later.

The

above

programs

are

careful

to

match

record

lengths

exactly

to

the

space

available.

Programs

that

don't

do

so

will

discover

that

DOS

pads

short

records

out

to

full

size

with

fill

characters,

and

truncates

overlong

records

to

fill

only

their

allotted

space.

When

a

record

is

truncated,

DOS

will

indicate

error

51,

"RECORD

OVER

FLOW,"

but

short

records

will

be

accepted

withoutaDOS

error

message.

READINGARELATIVE

RECORD

Oncearelative

record

has

been

written

properly

to

diskette,

reading

it

back

into

computer

memory

is

fairly

simple,

but

the

proce

dure

again

varies,

depending

on

whether

it

uses

fixed

or

variable

length

fields.

Here

are

the

program

lines

needed

to

read

back

the

64

variable

fields

created

above

from

record

number

RE

in

file

and

channel

3:

BASIC

7.0:

10:

20

DOPEN#3,"MYRELFILE",L88

30

INPUT'ENTER

RECORD

NUMBERM;RE

40:

50:

60

RECORD#3,(RE),1

70

GOSUB1000

80

INPUT#3,NA$,SA$,CS$,ZP$

90

GOSUB1000

100

RECORD#3,(RE),1

110GOSUB1000

120

PRINTNA$:PRINTSA$

130

PRINTCS$:PRINTZP$

140

DCLOSE#3:END

1000

IFDS<20

THEN

RETURN

1002:

1010

PRINTUERROR:"DS$:DCLOSE#3:END

BASIC

2.0:

10

OPEN

15,8,15

20

OPEN3,8,3,ttMYRELFILE,L;'

+CIIR$(88)

30

INPUT

ENTER

RECORD

NUMBER";RE

40RH=INT(RE/256)

50RL=RE-256*RH

60

PRINT#15,4<P"

+CIIR$(96+3)+CI

IR$(RL)+CI

IR$(RII)+CIIR$(

1)

70

GOSUB1000

80

INPUT#3,NA$,SAJ,CS$,ZPS

90

GOSUB1000

110GOSUB1000

120

PRINTNA$:PRINTSA$

130

PRINTCS$:PRINTZP$

140

CLOSE3:CLOSE15:END

1000

INPUT#15,EN,EM$,ET,ES

1002IFEN<20

THEN

RETURN

1002

PRINTI4ERROR:1'EM$:CLOSE3:CLOSE15:END

READY.

65

Here

are

the

lines

needed

to

read

back

the

version

with

fixed

length

fields:

BASIC

7.0:

10:

20

DOPEN#3,"MYRELFBLE'%88

30

INPUT'ENTER

RECORD

NUMBER";RE

40:

50:

60

RECORD#3,(RE),1

70

GOSUB1000

80

INPUT#3,DA$

90

GOSUB1000

100

RECORD#3,(RE),1

110GOSUB1000

112NA$=LEFT$(DA$,27)

114

SA$=MID$(DA$,28,27)

116

CS$=MID$(DA$,55,23)

118

ZP$=RIGHT$(DA$,10)

120

PRINTNA$:PRINTSA$

130

PRINTCS$:PRINTZP$

140

DCLOSE#3:END

1000

IFDS<20

THEN

RETURN

1002:

1010

PRINT"ERROR:"DS$:DCLOSE#3:END

BASIC

2.0:

10

OPEN

15,8,15

20 OPEN3,8,3,"MYRELFILE,L"

4-

CHR$(88)

30

INPUT'ENTER

RECORD

NUMBER";RE

40RH=INT(RE/256)

50RL=RE-256*RH

60

PRINT#15/lP"

+

CHR$(96+3)+CHR$(RL)+CHR$(RH)+CHR$(1)

70

GOSUB1000

80

INPUT#3,DA$

90

GOSUB1000

100

PRINT#

15,"?"+CHR$(96+3)+CHR$(RL)+CHR$(RII)4-CIIR$(

1)

110GOSUB1000

112

NA$=LEFT$(DA$,27)

114

SA$=MID$(DA$,28,27)

116CS$=MID$(DA$,55,23)

118

ZP$=RIGHT$(DA$,10)

120

PRINTNA$:PRINTSA$

130

PRINTCS$:PRINTZP$

140

CLOSE3:CLOSE15:END

1000

INPUT#15,EN,EM$,ET,ES

1002IFEN<20

THEN

RETURN

1002

PRINTltERROR:"EM$:CLOSE3:CLOSE15:END

READY.

66

THE

VALUE

OF

INDEX

FILES

In

the

last

two

chapters

you

have

learned

how

to

use

sequential

and

relative

files

separately.

But

they

are

often

used

together,

with

the

sequential

file

used

to

keep

brief

records

of

which

name

in

the

relative

file

is

stored

in

each

record

number.

That

way

the

contents

of

the

sequential

file

can

be

read

intoastring

array

and

sorted

alphabetically.

After

sorting,

a

technique

known

asabinary

search

can

be

used

to

quickly

find

an

entered

name

in

the

array,

and

read

in

or

write

the

associated

record

in

the

relative

file.

Advanced

programs

can

maintain

two

or

more

such

index

files,

sorted

in

differing

ways

simultaneously.

67

CHAPTER

6

DIRECT

ACCESS

COMMANDS

Direct

access

commands

specify

individual

sectors

on

the

dis

kette,

reading

and

writing

information

entirely

under

your

direction.

This

gives

them

almost

complete

flexibility

in

data-handling

programs,

but

imposes

tremendous

responsibilities

on

the

programmer.

As

a

result,

they

are

normally

used

only

in

complex

commercial

programs

able

to

properly

organize

data

without

help

from

the

disk

drive

itself.

A

far

more

common

use

of

direct

access

commands

is

in

utility

programs

used

to

view

and

alter

parts

of

the

diskette

that

are

not

normally

seen

directly.

For

instance,

such

commands

can

be

used

to

change

the

name

ofadiskette

without

erasing

all

of

its

programs,

to

lockaprogram

so

it

can't

be

erased,

or

hide

your

name

inalocation

where

it

won't

be

expected.

OPENINGADATA

CHANNEL

FOR

DIRECT

ACCESS

When

working

with

direct

access

data,

you need

two

channels

open

to

the

disk:

the

command

channel

we've

used

throughout

the

book,

and

another

for

data.

The

command

channel

is

opened

with

the

usual

OPEN

15,8,15

or

equivalent.

A

direct

access

data

channel

is

opened

much

like

other

files,

except

that

the

pound

sign

(#),

option

ally

followed

byamemory

buffer

number,

is

used

asafile

name.

FORMAT

FOR

DIRECT

ACCESS

FILE

OPEN

STATEMENTS:

OPEN

file

#,device

#,

channel

#,

"#buffer

#"

where

"file

#"

is

the

file

number,

"device

#"

is

the

disk's

device

num

ber,

normally

8;

"channel

#"

is

the

channel

number,anumber

be

tween2and

14

not

used

by

other

files

open

at

the

same

time;

and

"buffer

#,"

if

present,

isa0,1,

2,

3,

4,

5,

or

6,

specifying

the

memory

buffer

within

the

1581

to

use

for

this

file's

data.

EXAMPLES:

To

specify

which

disk

buffer

to

use:

OPEN

4,8,4,"#2"

-

If

you

don't

specify

which

to

use

(OPEN

5,8,5,"#"),

the

1581

selects

one.

69

BLOCK-READ

The

purpose

ofaBLOCK-READ

is

to

load

the

contents

ofaspeci

fied

sector

intoafile

buffer.

Although

the

BLOCK-READ

command

(B-

R)

is

still

part

of

the

DOS

command

set,

it

is

nearly

always

replaced

by

the

Ul

command

(See

Chapter

6).

FORMAT

FOR THE

BLOCK-READ

COMMAND:

PRINT#15,

"Ul";

channel

#;

drive

#;

track

#;

sector

#

where

"channel

#"

is

the

channel

number

specified

when

the

file

into

which

the

block

will

be

read

was

opened,

"drive

#"

is

the

drive

num

ber,

and

"track

#"

and

"sector

#"

are

respectively

the

track

and

sector

numbers

containing

the

desired

block

of

data

to

be

read

into

the

file

buffer.

ALTERNATE

FORMATS:

PRINT#15,"Ul:"channel

#;drive

#;track

#;sector

#

PRINT#15,"UA:"channel

#;drive

#;track

#;sector

#

PRINT#15,"Ul:channel

#,drive

#,track

#,sector

#"

EXAMPLE:

Here

isacomplete

program

to

readasector

into

disk

memory

us

ing

Ul,

and

from

there

into

computer

memory

via

GET#.

(Ifacarriage

return

will

appear

at

least

once

in

every

88

characters

of

data,

INPUT#

may

be

used

in

place

of

GET#).

110

MB=7936:REM

$1FOO

Defineamemory

buffer.

120

INPUT"TRACK

TO

READ";T

Selectatrack

130

INPUrSECTOR

TO

READ";S

and

sector.

140

OPEN

15,8,15

Open

command

channel.

150

OPEN

5,8,5,"#"

Open

direct

access

channel.

160

PRINT#15,"Ul";5;0;T;S

Read

sector

into

disk

buffer.

170

FORI=

MB

TO

MB+255

Usealoop

to

180

GET#5AWF

A$="

"

copy

disk

buffer.

THEN

A$=CHR$(0)

into

computer

memory.

190

POKE

IASC(A$)

Tidy

up

after.

200

NEXT

210

CLOSE

5:CLOSE

15

220

END

70

As

the

loop

progresses,

the

contents

of

the

specified

track

and

sector

are

copied

into

computer

memory,

beginning

at

the

address

set

by

variable

MB

in

line

160,

and

may

be

examined

and

altered

there.

The

DOS

always

checks

that

the

track

and

sector

parameters

of

the

BLOCK-READ

command

are

within

the

proper

range.

If

they're

not,

a

"66

ILLEGAL

TRACK

AND

SECTOR"

error

occurs.

In

certain

instances

it

might

be

necessary

to

accessatrack

and

sector

that

are

not

within

what

the

DOS

considers

the

proper

bounds.

This

isaspecial

case

and,

un

less

absolutely

necessary,

should

be

avoided.

Nonetheless, there

is

a

command

identical

in

function

to

"Ul"

that

doesn't

check

to

see

if

the

track

and

sector

parameters

are.

within

bounds

before

attempting

to

read

it.

Its

format

is:

PRINT#15,"B-_";channel

#;track

#;sector

#

(The

character

following

the

B-

isashifted

R.)

or

PRINT#15,"B-";CHR$(210);channel

#;track

#;sector

#

BLOCK-WRITE

The

purpose

ofaBLOCK-WRITE

is

to

save

the

contents

ofafile

buffer

intoaspecified

sector.

It

is

thus

the

reverse

of

the

BLOCK-READ

command.

Although

the

BLOCK-WRITE

command

(B-W)

is

still

part

of

the

DOS

command

set,

it

is

nearly

always

replaced

by

the

U2

com

mand.

FORMAT FOR

THE

BLOCK-WRITE

COMMAND:

PRINT#15,"U2";channel

#;drive

#;track

#;sector

#

where

"channel

#"

is

the

channel

number

specified

when

the

file

into

which

the

block

will

be

read

was

opened;

"drive

#"

is

the

drive

number;

and

"track

#"

and

"sector

#"

are

respectively

the

track

and

sector

numbers

that

should

receive

the

block

of

data

being

saved

from

the

file

buffer.

ALTERNATE

FORMATS:

PRINT#15,"U2:"channel

#;drive

#;track

#;sector

#

PRINT#15,"UB:"channel

#;drive

#;track

#;sector

#

PRINT#15,"U2:channel

#,drive

#,track

#,sector

#"

71

EXAMPLES:

To

restore

track

40,

sector

3 of

the

directory

from

the

disk

buffer

filled

byaBLOCK-READ,

use:

PRINT#15,"U2";5;0;40;3

You'll

return

to

this

example

on

the

next

page,

after

you

learn

to

alter

the

directory

inauseful

way.

You

can

also

useaBLOCK-WRITE

to

write a

name

in

Track

1,

Sector

1,ararely-used

sector.

This

can

be

used

asaway

of

marking

a

diskette

as

belonging

to

you.

Here

isaprogram

to

do

it,

using

the

alternate

form

of

the

BLOCK-WRITE

command:

110

INPUT"YOUR

NAME";NA$

Enteraname.

120

OPEN

15,8,15

Open

command

channel.

130

OPEN

4,8,4,"#"

Open

direct

access

channel

140

PRINT#4,NA$

Write

name

to

buffer.

150

PRINT#15,"U2";4;0;l;l

Write

buffer

to

Track

1,

160

CLOSE

4

Sector1of

diskette.

170

CLOSE

15

Tidy

up

after.

180

END

As

with

the

BLOCK-READ

command,

there

isaBLOCK-WRITE

com

mand

identical

in

function

to

"U2"

that

does

not

check

the

track

and

sector

parameters

for

valid

bounds

before

attempting

to

write

the

sector.

Its

format

is:

PRINT#15,"B-on;channel

#;drive

#;track

#;sector

#

(The

character

after

the

B-

isashifted

W.)

or

PRINT#15,uB-";CHR$(215);channel

#;track

#;sector

#

THE

ORIGINAL

BLOCK-READ

AND

BLOCK-WRITE

COMMANDS

Although

the

BLOCK-READ

and

BLOCK-WRITE

commands

are

nearly

always

replaced

by

the

Ul

and

U2

commands

respectively,

the

original

commands

can

still

be

used,

as

long

as

you

fully

understand

their

effects.

Unlike

Ul

and

U2,

B-R

and

B-W

allow

you

to

read

or

write

less

thanafull

sector.

In

the

case

of

B-R,

the

first

byte

of

the

selected

sector

is

used

to

set

the

buffer

pointer

(see

next

section),

and

deter-

72

mines

how

many

bytes

of

that

sector

are

read

intoadisk

memory

buffer.

A

program

may

check

to

be

sure

it

doesn't

attempt

to

read

past

the

end

of

data

actually

loaded

into

the

buffer,

by

watching

for

the

value

of

the

file

status

variable

ST

to

change

from0to

64.

When

the

buffer

is

written

back

to

diskette

by

B-W,

the

first

byte

written

is

the

current

value

of

the

buffer

pointer.

Only

that

many

bytes

are

written

into

the

specified

sector.

B-R

and

B-W

may

thus

be

useful

in

working

with

custom-designed

file

structures.

FORMAT

FOR

THE

ORIGINAL

BLOCK-READ

AND

BLOCK-WRITE

COMMANDS:

PRINT#15,"BLOCK-READ";channel

#;drive

#;track

#;sector

#

abbreviated

as:

PRINT#15,UB-R";channel

#;drive

#;track

#;sector

#

and

PRINT#15,uBLOCK-WRITE";channel

#;drive

#;track

#;sector

#

abbreviated

as:

PWNT#15,"B-W";channel

#;drive

#;track

#;sector

#

where

"channel

#"

is

the

channel

number

specified

when

the

file

into

which

the

block

will

be

read

was

opened,

"drive

#"

is

the

drive

number,

and

"track

#"

and

"sector

#"

are

the

track

and

sector

numbers

containing

the

desired

block

of

data

to

be

partially

read

into

or

written

from

the

file

buffer.

-NOTE

Inatrue

BLOCK-READ,

the

first

byte

of

the

selected

sector

is

used

to

determine

how

many

bytes

of

that

sector

to

read

into

the

disk

memory

buffer.

It

thus

cannot

be

used

to

read

an

entire

sector

into

the

buffer,

as

the

first

data

byte

is

always

interpreted

as

being

the

number

of

characters

to

read,

rather

than

part

of

the

data.

Similarly,

inatrue

BLOCK-WRITE,

when

the

buffer

is

written

back

to

diskette,

the

first

byte

written

is

the

current

value

of

the

buffer

pointer.

Only

that

many

bytes

are written

into

the

specified

sector.

It

cannot

be

used

to

rewrite

an

entire

sector

onto

diskette

unchanged,

because

the

first

data

byte

is

overwritten

by

the

buffer

pointer.

73

THE

BUFFER

POINTER

The

buffer

pointer

points

to

where

the

next

READ

or

WRITE

will

begin

withinadisk

memory

buffer.

By

moving

the

buffer

pointer,

you

can

access

individual

bytes

withinablock

in

any

order.

This allows

you

to

edit

any

portion

ofasector,

or

organize

it

into

fields,

likearelative

record.

FORMAT

FOR THE

BUFFER-POINTER

COMMAND:

PRINT#15,uBUFFER-POINTERn;channel#;byte

usually

abbreviated

as:

PRINT#15,"B-P";channel

#;byte

where

"channel

#"

is

the

channel

number

specified

when

the

file

reserving

the

buffer

was

opened,

and

ubyte"

is

the

character

number

within

the

buffer

at

which

to

point

(from0through

255).

ALTERNATE

FORMATS:

PRINT#15,"B-P:"channel

#;byte

PRINT#15,"B-P:channel

#;byte"

EXAMPLE:

Here

isaprogram

that

locks

the

first

program

or

file

onadiskette.

It

works

by

reading

the

start

of

the

directory

(Track

40,

Sector

3)

into

disk

memory,

setting

the

buffer

pointer

to

the

first

file

type

byte

(see

AppendixCfor

details

of

directory

organization),

locking

it

by

setting

bit6and

rewriting

it.

110

OPEN

15,8,15

Open

command

channel.

120

OPEN

5,8,5,"#"

Open

direct

access

channel.

130

PRINT#15/'Ul";5;0;40;3

Read

Track

40,

Sector

3.

140

PRINT#15,"B-P";5;2

Point

to

Byte2of

the

buffer.

15OGET#5A$:IFA$

=

""

THEN

A$=CHR$(0)

Read

it

into

memory.

160

A=ASC(A$)

OR

64

Turn

on

bit6to

lock.

170

PRINT#15,"B-P";5;2

Point

to

Byte2again.

180

PRINT#5,CHR$(A);

Overwrite

it

in

buffer.

190

PRINT#15,uU2";5;0;40;3

Rewrite

buffer

to

diskette.

200

CLOSE

5

Tidy

up

after.

210

CLOSE

15

220

END

74

After

the

above

program

is

run,

the

first

file

on

that

diskette

can

no

longer

be

erased.

If

you

later

need

to

erase

that

file,

rerun

the

same

program,

but

substitute

the

revised

line

160

below

to

unlock

the

file

again:

160

A=ASC(A$)

AND

191

Turn

off

bit6to

unlock

ALLOCATING

BLOCKS

Once

you

have

written

something

inaparticular

sector

on

a

diskette

with

the

help

of

direct

access

commands,

you

may

wish

to

mark

that

sector

as

"already

used",

to

keep

other

files

from

being

written

there.

Blocks

thus

allocated

will

be

safe

until

the

diskette

is

validated.

FORMAT

FOR

BLOCK-ALLOCATE

COMMAND:

PRINT#15,uBLOCK-ALLOCATE";drive

#;

track

#;sector

#

usually

abbreviated

as:

PRINT#15,"B-A";drive

#;

track

#;sector

#

where

"drive

#"

is

the

drive

number,

and

"track

#"

and

"sector

#"

are

the

track

and

sector

containing

the

block

of

data

to

be

read

into

the

file

buffer.

ALTERNATE

FORMAT:

PRINT#15,"B-A:";drive

#;

track

#;sector

#

EXAMPLE:

If

you

try

to

allocate

a

block

that

isn't

available,

the

DOS

will

set

the

error

message

to

number

65,

NO

BLOCK,

and

set

the

track

and

block

numbers

in

the

error

message

to

the

next

available

track

and

block

number.

Therefore,

before

selecting

a

«block

to

write,

try

to

allocate

that

block.

If

the

block

isn't

available,

read

the

next

available

block

from

the

error

channel

and

allocate

it

instead.

However,

do

not

allocate

data

blocks

in

the

directory

track.

If

the

track

number

re

turned

is

0,

the

diskette

is

full.

Here

isaprogram

that

allocates

a

place

to

storeamessage

on

a

diskette.

100

OPEN15,8,15

Open

command

channel.

110

OPEN5,8,5,"#"

"

direct

access

"

75

120

PRINT#5,"I

THINK

THEREFOREIAM"

Writeamessage

to

buffer.

130T=1:S=1

Start

at

first

track§or.

140

PRINT#15,"B-A";0;T;S

Try

allocating

it.

150

INPUT#15,EN,EM$,ET,ES

See

if

it

worked.

160

IF

EN=0

THEN

210

If

so,

we're

almost

done.

170

IF

ENO65

THEN

PRINT

"NO

BLOCK"

EN,EM$,ET,ES:STOP

means

already

allocated.

180

IF

ET=0

THEN

PRINT

"DISK

FULL":STOP

If

next

track

is

0,

we're

out

of

room.

190

IF

ET=40

THEN

ET=4l:ES=0 Don't

allocate

the

directory.

200

T=ET:S=ES:GOTO

140 Try

suggested

track§or

next.

210

PRINT#15,"U2";5;0;T;S

Write

buffer

to

allocated

sector.

220

PRINT

"STORED

AT:",T,S

Say

where

message

went

230

CLOSE

5:CLOSE

15

and

tidy

up.

240

END

FREEING

BLOCKS

The

BLOCK-FREE

command

is

the

opposite of

BLOCK-ALLOCATE.

It

freesablock

that

you

don't

need

any

more,

for

re-use

by

the

DOS.

BLOCK-FREE

updates

the

BAM

to

showaparticular

sector

is

not

in

use,

rather

than

actually

erasing

any

data.

FORMAT

FOR

BLOCK-FREE

COMMAND:

PRINT#15,uBLOCK-FREE";drive

#;track

#;sector

#

abbreviated

as:

PRINT#15,"B-F";drive

#;track

#;sector

#

where

"drive

#"

is

the

drive

number,

and

"track

#"

and

"sector

#"

are

respectively

the

track

and

sector

numbers

containing

the

desired

block

of

data

to

be

read

into

the

file

buffer.

ALTERNATE

FORMAT:

PRINT#15,"B-F:'';drive

#;track

#;sector

#

EXAMPLE:

To

free

the

sector

in

which

we

wrote

our

name

in

the

BLOCK

WRITE

example,

and

allocated

in

the

first

BLOCK-ALLOCATE

example,

we

could

use

the

following

command:

PRINT#15/'B-F";0;l;l

76

PARTITIONS

and

SUB-DIRECTORIES

The

1581

allows

the

user

to

create

partition

areas

on

the

disk.

Partitions

were

originally

implemented

to

provideamechanism

for

easily

protecting

a

particular

section

of

the

disk.

That

is

useful

for

permanently

allocating

part

of

the

disk

for

things

such

as

BOOT

sectors,

CP/M

work

area,

or

reserving

space

for

user

defined

random

files.

Normally,

sectors

on

the

disk

can

be

marked

as

used by

setting

the

appropriate

bit

in

the

BAM

(most

easily

done

with

the

BLOCK-

ALLOCATE

command).

That

prevents

them

from

being

overwritten.

A

VALIDATE

command,

however,

will

de-allocate

this

area.

To

protect

these

special

blocks

from

being

de-allocated

duringaVALIDATE,

place

them

inauser

defined

partition

area.

The

VALIDATE

command

in

the

1581

automatically

skips

over

file

entries

that

are

partition

files

(file

type=CBM),

which

guarantees

the

intended

area

is,

and

remains,

allocated.

Partition

areas

are

given

names

by

the

user

when

first

created.

They

appear

in

the

main

directory

as

file

type

CBM.

A

partition

area

is

created

by

the

following

command

(file#

should

be

opened

to

the

command

channel):

PRINT#file#,"/0:partition

name,"+CHR$(starting

track)

+

CHR-

$(starting

sector)

+

CHR$(<#of

sectors)

+

CHR$(>#of

sec

tors)+",C"

Large

enough

partitions

can

also

be

used

as

sub-directories.

There

are,

however,

certain

limitations

ifapartition

area

is

to

be

used

asasub-directory

area:

1)

The

partition

area

must

be

at

least

120

sectors

in

size.

2)

The

starting

sector

must

be

0.

3)

The

ending

sector

must

beamultiple

of

40.

4)

The

area

to

be

allocated

cannot

contain

track

40

(the

original

system

track).

Partitions

can

also

be

created

withapartition.

This

means

that

sub-sub-directories

can

be

created

if

their

partitions

meet

the

above

rules.

Graphically,

it

looks

like

this:

77

ROOT

(/)

/O:PART1

/0:PART2

/0:PART3

/0:PARTn

/0:PART2 /0:PART2

/0:PART21

/0:PART22

Partition

areas

which

meet

the

qualifications

of

beingasubdirec

tory

can

then

be

selected

by

the

following

command.

PRINT#file#;70:partition

name"

Once

selected,

the

partition

area

cannot

be

used

asasub-directo

ry

until

it

is

formatted.

The

HEADER

or

NEW

commands

are

used

to

format

this

sub-disk

area.

Make

sure

that

you

have

successfully

select

ed

this

partition

area

before

formatting.

If

not,

the

wrong

directory

area

will

be

reformatted.

You

can

check

if

the

area

was

successfully

selected

by

checking

the

error

channel.

If

everything

went

OK,

the

error

channel

would

read:

02,

SELECTED

PARTITION,first

track

#,last

track

#

If

the

area

you

attempt

to

select

does

not

meet

the

qualifications

of a

sub-directory,

then

the

error

channel

would

return:

77,

SELECTED

PARTITION

ILLEGAL,00,00

Only

one

level

of

subdirectory

can

be

selected

atatime.

To

get

from

the

ROOT

to

PART21

you

would

have

to

execute

the

command

twice.

PRINT#file#,70:PART2"

PRINT#file#,70:PART21"

Directories

can

only

be

traversed

in

the

forward

direction.

To

get

toasub-directory

which

is

onanode

above

the

presently

selected

node

of

the

tree,

you

must

select

the

ROOT

directory

and

work

your

way

down

the

tree,

selecting

a

branch

atatime.

To

get

to

the

ROOT

directory

directly

from

any

node

type:

PRINT#file#,7"

78

When

the

user

selectsaparticular

sub-directory

area,

it

then

becomes

the

default

working

area.

Accesses

to

the

disk

for

directories,

loading

files,

saving

files,

etc.,

will

all

be

done

within

this

area.

Files

outside

of

the

selected

area

are

effectively

invisible.

File

and

local

BAM

information

for

sub-directories

are

stored

within

the

sub-directory

areas

themselves.

The

information

is

stored

on

the

first

allocated

track

of

the

partition

area,

and

has

the

same

format

as

track

40.

When

creating

partitions

and

sub-directories

within

sub-directories

it

is

the

responsibility

of

the

user

to

make

sure

that

he

doesn't

overwrite

this

information!

The

DOS

only

checks

to

make

sure

that

you

don't

attempt

to

overwrite

this

information

for

the

ROOT

directory

(track

40).

It is

up

to

the

user

to

make

sure

that

this

information

isn't

corrupted

in

the

sub-directories.

Partitioned

areas

can

be

freed

up

simply

by

SCRATCHING

the

partition

file

entry

in

the

appropriate

directory.

If

the

partition

was

being

used

asasub-directory,

all

of

the

files

in that

sub-directory

will

be

lost.

USING

RANDOM

FILES

By

combining

the

commands

in

this

chapter,

it

is

possible

to

developafile-handling

program

that

uses

random

files.

What

you

need

to

know

now

is

how

to

keep

track

of

which

blocks

on

the

disk

suchafile

has

used.

(Even

though

you

knowasector

has

not

been

allocated

by

your

random

file,

you

must

also

be

sure

it

wasn't

allocated

by

another

unrelated

file

on

the

diskette.)

The

most

common

way

of

recording

which

sectors

have

been

used

byarandom

file

is

inasequential

file.

The

sequential

file

stores

a

list

of

record

numbers,

with

the

track,

sector,

and

byte

location

of

each

record.

This

means

three

channels

are

needed

byarandom

file:

one

for

the

command

channel,

one

for

the

random

data,

and

the

last

for

the

sequential

data.

79

CHAPTER

7

INTERNAL

DISK

COMMANDS

Expert

programmers

can

give

commands

that

directly

alter

the

workings

of the

1581,

much

as

skilled

programmers

can

alter

the

workings

of

BASIC

inside

the

computer

with

Peeks,

Pokes

and

Sys

calls.

It

is

also

possible

to

write

machine

language

programs

that

load

and

run

entirely

within

the

1581,

either

by

writing

them

into

disk

memory

from

the

computer,

or

by

loading

them

directly

from

diskette

into

the

desired

disk

memory

buffer.

This

is

similar

to

loading

and

running

machine

language

programs

in

your

computer.

As

when

learning

to

use

Peek,

Poke

and

Sys

in

your

computer,

extreme

caution

is

advised

in

using

the

commands

in

this

chapter.

They

are

essentially

machine

language

commands,

and

lack

all

of

BASIC'S

safeguards.

If

anything

goes

wrong,

you

may

have

to

turn

the

disk

drive

off

and

on

again

(after

removing

the

diskette)

to

regain

control.

Do

not

practice

these

commands

on

any

important

diskette.

Rather,

makeaspare

copy

and

work

with

that.

Knowing

how

to

programa6502

in

machine

language

will

help

greatly,

and

you

will

also

needagood

memory

map

of

the

1581.Abrief

1581

map

appears

below.

Location

1581

MEMORY

MAP

Purpose

0000-OOFF

0100-01FF

0200-02FF

0300-09FF

0A00-0AFF

0B00-0BFF

0C00-1FFF

4000-5FFF

6000-7FFF

8000-FEFF

FFOO-FFFF

Zero

page

work

area,

job

queue,

variables

Stack,

variables,

vectors

Command

buffer,

tables,

variables

Data

buffers

(0-6)

BAM

for tracks

0-39

BAM

for

tracks

40-79

Track

cache

buffer

8520A

CIA

WD177XFDC

32K

byte

ROM,

DOS

and

controller

routines

Jump

table,

vectors

81

NOTE

The

1581,

as

well

as

other

Commodore

peripherals,

is

designed

to

support

interfacing

via

software

command

structures.

The

software

commands

provided

in

the

1581

allow

forasmooth

and

controllable

interface

between

the

peripheral

and

CPU.

Although

Commodore

has

provided

the

mechanism

enabling

users

to

load

and

execute

their

own

machine

language

programs

within

the

1581

system,

please

keep

in

mind

that

Commodore

reserves

the

right

to

change

ROM,

RAM,

I/O

and

hardware

structure

at

any

time.

Consequently,

if

the

defined

software

interface

is

bypassed,

future

compatibility

of

the

user's

machine

language

soft

ware

within

the

1581

may

be

in

question.

The

1581

was

not

designed

primarily

asauser

programmable

device,

but

Commodore

recognizes

that

certain

operations

(such

as

copy

protection)

cannot

be

easily

achieved

without

this

ability.

If

you

find

it

necessary

to

use

machine

language

within

the

1581,

use

the

jump

table

listed

in

this

chapter

and

Chapter

10.

That

will

lessen

the

possibility

of

incompatibil

ity

ifafuture

version

of

the

1581

changes

internally.

Also,

let

the

controller

work

for

you

on

the

physical

level

by

request

ing

its

help

via

the

JOB

QUEUE.

That

too

will

greatly

in

crease the

likelihood

of

future

compatibility.

MEMORY-READ

The

6502

has

an

address

space

from

$0000—$FFFF.

You

can

get

direct

access

to

any

location

within

this

by

using

memory

commands.

MEMORY-READ

allows

you

to

select

which

byte

or

bytes

to

read

from

disk

memory

into

the

computer.

The

MEMORY-READ

command

is

the

equivalent

of

the

BASIC

Peek()

function,

but

reads

the

disk's

memory

instead

of

the

computer's

memory.

-NOTE

Unlike

other

disk

commands,

those

in

this

chapter

cannot

be

spelled

out

in

full.

Thus,

M-R

is

correct,

but

MEMORY-READ

is

notapermitted

alternate

wording.

82

FORMAT FOR THE

MEMORY-READ

COMMAND:

PRINT#15,uM-R"CHR$(<addfess)CHR$(>address)CHR$(#

of

bytes)

where

"<address"

is

the

low

order

part,

and

u>address"

is

the

high

order

part

of

the

address

in

disk

memory

to

be

read.

If

the

optional

"#

of

bytes"

is

specified,

it

selects

how

many

memory

locations

will

be

read

in,

from

1-256

(#

of

bytes=0

for

256).

Otherwise,

1

character

will

be

read.

The

next

byte

read

using

the

GET#

statement

through

channel

#15

(the

error

channel),

will

be

from

that

address

in

the

disk

control

ler's

memory,

and

successive

bytes

will

be

from

successive

memory

locations.

Any

INPUT#

from

the

error

channel

will

give

peculiar

results

when

you're

using

this

command.

This

can

be

cleared

up

by

sending

any

other

command

to

the

disk,

except

another

memory

command.

EXAMPLES:

To

see

how

many

tries

the

disk

will

make

to

readaparticular

sector,

and

whether

"bumps"

to

track

one

and

back

will

be

attempted

before

declaring the

sector

unreadable,

you

can use

the

following

lines.

They

will

readaspecial

variable

in

the

zero

page

of

disk

memory,

called

REVCNT.

It

is

located

at

$30

hexadecimal.

110

OPEN

15,8,15

Open

command

channel.

120

PRINT#15/'M-ira

IR$(48)CI

IR$(0)

SameasG=PEEK(

106).

130

GET#15,G$:IFG$=""THENG$=

CIIR$(0)

14OG=ASC(G$)

150B=GAND

128:B$="ON":IFBTIIENB$=

"OFF"

Check

bit

7.

170

T=G

AND

31:PRINT"#OF

TRIES

IS";T

Check

bits

0-5

180

PRINT

"BUMPS

ARE";B$

and

give

results.

200

CLOSE

15

Tidyupafter.

210

END

83

Here'samore

general

purpose

program

that

reads

one

or

more

locations

anywhere

in

disk

memory:

110

OPEN15,8,15

120

INPUT"#OFBYTESTOREAD(0=

END)";NL

130IFNL<1

THEN

CLOSE

15:END

140IFNL>255

THEN

120

150

INPUT'STARTING

AT

ADDRESS";AD

160AH=

INT(AD/256)AL=AD-AH*256

170

PRINT#15,"M-R"CHR$(AL)CHR$(AH)

CHR$(NL)

180

FOR

1=1TONL

190

GET#15A$:IFA$=""THENA$=

CHR$(0)

200

PRINT

ASC(A$);

210

NEXT

I

220

PRINT

230

GOTO

120

Open

command

channel.

Enter

numberofbytes

want

ed

unless

done,

or

way

outofline.

Enter

starting

address.

Convertitinto

disk

form.

Actual

Memory-Read.

Loop

until

have

all

the

data,

printingitaswego,

forever.

MEMORY-WRITE

The

MEMORY-WRITE

command

is

the equivalent

of

the

BASIC

Poke

command,

but

has

its

effect

in

disk

memory

instead

of

within

the

computer.

M-W

allows

you

to

write

up

to

35

bytes

atatime

into

disk

memory.

The

MEMORY-EXECUTE

and

some

User

commands

can

be

used

to

run

any

programs

written

this

way.

FORMAT FOR

THE

MEMORY-WRITE

COMMAND:

PRINT#15,"M-W"CHR$(<address)CHR$(>address)CHR$

(#

of

bytes)CHR$(data

byte(s))

where

"<address"

is

the

low

order

part,

and

">address"

is

the

high

or

der

part

of

the

address

in

disk

memory

to

begin

writing,

"#

of

bytes"

is

the

number

of

memory

locations

that

will

be

written

(from

1-35),

and

"data

byte"

is1or

more

byte

values

to

be

written

into

disk

memory,

each

asaCHR$()

value.

EXAMPLES:

We

can

use

this

line

to

turn

off

the

"bumps"

when

loading

DOS-pro

tected

programs

(i.e.,

programs

that

have

been

protected

against

being

copied

by

creating

and

checking

for

specific

disk

errors).

PRINT#15,"M-W"CHR$(48)CHR$(0)CHR$(1)CHR$(133)

84

The

following

line

can

be

used

to

recover

bad

sectors,

such

as

when

an

important

file

has

been

damaged

and

cannot

be

read

normally.

PRINT#15,"M-W"CHR$(48)CHR$(0)CHR$(1)CHR$(31)

These

two

examples

may

be

very

useful

under

some

circum

stances.

They

are

the

equivalent

of

POKE

48,133

and

POKE

48,31

re

spectively,

but

in

disk

memory,

not

inside

the

computer.

As

mentioned

in

the

previous

section's

first

example,

location

48

in

the

1581

disk

drive

signifies

two

separate

activities

to

the

drive,

all

related

to

error

recovery.

Bit7(the

high

bit),

if

set

means

no

"bumps"

(don't

move

the

read

head

to

track

1).

The

bottom

six

bits

are

the

count

of

how

many

times

the

disk

will

try

to

read

each

sector

before

and

after

trying

seeks

and

bumps

before

giving

up.

Since

31

is

the

largest

number

that

can

be

expressed

in six

bits,

that

is

the

maximum

number

of

tries

allowed.

From

this

example,

you

can

see

the

value

of

knowing

something

about

Peeks,

Pokes,

and

machine-language

before

using

direct-access

disk

commands,

as

well

as

their

potential

power.

MEMOFY-EXECUTE

Any

routine

in

disk

memory,

either

in

RAM

or

ROM,

can

be

ex

ecuted

with

the

MEMORY-EXECUTE

command.

It

is

the

equivalent

of

the

BASIC

Sys

call

toamachine

language

program

or

subroutine,

but

works

in

disk

memory

instead

of

within

the

computer.

FORMAT

FOR THE

MEMORY-EXECUTE

COMMAND:

PRINT#15,"M-E"CHR$(<address)CHR$(>address)

where

"<address"

is

the

low

order

part,

and

">address"

is

the

high

or

der

part

of

the

address

in

disk

memory

at

which

execution

is

to

begin.

Most

uses

require

intimate

knowledge

of

the

inner

workings

of

the

DOS,

and

preliminary

setup

with

other

commands,

such

as

MEMORY-WRITE.

The

routine

should

end

with

an

RTS

to

return

control

to

the

1581.

BLOCK-EXECUTE

This

rarely-used

command

will

loadasector

containing

a

machine

language

routine

intxra

memory

buffer

from

diskette,

and

execute

it

85

from

the

first

location

within

the

buffer,

untilaRETURN

from

Subrou

tine

(RTS)

instruction

ends

the

command.

FORMAT

FOR

THE

BLOCK-EXECUTE

COMMAND:

PRINT#15,"B-E:";channel

#;drive

#;track

#;sector

#

where

"channel

#"

is

the

channel

number

specified

when

the

file

into

which

the

block

will

be

loaded

was

opened,

"drive

#"

is

the

drive

number,

and

"track

#"

and

"sector

#"

are

respectively

the

track

and

sector

numbers

containing

the

desired

block

of

data

to

be

loaded

into

the

file

buffer

and

executed

there.

ALTERNATE

FORMATS:

PRINT#15,"B-E:";channel

#;drive

#;track

#;sector

#

PRINT#15,"B-E.channel

#,drive

#,track

#,sector

#"

EXAMPLES:

Assuming

you

Ve

written

a

machine

language

program

onto

Track

1,

Sector8ofadiskette,

and

would

like

to

run

it

in

buffer

number1in

disk

memory

(starting

at

$0400

hexadecimal,

you

could

do

so

as

fol

lows:

110

OPEN

15,8,15

Open

command

channel.

120

OPEN

2,8,2,"#1"

Open

direct

access

channel

to

buffer

1.

130

PRINT#15,"B-E:";2;0;l;8

Load

Track

1,

Sector8in

it&execute.

140

CLOSE

2

Tidy

up

after.

150

CLOSE

15

160

END

•

USER

COMMANDS

Most

User

commands

are

intended

to

be

used

as

machine

lan

guage

JMP

or

BASIC

SYS

commands

to

machine

language

programs^

that

reside

inside

the

disk

memory.

However,

some

of

them

have

other

uses

as

well.

The

Userl

and

User2

commands

are

used

to

replace

the

BLOCK-READ

and

BLOCK-WRITE

commands,

UI

re-starts

the

1581

without

changing

many

variables,

UJ

cold-starts

the

1581

almost

as

if

it

had been

turned

off

and

on

again.

86

User

Command

U0

u0+(cmd)

ulorua

u2orub

u3oruc

u4orud

u5orue

u6oruf

u7orug

u8oruh

u9orui

u:oruj

Function

restores

default

user

jump

table

burst

utility

command

(see

Chapter9Burst

Commands)

block

read

replacement

block

write

replacement

jumpto$0500

jumpto$0503

.

jumpto$0506

jumpto$0509

jumpto$050c

jumpto$050f

jumpto($fffa)

reset

tables

powerupvector

By

loading

these

memory

locations

with

another

machine

lan

guage

JMP

command,

such

as

JMP

$0520,

you

can

create

longer

rou

tines

that

operate

in

the

disk's

memory

along

with

an

easy-to-use

jump

table.

FORMAT

FOR

USER

COMMANDS:

PRINT#15,"Ucharacter";

where

"character"

defines

one

of

the

preset

user

commands

listed

above.

EXAMPLES:

PRINT#15,"U:";

Form

of

DOS

RESET

command

PRINT#15,"U3";

Execute

program

at

start

of

buffer

2

UTILITY

LOADER

This

command

loadsauser-type

(USR)

file

into

the

drive

RAM.

The

first

two

bytes

of

the

file

must

contain

the

low

and

high

addresses

respectively.

The

third

byte

is

the

amount

of

characters

to

follow.

In

addition,

a

trailing

checksum

byte

must

be

included.

The

load

address

is

the

starting

address.

FORMAT

FOR

THE

UTILITY

LOADER

COMMAND

PRINT#15,u&0:filename"

To

return

from

this

routine,

the

program

should

end

with

an

RTS.

87

AUTO

BOOT

LOADER

During

some

operations

(power-up

reset,

burst

INQURE,

burst

QUERY,

an

initialize

command)

the

1581

will

automatically

look

for

a

file

or

the

disk

named

'COPYRIGHT

CBM

86'

that

isaUSR

type-file.

The

format

of

the

file

is

the

same

as

that

described

previously

for

the

utility

loader.

If

it

is

present,

the

file

is

automatically

loaded

and

executed.

The

automatic

loading

of

this

file

can

be

disabled

by

either

renaming

it,

setting

the

appropriate

flag

in

the

BAM

sectors

(see

Appendix

C),

or

by

setting

a

flag

variable

in

RAM

to

disable

further

autoboots

(see

JDEJAVU

jump

table

vector

in

Chapter

10).

At

the

end

of

the

autobooted

program

it

should

return

control

to

the

1581

via

the

JCBMBOOTRTN

jump

table

vector.

88

CHAPTER

8

MACHINE

LANGUAGE

PROGRAMS

Here

isalist

of

host

computer

disk-related

Kernal

ROM

subrou

tines

andapractical

example

of

their

use

inaprogram

that

reads

a

sequential

file

into

memory

from

disk.

Most

require

advance

setup

of

one

or

more

processor

registers

or

memory

locations

and

all

are

called

with

the

assembly

language

JSR

command.

Foramore

complete

description

as

to

what

each

routine

does

and

how

parameters

are

set

for

each

routine,

see

the

Programmer's

Reference

Guide

for

your

specific

computer.

Label

DISK-RELATED

KERNAL

SUBROUTINES

Address

Function

SETLFS

=

$FFBA

;SET

LOGICAL,

FIRST&SECOND

ADDRESSES

SETNAM

=

$FFBD

;SET

LENGTH&ADDRESSOFFILENAME

OPEN

=

$FFC0

;OPEN

LOGICAL

FILE

CLOSE

=

$FFC3

;CLOSE

LOGICAL

FILE

CHKIN

=

$FFC6

;SELECT

CHANNEL

FOR

INPUT

CHKOUT

=

$FFC9

;SELECT

CHANNEL

FOR

OUTPUT

ORCHN

=

$FFCC

;OEAR

ALL

CHANNELS&RESTORE

DEFAULT

I/O

CHRIN

=

$FFCF

;GET

BYTE

FROM

CURRENT

INPUT

DEVICE

CHROUT

=

$FFD2

;OUTPUT

BYTETOCURRENT

OUTPUT

DEVICE

START

LDA

#4

;SET

LENGTH&ADDRESS

LDX

#<FNADR

;OF

FILE

NAME,

LOW

LDY

#>FNADR

;&

HIGH

BYTES

JSR

SETNAM

;FOR

NAME

SETTER

LDA

#3

;SET

FILE

NUMBER

LDX

#8

;DISK

DEVICE

NUMBER

LDY

#0

;AND

SECONDARY

ADDRESS

JSR

SETLFS

;AND

SET

THEM

JSR

OPEN

;OPEN

3,8,0,"TEST"

LDX

#3

JSR

CHKIN

;SELECT

FILE3FOR

INPUT

NEXT

JSR

CHRIN

;GET

NEXT

BYTE

FROM

FILE

BEQ

END

jUNTEL

FINISHORFAIL

JSR

CHROUT

;OUTPUT

BYTETOSCREEN

JMP

NEXT

AND

LOOP

BACK

FOR

MORE

END

LDA

#3

;WHENDONE

JSR

CLOSE

;CLOSE

FILE

JSR

CLRCHN

;RESTORE

DEFAULT

I/O

RTS

;BACKTOBASIC

FNADR

.BYT

"TEST"

;STORE

FILE

NAME

HERE

89

CHAPTER

9

BURST

COMMANDS

The

Burst

Command

Instruction

Set

(BCIS)

isaseries

of

power

ful,

versatile,

and

complex

commands

that

enables

the

user

to

format,

read,

and

write

in

numerous

formats.

Burst

commands

are sent

via

kernal

calls,

but

the

handshaking

of

data

is

done

by

the

user

for

maximum

performance.

There

is

no

parameter

checking,

so

exercise

care

when

using

the

BCIS.

For

instance,

ifaburst

read

with

an

illegal

track

address

is

sent

toa1581,

the

drive

will

keep

trying

to

find

the

invalid

track.

Reading

and

writing

in

other

formats

is

automatic

if

the

commands

are

given

in

proper

sequence.

Please

become

thoroughly

familiar

with

all

the

commands

and

follow

the

examples

given

in

this

chapter.

It's

important

to

follow

the

handshake

conventions

exactly

for

maximum

performance.

With

the

exception

of

READ

and

WRITE,

burst

commands

do

not

translate

from

logical

to

physical

track

and

sector.

All

track

and

sector

parameters

refer

to

physical

locations

(see

Chapter

10).

Burst

sector

READ

and

WRITE

commands

provideaflag

to

enable

logical

to

phys

ical

translation.

If

the

flag

is

set,

the

drive

does

the

translation

and

the

default

logical

number

of

bytes

per

sector

(256)

is

transferred

instead

of

the

physical

number

of

bytes

per

sector

(512).

CMDl—READ

BYTE

00

01

02

03

04

05

06

BIT

7

0

0

L

6

1

0

E

5

4

3

0

1

0

1

1

0

X

S

0

DESTINATION

TRACK

DESTINATION

SECTOR

NUMBEROFSECTORS

NEXT

TRACK

(OPTIONAL)

2

1

0

0

1

0

0

0

0

1

0

N

RANGE:

All

values

are

determinedbythe

particular

disk

format

and

formatoftransla

tion

table.

SWITCHES:

L—logical

flag(1=

do

logicaltophysical

translation)

E—ignore

error(1=

ignore)

S—side

select

N—drive

number

PROTOCOL:

Burst

handshake

CONVENTIONS:

Before

you

can

READorWRITEtoa

diskette,

it

mustbelogged-in

using

either

the

INQUIRE

DISKorQUERY

DISK

FORMAT

command

(both

are

described

later).

This

mustbedone

once

each

time

you

change

diskettes.

91