APPEND~ II

ProDOS

Sectors

The ProDOS 8 READ - BLOCK and WRITE - BLOCK commands discussed in
Chapter 4 can be used to access directly any sector on any track of a DOS 3.3-
formatted disk. This makes it easier to write ProDOS utilities capable of reading DOS
3.3 files or creating and writing DOS 3.3 files. To handle DOS 3.3 files properly you
will, of course, need detailed information on how DOS 3.3 organizes and manages
diskette files. (See Chapter 5 of Inside the Apple lIe for this information.)

To use READ - BLOCK and WRITE - BLOCK with DOS 3.3 disks, first translate
the DOS 3.3 sector number into a block number that these commands understand.
Sectors on a DOS 3.3 diskette are identified by a track number (~34) and a sector
number within the track (~15). The corresponding ProDOS block number can be
calculated from the track and sector values by first multiplying the track number by 8 to
determine the base block number and then adding to the base the relative block number
for the sector. The relative block numbers for each DOS 3.3 sector are as follows:

Belntive Block Number

DOS 3.3 Sector Number

0 and 14

0
1
2
3
4
5
6
7

13 and 12
11 and 10
9 and 8
7 and 6
5 and 4
3 and 2
1 and 15

APW Assembler 357

For example, track 17, sector 15 on a DOS 3.3 diskette corresponds to block
143(8 X 17 + 7).

Since a ProDOS block is twice the size of a DOS 3.3 sector, each ProDOS
corresponds to two DOS 3.3 sectors, as shown in the table. The first half of the I -
corresponds to the first sector in the pair, and the last half corresponds to the
sector. This doubling causes a complication when writing to a DOS 3.3 diskette: &
sector other than the one you want to write to will also be written to. To avoid
destroying the data in the other sector, you must first read the desired block into a
buffer, transfer to it the contents of the sector to be written, and then write the bl~
back to diskette. In this way, the contents of the other sector are not disturbed.

358 ProDOS Blocks and DOS 3.3 Sectors

APPEND~ III

GS,'OS AND PRODOS 8 REFERENCE BOOKS

