The ProDOS 8 Technical Reference Manual is identical in content to the previously
published ProDOS Technical Reference Manual.
Information in this manual covers ProDOS 8 through 1.1.1. For details
on changes to more recent versions, see ProDOS Technical Note #23.
Page vi
Page vii
Page viii
Page ix
Page x
Page xi
Page xii
Page xiii
Page xiv
The ProDOS Technical Reference Manual is the last of three
manuals that describe ProDOS(TM), the most powerful disk operating
system available for the Apple II.
The set of machine-language routines described in this manual provides
a consistent and interruptible interface to any of the disk devices
manufactured by Apple Computer, Inc. for the Apple II. They are
designed to be used in programs written in the 6502 machine language.
Page xv
This manual
Some advantages of programs written using these ProDOS
machine-language routines are:
Apple II
In this manual the name Apple II implies the Apple II Plus, the
Apple IIe, and the Apple IIc, as well as the Apple II, unless it
specifically states otherwise.
This manual is written to serve as a learning tool and a reference tool.
It assumes that you have had some experience with the 6502 assembly
language, and that you are familiar with the Apple II's internal
structure.
Page xvi
If you have read BASIC Programming With ProDOS and you want to
find out more about how the BASIC system program works, refer first
to Appendix A. If you still want more details, Chapters 1 through 3 tell
what ProDOS is and how it works. If you plan to write
machine-language programs that use ProDOS, you will also need to
read Chapters 4 and 5. Chapter 6 shows techniques for adding various
devices to the ProDOS system.
This manual does not explain 6502 assembly language. If you plan to
read beyond Chapter 3, you should be familiar with the 6502 assembly
language and with the ProDOS Editor/Assembler.
By the Way: Text set off in this manner presents sidelights or
interesting points of information.
Important!
Text set off in this manner -- and with a tag in the margin -- presents
important information.
Warning
Warnings like this indicate potential problems or disasters.
Although the Apple IIc has no slots for peripheral cards, it is
configured as if it were an Apple IIe with
Page xvii
Page xviii
Page 1
This chapter contains an overview of ProDOS and of the material
explained in the rest of this manual. It presents a conceptual picture of
the organization and capabilities of ProDOS. It also tells you where in
the manual each aspect of ProDOS is explained.
ProDOS is an operating system that allows you to manage many of the
resources available to an Apple II. It functions primarily as a disk
operating system, but it also handles interrupts and provides a simple
means for memory management. ProDOS marks files with the current
date and time, taken from a clock/calendar card if you have one.
All ProDOS startup disks have two files in common: PRODOS and
XXX.SYSTEM (Chapter 2 explains the possible values for XXX). The
file PRODOS contains the ProDOS operating system; it performs most of
the communication between a system program and the computer's
hardware. The file XXX.SYSTEM contains a system program, the
program that usually communicates between the user and the operating
system. Figure 1-1 shows a simplified block diagram of the ProDOS
system.
------
( User )
------
^
|
v
+------------------+ From File
| System Program | xxx.SYSTEM
+------------------+
^
|
v
+------------------+ From File
| Operating System | PRODOS
+------------------+
^
|
v
+------------------+ Disk Drives,
| Hardware | Memory,
+------------------+ and Slots
Page 2
A ProDOS system program -- such as the BASIC system program (file
BASIC.SYSTEM on the ProDOS BASIC Programming Examples
disk), the ProDOS Filer (file FILER on the ProDOS User's Disk), or
the DOS-ProDOS Conversion program (file CONVERT on the ProDOS
User's Disk) -- is an assembly-language program that accepts commands
from a user, makes sure they are valid, and then takes the appropriate
action. One course of action is to make a call to the Machine Language
Interface (MLI), the portion of the operating system that receives,
validates, and issues operating system commands.
Calls to the MLI give you control over various aspects of the hardware.
MLI calls can be divided into housekeeping calls, filing calls, memory
calls, and interrupt handling calls. The way that the MLI
communicates with disk drives, memory, and interrupt driven devices
is described in the following sections.
Calls to the MLI: see Chapter 4.
About System Programs: If you have dealt with system programs
before, you may be a bit confused about the term as used in this
manual. True system programs are neither application programs (such
as a word processor) nor operating systems: they provide an easy
means of making operating system calls from application programs.As used in this manual, system program refers to a program that is
written in assembly language, makes calls to the Machine Language
Interface, and adheres to a set of conventions, making it relatively easy
to switch from one system program to another. System programs can
be identified by their file type.In short, it is the structure of a program, not its function, that makes a
program a ProDOS system program.The rules for organizing system programs are given in Chapter 5.
Although ProDOS is able to communicate with several different types
of disk drives, the type of disk drive and the slot location of the drive
need not be known by the system program: the MLI takes care of such
details. Instead disks -- or, more accurately, volumes of information -- are
identified by their volume names.
The information on a volume is divided into files. A file is an ordered
collection of bytes, having a name, a type, and several other properties.
One important type of file is the directory file: a directory file
contains the names and location on the volume of other files. When a
disk is formatted using the Format a Volume option of the ProDOS
Filer program, a main directory file for the volume is automatically
Page 3
Any file in the volume directory may itself be a directory file (called a
subdirectory), and any file within a subdirectory can also be a
subdirectory. Using directory files, you can arrange your files so that
they can be most easily accessed and manipulated. This is especially
useful when you are working with large capacity disk drives such as
the ProFile. A sample directory structure is shown in Figure 1-2.
Directory structures are described in Chapter 2.
Figure 1-2. A Typical ProDOS Directory Structure
+---------------+
+-----------------+ +-->| VIDEOBALL |
+---->| PROGRAMS/ | | +---------------+
| |-----------------| |
| | VIDEOBALL |--+ +---------------+
| | DISKWARS |----->| DISKWARS |
| | | +---------------+
| +-----------------+
+-----------------+ |
| /PROFILE/ | |
|-----------------| | +---------------+
| PROGRAMS/ |--+ +-----------------+ +-->| MOM |
| LETTERS/ |------->| LETTERS/ | | +---------------+
| SYSTEMPROGRAMS/ |----+ |-----------------| |
| JUNK/ |--+ | | MOM |--+ +---------------+
+-----------------+ | | | DAD |----->| DAD |
| | | SPOT |--+ +---------------+
| | +-----------------+ |
| | | +---------------+
| | +-->| SPOT |
| | +---------------+
| |
| |
| | +---------------+
| | +-----------------+ +-->| BASIC.SYSTEM |
| +-->| SYSTEMPROGRAMS/ | | +---------------+
| |-----------------| |
| | BASIC.SYSTEM |--+ +---------------+
| | FILER |----->| FILER |
| | CONVERT |--+ +---------------+
| +-----------------+ |
| | +---------------+
| +-->| CONVERT |
| +---------------+
|
| +-----------------+
+---->| JUNK |
+-----------------+
The filing calls, described in Chapter 4, provide all functions necessary
for the access and manipulation of files.
Page 4
Programs that make filing calls to the ProDOS Machine Language
Interface can take advantage of the following features:
The use of files is described in
Chapter 2; their format is given in
Appendix B.
ProDOS treats memory as a sequence of 256-byte pages. It represents
the status of each page, used or unused, as a single bit in a portion of
memory called the system bit map.
When ProDOS initializes itself, it marks all the pages in memory it
needs to protect. Once running, it sets the corresponding bit in the bit
map for each new page it uses; when it releases the page, it clears the
bit.
If your program allows the user to read information into specific areas
of memory, you can use the bit map to prevent ProDOS from
overwriting the program.
The arrangement of ProDOS in memory
is described in Chapter 3.
Page 5
Certain devices generate interrupts, signals that tell the controlling
computer (in this case an Apple II), that the device needs attention.
ProDOS is able to handle up to four interrupting devices at a time. To
add an interrupt driven device to your system:
This causes the routine to be called each time an interrupt occurs. If
you install more than one routine, the routines will be called in the
order in which they were installed.
To remove an interrupt handling routine:
Warning:
Failure to follow these procedures in sequence may cause system
error.
The use of interrupt driven devices is
described in Chapter 6.
Other than disks, ProDOS communicates only with clock/calendar
cards. If your system has a clock/calendar card that follows ProDOS
protocols (see Chapter 6), ProDOS automatically sets up a routine so
that it can read from the clock before marking files with the time. If
you have some other type of clock, you must write your own routine,
place it in memory, and tell ProDOS where the routine is located.
Page 6
Figure 1-3 illustrates the entire mechanism used by ProDOS and shows
the interaction between the levels of ProDOS. A complete ProDOS
system consists of the Machine Language Interface, a system program,
and some external routines. If you wish your system to operate with
interrupt driven devices, a clock/calendar card, or other external
devices, you must supply routines that communicate with these
devices.
The system program takes commands from the user and issues them to
the Command Dispatcher portion of the Machine Language Interface or
to independently controlled devices. The Command Dispatcher validates
each command before passing it to the Block File Manager (which also
manages memory) or to the Interrupt Receiver/Dispatcher. The Block
File Manager calls a disk driver routine and the clock/calendar routine
if necessary; the Interrupt Receiver/Dispatcher calls the interrupt
handling routines.
Page 7
Figure 1-3. The Levels of ProDOS
------
USER ( User ) IMA.USER
------
^
- - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - -
v
+----------------+
USER INTERFACE | System Program | xxx.SYSTEM
+----------------+
^ ^
| \
v \
+------------+ \
- - - - - - - - - - - - - - - - - - - - | Command | - \ - - - - - - - - - - - - - - - - - - - -
| Dispatcher | \
+------------+ \
^ ^ +-------------------+
| | |
+-----------------+ | |
| | |
v v |
+------------+ +---------------------+ | PRODOS
| Block File | | Interrupt | |
OPERATING | Manager | | Receiver/Dispatcher | |
SYSTEM +------------+ +---------------------+ |
^ ^ ^ |
| | +- - - - | - - - - - - - - - - - | - - - - - - - -
v v | v v
+-------------+ +----------------+ | +------------+ +-----------------+
| Disk Driver | | Clock/Calendar | | | Interrupt | | Other Device | User
| Routines | | Routine | | | Routine(s) | | Driver Routines | Installed
+-------------+ +----------------+ | +------------+ +-----------------+
^ ^ | ^ ^
- - - - - - - -|- - - - - - - - - | - - - - - -+- - - - | - - - - - - - - - | - - - - - - - - - -
v v v v
+---------+ +----------------+ +----------------+ +---------------+
HARDWARE | Disk II | | Clock/Calendar | | Interrupt | | Other Devices |
| ProFile | | Card | | Driven Devices | | |
+-----+ | +--------+ | +--------+ | +--------+ |
| | | | | | | |
+---+ +-------+ +-------+ +------+
The following chapters describe the implementation of this mechanism.
After reading through Chapter 5, you will be ready to start writing
your own system programs. After reading through Chapter 6, you will
be able to write your own external routines.
Page 8
Page 9
Chapter 1 introduced you to the concepts of volumes and files. This
chapter explains how files are named, how they are created and used
and a little about how they are organized on disks. When you have
finished reading this chapter you will be nearly ready to start using
the ProDOS Machine Language Interface filing calls.
The technical details of file organization
are given in Appendix B.
A ProDOS filename or volume name is up to 15 characters long. It
may contain capital letters (A-Z), digits (0-9), and periods (.), and it
must begin with a letter. Lowercase letters are automatically converted
to uppercase. A filename must be unique within its directory. Some
examples are
LETTERS JUNK1 BASIC.SYSTEM
By the Way: On the Apple II, an ASCII character is read from the
keyboard and printed to the screen with its high bit set. ProDOS clears
this high bit.
A ProDOS pathname is a series of filenames, each preceded by a
slash (/). The first filename in a pathname is the name of a volume
directory. Successive filenames indicate the path, from the volume
directory to the file, that ProDOS must follow to find a particular file.
The maximum length for a pathname is 64 characters, including
slashes. Examples are
/PROFILE/GAMES/DISKWARS /PROFILE/JUNK1 /PROFILE/SYSTEMPROGRAMS/FILER
All calls that require you to name a file will accept either a pathname
or a partial pathname. A partial pathname is a portion of a pathname
that doesn't begin with a slash or a volume name. The maximum
length for a partial pathname is 64 characters, including slashes. These
partial pathnames are all derived from the sample pathnames above.
Page 10
The partial pathnames are
DISKWARS JUNK1 SYSTEMPROGRAMS/FILER FILER
ProDOS automatically adds the prefix to the front of partial pathnames
to form full pathnames. The prefix is a pathname that indicates a
directory; it is internally stored by ProDOS. To locate a file by its
pathname, ProDOS must look through each file in the path. If you
specify a partial pathname, however, ProDOS jumps straight to the
prefix directory and starts searching from there. Thus disk accesses are
faster when you set the prefix and use partial pathnames.
For the partial pathnames listed above to indicate valid files, the prefix
should be set to /PROFILE/GAMES/, /PROFILE/,
/PROFILE/, and /PROFILE/SYSTEMPROGRAMS/,
respectively. The slashes at the end of these prefixes are optional;
however, they are convenient reminders that prefixes indicate directory
files.
The maximum length for a prefix is 64 characters. The minimum
length for a prefix is zero characters, known as a null prefix. You set
and read the prefix using the MLI calls, SET_PREFIX and
GET_PREFIX, respectively. The 64 character limits for the prefix and
partial pathname combine to create a maximum pathname of
128 characters.
Figure 2-1 illustrates a typical directory structure; it contains all the
files mentioned above.
Page 11
Figure 2-1. A Typical ProDOS Directory Structure
+---------------+
+-----------------+ +-->| VIDEOBALL |
+---->| PROGRAMS/ | | +---------------+
| |-----------------| |
| | VIDEOBALL -|--+ +---------------+
| | DISKWARS -|----->| DISKWARS |
| | | +---------------+
| +-----------------+
+-----------------+ |
| /PROFILE/ | |
|-----------------| | +---------------+
| PROGRAMS/ |--+ +-----------------+ +-->| MOM |
| LETTERS/ |------->| LETTERS/ | | +---------------+
| SYSTEMPROGRAMS/ |----+ |-----------------| |
| JUNK/ |--+ | | MOM -|--+ +---------------+
+-----------------+ | | | DAD -|----->| DAD |
| | | SPOT -|--+ +---------------+
| | +-----------------+ |
| | | +---------------+
| | +-->| SPOT |
| | +---------------+
| |
| |
| | +---------------+
| | +-----------------+ +-->| BASIC.SYSTEM |
| +-->| SYSTEMPROGRAMS/ | | +---------------+
| |-----------------| |
| | BASIC.SYSTEM -|--+ +---------------+
| | FILER -|----->| FILER |
| | CONVERT -|--+ +---------------+
| +-----------------+ |
| | +---------------+
| +-->| CONVERT |
| +---------------+
|
| +-----------------+
+---->| JUNK |
+-----------------+
Page 12
A file is placed on a disk by the CREATE call. When you create a file,
you assign it the following properties:
When you create a file, these properties are placed on the disk. The
file's name can be changed using the RENAME call; other properties
can be altered using the SET_FILE_INFO call. The disk storage
format of these properties is given in Appendix B.
Once a file has been created, it remains on the disk until it is
destroyed (using the DESTROY call).
Before you can read information from or write information to a file
you must use the OPEN call to open the file for access. When you
open a file you specify:
The OPEN call returns a reference number (ref_num). All subsequent
references to the open file must use this reference number. The file
remains open until you use the CLOSE call.
Page 13
Each open file's I/O buffer is used by the system the entire time the
file is open. Thus it is wise to keep as few files open as possible. A
maximum of eight files can be open at a time.
When you open a file, some of the file's characteristics are placed into
a region of memory called a file control block. Several of these
characteristics -- the location in memory of the file's buffer, a pointer to
the end of the file (the EOF), and a pointer to the current position in
the file (the file's MARK) -- are accessible to system programs via MLI
calls, and may be changed while the file is open.
It is important to be aware of the differences between a file on the
disk and an open file in memory. Although some of the file's
characteristics and some of its data may be in memory at any given
time, the file itself still resides on the disk. This allows ProDOS to
manipulate files that are much larger than the computer's memory
capacity. As a system program writes to the file and changes its
characteristics, new data and characteristics are written to the disk.
Warning
In is crucial that you close all files before turning off the
computer or pressing [CONTROL]-[RESET]. This is the only way
than you can ensure that all written data has been placed on the
disk. See also the FLUSH call.
To aid the tasks of reading from and writing to files, each open file
has one pointer indicating the end of the file, the EOF, and another
defining the current position in the file, the MARK. Both are moved
automatically by ProDOS, but can also be independently moved by the
system program.
The EOF is the number of readable bytes in the file. Since the first
byte in a file has number 0, the EOF, when treated as a pointer, points
one position past the last character in the file.
When a file is opened, the MARK is set to indicate the first byte in the
file. In is automatically moved forward one byte for each byte written
to or read from the file. The MARK, then, always indicates the next
byte to be read from the file, or the next byte position in which to
write new data. It cannot exceed the EOF.
Page 14
If during a write operation the MARK meets the EOF both the MARK
and the EOF are moved forward one position for every additional byte
written to the file. Thus, adding bytes to the end of the file
automatically advances the EOF to accommodate the new information.
Figure 2-2 illustrates the relationship between the MARK and the EOF.
Figure 2-2. Automatic Movement of EOF and MARK
EOF EOF Old EOF EOF
| | \ |
v v v v
+---------+ + +---------+ + +------------ +
| | | | | | | | | | | | | | | | | | | | | |
+---------+ + +---------+ + +------------ +
^ ^ ^ ^ ^
| | | | |
MARK Old MARK MARK Old MARK MARK
Beginning Position After Reading Two Bytes After Writing Two Bytes
A system program can place the EOF anywhere, from the current
MARK position to the maximum possible byte position. The MARK can
be placed anywhere from the first byte in the file to the EOF. These
two functions can be accomplished using the SET_EOF and
SET_MARK calls. The current values of the EOF and the MARK can
be determined using the GET_EOF and GET_MARK calls.
READ and WRITE calls to the MLI transfer data between memory and
a file. For both calls, the system program must specify three things:
When the request has been carried out, the MLI passes back to the
system program the number of bytes that it actually transferred.
Page 15
A read or write request starts at the current MARK, and continues
until the requested number of bytes has been transferred (or, on a
read, until the end of file has been reached). Read requests can also
terminate when a specified character is read. You turn on this feature
and set the character(s) on which reads will terminate using the
NEWLINE call. It is typically used for reading lines of text that are
terminated by carriage returns.
By the Way: Neither a READ nor a WRITE call necessarily causes a
disk access. It is only when a read or write crosses a 512-byte (block)
boundary that a disk access occurs.
When you finish reading from or writing to a file, you must use the
CLOSE call to close the file. When you use this call, you specify
CLOSE writes any unwritten data to the file, and it updates the file's
size in the directory, if necessary. Then it frees the 1024-byte
io_buffer for other uses and releases the file's reference number.
Information in the file's directory, such as the file's size, is normally
updated only when the file is closed. If you were to press
[CONTROL]-[RESET] (typically halting the current program) while a
file is open, data written to the file since it was opened could be lost
and the integrity of the disk could be damaged. This can be prevented
by using the FLUSH call. To use FLUSH you specify
If you press [CONTROL]-[RESET] while an open but flushed file is in
memory, there is no loss of data and no damage to the disk.
Both the CLOSE and FLUSH calls, when used with a reference number
of 0, normally cause all open files to be closed or flushed. Specific
groups of files can be closed or flushed using the system level.
Page 16
When a file is opened, it is assigned a level, according to the value of
a specific byte in memory (the system level). If the system level is
never changed, the CLOSE and FLUSH calls, when used with a
reference number of 0, cause all open files to be closed or flushed. But
if the level has been changed since the first file was opened, only the
files having a file level greater than or equal to the current system
level are closed or flushed.
The system level feature is used, for example, by the BASIC system
program to implement the EXEC command. An EXEC file is opened
with a level of 0, then the level is set to 7. A BASIC CLOSE command
(intended to close all files opened within the EXEC program) closes all
files at or above level 7, but the EXEC file itself remains open.
This portion of the chapter describes in general terms the organization
of files on a disk. It does not attempt to teach you everything about
file organization: its purpose is to familiarize you with the terms and
concepts required by the filing calls.
Appendix B elaborates on the subject of
file organization.
Every ProDOS file is a named, ordered sequence of bytes that can be
read from, and to which the rules of MARK and EOF apply. However,
there are two types of files: directory files and standard files.
Directory files are special files that describe and point to other files on
the disk. They may be read from, but not written to (except by
ProDOS). All nondirectory files are standard files. They may be read
from and written to.
A directory file contains a number of similar elements, called entries.
The first entry in a directory file is the header entry: it holds the
name and other properties (such as the number of files stored in that
directory) of the directory file. Each subsequent entry in the file
describes and points to some other file on the disk. Figure 2-3
represents the structure of a directory file.
Page 17
Figure 2-3. Directory File Structure
Directory File Other Files +--------------+ +--------------+ | | +---->| File | | Header Entry | | +--------------+ | | | |--------------| | +--------------+ | | | +-->| File | | Entry -|--+ | +--------------+ | | | |--------------| | | -|----+ | -|---> | More Entries-|--> | -|---> +--------------+ | -|------->| File | |--------------| +--------------+ | | | Entry -|---+ +--------------+ | | +--->| File | |--------------| +--------------+ | | | Entry -|---+ +--------------+ | | +--->| File | +--------------+ +--------------+
The files described and pointed to by the entries in a directory file can
be standard files or other directory files.
A system program does not need to know the details of directory
structure to access files with known names. Only operations on
unknown files (such as listing the files in a directory) require the
system program to examine a directory's entries. For such tasks, refer
to Appendix B.
Standard files have no such predefined internal structure: the format of
the data depends on the specific file type.
Because directory files are generally smaller than standard files, and
because they are sequentially accessed, ProDOS uses a simpler form of
storage for directory files. Both types of files are stored as a set of
512-byte blocks, but the way in which the blocks are arranged on the
disk differs.
A directory file is a linked list of blocks: each block in a directory file
contains a pointer to the next block in the directory file as well as a
pointer to the previous block in the directory. Figure 2-4 illustrates this
structure.
Page 18
Figure 2-4. Block Organization of a Directory File
+------------+ +------------+ +------------+ | Key Block |<------| |<-...<-| Last Block | | |------>| |->...->| | | | | | | | | | | | | | | | | | | | +------------+ +------------+ +------------+
Data files, on the other hand, are often quite large, and their contents
may be randomly accessed. It would be very slow to access such large
files if they were organized sequentially. Instead ProDOS stores
standard files using a tree structure. The largest possible standard file
has a master index block that points to 128 index blocks. Each index
block points to 256 data blocks and each data block can hold 512
bytes of data. The block organization of the largest possible standard
file is shown in Figure 2-5.
Figure 2-5. Block Organization of a Standard File
+---------------------+
| Master Index |
| Block |
+---------------------+
| | | | | | | | | | |
| v v v v | v v v v |
+----------+ | +----------+
| | |
v v v
+-------------+ +-------------+ +-------------+
| Index | | Index | | Index |
| Block 0 | | Block n | | Block 127 |
+-------------+ +-------------+ +-------------+
| | | | | | | | | | | | | | | | | |
| v v v v | | v v v v | | v v v v |
| | | | | |
v v v v v v
+-------+ +-------+ +-------+ +-------+ +-------+ +-------+
| Data | | Data | | Data | | Data | | Data | | Data |
| Block | | Block | | Block | | Block | | Block | | Block |
| 0 | | 255 | | 0 | | 255 | | 0 | | 255 |
+-------+ +-------+ +-------+ +-------+ +-------+ +-------+
Most standard files do not have this exact organization. ProDOS only
writes a subset of this structure to the file, depending on the amount
of data written to the file. This technique produces three distinct forms
of standard file: seedling, sapling, and tree files.
Appendix B describes the three forms of
standard file.
Page 19
In most instances a program writes data sequentially into a file. By
writing data, moving the EOF and MARK, and then writing more data,
a program can also write nonsequential data to a file. For example, a
program can open a file, write ten characters of data, and then move
the EOF and MARK (thereby making the file bigger) to $3FE0 before
writing ten more bytes of data. The file produced takes up only three
blocks on the disk (a total of 1536 bytes), yet over 16,000 bytes can be
read from the file. Such files are known as sparse files.
Important!
The fact that more data can be read from the file than actually resides
on the disk can cause a problem. Suppose that you were trying to copy
a sparse file from one disk to another. If you were to read data from
one file and write it to another, the new file would be much larger
than the original because data that is not actually on the disk can be
read from the file. Thus if your system program is going to transfer
sparse files, you must use the information in Appendix B to determine
which data segments should be copied, and which should not.The ProDOS Filer automatically preserves the structure of sparse files
on a copy.
Page 20
Page 21
This chapter explains the way the Machine Language Interface uses
memory. It tells how much memory system programs have available to
them, how system programs should manage this free memory, and it
discusses the contents of important areas of memory while ProDOS is
inn use.
When you start up your Apple II from a ProDOS startup disk -- one
that contains both the MLI (ProDOS) and a system program
(XXX.SYSTEM) -- a complex loading sequence is initiated.
A preliminary loading program is stored in the read-only memory (boot
ROM) on a disk drive's controller card; the main part of the loader
program, as it is called, resides in blocks 0 and 1 of every
ProDOS-formatted disk.
When you turn on your computer, or use a PR# or IN# command to
reference a disk drive from Applesoft, or otherwise transfer control to
the ROM on the disk-drive controller card when a ProDOS startup disk
is in the drive, this is what happens:
If PRODOS cannot be found, the loader reports to the user that it is
unable to load ProDOS. If no XXX.SYSTEM program is found, ProDOS
displays the message UNABLE TO FIND A SYSTEM FILE.
The rules for system programs are
described in Chapter 5.
Page 22
The MLI is entirely memory resident. Once it is in memory, it neither
moves, nor does it require any additional disk accesses (although the
system program might). The memory configuration that results from
this loading process is described in the section "Memory Map."
When a program or user requests access to a volume that ProDOS has
not yet accessed, it must search through the volumes that are
currently online for the requested volume. The order in which it
searches the devices is determined during step 3 above.
The first volume checked is /RAM, if present, then the startup volume
(generally slot 6, drive 1). The search then checks slots in descending
slot order, starting with slot 7. In any slot, drive 1 is searched before
drive 2.
For example, if there are two Disk II drives in slot 6, two Disk II
drives in slot 5, and a ProFile in slot 7, the search order is:
/RAM
Slot 6, drive 1
Slot 6, drive 2
Slot 7
Slot 5, drive 1
Slot 5, drive 2
The startup volume is the volume in the highest numbered slot that
can be identified by the system as a startup volume. This sequence is
kept in the device list in the ProDOS global page and can be altered.
Note: If the startup volume is a hard disk, the search order is from
slot 7 to slot 1.
ProDOS requires at least 64 kilobytes of memory. Figure 3-1 is the
ProDOS memory map.
Page 23
Figure 3-1. Memory Map
Main Memory Auxiliary Memory
(IIc or 128K IIe only)
$FFFF+---------+$FFFF+---------+ $FFFF+---------+
|.Monitor.| |#########| |.........|
$F800|---------| |#########| |.........|
|.........| |#########| |.........|
|.........| |#########| |.........|
|.........| |#########| |.........|
|.........| |#########| |.........|
|.........| |#########| |.........|
|.........| |#ProDOS##| |.........|
|Applesoft| |#########|$DFFF+---------+$E000|---------|$DFFF+---------+
|.........| |#########| |.........| | | |.........|
|.........| |#########| |.........| | | |.........|
|.........| |#########|$D400|---------| | | |.........|
|.........| |#########| |#########| | | |.........|
|.........| |#########|$D100|---------| | |$D100|---------|
|.........| |#########| | | | | | |
$D000|---------| +---------+ +---------+$D000+---------+ +---------+
|..Other..|
$C100+---------+
^ $BFFF+---------+ $BFFF+---------+
| |#########| |.........|
This ROM area| $BF00|---------| $BF00|---------|
on IIc and IIe |\\\\\\\\\| | |
only! |\\\\\\\\\| | | +---------+
|\\\\\\\\\| | | |#########|
|\\\\\\\\\| | | +---------+
|\\\\\\\\\| | | Used by ProDOS
|\BASIC.\\| | |
|\SYSTEM\\| | |
|\\\\\\\\\| | | +---------+
|\\\\\\\\\| | | |\\\\\\\\\|
|\\\\\\\\\| | | +---------+
|\\\\\\\\\| | | Used by
|\\\\\\\\\| | | BASIC.SYSTEM
$9600|---------| | |
| | | |
| | | | +---------+
| | | | |.........|
| | | | +---------+
| | | | Other used or
| | | | reserved areas
| | | |
| | | |
| | | | +---------+
| | | | | |
| | | | +---------+
| | | | Free Space
| | | |
/\/\/\/\/\/ /\/\/\/\/\/
/\/\/\/\/\/ /\/\/\/\/\/
| | | |
| | | |
| | | |
| | | |
| | | |
$800|---------| $800|---------|
|.........| |.........|
|.........| |.........|
|.........| |.........|
|.........| $400|---------|
|.........| |#########|
$300|---------| |#########|
| | |#########|
$300|---------| |#########|
|.........| $200|---------|
|.........| | |
$100|---------| $100|---------|
| | |#########|
| | $80|---------|
$4F|---------| | |
|#Shared/#| | |
|####safe#| | |
$3A|---------| | |
| | | |
+---------+ +---------+
$00
Page 24
A system program as large as $8F00 (36608) bytes can be loaded into a
64K system. The total amount of space available to a system program
running on a 64K system is $B700 (46848) bytes.
The ProDOS Machine Language Interface uses zero-page locations
$40-$4E, but it restores them before it completes a call. The disk-driver
routines, called by the MLI, use locations $3A through $3F. These
locations are not restored. See Chapter 4 for details.
The $BF-page of memory, addresses $BF00 through $BFFF, contains
the system's global variables. This section of memory is special because
no matter what system ProDOS is booted on, the global page is always
in the same location. Because of this it serves as the communication
link between system programs and the operating system. The MLI
places all information that might be useful to a system program in
these locations. These locations are defined and described in Chapter 5.
ProDOS uses a simple form of memory management that allows it to
protect itself and the user's data from being overwritten by ProDOS
buffer allocation. It represents the lower 48K of the Apple II's
random-access memory using twenty-four bytes of the system global
page: one bit for each 256-byte page of RAM in the lower 48K of the
Apple II. These twenty-four bytes are called the system bit map.
When ProDOS is started up, it protects the zero page, the stack, and
the global page, by setting the bits that correspond to the used pages.
If at all possible, a system program should not use pages of memory
that are already used. If this is not possible, the system program must
close all files and clear the bit map, leaving pages 0, 1, 4 through 7,
and BF (zero page, stack, text, and ProDOS global page) protected. If
an error occurs on the close, the program should ask the user to
restart the system. See Chapter 5 for details.
Page 25
While a system program is using the MLI, there are only three calls
that affect the setting of the bit map: OPEN, CLOSE, and SET_BUF.
When the system program opens a file, it must specify the starting
address of a 1024-byte file buffer. As long as the file is open, this
buffer is a part of the system, and is marked off in the bit map. When
the file is closed, the buffer is released, and its bits are cleared.
In general, a system program requires the used pages of memory to be
contiguous, or touching. This leaves the maximum possible unbroken
memory space for the reading and manipulation of data. Suppose a
system program opens several files and then closes the one that was
opened first. In most cases, this causes a vacant 1K area to appear.
The GET_BUF and SET_BUF calls can be used to find this vacant
area, and to move another file's buffer into this space.
Refer to Chapter 5 for a specific example
of using the system bit map.
Page 26
Page 27
This chapter is about the ProDOS Machine Language Interface (MLI),
which provides a simple way to use disk files from machine-language
programs. This chapter describes
The ProDOS MLI is a complete, consistent, and interruptible interface
between the machine-language programmer and files on disks. It is
entirely independent of the ProDOS BASIC system program; thus, it
serves as a base upon which other system programs can be written. Its
filename is PRODOS. It consists of:
Page 28
A program sends a call to the Machine Language Interface by
executing a JSR (jump to subroutine) to address $BF00 (referred to
below as MLI). The call number and a two-byte pointer (low byte first)
to the call's parameter list must immediately follow the call. Here is an
example of a call to the MLI:
SYSCALL JSR MLI ;Call Command Dispatcher
DB CMDNUM ;This determines which call is being made
DW CMDLIST ;A two-byte pointer to the parameter list
BNE ERROR ;Error if nonzero
Upon completion of the call, the MLI returns to the address of the
JSR plus 3 (in the above example, the BNE statement); the call
number and parameter list pointer are skipped. If the call is successful,
the C-flag is cleared and the Accumulator is set to zero. If the call is
unsuccessful, the C-flag is set and the Accumulator is set to the error
code. The register status upon call completion is summarized below.
Note that the value of the N-flag is determined by the Accumulator
and that the value of the V-flag is undefined.
N Z C D V Acc PC X Y SP
Successful call: 0 1 0 0 x 0 JSR+3 unchanged
Unsuccessful call: x 0 1 0 x error JSR+3 unchanged
code
Page 29
Here is an example of a small program that issues calls to the MLI. It
tries to create a text file named NEWFILE on a volume named
TESTMLI. If an error occurs, the Apple II beeps and prints the error
code on the screen. Both the source and the object are given so you
can enter it from the Monitor if you wish (remember to use a
formatted disk named /TESTMLI).
------------------------------------------------------------------------ SOURCE FILE #01 =>TESTCMD ----- NEXT OBJECT FILE NAME IS TESTCMD.0 2000: 2000 1 ORG $2000 2000: 2000 1 ORG $2000 2000: 2 * 2000: FF3A 3 BELL EQU $FF3A ;Monitor BELL routine 2000: FD8E 4 CROUT EQU $FD8E ;Monitor CROUT routine 2000: FDDA 5 PRBYTE EQU $FDDA ;Monitor PRBYTE routine 2000: BF00 6 MLI EQU $BF00 ;ProDOS system call 2000: 00C0 7 CRECMD EQU $C0 ;CREATE command number 2000: 8 * 2000:20 06 20 9 MAIN JSR CREATE ;CREATE "/TESTMLI/NEWFILE" 2003:D0 08 200D 10 BNE ERROR ;If error, display it 2005:60 11 RTS ;Otherwise done 2006: 12 * 2006:20 00 BF 13 CREATE JSR MLI ;Perform call 2009:C0 14 DFB CRECMD ;CREATE command number 200A:17 20 15 DW CRELIST ;Pointer to parameter list 200C:60 16 RTS 200D: 17 * 200D:20 DA FD 18 ERROR JSR PRBYTE ;Print error code 2010:20 3A FF 19 JSR BELL ;Ring the bell 2013:20 8E FD 20 JSR CROUT ;Print a carriage return 2016:60 21 RTS 2017: 22 * 2017:07 23 CRELIST DFB 7 ;Seven parameters 2018:23 20 24 DW FILENAME ;Pointer to filename 201A:C3 25 DFB $C3 ;Normal file access permitted 201B:04 26 DFB $04 ;Make it a text file 201C:00 00 27 DFB $00,$00 ;AUX_TYPE, not used 201E:01 28 DFB $01 ;Standard file 201F:00 00 29 DFB $00,$00 ;Creation date (unused) 2021:00 00 30 DFB $00,$00 ;Creation time (unused) 2023: 31 * 2023:10 32 FILENAME DFB ENDNAME-NAME ;Length of name 2024:2F 54 45 53 33 NAME ASC "/TESTMLI/NEWFILE" ;followed by the name 2034: 2034 34 ENDNAME EQU * ------------------------------------------------------------------------
The parameters used in TESTCMD are explained in the following
sections. The MLI error codes are summarized in Section 4.7.
Page 30
A value is a one or more byte quantity that is passed to the Block
File Manager (BFM). Values help determine the action taken by the
BFM.
A result is a one or more byte space in the parameter list into which
the Block File Manager will place a value. From results, programs can
get information about the status of a volume, file, or interrupt, or about
the success of the call just completed.
A pointer is a two-byte memory address that indicates the location of
data, code, or a space in which the Block File Manager can place or
receive data. All pointers are arranged low byte first, high byte second.
The first element in every parameter list is the parameter count, a
one-byte value that indicates the number of parameters used by the
call (not including the parameter count). This byte is used to verify
that the call was not accidental.
To help you learn to use the ProDOS Machine Language Interface,
there is a useful little program called the ProDOS Machine Language
Exerciser. It allows you to execute MLI calls from a menu; it has a
hexadecimal memory editor for reviewing and altering the contents of
buffers; and it has a catalog command.
Instructions for using the Machine
Language Exerciser program are in
Appendix D.
When you use it to make an MLI call, you request the call by its call
number, then you specify its parameter list, just as if you were coding
the call in a program. When you press [RETURN], the call is executed.
Using the Exerciser, you can try out sequences of MLI calls before
actually coding them.
Page 31
The MLI calls can be divided into three groups: housekeeping calls,
filing calls, and system calls.
The housekeeping calls perform operations such as creating, deleting,
and renaming, which cannot be used on open files. They are used to
change a file's status, but not the information that is in the file. They
refer to files by their pathnames, and each requires a temporary buffer,
which is used during execution of the call. The housekeeping calls are:
Page 32
The filing calls cause the transfer of data to or from files. The first
filing call, OPEN, must be used before any of the others can be used.
The OPEN call specifies a file by its pathname; the other filing calls
refer to files by the reference number returned by the OPEN call. In
addition, an input/output buffer (io_buffer), is allocated to the open
file; subsequent data transfers go through this buffer. The reference
number remains assigned and the buffer remains allocated until the file
is closed. The filing calls are:
Page 33
Page 34
System calls are those calls that are neither housekeeping nor filing
calls. They are used for getting the current date and time, for installing
and removing interrupt routines, and for reading and writing specific
blocks of a disk. The system calls are:
Page 35
Each of the following sections contains a description of a housekeeping
call, including its parameters and the possible errors that may be
returned.
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 7 |
+---+---+---+---+---+---+---+---+
1 | pathname (low) |
2 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
3 | access (1-byte value) |
+---+---+---+---+---+---+---+---+
4 | file_type (1-byte value) |
+---+---+---+---+---+---+---+---+
5 | aux_type (low) |
6 | (2-byte value) (high) |
+---+---+---+---+---+---+---+---+
7 | storage_type (1-byte value) |
+---+---+---+---+---+---+---+---+
8 | create_date (byte 0) |
9 | (2-byte value) (byte 1) |
+---+---+---+---+---+---+---+---+
A | create_time (byte 0) |
B | (2-byte value) (byte 1) |
+---+---+---+---+---+---+---+---+
Every disk file except the volume directory file must be created using
this call. There are two organizationally distinct types of file storage:
tree structure (storage_type = $1), used for standard files; and linked
list (storage_type = $D), used for directory files.
Pathname specifies the name of the file to be created and the directory
in which to insert an entry for the new file. One block (512 bytes) of
disk space is allocated, and the entry's key_pointer field is set to
indicate that block. Access, in most cases, should be set to $E3 (full
access permitted). File_type and aux_type may be anything, but it is
strongly recommended that conventions be followed (see below).
Page 36
Parameters
7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |D |RN|B |Reserved|W |R | +--+--+--+--+--+--+--+--+ D: Destroy enable bit RN: Rename enable bit B: Backup needed bit W: Write enable bit R: Read enable bitFor all bits, 1 = enabled, 0 = disabled. Bits 2
Page 37
File Type Preferred Use $00 Typeless file (SOS and ProDOS) $01 Bad block file $02 * Pascal code file $03 * Pascal text file $04 ASCII text file (SOS and ProDOS) $05 * Pascal data file $06 General binary file (SOS and ProDOS) $07 * Font file $08 Graphics screen file $09 * Business BASIC program file $0A * Business BASIC data file $0B * Word Processor file $0C * SOS system file $0D,$0E * SOS reserved $0F Directory file (SOS and ProDOS) $10 * RPS data file $11 * RPS index file $12 * AppleFile discard file $13 * AppleFile model file $14 * AppleFile report format file $15 * Screen library file $16-$18 * SOS reserved $19 AppleWorks Data Base file $1A AppleWorks Word Processor file $1B AppleWorks Spreadsheet file $1C-$EE Reserved $EF Pascal area $F0 ProDOS added command file $F1-$F8 ProDOS user defined files 1-8 $F9 ProDOS reserved $FA Integer BASIC program file $FB Integer BASIC variable file $FC Applesoft program file $FD Applesoft variables file $FE Relocatable code file (EDASM) $FF ProDOS system file
Note: The file types marked with a * in the above list apply to
Apple III SOS only; they are not used by ProDOS. For the file_types
used by Apple III SOS only, refer to the SOS Reference Manual.
Page 38
byte 1 byte 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| Year | Month | Day |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
byte 1 byte 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
|0 0 0| Hour | |0 0| Minute |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
See Chapter 6 for information about the
use of ProDOS with a clock/calendar
card.
Page 39
Possible Errors
$27 - I/O error
$2B - Disk write protected
$40 - Invalid pathname syntax
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
$47 - Duplicate filename
$48 - Overrun error: not enough disk space
$49 - Directory full
-- ProDOS can have no more than 51 files in a volume directory.
$4B - Unsupported storage_type
$53 - Invalid parameter
$5A - Bit map disk address is impossible
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 1 |
+---+---+---+---+---+---+---+---+
1 | pathname (low) |
2 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
Deletes the file specified by pathname by removing its entry from the
directory that owns it, and by returning its blocks to the volume bit
map. Volume directory files and open files cannot be destroyed.
Subdirectory files must be empty before they can be destroyed.
Page 40
Parameters
Possible Errors
$27 - I/O error
$2B - Disk write protected
$40 - Invalid pathname syntax
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
$4A - Incompatible file format
$4B - Unsupported storage_type
$4E - Access error: destroy not enabled
$50 - File is open: request denied
$5A - Bit map disk address is impossible
Page 41
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 2 |
+---+---+---+---+---+---+---+---+
1 | pathname (low) |
2 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
3 | new_pathname (low) |
4 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
Changes the name of the file specified by pathname to that specified
by new_pathname. Both pathname and new_pathname must be
identical except for the rightmost filename (they must indicate files in
the same directory). For example, the path /EGG/ROLL can be
renamed /EGG/PLANT, but not /JELLY/ROLL or /EGG/DRUM/ROLL.
Parameters
Possible Errors
$27 - I/O error
$2B - Disk write protected
$40 - Invalid pathname syntax
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
Page 42
$47 - Duplicate filename
$4A - Incompatible file format
$4B - Unsupported storage_type
$4E - Access error: rename not enabled
$50 - File is open: request denied
$57 - Duplicate volume
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 7 |
+---+---+---+---+---+---+---+---+
1 | pathname (low) |
2 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
3 | access (1-byte value) |
+---+---+---+---+---+---+---+---+
4 | file_type (1-byte value) |
+---+---+---+---+---+---+---+---+
5 | aux_type (low) |
6 | (2-byte value) (high) |
+---+---+---+---+---+---+---+---+
7 | |
8 | null_field (3 bytes) |
9 | |
+---+---+---+---+---+---+---+---+
A | mod_date (byte 0) |
B | (2-byte value) (byte 1) |
+---+---+---+---+---+---+---+---+
C | mod_time (byte 0) |
D | (2-byte value) (byte 1) |
+---+---+---+---+---+---+---+---+
Modifies information in the specified file's entry field. This call can be
performed when the file is either open or closed. However, new access
attributes are not used by an open file until the next time the file is
opened (that is, this call doesn't modify existing file control blocks).
You should use the GET_FILE_INFO call to read a file's attributes
into a parameter list, modify them as needed, and then use the same
parameter list for the SET_FILE_INFO call.
Page 43
Parameters
7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |D |RN|B |Reserved|W |R | +--+--+--+--+--+--+--+--+ D: Destroy enable bit RN: Rename enable bit B: Backup needed bit W: Write enable bit R: Read enable bit
For all bits, 1 = enabled, 0 = disabled. Bits 2
through 4 are used internally and should be set
to 0. Usually access should be set to $C3.
If the file is destroy, rename, and write enabled
it is unlocked. If all three are disabled, it is
locked. Any other combination of access bits is
called restricted access.
The backup bit (B) is set by this call.
Page 44
File Type Preferred Use $00 Typeless file (SOS and ProDOS) $01 Bad block file $02 * Pascal code file $03 * Pascal text file $04 ASCII text file (SOS and ProDOS) $05 * Pascal data file $06 General binary file (SOS and ProDOS) $07 * Font file $08 Graphics screen file $09 * Business BASIC program file $0A * Business BASIC data file $0B * Word Processor file $0C * SOS system file $0D,$0E * SOS reserved $0F Directory file (SOS and ProDOS) $10 * RPS data file $11 * RPS index file $12 * AppleFile discard file $13 * AppleFile model file $14 * AppleFile report format file $15 * Screen library file $16-$18 * SOS reserved $19 AppleWorks Data Base file $1A AppleWorks Word Processor file $1B AppleWorks Spreadsheet file $1C-$EE Reserved $EF Pascal area $F0 ProDOS added command file $F1-$F8 ProDOS user defined files 1-8 $F9 ProDOS reserved $FA Integer BASIC program file $FB Integer BASIC variable file $FC Applesoft program file $FD Applesoft variables file $FE Relocatable code file (EDASM) $FF ProDOS system file
Note: The file types marked with a * in the above list apply to
Apple III SOS only; they are not used by ProDOS. For the file_types
used by Apple III SOS only, refer to the SOS Reference Manual.
Page 45
byte 1 byte 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| Year | Month | Day |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
byte 1 byte 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
|0 0 0| Hour | |0 0| Minute |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
See Chapter 6 for information about the
use or ProDOS with a clock/calendar
card.
Possible Errors
$27 - I/O error
$2B - Disk write protected
$40 - Invalid pathname syntax
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
$4A - Incompatible file format
$4B - Unsupported storage_type
$4E - Access error: file not write enabled
$53 - Invalid value in parameter list
$5A - Bit map disk address is impossible
Page 46
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = $A |
+---+---+---+---+---+---+---+---+
1 | pathname (low) |
2 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
3 | access (1-byte result) |
+---+---+---+---+---+---+---+---+
4 | file_type (1-byte result) |
+---+---+---+---+---+---+---+---+
5 | aux_type (low) | *
6 | (2-byte result) (high) |
+---+---+---+---+---+---+---+---+
7 | storage_type (1-byte result) |
+---+---+---+---+---+---+---+---+
8 | blocks used (low) | *
9 | (2-byte result) (high) |
+---+---+---+---+---+---+---+---+
A | mod_date (byte 0) |
B | (2-byte result) (byte 1) |
+---+---+---+---+---+---+---+---+
C | mod_time (byte 0) |
D | (2-byte result) (byte 1) |
+---+---+---+---+---+---+---+---+
E | create_date (byte 0) |
F | (2-byte result) (byte 1) |
+---+---+---+---+---+---+---+---+
10 | create_time (byte 0) |
11 | (2-byte result) (byte 1) |
+---+---+---+---+---+---+---+---+
* When file information about a volume directory is requested, the
total number of blocks on the volume is returned in the aux_type field
and the total blocks for all files is returned in blocks_used.
GET_FILE_INFO returns the information that is stored in the
specified file's entry field. This call can be performed whether the file
is open or closed. If the SET_FILE_INFO call is used to change the
access while the file is open, the change does not take effect until the
file has been closed and reopened.
Page 47
Parameters
7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |D |RN|B |Reserved|W |R | +--+--+--+--+--+--+--+--+ D: Destroy enable bit RN: Rename enable bit B: Backup needed bit W: Write enable bit R: Read enable bit
For all bits, 1 = enabled, 0 = disabled. Bits 2
through 4 are not used. Usually access should be
set to $C3.
If the file is destroy, rename, and write enabled
it is unlocked. If all three are disabled, it is
locked. Any other combination of access bits is
called restricted access.
Page 48
File Type Preferred Use $00 Typeless file (SOS and ProDOS) $01 Bad block file $02 * Pascal code file $03 * Pascal text file $04 ASCII text file (SOS and ProDOS) $05 * Pascal data file $06 General binary file (SOS and ProDOS) $07 * Font file $08 Graphics screen file $09 * Business BASIC program file $0A * Business BASIC data file $0B * Word Processor file $0C * SOS system file $0D,$0E * SOS reserved $0F Directory file (SOS and ProDOS) $10 * RPS data file $11 * RPS index file $12 * AppleFile discard file $13 * AppleFile model file $14 * AppleFile report format file $15 * Screen library file $16-$18 * SOS reserved $19 AppleWorks Data Base file $1A AppleWorks Word Processor file $1B AppleWorks Spreadsheet file $1C-$EE Reserved $EF Pascal area $F0 ProDOS added command file $F1-$F8 ProDOS user defined files 1-8 $F9 ProDOS reserved $FA Integer BASIC program file $FB Integer BASIC variable file $FC Applesoft program file $FD Applesoft variables file $FE Relocatable code file (EDASM) $FF ProDOS system file
Note: The file types marked with a * in the above list apply to
Apple III SOS only; they are not used by ProDOS. For the file_types
used by Apple III SOS only, refer to the SOS Reference Manual.
Page 49
byte 1 byte 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| Year | Month | Day |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
byte 1 byte 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
|0 0 0| Hour | |0 0| Minute |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
Page 50
byte 1 byte 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
| Year | Month | Day |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
byte 1 byte 0
7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
|0 0 0| Hour | |0 0| Minute |
+-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
See Chapter 6 for information about the
use of ProDOS with a clock/calendar
card.
Possible Errors
$27 - I/O error
$40 - Invalid pathname syntax
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
$4A - Incompatible file format
$4B - Unsupported storage_type
$53 - Invalid value in parameter list
$5A - Bit map address is impossible
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 2 |
+---+---+---+---+---+---+---+---+
1 | unit_num (1-byte value) |
+---+---+---+---+---+---+---+---+
2 | data_buffer (low) |
3 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
This command can be used to determine the names of all ProDOS (or
SOS) volumes that are currently mounted (such as disks in disk
drives), or it can be used to determine the name of a disk in a
specified slot and drive.
Page 51
When unit_num is 0, this command places a list of the volume names,
slot numbers, and drive numbers of all mounted disks into the
256 byte buffer pointed to by data_buffer. When a specific unit_num
is requested, only 16 bytes need be set aside for the buffer. The format
of the returned information is described below.
The volume names are placed in the list in volume search order, as
described in section 3.2.
Parameters
7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |Dr| Slot | Unused | +--+--+--+--+--+--+--+--+
For drive 1, Dr = 0; for drive 2, Dr = 1. Slot
specifies the device's slot number (1-7). If
unit_num is 0, all mounted disks are scanned.
Here are possible values for unit_num:
Slot: 7 6 5 4 3 2 1 Drive 1: 70 60 50 40 30 20 10 Drive 2: F0 E0 D0 C0 B0 A0 90
Page 52
7 6 5 4 3 2 1 0 +--+--+--+--+--+--+--+--+ |dr| slot | name_len | +--+--+--+--+--+--+--+--+Bit 7 specifies drive 1 (Dr = 0) or drive 2 (Dr =
Remember: ON_LINE returns volume names that are not preceded by
slashes. Remember to put a slash in front of the name before you use
it in a pathname.
Possible Errors
$27 - I/O error
$28 - Device not connected
$2E - Disk switched: File still open on other disk
$45 - Volume directory not found
$52 - Not a ProDOS disk
$55 - Volume Control Block full
$56 - Bad buffer address
$57 - Duplicate volume
When an error pertains to a specific drive, the error code is returned in
the second byte of the record corresponding to that drive, as described
above. In such cases, the call completes with the accumulator set to 0,
and the carry flag clear. Only errors $55 and $56 are not drive specific.
Page 53
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 1 |
+---+---+---+---+---+---+---+---+
1 | pathname (low) |
2 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
Sets the system prefix to the indicated directory. The pathname may
be a full pathname or a partial pathname. The system prefix can be
set to null by indicating a pathname with a count of zero. The prefix
must be no longer than 64 characters. When ProDOS is started up, the
system prefix is set to the name of the volume in the startup drive.
The MLI verifies that the requested prefix directory is on an on-line
volume before accepting it.
Parameters
Possible Errors
$27 - I/O error
$40 - Invalid pathname syntax
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
$4A - Incompatible file format
$4B - Unsupported storage_type
$5A - Bit map disk address is impossible
Page 54
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 1 |
+---+---+---+---+---+---+---+---+
1 | data_buffer (low) |
2 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
Returns the current system prefix. If the system prefix is set to null
(no prefix), then a count of 0 is returned. Otherwise the returned
prefix is preceded by a length byte and bracketed by slashes. Examples
are $7/APPLE/ and $D/APPLE/BYTES/. Each character in the prefix
is returned with its high bit cleared.
The buffer pointed to by data_buffer is assumed to be 64 bytes long.
Parameters
Possible Error
$56 - Bad buffer address
Page 55
Each of the following sections contains a description of a filing
command, including its parameters and the possible errors that may be
returned.
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 3 |
+---+---+---+---+---+---+---+---+
1 | pathname (low) |
2 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
3 | io_buffer (low) |
4 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
5 | ref_num (1-byte result) |
+---+---+---+---+---+---+---+---+
OPEN prepares a file to be read or written. It creates a file control
block that keeps track of the current (open) characteristics of the file
specified by pathname, it sets the current position in the file to zero,
and it returns a reference number by which the other commands in
this section must refer to the file.
The I/O buffer is used by the system for the entire time the file is
open. It contains information about the file's structure on the disk, and
it contains the current 512-byte block being read or written. It is used
until the file is closed, and therefore should not be modified directly by
the user. A maximum of eight files can be open at a time.
When a file is opened it is assigned a level, from 0 to $F, depending
on the current value of the LEVEL location ($BF94) in the system
global page. When the CLOSE command is issued with a ref_num of 0,
all files at or above the current level are closed. Thus, a CLOSE with a
ref_num of 0 and a level of 0 will close all open files.
Refer to Section 2.1.7, "File Levels," for
an example of the use of level.
Warning
Once a file has been opened, that file's disk must not be removed
from its drive and replaced by another. The system does not
check the identity of a volume before writing on it. A system
program should check a volume's identity before writing to it.
Page 56
Parameters
Refer to Appendix B for more
information on directory file blocks,
index blocks, and data blocks.
Possible Errors
$27 - I/O error
$40 - Invalid pathname syntax
$42 - File Control Block table full
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
$4B - Unsupported storage_type
$50 - File is open
$53 - Invalid value in parameter list
$56 - Bad buffer address
$5A - Bit map disk address is impossible
Page 57
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 3 |
+---+---+---+---+---+---+---+---+
1 | ref_num (1-byte value) |
+---+---+---+---+---+---+---+---+
2 | enable_mask (1-byte value) |
+---+---+---+---+---+---+---+---+
3 | newline_char (1-byte value) |
+---+---+---+---+---+---+---+---+
This call allows you to enable or disable newline read mode for any
open file. When newline is disabled, a read request terminates when
the requested number of characters has been read, or when the end of
file is encountered. When newline is enabled, a read request will also
terminate if the newline character (newline_char) is read.
Each character read is first transferred to the user's data buffer. Next
it is ANDed with the enable_mask and compared to the newline_char.
If there is a match, the read is terminated. For example, if
enable_mask is $7F and newline_char is $0D (ASCII CR), either a
$0D or $8D matches and terminates input. This process does not
change the character.
Parameters
Possible Error
$43 - Invalid reference number
Page 58
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 4 |
+---+---+---+---+---+---+---+---+
1 | ref_num (1-byte value) |
+---+---+---+---+---+---+---+---+
2 | data_buffer (low) |
3 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
4 | request_count (low) |
5 | (2-byte value) (high) |
+---+---+---+---+---+---+---+---+
6 | trans_count (low) |
7 | (2-byte result) (high) |
+---+---+---+---+---+---+---+---+
Tries to transfer the requested number of bytes (request_count),
starting at the current position (MARK) of the file specified by
ref_num to the buffer pointed to by data_buffer. The number of bytes
actually transferred is returned in trans_count.
If newline read mode is enabled and a newline character is
encountered before request_count bytes have been read, then the
trans_count parameter is set to the number of bytes transferred,
including the newline byte.
If the end of file is encountered before request_count bytes have been
read, then trans_count is set to the number of bytes transferred. The
end of file error ($4C) is returned if and only if zero bytes were
transferred (trans_count = 0).
Page 59
Parameters
Possible Errors
$27 - I/O error
$43 - Invalid reference number
$4C - End of file has been encountered
$4E - Access error: file not read enabled
$56 - Bad buffer address
$5A - Bit map address is impossible
Page 60
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 4 |
+---+---+---+---+---+---+---+---+
1 | ref_num (1-byte value) |
+---+---+---+---+---+---+---+---+
2 | data_buffer (low) |
3 | (2-byte pointer) (high) |
+---+---+---+---+---+---+---+---+
4 | request_count (low) |
5 | (2-byte value) (high) |
+---+---+---+---+---+---+---+---+
6 | trans_count (low) |
7 | (2-byte result) (high) |
+---+---+---+---+---+---+---+---+
Tries to transfer a specified number of bytes (request_count) from the
buffer pointed to by data_buffer to the file specified by ref_num
starting at the current position (MARK) in the file. The actual number
of bytes transferred is returned in trans_count.
The file position is updated to position + trans_count. If necessary,
additional data and index blocks are allocated to the file, and EOF is
extended.
See Appendix B for an explanation of
data and index blocks.
Page 61
Parameters
Possible Errors
$27 - I/O error
$2B - Disk write protected
$43 - Invalid reference number
$48 - Overrun error: not enough disk space
$4E - Access error: file not write enabled
$56 - Bad buffer address
$5A - Bit map disk address is impossible
Page 62
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 1 |
+---+---+---+---+---+---+---+---+
1 | ref_num (1-byte value) |
+---+---+---+---+---+---+---+---+
This call is used to release all resources used by an open file. The file
control block is released. If necessary, the file's buffer (io_buffer) is
emptied to the file and the directory entry for the file is updated. Until
that ref_num is assigned to another open file, subsequent filing calls
using that ref_num will fail.
If ref_num equals zero ($0), all open files at or above the current
level are closed. For example, if you open files at levels 0, 1, and 2,
set the level to 1, and then use CLOSE with ref_num set to 0, the
files at level 1 and 2 are closed, but the ones at level 0 are not.
The level is a value from 0 to $F that is stored in the LEVEL location
($BFD8) of the system global page. It is only changed by system
programs, and it is used by OPEN and CLOSE.
This call causes the backup bit to be set.
Parameters
Possible Errors
$27 - I/O error
$2B - Disk write protected
$43 - Invalid reference number
$5A - Bit map disk address is impossible
Page 63
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
0 | param_count = 1 |
+---+---+---+---+---+---+---+---+
1 | ref_num (1-byte value) |
+---+---+---+---+---+---+---+---+
The file's write buffer (io_buffer) is emptied to the file, and the file's
directory is updated. If ref_num equals zero ($0), then all open files at
or above the current level are flushed.
The backup bit is set by this call.
FLUSH is further explained in Chapter 2,
section "Closing and Flushing Files."
Parameters