[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Apple II FAQs DOS & ProDOS
The comp.sys.apple2 Usenet newsgroup Apple II FAQs originate from
the Ground Apple II archive, 1997-1999. Administrator: Steve Nelson
Csa2 FAQs-on-Ground ref: Csa2DOSMM.txt rev020 10/27/1999
DOS & ProDOS
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- How can I find out the address and size of a BLOADed file?
019- What information is included in the VTOC and Catalog sectors?
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 run DOS 3.3 programs from 3.5" disks and 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: David Empson
018- How can I find out the address and size of a BLOADed
DOS 3.3 file?
After you BLOAD a file, you can use the following command to find out the
exact length of the file you just BLOADed:
PRINT PEEK(43616) + 256 * PEEK(43617)
Use another PEEK to find out where it was loaded:
PRINT PEEK(43634) + 256 * PEEK(43635)
The value displayed is the load address of the binary file.
_____________________
From: Neil Parker
019- What information is included in the DOS 3.3 VTOC and
catalog sectors?
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.)
Catalog
Starting at track 17 ($11 in hexadecimal) sector 15, ($0F) and working
downward, 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 run DOS 3.3 programs from 3.5" disks and hard disk?
You can run quite a few DOS 3.3 programs from 3.5" disk, a large RAM disk,
or hard disk. However, there are numerous DOS 3.3 programs which will not run
this way and which could even damage files and directories on the larger media.
Problems are especially likely when a program modifies and CALLs machine
code routines such as Read/Write Track-Sector (RWTS) and/or makes assumptions
about the physical locations on disk of important DOS 3.3 areas such as the
Volume Table of Contents, CATALOG track, and DOS itself. Using a special
routine to save "High Scores" to a specific Track/Sector is just one of many
ways a DOS 3.3 program might create havoc on a hard disk.
On the other hand, you have programs which stick to using standard DOS
commands from BASIC such as, probably, most of your own DOS 3.3 programs and
most 'type-in' software from publications like SoftSide. Programs like these
should run fine using one of the techniques for accessing DOS 3.3 software from
3.5" diskette or hard disk.
There are two fairly popular approaches to running DOS 3.3 software from
3.5" diskette on an Apple II. One is to copy it to a specially formatted 3.5"
diskette which boots a modified "DOS 3.3" such as AmDOS or OzDOS. Typically,
you get two "400k disks" on each 3.5" diskette.
A very different approach is used by DOS 3.3 Launcher. It offers two
options:
1- You can save some DOS 3.3 programs to ProDOS disk (including 3.5" disk or
hard disk). These must be single-file programs that do not access the disk
once they are loaded into memory. DOS 3.3 Launcher's Copier is used to set
launch options.
2- Using the DOS 3.3 Launcher Copier, you can save an entire DOS 3.3 disk as a
disk image to a ProDOS 3.5" diskette, hard disk, etc.. According to 'Launcher's
docs:
>>
Any disk that uses a standard RWTS (Read/Write Track/Sector) routine can be
copied in this manner. This includes not only DOS 3.3 disks, but also many old
games which use a standard RWTS, but are not actually DOS 3.3. They can then be
launched by DOS 3.3 Launcher, which "boots" the large file directly from your
hard disk.
<<
To run a program on a ProDOS-8, you start DOS 3.3 Launcher from a program
selector such as ProSel-8 which supports the ProDOS 8 startup protocol-- i.e.
it can make applications automatically open a data file. (The DOS 3.3 Launcher
docs tell how to setup a ProSel entry for a program.)
Running a program from the IIgs System Finder is much easier.
>>
If you have properly installed DOS 3.3 Launcher, your DOS 3.3 programs should
appear with DOS 3.3 icons when viewed through the Finder. To launch them, you
simply double click on them, which launches them via ProDOS 8.
<<
Of the two basic approaches (a special 3.5" DOS 3.3 or DOS 3.3 Launcher),
DOS 3.3 Launcher seems to be the better way to go:
First, it is easy to set up the contents of a DOS 3.3 disk prior to converting
it to disk image form-- you can use any of the popular disk management
utilities such as Copy II Plus. Moving DOS 3.3 files onto an AmDOS or OzDOS
disk with the crude FID-type copiers available is a hassle.
Second, DOS 3.3 Launcher turns out to create and use standard 143,360-byte
ProDOS order (.po) disk images except that 'Launcher requires the filetype to
be User#1. (It may accept User#2-4, too; not sure.) So, you should be able to
download any .dsk disk image on your PC, use an emulator to transfer the
contents to a .po disk image, and transfer the .po file via NULL modem to your
Apple II. Here you just need to adjust the filetype for use under DOS 3.3
Launcher. Or you can convert 5.25" .sdk (shrinked disk) files to .po disk image
form and transfer these via NULL modem.
You can find ...
AmDOS at ftp://apple2.caltech.edu/pub/apple2/8bit/utils/
OzDOS at ftp://ftp.gno.org/pub/apple2/appledos33/system/
DOS3.3.Launcher at ftp://ftp.uni-kl.de/pub/apple2/gs/utils/files/
ProSel 8 at ftp://24.96.48.134:6502/Cabi_Archives/Utilities/
or http://www.grin.net/~cturley/USA2WUG/Utilities/
-------------------------
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.
Along with the above, also do this ...
READ Track 0, Sector 0
Search for (Hex bytes): AE B3 FB E0 38
When you find the above, change it to A2 EA EA E0 38
and write the changed sector back to diskette.
The combination of patches is recommended by Jim Sather (inCider, March
1986). The patches have 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
_________________________