Apple Computer, Inc., GS/OS Reference, Volume 1 (Apple Programmer's and Devel-
oper's Association, 1988). This manual gives a programmer's overview of GS/OS,
describes the CS/OS commands, and discusses specific file system translators.

Apple Computer, Inc., GS/OS Reference, Volume 2 (Apple Programmer's and Devel-
oper's Association, 1988). This manual describes low-level GS/OS entities, like
device drivers and interrupt handlers.

Apple Computer, Inc., Apple IIGs ProDOS 16 Reference (Addison-Wesley, 1987). This

is the official reference manual for ProDOS 16.

Apple Computer, Inc., ProDOS 8 Technical Reference Manual (Addison-Wesley,

1987). This is the official reference manual for ProDOS 8.

Apple Computer, Inc., BASIC Programming with ProDOS (Addison-Wesley, 1987).

This book describes how to use the BASIC.SYSTEM commands.

APPLE II REFERENCE BOOKS

Apple II Reference Manual (Apple Computer, Inc., 1979). The official reference

manual for the Apple II and Apple II Plus.

Apple Computer, Inc., Apple lIe Technical Reference Manual (Addison-Wesley, 1987).

The official reference manual for the Apple lIe.

Apple Computer, Inc., Apple Ilc Technical Reference Manual (Addison-Wesley, 1987).

The official reference manual for the Apple IIc.

Apple Computer, Inc., Apple Ilcs Toolbox Reference: Volume 1 (Addison-Wesley,

1988). This book describes the Apple IIcs tool set functions.
Apple Computer, Inc., Apple IIGs Toolbox Reference: Volume 2 (Addison-Wesley,

1988). This book describes the Apple IIcs tool set functions.

359

Apple Computer, Inc., Apple II SCSI Card Technical Reference (Apple Programmer's

and Developer's Association, 1988). This book describes the SmartPort calls for the
Apple II SCSI interface card.

Gary B. Little, Inside the Apple IIc (Brady/Prentice Hall Press, 1985). This book is a

programmer's guide to the Apple IIc.

Gary B. Little, Inside the Apple lIe (Brady/Prentice Hall Press, 1985). This book is a

programmer's guide to the Apple lIe.

Gary B. Little, Exploring the Apple II&s (Addison-Wesley, 1987). This book is a

programmer's guide to the Apple IIcs.

65816 ASSEMBLY-LANGUAGE BOOKS

David Eyes and Ron Lichty, Programming the 65816 (Brady/Prentice Hall Press,

1986). This book is a programmer's guide to the 65816 microprocessor.

360 Bibliography

APPEND~ I'v'

A disk containing the source code for each of the programs described in this book, as
well as four bonus programs, can be ordered directly from Gary Little. See the last
page of this book for ordering information.

The files on the disk are one of five types:

z TXT (text) files having names of the form xxxxxxxxxxx.S. These files contain
assembly-language source code in the format expected by the Merlin 8/16
assembler.

z $B0 (source) files. These files contain assembly-language source code in the
format expected by the APW assembler.

z BAS (BASIC) files. These files contain Applesoft programs that you can run
using the BASIC.SYSTEM RUN or - command.

z BIN (binary) files. These files contain assembly-language programs you can run
using the BASIC.SYSTEM BRUN or - command. A BIN file is created from its
corresponding source code file by assembling the source with Merlin 8/16 and
saving the object code to disk.

z SYS (system) files. These files contain assembly-language programs you can run
by using the BASIC.SYSTEM - command or by specifying the file's pathname
in a program selector utility.

The program disk is not bootable because it does not contain a copy of the PRODOS
and BASIC.SYSTEM files. These files can be transferred to it from a ProDOS 8
master disk using the ProDOS 8 Filer or System Utilities program.

The names of the programs on the disk are the same as those used in this book.
Here are descriptions of the four bonus programs (source code is included on the
program disk):

65816 Assembly-language Books 361

THE DISK.MAP PROGRAM

The DISK.MAP program draws a map on the Apple's low-resolution graphics screen
showing the usage of each block on a ProDOS-formatted 5.25-inch disk. To rvn the
program, enter the command

-DI$K.MAP

from Applesoft command mode. Alter you do this, you will be asked for the slot
number of the drive in which the disk has been placed. (If you have two drives for a
slot, put the disk in the drive 1.) DISK.MAP maps each block on the disk to a unique
position in an 8 by 35 rectangular grid map. The horizontal axis represents the track
number from 0 (left) to 34 (right); the vertical axis represents the relative block
number within the track from 0 (bottom) to 7 (top).

Differently colored low-resolution graphic blocks are used to indicate the usage of
any particular disk block. If blue is used, the disk block is in use and readable; if white
is used, the disk block is in use but not readable (that is, it has been damaged). If the
graphic block is gray, the disk block is not being used.

DISK.MAP also displays the amount of free space on the disk and the name of the
volume directory.

THE PROTIME PROGRAM

When you execute PROTIME (with the - command), the TIME command is added to
the BASIC.SYSTEM command set. When you enter the TIME command from Apple-
soft command mode, the current time and date are displayed in the following format:
DO-~-19YY HH:MM

where DD represents the day of the month, M M M represents the first three charac-
ters in the name of the month, 19YY represents the year, HH represents the hour, and
MM represents the minute.

For example, if the current date is November 30, 1988 and the time is 9:20 p.m.,
you will see
30-N0V-1988 21:20

As you see, the time is displayed in 24-hour (military) format.
The TIME command behaves differently when it is invoked from within an Apple-
soft program. In this case, the time is not displayed on the screen; rather, the string
variable associated with the very next INPUT statement in the program is set equal to
the time string. For example, when you execute the program line
100 PRINT CHR$(4);"TINE": INPUT TN$
362 The Program Disk

the time string is assigned to the TM~ variable. The Applesofr string parsing commands
can then be used to isolate elements of the string your program may need to examine.

THE PRO'YYPE PROGRAM

The PROTYPE program adds the TYPE command to the BASIC. SYSTEM command set.
This command displays the contents of a file on the video screen or sends it to a printer.
It is most useful for examining the contents of a file that contains readable text.
To install the TYPE command, enter the command

-PR0TYPE

from Applesoft command mode. If all goes well, you will see the message

TYPE C0NNAND IS NOW INSTALLED.

and the command will be available for use.

The syntax for the TYPE command is

TYPE pn [.L#J I, F#] [,E#] [,R#] [,T#] [,Q#] [,5#1 [,D#]

where brackets are used to enclose optional parameters, and # represents a decimal
or hexadecimal number. (a hexadecimal number must be preceded by $.) Here is the
meaning of each parameter:

pn = pathname for the file

,L# = number of lines to be printed per page
,F# = form size (in lines)
,E# = left margin position

,R# = rest code (nonzero means page pause)
,T# = title code (nonzero means number the pages)
= slot number for output
,S# = slot number for the file
,D# = drive number for the file

The default parameters are 54 (,L#), 66 (,F#), 0 (,E#), 0 (,R#), 0 (,T#), current
output (,@#).

As you can see, the TYPE command supports several parameters used to format the
output and speci~ its destination. For example, the command

The PROTYPE Program 363

TYPE NY.TEXT,Q1,F84,L72,RI,TI,Es

would be used to send a file called MY.TEXT to a printer in slot 1 (,@1). The size of
the paper is 84 lines (,F84), 72 lines will be printed before a form feed is generated
(,L72), and there will be a pause at the top of each new page to allow you to insert
single sheet paper (,R1). Moreover, a page number will appear on each page (,T1), and
there will be a left margin of five spaces (,E5).

You can temporarily halt all output generated by the TYPE command by entering
[ControlS] from the keyboard. To resume, press [ControlS] once again. You can press
[Control-C] at any time to cancel the command.

THE SMARTPORT PROGRAM

SMARTPORT is for determining which slots in the Apple II have SmartPort control-
lers connected to them. It displays status information for the devices connected to
each SmartPort it finds. In particular, it displays the device name, the slot number and
unit number, the device type and subtype, the version number, the device status, and
the total number of blocks the device supports. This last number is either a 4-byte
quantity or a 3-byte quantity depending on whether the SmartPort supports extended
commands. (See Chapter 7 for a thorough discussion of the characteristics of a
SmartPort.)

To rvn SMARTPORT, enter the command

-SNARTP0RT

from Applesoft command mode. (SMARTPORT is a system program, so you could also
run it from any program selector.) When it starts up, you can specifi' whether or not
you want to send the results of the scan to a printer in slot 1.

364 The Program Disk

HEX

/RAM volume ~, 22,53,301-305

double hi-res 303
how to remove 303~05
volume bit map 23,302
/RAM5 volume 9,292,296
- (dash) command 9,232

~/ boot prefix 17
& vector 55

access code 88

ALLOC INTERRUPT 9~1, 93,107,
267,268,270
APDA 353
APPEND 234
Apple 3.5 Drive 2,4
Apple 5.25 Drive 2

Apple II Memory Expansion Card 4
Apple Programmer's Workshop 79,220,
353~55

AppleTalk 50,185
AppleWorks 14

APW see Apple Programmer's Workshop
assemblers 35~55
asynchronous serial 266
ATINIT file 50
Auricchio, Rick 2
auto-rvn protocol 180,223
v>xil,a~'n~~~
auxiliary type code 32,33,34

backup-needed bit 37,39
BADCALL 248

bank-switched EAM 5, 51~3

and interrupts 273

BAS file 32~3

BASIC.SYSTEM program ~, 9,11,219,
22~63

auto-rvn protocol 223
commands 5, 22~236
error codes 82,248
global page 24~48
parameters 9

slot and drive parameters 17
user commands 250-255
BeginSession 92, 122, 191
BIN file 33

BindInt 90, 9~94, 267,280,282
BLOAD 232
block 22

boot prefix (*/) 17
boot record 23, 4~50
booting

ProDOS 5-1
GS/OS 6~7

BRK vector 55
BRUN 232
BSAVE 233
BUBIT byte 198

BUFFERPTR byte 295
buffers, file 5, 18, 19, 134, 192

and BASIC. SYSTEM 5,237-238
BYE 235

caching, GS/OS 11, 1-0
cassette recorder 2
CAT 22~29
CATALOG 229-231
CD-ROM 2,4
CHAIN 235

'tl~n~e~h 11', ib~
character devices 329 ff
character FST 329
ClearBackup 97-98, 198
clock driver 317, 321~22
page two usage 54

clock cards
identification bytes 32~21
interrupts 266
Close 9~100

CLOSE (BASIC.SYSTEM) 234
closing a file 19

CMDADR 72,76,82, 27~75
COMMAND byte 29~95
Console Driver 68, 32~30

365

programming example
Control Panel

RAMdisk size 292
startup device 296
time format 320
Control-Y vector 55
Create 101-104

34~51 dispatcher code 51, 175
DOS 3.1 2~
DOS 3.2.1 3
DOS 3.3 3,14,17
directory 14

relationship to ProDOS
sectors 357~58

CREATE (BASIC.SYSTEM) 231 DOSCMD 24~0

critical error 74
CSW link 226, 23~37

dash (-) command 9,232
data fork 11, 3~0
date-stamping 8
DATE byte 88,159,318
DATETIME 318

DControl 10~106, 33~31

for Console Driver 33~42
DEALLOC INTERRUPT 90,91,

107-108, 27~74
default prefix 10,16
default string (UIR) 331,342
DELETE 231

desk accessories 20,67,89
Desk Manager 172
Destroy 10-110

DEVCNT 28~90, 304,305.
device drivers 8, 6~7
device names 15,22,288
device reference number 22,288
DEVLST 28~90, 292,293, 30~04,
305

DInfo 112-115,211,388,330
direct page 22~22
directories 1-15
directory entries 26
directory header 26
Disk Cache desk accessory 20
Disk II 2

disk controller protocol 8,291-294
disk devices 28~92
identification of 2~292

disk drivers 287
under GS/OS 288
using commands 29~95
vector table 290
disk-switched bit 299

366 Index

DRead 11~117, 185
DStatus 11~119

and Console Driver 331,338,
342~43

DWrite 12~121

ejecting disks 106,301
EndSession 92, 122, 191

EOF pointer 19, 19~196
EraseDisk 26, 12~124
ERRCODE 248
error handling
BASIC.SYSTEM 248
ERROR.MSG file 66
ERROUT 262
Event Manager 330
EXEC 233
ExpandPath 125
extended file 11,39-I1
EXTRNCMD 250,262

FBITS 25~55, 263
field 32

file access code 3~7
file level 1~19, 99,100,151,202
file system translator 2,4, 11,66,

13~131, 14~150
file type code 2~5, 89
file naming rvles 1~14
FILETYPE command 220
Finder 20,21, 172, 180
Flush 12~127

FLUSH (BASIC.SYSTEM) 234
Format 11,21,26, 123, 12~129
formatting disks 21-22
FRE 235

FREEBUFR 238

FST see file system translator
FSTSpecific 13~131

GetBootVol 132-133
GETBUF 13~135
GetDevNumber 13~137
GetDirEntry 11, I3~I42

buffer size error 88
GetEOF I4~I44, 215
GetFileInfo 14~I48
GetFSTInfo I4~I50
GetLevel 151
GetMark I5~153
GetName 11,154-155
GetPrefix I5~I57
GetSysPrefs 158

GET TIME 159,275,318,321
GetVersion 16~161
GETBUFR 238,262
global page

BASIC.SYSTEM 2404248
ProDOS 49,50, 5~7
GOSYSTEM 240,248,255
GSString macro 82,355

HD20SC hard disk 2,3
heartbeat tasks 281

hierarchical directories 8, 1-15
High Sierra 4,11,14

HIMEM 5,226,237-238,263,316
Huston, Dick 2

IBAKVER byte 224
IN# 235

inline entry point (GS/OS) 76
input link 2304237

input port 331, 33~34, 342,343
input string

class 0 82
class 1 82

Integer BASIC 5
interleave 11

interrupt dispatcher 267
interrupt handling 8, 265ff

and MLIACTV 27~"5
during MLI commands 27~75
GS/OS 2704284
installing handler ~91
ProDOS 2~275
IntSource 282

invisibility bit 35,37
IRQ interrupt 2~68
masking 266

user vector 55,266,268
IVERSION byte 224

key block 38,49-I1
keyboard input 339-I36
KWS link 226, 23~37

LEVEL 126,127,151,202
LOAD 233

load files 10,66,353
LOCK 36,231

M16.GSOS file 7~
MACHID 5~7, 303,321,322
machine identification byte 56,i;7
machine language interiace see MLI
Macintosh HFS 4,11,14
macros 7~0

Mark pointer 19, 20~04
master index block 38

Memory Manager 10, 67~, 181,219,
220

Menu Manager 20

Merlin 8/16 assembler 35~54
MLI 7~, 71

command number 74
page zero usage 54
MLIACTV 72, 27~75
mount volume dialog box 208
mouse interrupts 266,2704274
MouseText 337~38
MOVE 262
MS-DOS 4,14

NewLine 16~163, 184

and character FST 329
NMIvector 55

no-wait mode 330,342,343
NOMON 235
Null 164

object module format 220
OMF see object module format
ON LINE 1~167, 207,263,288

Index 367

Open 1~19, 16~171OPEN
(BASIC.SYSTEM) 23~4
opening a file 1~19
OSBOOT byte 69
OSKIND byte 69
output buffer

class 0 87~8
class 1 87-88
output link 2304237
05 Shutdown 172

page three 5~55, 23~40
page two 54
page zero 54
PAGETOP 238
parameter table 74
partial pathname 1~17
Pascal 3,22,37
Pascal area 38
pathname 15

PBITS 252-253,255,262
pcount 79
pointers 74
polling 265
POSITION 234
powered-up byte 55
PR# 235

prefix 10, 1~17, 88

default 10, 16

PREFIX (BASIC. SYSTEM) 232
PRINTERR 248
ProDOS 16 1,4,49,89

interrupts 267

PRODOS file ~, 4~0, 6~
ProFile hard disk 3

volume bit map 23-24
PushLong macro 355
PushPtr macro 355
PushWord macro 355
PWREDUP byte 224,225

QuickDraw II 115

Quit 11, 17~181, 220,222,225
Quit Return Stack 180-181

RAMdisk 8-9, 154,292, 301~16

writing a driver 30~16

368 Index

random-access file 19,32
raw mode 330,342,343
Read 182-184

caching 20

READ (BASIC. SYSTEM) 234
READ BLOCK 116,185-187,357
READ.BLOCK program 4~8
ReadAsciiTime 159, 31~20
reading a file 19

ReadTimeHex 89, 159, 31~20
RENAME 95,96, 18~189
RENAME (BASIC.SYSTEM) 232
ResetCache 20,190
Reset vector 55
resource file 11
resource fork 11, 39-I0
RESTORE 235
ROMdisk 292,296
RUN 233

516 file 219
sapling file 38
SAVE 233
SAVEX 72,76
SAVEY 72,76
Scheduler 164

SCSI interface 2,3,301
sectors 21-22, 347~58
seedling file 38
selector code 175
separator 15
SERR 76

SessionStatus 191
SET BUF 192-193
SetEOF 19, 19~196
SetFileInfo 36,97, 197-201
SetHeartbeat 281
SetLevel 18,202
SetMark 20~04, 215
SetPrefix 15, 17, 20~07
SetSysPrefs 158,208
Shepardson, Bob 2
signal handler 282-284
signal queue 164,282-284
SLOT - DRIVE byte 295
SmartPort 291, 29~01

Control command 3004301

dispatch address 297
extended commands 297
standard commands 297
Status command 29~00
unit number 296
SOFTEV bytes 224
sparse files 41~3

stack-based entry point (GS/OS) 80
START program 67,220
START.GS.OS file 6~7
stepping motor 21
storage type 38-39
STORE 236

STR macro 82,355
subdirectories 1-15
SYS file 33,219

SYS16 suffix 220
SYSCALL 240
SYSDEATH 74
SYSERR 74
SYSPARM 240
system bit map 5~6
system disk, GS/OS 57
system error 8~2

System Loader 50,66,220,221
system program

GS/OS 2204222
ProDOS 222-225

terminators

characters 33~31, 335~36, 342
count 336
mask 336
modifiers 336

text port 33~38, 342,343
Text tool set 68,329
time and date
Applesoit variable 322-327
ProDOS 37
GS/OS 8~9

Time byte 88, 159,275,318
tool sets 67

TOOL. SETUP file 67
tracks 21
tree file 38

TXT files 27~, 41

UIR see user input routine
UnbindInt 93,209,282
UniDisk 3.5 4
unit number 22,288
UNLOCK 36,232
user input mode 330
user input routine 330-332
default string 331,342
editing 334-335

values 74

VAR file 33-35
VDRIV 263
VECTIN 237

vector reference number 9~94, 2804281
VECTOUT 237
VERIFY 232

video output 33~38
Volume 165,2104212
volume bit map 22-25
volume directory 14, 2~37
volume size 10, 11
VPATH1 25~55
VPATH2 25~55

vm see vector reference number
VSLOT 263

wait mode 330,342,343
Wigginton, Randy 2
windows 337~37
Wozniak, Steve 2
Write 21~15

caching 20

WRITE (BASIC.SYSTEM) 234
WRITE BLOCK 12,123,186,2104218,
306,357

WriteBParam 20, 190

XCNUM 253,262
XFER vector 55
XLEN 253,262
XRETURN 250

XTRNADDR 253,255,262