P8 Tech Ref Chapter 1 - wiki.apple2.org

P8 Tech Ref Chapter 1

Jump to: navigation, search

ProDOS 8 Technical

Reference Manual

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.


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 ProDOS User's Manual tells how to copy, rename, and remove ProDOS files using the ProDOS Filer program, and how to move files from DOS disks to ProDOS disks using the DOS-ProDOS Conversion program.

BASIC Programming With ProDOS describes ProDOS to a user of the BASIC system program. It explains how to store information on ProDOS disks and to retrieve information from ProDOS disks using Applesoft BASIC.

This manual, the ProDOS Technical Reference Manual, explains how to use the machine-language routines upon which the Filer program, the DOS-ProDOS Conversion program, and the BASIC system program are based. Appendix A reveals a more technical side of the BASIC system program.

About ProDOS

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.

This manual

  • describes the files that these routines create and access
  • tells how each of the routines is used
  • explains how to combine the routines into an application program
  • tells how to write and install routines to be used when an interrupt is detected
  • tells how to write a routine that automatically reads the date from a clock/calendar card when a file is created or modified
  • explains how to attach other devices to ProDOS.

Some advantages of programs written using these ProDOS machine-language routines are:

  • They store information on disks using a hierarchical directory structure.
  • They are able to access all disk devices manufactured by Apple Computer, Inc. for the Apple II.
  • They can read data from a Disk II drive at a rate of approximately eight kilobytes per second (compared to one kilobyte per second for DOS).
  • They are interruptible.
  • They have the same disk and directory format as Apple III SOS disks.
  • Calls to ProDOS are very similar to calls to SOS; programs can be readily developed for both the Apple II and the Apple III. Appendix C explains the similarities and differences between ProDOS and SOS.

About This Manual

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.

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.

What These Mean

By the Way: Text set off in this manner presents sidelights or interesting points of information.


Text set off in this manner -- and with a tag in the margin -- presents important information.


Warnings like this indicate potential problems or disasters.

About the Apple IIc Although the Apple IIc has no slots for peripheral cards, it is configured as if it were an Apple IIe with

  • 128 Kbytes of RAM
  • serial I/O cards in slots 1 and 2
  • an 80-column text card in slot 3
  • a mouse (or joystick) card in slot 4
  • a disk controller (for two disk drives) in slot 6.

Chapter 1 - Introduction

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.

What Is ProDOS?

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 )
 +------------------+  From File
 |  System Program  |  xxx.SYSTEM
 +------------------+  From File
 | Operating System |  PRODOS
 +------------------+  Disk Drives,
 |     Hardware     |  Memory,
 +------------------+  and Slots

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.

Use of Disk Drives

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 placed on the disk. It is called the disk's volume directory file, and it has the same name as the volume itself. Although it is initially empty, a volume directory file has a maximum capacity of 51 files.

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.

Volume and File Characteristics

Programs that make filing calls to the ProDOS Machine Language Interface can take advantage of the following features:

  • Access to all ProDOS formatted disks; maximum capacity 32 megabytes on a volume.
  • Files can be stored in up to 64 levels of readable directory and subdirectory files.
  • A volume directory holds up to 51 entries.
  • Subdirectories can hold as many files as needed; they become larger as files are added to them.
  • There are over 60 distinct file identification codes; some are predefined, others can be defined by the system program. For compatibility, existing file types should be used.
  • Up to eight files can be open for access simultaneously.
  • A file can hold up to 16 megabytes of data.
  • Disks can be accessed by block number as well as by file.
  • If the data in a file is not sequential, the logical size of the file can be bigger than the amount of disk space used.

The use of files is described in Chapter 2; their format is given in Appendix B.

Use of Memory

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.

Use of Interrupt Driven Devices

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:

1. Place an interrupt handling routine into memory. 2. Mark the block of memory as used. 3. Use the MLI call that adds interrupt routines to the system. 4. Enable the device.

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:

1. Disable the device. 2. Unmark its block in memory 3. Use the MLI call that removes interrupt routines from the system.


Failure to follow these procedures in sequence may cause system error. The use of interrupt driven devices is described in Chapter 6.

Use of Other Devices

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.


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.

Figure 1-3. The Levels of ProDOS
 USER                                      ( User )                                        IMA.USER
 - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - -
 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.

Content is available under Creative Commons Attribution-NonCommercial-ShareAlike unless otherwise noted.
Powered by MediaWiki