Apple IIgs ProDOS 16 Reference Manual

288 Pages·2009·55.49 MB·English

APPLE
PROGRAMMER'S
AND DEVELOPER'S
ASSOCIATION
290 SW 43rd. Street
Renton, WA 98055
206-251-6548
AppiellGs
ProDOS 16
Reference
Manual
Includes System Loader
November 13, 1986
APDA#: K2SP16

Apple IIGS ProDOS 16 Reference
Includes System Loader
APDA Draft
November 13, 1986
Apple Technical Publications
This docwnent contains preliminary information. It cines not include
• final editorial corrections
• final art work
• an index
It may not include final technical changes.
Copyright © 1986 Apple Computer, Inc. All rights reserved.
-.
.. APPLE COMPUTER, INC.
This manual is copyrighted by
Apple or by Apple's suppliers,
wilh all righlS reserved. Under
the copyright laws, this manual
may not be copied, in whole or
in part, without the written
consent of Apple Computer, Inc.
This exception does not allow
copies [0 be made for others,
whethcr or not sold, but all of
the material purchased may be
sold, given, or lent to another
person. Under the law, copying
includes translating into another
language.
© Apple Computer, Inc., 1986
20525 Mariani Avenue
Cupertino, California 95014
[phone]
Apple, the Apple logo,
AppleTalk, Disk II, and ProDOS
are registered trademarks of
Apple Computer, Inc.
Apple IIGS, AppleWorks,
Macintosh, and Unidisk are
trademarks of Apple Computer,
Inc.
Simultnneously published in the
United S taleS and Canada.
Contents
1 Preface
1 Road map to the Apple IIGS technical manuals
3 How to use this manual
3 Other materials you'll need
3 Hardware and software
4 Publications
5 Notations and conventions
5 Terminology
5 Typographic conventions
6 Watch for these
7 Part I: How ProDOS 16 Works
9 Chapter 1. About ProD OS 16
9 Background
9 What is ProDOS 16?
10 Programming levels in the Apple IIGS
11 Disks, volumes, and files
12 Memory use
12 External devices
12 ProDOS 16 and ProDOS 8
13 Upward compatibility
13 DO»lllward compatibility
13 Eliminated ProDOS 8 system calls
14 New ProDOS 16 system calls
14 Other features
15 Summary of ProDOS 16 features
17 Chapter 2. ProDOS 16 Files
17 U sing files
17 Filenames
17 Pathnames
19 Creating files
20 Opening files
20 The EOF and Mark
21 Reading and writing files
22 Closing and flushing files
APDA Drqft 1 11113186
Apple II GS ProDGS 16 Reference
22 File levels
23 File format and organization
23 Directory fIles and standard files
24 File organization
25 Sparse files
27 Chapter 3. ProDOS 16 and Apple IIGS Memory
27 Apple IIGS memory configurations
28 Special memory and shadowing
28 ProDOS 16 and System Loader memory map
29 Entry points and fLXed locations
30 Memory management
30 The Memory Manager
31 Pointers and handles
32 How an application obtains memory
35 Chapter 4. ProDOS 16 and External Devices
35 B lock devices
36 Character devices
36 Accessing devices
36 Named devices
36 Last device accessed
37 Block read and block write
37 Formatting a disk
37 Number of online devices
37 Device search at startup
38 Volume control blocks
38 Interrupt handling
40 U nclairned interrupts
41 Chapter 5. ProDOS 16 and the Operating Environment
41 Apple nGS system disks
41 Complete system disk
42 The SYSTEM.SETUP! subdirectory
43 Application system disks
44 System startup
44 Boot initialization
45 Startup program selection
47 Starting and quitting applications
47 PQUIT
47 Standard ProDOS 8 QUIT call
47 Enhanced ProDOS 8 QUIT call
48 ProDOS 16 QUIT call
APDA Draft 11 11113186
Apple lles ProD OS 16 Reference
48 QUIT procedure
50 Machine state at application launch
'--
51 Pathname prefIxes
53 Initial ProDOS 16 prefIx values
54 ProD OS 8 prefIx and pathname convention
55 Tools, finnware, and system software
55 The Memory Manager
56 The System Loader
56 The Scheduler
56 The User 10 Manager
57 The System Failure Manager
59 Chapter 6. Programming With ProDOS 16
59 Application requirements
60 Stack and direct page
60 Automatic allocation of stack and direct page
60 DefInition during program development
61 Allocation at run time
62 ProD OS 16 default stack and direct page
62 Manual allocation of stack and direct page
62 Managing system resources
63 Global variables
63 PrefIxes
64 Native mode and emulation mode
64 Setting initial machine confIguration
64 Allocating memory
64 Loading another program
65 U sing interrupts
66 Accessing devices
66 File creation/modifIcation date and time
67 Revising a ProDOS 8 application for ProD OS 16
68 Memory management
68 Hardware confIguration
69 Converting system calls
69 Modifying interrupt handlers
69 Converting stack and zero page
69 Compilation/assembly
70 Apple IIGS Programmer's Workshop
70 Human Interface Guidelines
73 Chapter 7. Adding Routines to ProDOS 16
73 Interrupt handlers
APDA Draft ill 11113186
Apple IIGS ProDDS 16 Reference
73 Interrupt handler conventions
74 In stalling interrupt handlers
74 Making operating system calls during interrupts
77 Part II: ProDOS 16 System Call Reference
79 Chapter 8. Making ProD OS 16 Calls
79 The call block
80 The parameter block
80 Types of parameters
81 Parameter block format
82 Setting up a parameter block in memory
82 Register values
83 Comparison with the ProDOS 8 call method
83 The ProDOS 16 Exerciser
84 Format for system call descriptions
8S Chapter 9. File Housekeeping Calls
86 CREATE ($0 I)
90 DESTROY ($02)
91 CHANGEYATH($04)
93 SET_FILE_INFO ($05)
97 GET_FILE_INFO ($06)
101 VOLUME ($08)
104 SET_PREFIX ($09)
106 GETYREFIX ($OA)
107 CLEAR_BACKUP_ BIT ($OB)
109 Chapter 10. File Access Calls
110 OPEN ($10)
112 NEWLINE ($11)
114 READ ($12)
116 WRITE ($13)
118 CLOSE ($14)
119 FLUSH ($15)
120 SET_MARK ($16)
121 GET_MARK ($17)
122 SET_EOF ($18)
123 GELEOF ($19)
124 SET_LEVEL ($IA)
125 GET_LEVEL ($IB)
APDADrajt IV Il!l3186
Apple lIes ProD OS 16 Reference
127 Chapter 11. Device Calls
'~-- 128 GET_DEV _NUM ($20)
129 GET_LAST_DEV ($21)
130 READ_BLOCK ($22)
131 WRITE_BLOCK ($23)
132 FORMAT ($24)
135 Chapter 12. Environment Calls
136 GET_NAME ($27)
137 GET_BOOT_V OL ($28)
138 QUIT ($29)
141 GET_VERSION ($2A)
143 Chapter 13. Interrupt Control Calls
144 ALLOC_INTERRUPT ($31)
145 DEALLOC_INTERRUPT ($32)
147 Part III: The System Loader
149 Chapter 14. Introduction to the System Loader
"-
149 What is the System Loader?
150 Loader tenninology
151 Interface with the Memory Manager
152 Loading a relocatable segment
152 Load-fIle structure
153 Relocation
155 Chapter 15. System Loader Data Tables
155 Memory Segment Table
156 Jump Table
157 Creation of a Jump Table entry
158 Modification at load time
159 Use during execution
159 Jump Table diagram
161 Pathname Table
163 Mark List
APDA Draft v llfJ3/86
Apple II GS ProDOS 16 Reference
165 Chapter 16. Programming With the System Loader
165 Static programs
165 Programming with dynamic segments
166 Programming with run-time libraries
167 User control of segment loading
167 Designing a controlling program
169 Shutting down and restarting applications
169 Summary: loader calls categorized
171 Chapter 17. System Loader Calls
171 intrOduction
171 How calls are made
172 Parameter types
172 Format for System Loader call descriptions
17 4 Loader Initialization ($0 I)
175 Loader Startup ($02)
176 Loader Shutdown ($03)
177 Loader Version ($04)
179 Loader Reset ($05)
180 Loader Status ($06)
181 Initial Load ($09)
.- ,
184 Restan ($OA)
186 Load Segment by Number ($OB)
189 Unload Segment by Number ($OC)
191 Load Segment by Name ($00)
193 Unload Segment ($OE)
195 Get Load Segment Info ($OF)
197 Get User ID ($10)
199 Get Pathname ($11)
201 User Shutdown ($12)
203 Jump Table Load
205 Cleanup
207 Appendixes
209 Appendix A. ProDOS 16 File Organization
209 Organization of information on a volwne
210 Format and organization of directory files
211 Pointer fields
211 Volume directory headers
214 Subdirectory headers
APDA Draft vi 11113186