Apple II DOS and ProDOS Mini-Manual

 

Csa2 FAQs-on-Ground file: CSA2DOSMM.TXT rev010

 

 

The Csa2 (comp.sys.apple2) usenet newsgroup Frequently Asked

Questions files are compiled by the Ground Apple II site,

1997, 1998.

 

ftp://ground.ecn.uiowa.edu/2/apple2/Faqs

http://ground.ecn.uiowa.edu/2/apple2/Faqs

 

 

for on-line perusing via Netscape, etc. ...

 

http://www.grin.net/~cturley/A2.FAQs.and.INFO/CSA2.FAQs/

ftp://apple.cabi.net/pub/applegs/FAQs.and.INFO/A2.Csa2.FAQs/

 

 

The Csa2 FAQs may be freely distributed.

 

Note: To correctly view tables and diagrams on a super-res display,

use a mono-spaced Font such as CoPilot or PCMononspaced.

 

____________________________

 

 

 

 

001- What is a "DOS"?

002- What DOS's are available on Apple II computers?

003- Are there any faster better versions of DOS 3.3?

004- What commands are available in DOS 3.3?

005- How do I use DOS commands from the keyboard? a program?

006- How do I use variables in a DOS command?

007- How do I create new DOS 3.3 diskettes?

008- How much storage space is on a 5.25" diskette?

009- Can I format a DOS 3.3 diskette for just data storage?

010- What is the "Volume Table of Contents" or "VTOC"?

011- Can I assign names to my DOS 3.3 diskettes?

012- What does it mean to "Boot" a disk?

013- What file types does DOS 3.3 have

014- What do the entries in a DOS 3.3 Catalog display mean?

015- Re. DOS 3.3 file names: How long? What characters are legal?

016- How can I use DOS 3.3 to read/write sectors from machine code?

017- How many 'official' versions of DOS 3.3 are there?

018- What information is included in the VTOC?

019- What information is included in a DOS 3.3 Catalog sector?

020- How does DOS 3.3 remember which sectors are used?

021- What are the formats of DOS 3.3's main file types?

022- How can I know a DOS 3.3 prgm is safe to run from hard disk?

023- What are some good DOS 3.3 references?

024- What is ProDOS?

025- What are ProDOS's major features?

026- Which Apple II's can run which versions of ProDOS?

027- How can I create bootable ProDOS diskettes?

028- How do I make a ProDOS disk that will start BASIC?

029- What is the maximum size of a ProDOS volume?

030- How do I LOAD, SAVE, etc. files under ProDOS?

031- What is a "pathname"?

032- What is the default volume and folder when ProDOS boots?

033- How can I set default volume and folder under ProDOS?

034- How can I discover the name of the current default volume?

035- How do I create a folder?

036- How can I access ProDOS routines from machine language?

037- How can I convert DOS 3.3 wares to run under ProDOS?

038- How can I modify ProDOS to do BLOADs to Text Page 1?

039- How can I boot ProDOS on my Franklin computer?

040- What are some good ProDOS references?

 

 

 

 

 

 

From: Rubywand

 

001- What is a "DOS"?

 

"DOS" means "Disk Operating System". A DOS is a collection of

machine language routines and data which lets a computer Read and Write

information to/from disk. A DOS also includes commands, such as SAVE and

LOAD, which you can use to create and access files on disk.

 

Apple II DOS, Commodore 64 DOS, and the DOS used on PC's are all

called "DOS"; but, they are different systems. Their commands are

similar, sometimes identical, because what users want to do with disks

is about the same whatever the computer. However, the way each DOS

arranges and keeps track of data on disk is very different. You will

not, for example, be able to read files from a C-64 diskette on your

Apple II running under DOS 3.3.

 

--------------------

 

 

002- What DOS's are available on Apple II computers?

 

DOS 3.3 is the first DOS to be widely used on Apple II computers.

Many programs were written to use DOS 3.3 commands and saved on DOS 3.3

diskettes. Apple 'officially' replaced DOS 3.3 with ProDOS back in the

early '80's. However, DOS 3.3 continues to be popular with II users.

 

Another Apple II DOS is the one introduced with Apple Pascal.

Compared to DOS 3.3 or ProDOS, the Apple Pascal DOS is a very limited,

cumbersome operating system.

 

-------------------

 

 

003- DOS 3.3 seems kind of slow. Are there any faster

better versions of DOS 3.3?

 

Yes. Today, most "DOS 3.3 users" do not actually use DOS 3.3. Long

ago, Beagle Bros introduced patches which resulted in much better speed,

freed-up extra disk space, and added a CATALOG command which shows

number of Free Sectors. Their ProntoDOS or some modification of it is,

for practical purposes, the "current version" of DOS 3.3.

 

ES DOS ][ adds a few mods to ProntoDOS. CATALOG shows Free Sectors

and Number of Tracks and it scrolls the entire Catalog (scrolling

stopped by pressing any key) instead of stopping when the screen is

full. ES DOS ][ also lets you use the semi-colon as a terminating

'wildcard' character.

 

Other popular, higher speed versions of DOS 3.3 include David DOS

and Diversi-DOS; and, there are several small, special-purpose versions

of DOS 3.3. For example, one game maker used RDOS to save space and to

make its diskettes harder to copy.

 

-----------------------

 

 

004- What commands are available in DOS 3.3?

 

To get very far with "DOS 3.3" you will need the DOS Manual. This

is especially true when it comes to using TEXT files. Other good sources

of DOS 3.3 info include _Beneath Apple DOS_ and _Apple II User's Guide_.

For now, the following is a quickie guide to most Apple II DOS 3.3

commands:

 

 

LOAD NARF- loads a BASIC file named NARF.

 

SAVE NARF- saves current BASIC program in memory as file named NARF.

 

DELETE NARF - deletes file named NARF

 

CATALOG - lists contents of diskette to screen

 

RENAME NARF, NEWNARF - renames file NARF to NEWNARF

 

RUN NARF- loads and starts a BASIC file named NARF.

 

BLOAD NARF.PICTURE, A$2000 - loads in a binary file named NARF.PICTURE

starting at address $2000.

 

note: $2000 is a hexadecimal number ($2000 = 8192 in decimal). DOS

commands can use hex or decimal numbers.

 

 

BSAVE NARF, A$300, L$7F - saves $7F bytes of memory starting at address

$300 as a binary file named NARF. (BSAVE NARF, A768, L127 uses decimal

numbers to do the same thing.)

 

note: The above command statement illustrates typical DOS syntax ...

 

BSAVE-- the DOS command

 

NARF-- the file name (the space between the command and file name is

not a requirement; BSAVENARF is okay)

 

,-- a comma to separate file name from parms which follow

 

A-- means an Address follows

 

$300-- the address in hex from which you want to start saving bytes (=

768). Again, spaces do not matter; A768, A 768, A $ 300 are all okay

 

,-- a comma to separate one parm from another

 

L-- means a Length follows

 

$7F-- the length in hex (= 127); this is the number of bytes to be

saved

 

The command statement says Save $7F bytes, starting at address $300, to

a file named "NARF". NARF will have the bytes found at addresses $300

through $37E.

 

note: The order of parms following a file name does not matter.

 

 

BRUN NARF.DISP, A$1000 - loads in a binary file named NARF.DISP starting

at address $1000 and starts executing machine instructions at address

$1000

 

LOCK NARF- locks file NARF (indicated by * in a CATALOG). LOCKed files

cannot be deleted, over-written, etc.

 

UNLOCK NARF - cancels LOCKed status of NARF.

 

VERIFY NARF - uses checksums to verify that NARF is not a damaged file

 

MON C, I, O - tells DOS to display Commands, Inputs from disk, Outputs

to disk. You can specify one, two, or all three (e.g. MON C, O etc.).

 

NOMON C, I, O - cancels all MON requests. NOMON I cancels just the "I"

request.

 

MAXFILES 7 - sets the number of file buffers to 7. (Upon booting DOS,

the default for the MAXFILES value is 3.)

 

PR#1 - sets the destination for Apple outputs to the device in Slot 1

(usually a printer). PR# 3 sets it to Slot 3, etc.. PR# 0 sets the

destination back to the display screen.

 

PR#6 - normally, boots the diskette in Drive 1, Slot 6.

 

IN# 6 - sets the source for Apple inputs to the device in Slot 6.

 

IN# 0 - sets the source for Apple inputs to the keyboard (default).

 

INT - (integer) puts system into Integer BASIC if it is present.

 

FP - (floating point) puts system into standard Applesoft BASIC.

 

OPEN NARFOO - prepares to read or write a TEXT file named NARFOO.

 

READ NARFOO - tells DOS that INPUT and GET statements will obtain

characters from a TEXT file named NARFOO.

 

WRITE NARFOO - tells DOS that PRINTed characters will go to a TEXT file

named NARFOO.

 

CLOSE NARFOO - used to terminate access to a TEXT file named NARFOO.

Just CLOSE terminates access to all OPENed TEXT files.

 

EXEC NARFGO - tells DOS to execute the BASIC and DOS commands found in a

TEXT file named NARFGO

 

The above TEXT file commands handle 'normal' sequential TEXT files. DOS

can also OPEN, READ, WRITE, ... random access TEXT files. (See DOS

manual.)

 

 

Most DOS commands also let you specify Drive and/or Slot. For example

CATALOG, D2 lists the contents of the diskette in Drive 2 to screen.

SAVE NARF,S5,D2 saves NARF to Drive 2 in Slot 5.

 

NOTE --> Using Drive or Slot parms in a DOS command sets the default

Drive or Slot. So, after CATALOG, D2, a plain LOAD or SAVE will access

Drive 2.

 

--------------------

 

 

005- How do I use DOS commands from the keyboard? ... from

a program?

 

To use a DOS command from the keyboard, type it in. (A few commands

can be issued only from a program.) To use a DOS command in a program

enclose it in quotes preceded by PRINT CHR$(4). For example:

 

100 PRINT CHR$(4) "BLOAD NARF, A$2000"

 

-------------------------

 

 

006- How do I use variables, say for file length, in a

DOS command?

 

Use variables in a command this way:

 

120 PRINT CHR$(4) "BSAVE NARF, A$2000, L"; NB

 

Line 120 says that the Length of NARF is the value of variable NB. NB is

used here to represent the number of bytes (in decimal) to be saved.

 

--------------------------

 

 

007- How do I create new DOS 3.3 diskettes?

One of the best features of DOS 3.3 is that any bootable DOS

diskette can create other bootable diskettes.

 

INIT HELLO - formats one side of the diskette in the currently active

drive, adds DOS, and saves the current program as HELLO.

 

The program that's automatically placed on the new diskette is the

one in memory when INIT is executed. It is called the "greeting

program" or "hello program" because it is the program which will be run

when the diskette is booted. Usually, the program is named HELLO; but,

you can INIT HOWDY, or any name you like. The hello program can be very

simple, such as ...

 

100 PRINT CHR$(4) "CATALOG"

110 END

 

 

You are free to load in and change the hello program or even delete

it, just like any other. The one restriction is that once a diskette is

INITed, the name of the hello program is fixed for that diskette unless

you use a utility (like Copy II+) to make a change. This is why it's a

good idea to stick with the name HELLO. You will always know what the

hello program's name is.

 

Once a diskette is INITed it can be used to store your programs and

data files.

 

-----------------------

 

 

008- How much storage space is on a newly

INITialized 5.25" diskette?

 

A standard DOS 3.3 diskette has 35 Tracks. Each Track contains 16

256-byte Sectors. This gives 35 x 16 x 256 = 143360 bytes per side.

Current versions of DOS 3.3-- e.g. ProntoDOS, etc.-- use Track 0 and

Track 1 plus a sector on Track 2 for DOS; and, Track 17 is used for

holding the Catalog of files and other disk information. This leaves

roughly 130k bytes per side free for your HELLO program and other files.

 

By the way, when it comes to the way it is stored on-disk, DOS 3.3

is not like the PC's MSDOS or Apple's ProDOS. DOS 3.3 is 'hidden' on

reserved tracks, mainly Tracks 0 and 1. There is no "DOS 3.3" file which

will show up on a CATALOG.

 

 

----------------------

 

 

009- On my PC I can FORMAT diskettes with or without adding the

operating system. Can I format a DOS 3.3 diskette for just

data storage? -- i.e. without adding DOS or a HELLO program?

 

Yes. DOS 3.3 does not have a plain "FORMAT" command; but, you can

use utilities such as Copy II+ to easily format a diskette without

adding DOS or a HELLO program.

 

A format will create 35 Tracks of 16 256-byte sectors each, verify

that each Track is good, and create a 'Contents' and disk info record

called the "Volume Table of Contents" or "VTOC".

 

----------------------

 

 

010- What is the "Volume Table of Contents" or "VTOC"?

 

The VTOC is a Sector which stores such basic information as Number

of Tracks, Sectors per Track, DOS version, ..., and the 'map' of

used/un-used Sectors. DOS 3.3 writes the VTOC at Track 17, Sector 0.

(For more details on VTOC content see Question 018.)

 

----------------------

 

 

011- Can I assign names to my DOS 3.3 diskettes?

 

DOS 3.3 has no way to name a diskette "NARF", "DISK 100", "DATA

DISK ", etc. which DOS will recognize. You can, however, 'name' a

diskette by giving it a Volume Number in the range 1-255.

 

Volume Number is set at the time a diskette is initialized. For

example ...

 

INIT HELLO, V19

 

INITs a diskette as Volume 19. If no number is specified, the default

Volume Number used by INIT is 254.

 

Several DOS commands can specify a Volume Number in order to decide

whether a diskette is the right one for some application.

 

LOAD NARF, D2, V5 ... for example, will not load NARF from Drive 2

unless the diskette's Volume Number is 5.

 

 

A few early pieces of commercial software used Volume numbering;

and, new users often like to Volume number their diskettes. In practice,

this turns out to be a bad idea. A diskette with any Volume Number

except the default (254) is often difficult to work with via standard

utilities. Also, once a diskette is INITed for a certain Volume Number,

changing the number is difficult because Volume Number is embedded in

each Sector. (i.e. You'll end up having to copy every file to another

diskette and, then, re-INITing the source diskette to the new Volume

Number.)

 

Besides, there's an easy way to give descriptive names to your DOS

3.3 diskettes which will not interfer with normal access. Just write the

name ("GAMES DISK ONE", or whatever) to a Text file named, say,

"DISK.ID".

 

DOS 3.3 will not know about the name or show it in a CATALOG.

However, your programs will be able to find out the name by just reading

DISK.ID.

 

-----------------------------

 

 

012- What does it mean to "Boot" a disk?

 

BOOT comes from the idea of 'pulling yourself up by your

bootstraps'. The Apple II disk controller ROM has just enough smarts to

load-in DOS's Bootstrap Loader from Track 0, Sector 0 (it comes in at

address $800 ...).

 

The Loader loads in a still smarter, bigger routine from several

sectors of Track 0. This routine is the one which loads in the rest of

DOS, moves it to the proper place in memory, and ends up going to DOS's

Cold Start routine. Finally, the hello program is loaded and executed.

 

--------------------------------

 

 

013- What file types does DOS 3.3 have and how is file

type information saved in the Catalog?

 

In a DOS 3.3 Catalog sector, the third byte in each file's entry

tells the type of the file:

 

Byte Value* File Type

00 Text

01 Integer BASIC

02 AppleSoft BASIC

04 Binary

08 S type

10 R: Relocatable object module

20 new A type

40 new B type

 

 

*DOS 3.3 sets bit 7 of the byte if the file is locked. (e.g. 84 --> a

locked Binary file)

 

Type R files show up in just a few applications. An R file begins

with 6 bytes which a "loader" routine can use to tell the Target

location of file contents, How many bytes to move, and Source location

to move from.

 

Although S, new A, and new B are included, no official application

was defined for them and no DOS commands were created to make any

special use of these files.

 

---------------------

 

 

from David Empson

 

There was an "R" type relocating loader included with the toolkit

for use with BASIC programs and relocatable routines being loaded into

upper memory.

 

"S" was used by some programs for a generic image file, or something

that was not likely to be touchable with normal code.

 

The LISA assembler used the second "B" type for its source files.

It had a patched version of DOS that changed the file type list to read

"LARSBAIT", so the source files appeared in the catalog as "L" if you

booted LISA, or "B" if you booted a normal disk.

 

The "B", "A", "R" and "S" special file types cannot be accessed by

BASIC programs (unless you patch DOS) - commands are only provided for

dealing with "B", "A", "I" and "T" files.

 

The four special types can only be accessed using direct calls to

the File Manager.

 

___________________________

 

 

 

from Dave Althoff, Jr.

 

014- What do the entries in a DOS 3.3 Catalog display mean?

 

A standard DOS 3.3 Catalog display looks something like this:

 

DISK VOLUME 254

*A 002 HELLO

B 033 TETRA/SOFT LOGO.BIN

T 142 DAVE'S LIST OF DOS COMMANDS

I 002 INTEGER BASIC PROGRAM

^^ ^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

|| ||| ||||||||||||||||||||||||||||||

|| ||| |___________________________________Filename

|| |_______________________________________File length (in Sectors)

||_________________________________________File type

|________________________________________* means the file is locked

 

 

-----------------------------

 

 

015- How long can a DOS 3.3 file name be and what characters

can it include?

 

DOS 3.3 filenames may be up to 30 characters long, and must conform

to the following restrictions:

 

a. The first character must have an ASCII code value greater than 63.

This excludes numerals, SPACE, and most punctuation. The "@" character

is allowed as well as letters, and some special chars such as "]", "~",

"_", and a few others.

 

b. Commas and colons may not be used at all. Apart from these

restrictions, anything goes. All kinds of characters, including

uppercase, lowercase, numbers, symbols, and CONTROL characters can be

used after the first character.

 

____________________________

 

 

 

from Andy McFadden

 

016- How can I use DOS 3.3 to read and write sectors from

machine code?

 

DOS 3.3 works like this:

 

JSR $3E3 ;get address of RWTS IOB (low in Y, high in A)

 

(you can either change the stuff that Y/A point to, or set up

your own IOB and skip the call to $3E3)

 

JSR $3D9 ;call RWTS (with IOB address in Y/A)

 

 

The IOB (Input/Output Block) is small but non-trivial. Here's what

Beneath Apple DOS says:

 

$00 table type (always $01)

$01 slot *16

$02 drive (1 or 2)

$03 volume expected ($00 for any)

$04 track ($0-$22)

$05 sector ($0-$0f)

$06-07 address (lo/hi) of the Device Characteristics Table

$08-09 address (lo/hi) of the 256 byte buffer for read/write

$0A not used

$0B byte count for partial sector ($00 for 256 bytes)

$0C command code (0=seek, 1=read, 2=write, 4=format)

$0D return code (carry set on error):

 

$00 = no errors

$08 = error during initialization

$10 = write protect error

$20 = volume mismatch error

$40 = drive error

$80 = read error (obsolete)

 

$0E volume number of last access (must be initialized)

$0F slot number of last access *16 (must be initialized)

$10 drive number of last access (must be initialized)

 

 

Device characteristics table:

 

$00 device type (should be $00 for DiskII)

$01 phases per track (should be $01 for DiskII)

$02-03 motor on time count (should be $EFD8 for DiskII)

 

 

NOTE: RWTS uses zero-page location $48, which is also used by the Apple

monitor to hold the P-register value. Location $48 should be set to

zero after each call to RWTS.

 

________________

 

 

From: Edhel Iaur, Esq.

 

017- How many 'official' versions of DOS 3.3 are there

and how can I tell which is running?

 

According to The Dostalk Scrapbook, there are 3 official (as in

Apple made 'em, I think) versions of DOS 3.3. PEEK (46725) supposedly

tells you which is running:

 

165:oldest

186:better

182:latest

 

I remember one had something to do with the way text files are

handled.

 

---------------------

 

From: Dave Althoff

 

The third version then would be the ][e release which contains yet

another APPEND patch, and an additional bit of code which shuts off the

80-column firmware during boot. That version comes on a new System

Master which uses the LOADER.OBJ0 program to fast-load INTBASIC (or

FPBASIC), and a revised "HELLO" program which displays the "MAKE SURE

CAPS LOCK IS DOWN" reminder on a ][e.

 

_____________________

 

 

From: Neil Parker

 

018- What information is included in the VTOC?

 

On track 17 ($11 in hexadecimal) sector 0, you will find the Volume

Table of Contents (VTOC). This is the key sector from which all searches

start out.

 

Format of VTOC:

 

Byte Meaning

---- -------

$00 Unused (always $04 on my disks)

$01 Track number of first catalog sector

$02 Sector number of first catalog sector

$03 DOS version number ($03 for DOS 3.3)

$04-05 Unused

$06 Volume number ($01-$FE)

$07-26 Unused

$27 Number of track/sector pairs in a track/sector list (always

$7A on normal disks)

$28-2F Unused

$30 Last track where sectors were allocated

$31 Direction of allocation ($01=inward, $FF=outward)

$32-33 Unused

$34 Number of tracks per disk (normally $23)

$35 Number of sectors per track (normally $10)

$36-37 Number of bytes per sector (normally $0100)

$38-3B Bit map for track 0

$3C-3F Bit map for track 1

....

$C0-C3 Bit map for track $22

$C4-FF Unused on normal disks (may contain extra bit maps on disks

with more than 35 tracks)

 

Bit map format:

 

Byte 0 Byte 1 Byte 2 Byte 3

 

FEDC BA98 7654 3210 ........ ........

 

A 1-bit in any bit position indicates that the corresponding sector

is free. Bytes 2 and 3 in the bit map are always $00 on normal disks.

 

Bytes 1 and 2 in the VTOC point to the first catalog sector. On

most disks, the first catalog sector is track $11 sector $0F, and

subsequent catalog sectors occupy track $11 sector $0E, track $11 sector

$0D, and so on down to track $11 sector $01. However, DOS 3.3 doesn't

really care where the catalog sectors are or how many there are, as long

as there is a pointer to the first one in the VTOC. (Note, however,

that some utilities, such as Copy II Plus, DO care, and will get lost if

the catalog isn't in its normal position and exactly 15 sectors long.)

 

---------------------------------

 

 

019- What information is included in a DOS 3.3 Catalog

sector and how is it organized?

 

Each catalog sector contains a pointer to the next catalog sector,

and seven file entries. The format of a catalog sector is as follows:

 

 

Byte Meaning

---- -------

$00 Unused

$01 Track number of next catalog sector ($00 if no more)

$02 Sector number of next catalog sector ($00 if no more)

$03-0A Unused

$0B-2D First file entry

$2E-50 Second file entry

$51-73 Third file entry

$74-96 Fourth file entry

$97-B9 Fifth file entry

$BA-DC Sixth file entry

$DD-FF Seventh file entry

 

 

Each file entry looks like this:

 

Byte Meaning

---- -------

$00 Track number of this file's first track/sector list

$01 Sector number of this file's first track/sector list

$02 File type:

Bit Meaning

--- -------

7 0=unlocked, 1=locked

6-0 File type ($00=Text, $01=Integer, $02=Applesoft,

$04=Binary, $08=S, $10=Relocatable, $20=A, $40=B)

$03-20 File name (high bits set; padded with blanks on right)

$21-22 Number of sectors allocated to this file

 

----------------------------

 

 

020- How does DOS 3.3 remember which sectors

are used to store a file?

 

Every file has a set of one or more "track/sector lists". A

track/sector list lists sectors (by track and sector number) which make

up the file. Each track/sector list points to up to 122 data sectors;

if the file is too long for one track/sector list, a second one is

allocated, and a pointer to it is stored in the first one. Likewise, if

the file is too long for two track/sector lists, a third is allocated,

and so on.

 

Note that DOS 3.3 supports "sparse" files...there may 0/0 pairs in

the track/sector list indicating parts of the file that were never

written. When DOS 3.3 is reading a file and encounters a 0/0 pair in the

track/sector list, it passes a buffer full of binary zeros back to the

calling program.

 

A track/sector list looks like this:

 

Byte Meaning

---- -------

$00 Unused

$01 Track number of next track/sector list sect ($00 if no more)

$02 Sector number of next track/sector list sect ($00 if no more)

$03-04 Unused

$05-06 Sector number in file of first sector number represented in

this track/sector list sector (0 ($0000) for first T/S

sector, 122 ($007A) for second, 244 ($00F4) for third, etc.)

$07-0B Unused

$0C Track number of 0th (or 122nd, or 244th...) sector

$0D Sector number of 0th (or 122nd, or 244th...) sector

$0E Track number of 1st (or 123rd, or 245th...) sector

$0F Sector number of 1st (or 123rd, or 245th...) sector

....

$FE Track number of 121st (or 243rd, or 365th...) sector

$FF Sector number of 121st (or 243rd, or 365th...) sector

 

---------------------------

 

 

021- What are the formats of DOS 3.3's main file types?

 

A machine-language program is free to store whatever it wants in

any file, but most programs (including DOS 3.3's own command

interpreter) expect the data in each type of file to conform to certain

formats:

 

A sequential text file consists of lines of ASCII text separated by

carriage returns, and ending with a $00 byte. The high bit of each

character (except the $00 at the end) is set.

 

A random-access file may be thought of as a set of "mini sequential

access files" separated by strings of $00 bytes. Each "mini-file"

begins at a file position which is a multiple of the random-access

record length.

 

(Note that sequential and random-access text files share the same

file type. It is up to individual programs to know whether their data

files are sequential or random-access.)

 

 

Applesoft and Integer BASIC files have the following format:

 

Byte Meaning

---- -------

$00-01 Length of tokenized BASIC program

$02-end Tokenized BASIC program

 

Binary files have the following format:

 

Byte Meaning

---- -------

$00-01 Load address

$02-03 Length of binary image

$04-end Binary image

 

A Relocatable file contains the image of a program, followed by a

relocation dictionary containing the information necessary to relocate

the program to an arbitrary memory location. The file format is as

follows:

 

Byte Meaning

---- -------

$00-01 Original program load address

$02-03 File length (program image + relocation dictionary)

$04-05 Length of program image alone (not including relocation

dictionary)

$06-xx Program image

$xx-yy Relocation dictionary

 

(The format of the relocation dictionary is a bit too complex to

describe here. I can provide details if anybody's interested.)

 

The other three file types (S, A, and B) have never been

consistantly defined by anybody. Several programs use these file types

(especially type S) to store their private data files, but there doesn't

seem to be any agreement on their internal format.

 

For further information I recommend the book "Beneath Apple DOS" by

Don Worth and Pieter Lechner.

 

P.S. By the way, all two-byte fields in the above are stored in normal

Apple II byte order, low byte first.

 

______________________________

 

 

 

From: Rubywand

 

022- How can I tell which DOS 3.3 programs are safe to run

from my GS hard disk using utilities such as

Dos 3.3 Launcher?

 

So long as a DOS 3.3 program uses only standard SAVE, etc. commands

to write to disk, it will, most likely, pose no dangers running under

Dos 3.3 Launcher from your GS hard disk. Your main concern is making

sure that the software not do special, non-standard direct writes to

disk.

 

An example of destructive direct-writing is a machine language

routine which dumps game High Scores to a specially formatted 4096-byte

block. Another example is a routine which assumes that certain tracks

are open for caching data. Such actions could mess up formatting,

over-write directories, and do other bad things to files on hard disk.

 

First, you probably know enough about your own programs to say

whether or not any of them do direct writes. If all disk I/O is via the

usual DOS commands (like SAVE), then you are not doing any direct

writes.

 

Non-commercial programs which have no reason to store information,

like simple arcades with no High Scores record or Game Save, are

unlikely to write anything directly to disk. One check is to

write-protect the diskette and play the game. If it does not bomb or do

a lot of clattering while attempting a disk access, it probably does not

attempt any direct writes.

 

Another fairly good check is to list the program (if it's in BASIC)

under Program Writer and Search for any CALLs and & routines. If all

CALLs are to monitor routines ($F800 or higher); and, you can account

for any & commands (e.g. they play music, etc.); and, any expected Game

Saves, Pic Saves, etc. are accounted for by standard DOS 3.3 commands,

then, there are probably no direct writes.

 

If, via the above checks, a program seems free of direct writes

except for CALLs to the $300 area, then, you will need to account for

these CALLS. Often, they will be for sound effects, special

screen-clears, and/or KB-input processing.

 

Via the above checks, quite a few programs will seem free of direct

writes except for CALLs to code BLOADed somewhere before or after the

program. You will need to account for these CALLs.

 

Any program which does CALLs to the Text Page area ($400-$700) is

very suspect as is any program which does CALLs and/or PEEKs and POKEs

to addresses which fall inside the range occupied by the program.

 

Any program you cannot list and which saves information to disk is

suspect. This includes any games, word processors, and educational wares

which save scores, record position of an adventure party, maintain a

progress record, do document backups, etc..

 

Any program with REMs filled with 'garbage'-- evidence of hidden

lines-- or which otherwise seems to behave oddly when listed is suspect.

 

Any commercial program, especially games, educational programs, and

word processors, and any supposedly deprotected commercial program is

suspect.

 

Any program which automatically reboots upon a Reset is very

suspect.

 

About the only way to verify that some "suspect" program does not

do direct writes is go to the monitor and account for the functions of

machine code routines. Just noting than no JMPs or JSR's go to the usual

DOS locations does not protect against custom disk R/W routines which

can be located in all sorts of places.

 

Note: If code is in the Text Page or any other area which is

automatically changed when the program is halted, you will need custom

firmware to do an auto-move of these areas upon Reset. In fact, you may

need to check such areas at different times in the game, etc..

 

One alternative to a special auto-move is to look for and view the code

that you believe is going into the Text Page, etc. on diskette using a

utility like the Copy ][+ Sector Editor. This does not, however,

guarantee that the code is not greatly modified after being loaded by

the program.

 

 

If any of the above conveys the impression that some wares are

trapped specifically in order to mess up disks of users who copy or in

any way modify the wares, it is because this is the case. Many other

wares do direct writes in order to speed-up game play, make a word

processor's operation more 'transparent' and user-friendly, and for

other good reasons. There are, in short, lots of DOS 3.3 'icebergs'

waiting to sink your hard disk.

 

So; if you did not write a DOS 3.3 program yourself or do not have

some guarantee from the program's producer or an experienced user of the

program on hard disk, then, either list the program and check the code

or forget about launching it from hard disk.

 

-------------------------

 

 

023- What are some good DOS 3.3 references?

 

 

DOS Books

 

The DOS Manual from Apple

Beneath Apple DOS by Worth & Lechner

Apple II User's Guide by Poole, Martin, and Cook

 

 

=============================

 

 

024- What is ProDOS?

 

 

ProDOS

 

ProDOS is the official Apple ][ DOS which came after DOS 3.3. Do

not confuse "ProDOS" and "ProntoDOS". ProntoDOS is a slightly modified

DOS 3.3 which provides much faster disk I/O than standard DOS 3.3.

ProDOS is a whole new disk operating system.

 

----------------------------

 

 

025- What are ProDOS's major features?

 

ProDOS has lots of nice features-- mainly, you can create

sub-directories, diskettes ("volumes") can be named, and ProDOS works

well on hard disks. The GS System 6 Finder can handle ProDOS files and

launch programs from ProDOS diskettes. ProDOS's BASIC command

interpreter shares many commands with DOS 3.3, too; so, it is not

difficult for DOS 3.3 users to get started with the newer operating

system.

 

____________________________

 

 

From: David Empson

 

026- Which Apple II's can run which versions of ProDOS?

 

All Apple II's, from the 64k Apple II+ through the IIgs, can run

versions of ProDOS up through version 1.9. (A 48K II+ can also run

ProDOS 1.0 or 1.0.1, but this isn't very useful as there are few

applications that will work in this environment.)

 

Versions 2.x.x require an Apple II equipped with a 65C02, 65C802,

or 65C816 such as an Apple IIe-enhanced, //c, IIc+, or IIgs.

 

____________________________

 

 

From: Rubywand

 

027- How can I create bootable ProDOS diskettes?

 

Creating bootable ProDOS diskettes is a bit more bother because,

unlike DOS 3.3, ProDOS is not automatically written to protected sectors

on the diskette via an INIT command. (ProDOS does not have an INIT

command.) Instead, ProDOS is in a file on the diskette and so is the

ProDOS 'connection' to BASIC, called BASIC.SYSTEM.

 

To make new bootable ProDOS diskettes, the easiest approach is to

use Disk Muncher or some other whole-disk copier to just copy a bootable

ProDOS diskette. You can delete the files you don't want from the copy.

 

Another option is to use Copy II+ (a ProDOS version) to FORMAT a

ProDOS diskette. (FORMAT writes blank tracks so that the diskette can be

used to hold files.) Then, copy BASIC.SYSTEM and PRODOS to the new

diskette. On a IIgs, all of these operations are easily handled via the

Finder.

 

Note: If you want to copy ProDOS from GS/OS, copy the file P8 from the

SYSTEM/ folder and rename it to "PRODOS" on your diskette.

 

------------------------

 

028- How do I make a ProDOS disk that will start BASIC?

If you want ProDOS to boot and start a BASIC program, then both

PRODOS and BASIC.SYSTEM must be present. (BASIC.SYSTEM should be the

first .SYSTEM file on the diskette.) The "hello" program on a ProDOS

diskette is named "STARTUP". This is the program which will be run upon

booting the diskette. (If there is no "STARTUP" program, you will end

up at the usual BASIC prompt after booting.)

 

A simple STARTUP program you can type in and save to your new

ProDOS diskette is ...

 

10 TEXT: HOME

20 PRINT CHR$(4)"CAT"

30 END

 

After typing in the program, just enter SAVE STARTUP. Next time you

boot the diskette, the above program will run and the diskette's CATALOG

will be displayed.

 

A good ready-made STARTUP program and program selector for

launching ProDOS 8 programs on a IIgs is available on Ground as

speedgs.shk. The file unShrinks to the Startup program and a Readme

directions file. You can find speedgs.shk in the 1WSW collection at ...

 

ftp://ground.ecn.uiowa.edu/2/apple2/Collections/1WSW/

 

________________________

 

 

From: David Empson

 

029- What is the maximum size of a ProDOS volume?

 

When a diskette is formatted for ProDOS it is given a name by the

user. A ProDOS diskette is also called a "volume". A ProDOS hard disk

will, usually, be partitioned into two or more named volumes. The

maximum size of a ProDOS volume is 32767.5 kilobytes (65535 blocks).

 

________________________

 

 

From: Rubywand

 

030- How do I LOAD, SAVE, etc. files under ProDOS?

 

LOAD (SAVE, RENAME, etc.) work very much as in DOS 3.3.; so, you

can use Slot and Drive parms to specify the target volume. However, to

get the most from ProDOS you will usually be working with volume names

and folders. (or, "directories").

 

If GAME3.PIC is a binary file in a directory named "PICS" on a

volume named "NARF", you could load it into memory starting at address

$2000 via

 

BLOAD /NARF/PICS/GAME3.PIC,A$2000

 

or, in BASIC

 

100 PRINT CHR$(4)"BLOAD /NARF/PICS/GAME3.PIC,A$2000"

 

 

So, in ProDOS, you can access a disk (or volume) by name ...

 

RUN /GAMES/CHINA.SEA

 

will find the disk (volume) named "GAMES", then, find, load, and run

CHINA.SEA.

 

You can, also, refer to a disk by its location ...

 

CAT,S6,D1

 

will do a short-form catalog of the main directory of the diskette in

DRIVE 1 connected to SLOT 6.

 

-----------------------

 

031- What is a "pathname"?

 

Suppose the file BARDS2.PIC is in the folder PICS on the diskette

(volume) named "NARF". Then ...

 

/NARF/PICS/BARDS2.PIC is BARDS2.PIC's complete "pathname".

 

/NARF/PICS/ is a "pathname prefix" for all files in the PICS

directory on the volume named "NARF".

 

A leading "/" indicates a volume name (/NARF).

 

The "main directory" or "root directory" is the one in which the

files PRODOS and BASIC.SYSTEM (along with any other files the user wants

there) are usually located on a ProDOS diskette. NARF's main directory

pathname prefix is just /NARF/.

 

-----------------------

 

032- What is the default volume and folder when

ProDOS boots?

 

When ProDOS boots, it will assume that LOADs, SAVEs, etc. refer to

the main directory of the volume from which it was booted. For example,

if NARF is booted and JOYSTICK.TEST is a program in NARF's main

directory, then

 

RUN JOYSTICK.TEST

 

will run the program. There is no need to enter RUN /NARF/JOYSTICK.TEST

.

 

------------------------

 

 

033- How can I set default volume and folder

(directory) under ProDOS?

 

The ProDOS PREFIX command lets you set the volume and folder (or

directory) .

 

For example,

 

PREFIX /NARF

 

sets the current default directory to the main directory of the disk (or

volume) named "NARF".

 

PREFIX /NARF

 

also sets the default drive (that is, defaults for SLOT and DRIVE) to

that in which the volume named NARF is located. Usually, the user does

not notice or care about this feature since the location of a volume

does not, usually, change during a session. However, it _may_ change, as

when a user is swapping-in diskettes among two or three drives. If this

happens, ProDOS will look for the diskette.

 

To set the default folder without changing volume, you can use the

PREFIX command without a leading "/". For example, if the current

default volume is /NARF and NARF's main directory is the default

directory, then

 

PREFIX PICS

 

sets the current (default) directory to PICS. The default pathname

prefix would be /NARF/PICS/. Of course,

 

PREFIX /NARF/PICS

 

is also a legal command.

 

----------------------

 

 

From: David Empson

 

PREFIX /

 

reverts to the default behaviour of using the root directory of the

default drive, and the slot/drive options can be used to change disks,

as with DOS 3.3.

 

 

______________________

 

 

From: Rubywand

 

034- How can I discover the name of the current

default volume?

 

A program can discover the name of a disk (or volume) in the

current default drive as follows:

 

100 PRINT CHR$(4)"PREFIX": INPUT"";P$

 

The volume name will be saved in P$. This command is often employed

after booting to discover the volume name. Line 100 also sets the

default directory PREFIX to match the name of the disk (or volume) it

finds.

 

______________________

 

 

 

From: David Wilson

 

035- How do I create a folder?

 

Creating folders (or directories) is the one time you do not need

to provide a type parameter (e.g. TDIR) for the CREATE command. Hence

 

CREATE GIFPICS

 

would create a folder named "GIFPICS" in the current default directory.

 

______________________

 

 

 

From: Neil Parker

 

036- How do I access ProDOS routines from machine language?

 

There are 26 different functions that can be performed through the

ProDOS machine-language interface (MLI), and each one takes its own

unique parameter list. That's far more typing that I'm willing to do

tonight, but the information below should at least give a taste of

what's available. For more information, you might want to check out your

local used bookstores for old Apple ProDOS manuals, or for some of the

third-party books that used to be available (I don't even have Apple's

ProDOS manuals-- I get by just fine with _Beneath_Apple_ProDOS_ by Don

Worth and Pieter Lechner, and _Exploring_Apple_GS/OS_and_ProDOS_8_ by

Gary B. Little).

 

Machine-language programs call ProDOS by doing a JSR to $BF00. This

entry point is called the machine-language interface, or MLI, and it's

responsible for carrying out almost all of the functions tha ProDOS can

perform.

 

To determine what function to perform, ProDOS examines the byte

immediately following the JSR instruction. Immediately after the

command byte come two more bytes that point to the command's parameter

list. When the call completes, it returns to the code immediately

following the parameter list pointer. Thus, a ProDOS call looks like

this:

 

MLI EQU $BF00

 

JSR MLI

DB COMMAND_CODE

DW PARAM_LIST

BCS ERROR

 

The MLI returns with the carry flag set if an error occurred (hence the

"BCS ERROR" instruction in this example), and an error code in the

accumulator.

 

There are 26 command codes available:

 

$40 ALLOC_INT Set up an interrupt handler

$41 DEALLOC_INT Remove an interrupt handler

$65 QUIT Exit the current program; run prgm launcher

$80 READ_BLOCK Read a block from a device

$81 WRITE_BLOCK Write a block to a device

$82 GET_TIME Get the time from a clock card (if any)

$C0 CREATE Create a new file

$C1 DESTROY Delete a file

$C2 RENAME Rename a file

$C3 SET_FILE_INFO Change a file's charateristics

$C4 GET_FILE_INFO Get a file's characteristics

$C5 ONLINE Find the name of a disk in a drive

$C6 SET_PREFIX Set prefix to be added to partial pathnames

$C7 GET_PREFIX Get the current prefix

$C8 OPEN Open an existing file for I/O

$C9 NEWLINE Set line-terminator character for an open file

$CA READ Read data from an open file

$CB WRITE Write data to an open file

$CC CLOSE Close an open file

$CD FLUSH Flush file's block buffer to disk; don't close

$CE SET_MARK Set the current file position

$CF GET_MARK Get the current file position

$D0 SET_EOF Set the length of a file

$D1 GET_EOF Get the length of a file

$D2 SET_BUF Set the location of an open file's blk buffer

$D3 GET_BUF Get the location of an open file's blk buffer

 

Each call expects a different parameter list. Like I said earlier, the

list of parameter lists is too long for me to type in tonight. But I

can include a couple of examples...here's how to rename a file, for

example:

 

JSR $BF00

DB $C2 ; $C2 = RENAME

DW REN_PARMS

BCS ERROR

 

REN_PARMS DB 2 ; RENAME parm list contains 2 parms

DW OLD_NAME ; 1st parm is ptr to old name

DW NEW_NAME ; 2ns parm is ptr to new nme

 

OLD_NAME DB 8,"OLD.NAME" ; (name is count byte followed by ASCII chars)

NEW_NAME DB 8,"NEW.NAME"

 

And here's how to quit from a program and return to the ProDOS program

selector:

 

JSR $BF00

DB $65 ; $65 = QUIT

DW QUIT_PARMS

BRK ; (QUIT doesn't return)

 

QUIT_PARMS DB 4 ; QUIT parm list contains 4 parms

DB 0 ; All 4 parms normally null

DW 0

DB 0

DW 0

 

 

_______________________

 

 

 

From: Rubywand

 

037- How can I convert DOS 3.3 wares to run under ProDOS?

 

Quite a few DOS 3.3 programs will run fine under ProDOS with no

change at all. Unless you have some reason to believe a DOS 3.3 program

will not run under ProDOS, it's worthwhile to just copy it to a ProDOS

diskette and give it a try. Since DOS 3.3 programs which do direct

writes can, possibly, damage a ProDOS disk (see Question 22), be sure to

run any risky-looking tests from a booted ProDOS diskette for which you

have a backup.

 

The main barriers to running DOS 3.3 programs under ProDOS are ...

 

1. Size: DOS 3.3 leaves more space for programs than ProDOS +

BASIC.SYSTEM. Some DOS 3.3 programs are too large for ProDOS. To use

them you will need to find ways to reduce program size.

 

2. Areas of memory used: ProDOS reserves parts of memory, such as Text

Page 1 ($0400-$07FF), for various pointers. Some DOS 3.3 programs LOAD

or BLOAD into one or more of these areas. For example, some games BLOAD

a lo-res pic or Text for you to look at while the rest of the game

loads. Normally, ProDOS will refuse to do such loads and the result will

be a BUFFERS NOT AVAILABLE error message. To run these programs you will

need to unmark the reserved areas which get in the way and/or change the

location(s) of the program's troublesome LOADs and BLOADs.

 

When ProDOS loads it uses most of the memory in the "language card"

areas. Some DOS 3.3 programs also use this memory. If a DOS 3.3 program

uses the "language card" it will probably have to be modified in order

to run under ProDOS.

 

ProDOS handles buffer allocation differently than DOS. If a DOS 3.3

program lowers HIMEM in order to create space for BLOADing code or data,

it may need to be modified to guarantee that the code/area is safe. (See

page 237 of Exploring Apple GS/OS and ProDOS 8 or page 7-4 of Beneath

Apple ProDOS.)

 

3. Names: DOS 3.3 file names can be longer and have more kinds of

characters than ProDOS names. If a DOS 3.3. program BLOADs, WRITEs, etc.

to any files, you will need to be sure that the file names used are

compatible with ProDOS.

 

4. DOS/ProDOS Commands and Syntax: There are, really, very few DOS 3.3

command and syntax differences likely to cause problems under ProDOS.

Still, there are some and you will need to check for these and make any

indicated mods.

 

5. Integer BASIC: Int BASIC programs can be transferred to a ProDOS

diskette; but, you can not run them directly under ProDOS. If you are

willing to move an Int BASIC program to a Text editor, convert the

syntax to Applesoft BASIC, and EXEC the resulting Text file, you can

obtain an Applesoft BASIC program which you can modify as necessary for

ProDOS.

 

6. It's not DOS 3.3: Very old software, old commercial copy-protected

software, and deprotected copies of old software may not be on DOS 3.3

disks. Your first challenge with such software is getting it into a form

which will permit transferring files to a ProDOS diskette.

 

When checking and modifying a DOS 3.3 program for ProDOS a good

program editor is essential. You will save untold hours of work when you

invest in Beagle's tried and true "Program Writer".

 

 

_________________________

 

 

 

From: Jeff Blakeney

 

038- How can I modify ProDOS to do BLOADs in the input buffer

and Text Page 1 areas?

 

You can use a POKE 48984,192 to modify the bit map. This protects

pages $00 and $01, and unprotects pages $02-$07.

 

Note: Because the firmware and I/O cards make use of the "screen hole"

bytes in the $0400-$7FF area, BLOADing over these can interfere with

some devices.

 

For this reason, it is best to have special DOS wares on a separate

ProDOS diskette with a STARTUP program which does the POKE 48984,192.

This way you will know that the system has been changed to run the DOS

wares and not inadvertently try to run a program like Appleworks, etc..

under the modified ProDOS.

 

 

-------------------------

 

 

From: David Empson

 

A safer method is to BLOAD the file elsewhere, and copy data onto the

text screen in a loop, copying 120 bytes and skipping 8 bytes, repeated

8 times.

 

_________________________

 

 

 

From: Rubywand

 

039- How can I boot ProDOS on my Franklin computer?

 

In an old Apple Clinic note, Stephen Craft listed specific

locations to change after your Franklin freezes. You could then restart

via a 2000G from the monitor.

 

It turns out that the bytes Stephen was diddling are D0 03 in the

sequence 69 0B D0 03 A5 0C 60. The sequence is found in all versions of

ProDOS I've checked so far.

 

 

To fix the booting problem, try this:

 

Start Copy II+ and select "Sector Editor"

 

Swap-in the ProDOS diskette

 

READ Track 0, Sector 0

 

Search for (Hex bytes): 69 0B D0 03 A5 0C 60

 

When you find the above, change the D0 03 to EA EA

and write the changed sector back to diskette.

 

This patch has no effect on ProDOS functioning on regular Apple

II's. In fact, most users probably have diskettes on which the patch is

already present.

 

 

--------------------------

 

 

From: David Wilson

 

The D0 03 branch is at the end of some code that calculates a

checksum of the APPLE ][ string found in all genuine Apple II ROMs.

 

When I modified my first copy of ProDOS 1.0.1 to run on my

Multitech MPF-III, I simply changed D0 03 in that sequence to D0 00.

This has the same effect as substituting EA EA-- i.e. the routine exits

with the 'checksum is correct' value in register A.

 

_________________________

 

 

 

From: Rubywand

 

040- What are some good ProDOS references?

 

ProDOS Books

 

ProDOS Technical Reference Manual from Apple (Addison-Wesley)

Beneath Apple ProDOS by Worth & Lechner

Exploring Apple GS/OS and ProDOS 8 by Little

ProDOS Inside and Out by Doms and Weishaar