💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › System › GSOS.P8.Anatomy › CO… captured on 2024-02-05 at 14:49:02.
⬅️ Previous capture (2023-01-29)
-=-=-=-=-=-=-
Table 4-3 A standard ProDOS 8 MLI error-handling subroutine
2 **~**********************************
3 * General-Purpose MLI Error Handler
4
5 * Copyright 1985-1988 Gary Little
6
7 * Last modified: August 26, 1988
8
9 *************************************
10 CMDADR EQU $BF9C ;Return address for MLI call
11
12 CROUT EQU $FD8E Print a CR
13 PRHEX EQU $FDDA
14 COUT EQU $FDED
15
16 ORG $300
17
0300: 48 18 ERROR PHA
19
0301: A0 00 20 LDY #0
0303: B9 2E 03 21 1 LDA ERRMSG,Y
0306: F0 06 22 BEQ 2
0308: 20 ED FD 23 JSR COUT
030B: C8 24 INY
030C: D0 F5 25 BNE 1
26
030E: 68 27 :2 PLA
030F: 20 DA FD 28 JSR PRHEX
29
0312: A0 00 30 LDY #0
0314: B9 38 03 31 :3 LDA ERRMSG1,Y
0317: F0 06 32 BEQ 4
0319: 20 ED FD 33 JSR COUT
031C: C8 34 INY
031D: D0 F5 35 BNE 3
36
031F: AD 9D BF 37 :4 LDA GMDADR+1
0322: 20 DA FD 38 JSR PRHEX
0325: AD 9C BF 39 LDA CMDADR
0328: 20 DA FD 40 JSR PRHEX
0328: 4C 8E FD 41 JMP CROUT
42
032E: 8D 43 ERRMSG DFB $8D
032F: CD CC C9 44 ASC "MLI ERROR $"
0332: A0 C5 D2 D2 CF D2 A0 A4
Print byte as two hex digits
;Standard output subroutine
Save error code on stack
;Print first part of message
;(always taken)
;Get error code back
and print it
;Print second part of message
;(always taken)
;Print high part of address
Print low part of address
033A: 00 45 DFB 0
0338: A0 CF C3 46 ERRMSG1 ASC
033E: C3 D5 D2 D2 C5 C4 A0 C1
0346: D4 A0 CC CF C3 C1 D4 C9
034E: CF CE A0 A4
0352: 00 47 DFB
OCCURRED AT LOCATION
0
GS/OS and ProDOS 8 Error Handling 81
appears on the screen, where xx is the two-digit hexadecimal error code, and yyyy is
the address the ProDOS 8 MlLI interpreter stored in CMDADR before trying to
execute the command. This address is 6 bytes past the JSR $BF00 instruction that
caused the error. You can easily adapt this program for use in a GS/OS environment.
Table 4-4 summarizes the system error codes which the GS/OS and ProDOS 8
command interpreters use. It also indicates the Applesoft error messages that lBASIC.
SYSTEM displays when it encounters an MLI error in a ProDOS 8 environment.
COMMAND DESCRIPTIONS
In the following sections, we examine, in alphabetical order, all the commands that
make up GS/OS and ProDOS 8. The GS/OS command name and number appear in a
box in the top left-hand corner of the first page of the command description; the
ProDOS 8 name and number appear in a box in the top right-hand corner. By
convention, ProDOS 8 names are all uppercase and may contain underscore charac-
ters; the corresponding GS/OS names contain both uppercase and lowercase charac-
ters and do not contain underscores.
Although many of the commands are available in both operating systems, some are
unique. If a box contains the word none, the command is not available for the
operating system to which the box corresponds.
Keep in mind that even where GS/OS and ProDOS 8 have commands that share
the same name, the entries in the parameter tables are of different sizes and may be
arranged in a different order. For example, GS/OS pointers are always 4 bytes long so
that any address in the 65816 memory space may be accessed; ProDOS 8 pointers are
only 2 bytes long, long enough to access any byte in the 6502 memory space.
Moreover, parameters that are 1 or 2 bytes long in a ProDOS 8 parameter table are
usually twice as long in the corresponding GS/OS parameter table.
The description of each command includes a summary of the command's GS/OS
and ProDOS 8 parameter tables. These tables indicate the correct order of the
parameters, the sizes of the parameters, and whether a parameter is an Input (I) or a
Result (R). An Input is a parameter that must be provided before using the command.
A Result (R) is a parameter that the command returns.
Class 0 and Class 1 Input Strings
Many commands require a pointer to a character string as an input parameter.
ProDOS 8 uses class 0 character strings, where the first byte in the string space
represents the length of the string (not including the length byte) and is followed by
the ASCII-encoded bytes representing the characters. GS/OS uses class 1 character
strings, where the first word in the string represents the length of the string. As with
class 0 input strings, the character string is represented by a sequence of ASCII-
encoded bytes.
In this book, an assembler macro called GSString is used to store a string preceded
by a length word. The STR macro stores a string preceded by a length byte.
82 GS/OS and ProDOS 8 Commands
Table 4-4 GS/OS and ProDOS 8 command error codes
BASIC.SYSTEM
Error Code Error Message Meaning
$00 [none] No error occurred.
$01 I/O ERROR The MLI command number is invalid.
$04 I/O ERROR An incorrect number of parameters value
was specified in the parameter table.
$07 [not applicable] GS/OS is busy. This error can occur if
you try to use GS/OS commands from
inside an interrupt handler.
$10 [not applicable] The specified device cannot be found.
GS/OS reports this error after a
GetDevNum command if it cannot locate
the device.
$11 [not applicable] The device reference number is invalid.
GS/OS reports this error if the device
number is not in its list of active devices.
$22 [not applicable] Bad GS/OS driver parameter.
$23 [not applicable] GS/OS Console Driver is not open.
$25 I/O ERROR The ProDOS 8 internal interrupt vector
table is full.
$27 I/O ERROR A disk I/O error occurred that prevented
the proper transfer of data. If you get this
error, the disk is probably irreparably
damaged. You will also get this error if
there is no disk in a 5.25-inch disk drive.
$28 NO DEVICE CONNECTED The specified disk drive device is not
present. This error occurs if you try to
access a second 5.25-inch drive when only
one drive is present, for example.
$2B WRITE PROTECTED A write operation failed because the disk
is write-protected.
$2E I/O ERROR An operation failed because a disk
containing an open file has been removed
from its drive.
Command Descriptions 83
Table 4-4 Continued
BASIC.SYSTEM
Error Code Error Message Meaning
$2F I/O ERROR The specified device is off-line. This error
occurs if there is no disk in a 3.5-inch drive.
$40 SYNTAX ERROR The pathname syntax is invalid because one
of the filenames or directory names speci-
fied does not follow the operating system
naming rules or because a partial pathname
was specified and a prefix is not active.
$42 NO BUFFERS AVAILABLE An attempt was made to open a ninth file.
ProDOS 8 allows only eight files to be open
at once.
$43 FILE NOT OPEN The file reference number is invalid. This
error occurs if the wrong reference number
is specified for an open file or if the
reference number for a closed file is used.
$44 PATH NOT FOUND The specified path was not found. This
means one of the subdirectory names, in an
otherwise valid pathname, does not exist.
$45 PATH NOT FOUND The specified volume directory was not
found. This means the volume directory
name, in an otherwise valid pathname, does
not exist. A common reason for this error is
changing a disk without changing the active
prefix.
$47 DUPLICATE FILE
NAME
$48 DISK FULL The disk is full. This error can occur during
a write operation when there are no free
blocks on the disk to hold the data.
84 GS/OS and ProDOS 8 Commands
ecified file was not found. This
~c~Du 0
means the last filename, in an otherwise
valid pathname, does not exist.
The specified filename already exists. This
error occurs when a file is being renamed
or created, and the new name specified is
already in use.
Table 4-4 Continued
BASIC.SYSTEM
Error Code Error Message Meaning
$49 DIRECTORY FULL The volume directory is full. Only 51 files
can be stored in the volume directory.
$4A I/O ERROR The format of the file specified is unknown
or is not compatible with the version of the
operating system being used.
$4B FILE TYPE MISMATCH The storage type code for the file is invalid
or not supported.
$4C END OF DATA An end-of-file condition was encountered
during a read operation.
$4D RANGE ERROR The specified value for Mark is out of
range. When Mark (the position-in-file)
pointer is being changed, it cannot be set
higher than EOF.
$4E FILE LOCKED The file cannot be accessed. This error
occurs when the action prohibited by the
access code byte is requested. This byte
controls rename, destroy, read, and write
operations. The error also occurs if you try
to destroy a directory file that is not empty.
$4F [not applicable] The size of the GS/OS class 1 output buffer
is too small.
$50 FILE BUSY The command is invalid because the file is
open. The OPEN, RENAME, and
DESTROY commands operate only on
closed files.
$51 I/O ERROR The directory count is wrong. This error
occurs if the file counter stored in the
directory header is different from the actual
number of files.
$52 I/O ERROR This is not a ProDOS disk. This error
occurs if the MLI senses a directory
structure inconsistent with ProDOS.
$53 INVALID PARAMETER A parameter is invalid because it is out of
the allowable range.
Command Descriptions 85
Table 4-4 Continued
BASIC.SYSTEM
Error Code Error Message
$54 [not applicable]
$55 I/O ERROR
$56 NO BUFFERS AVAILABLE
$57 I/O ERROR
$58 [not applicable]
$59 [not applicable]
$5A I/O ERROR
$5B [not applicable]
$5C [not applicable]
86 GS/OS and ProDOS 8 Commands
Meaning
Out of memory.
The volume control block table is full. This
error occurs if eight files on eight separate
disk drives are open and the ON LINE
command is called for a drive having no
open files.
The buffer address is invalid because it
conflicts with memory areas marked as in
use by the ProDOS 8 system bit map or
because it does not start on a page
boundary.
Disks are on line that have the same
volume directory name.
The specified device is not a block device.
Certain commands work with block-
structured devices only.
The level parameter (passed to the GS/OS
SetLevel command) is out of range.
The volume bit map indicates that a block
beyond the number available on the disk
device is free for use. This error occurs if
the volume bit map has been damaged.
Illegal pathname change. This error occurs
if the pathnames specified in the GS/OS
ChangePath command refer to two different
volumes. You can move files only between
directories on the same volume.
The specified file is not an executable
system file. GS/OS reports this error if you
attempt to use Quit to pass control to a file
that is not a GS/OS system file (S16, code
$B3) (EXE, code $B5) or a ProDOS 8
system file (SYS, code $FF).
Table 4-4 Continued
BASIC.SYSTEM
Error Code Error Message Meaning
$5D [not applicable] The operating system specified is not
available or not supported. GS/OS returns
this error if you try to run a ProDOS 8
system program when the SYSTEM/P8
file is not on the system disk.
$5E [not applicable] /RAM cannot be removed.
$5F [not applicable] Quit Return Stack overflow. GS/OS returns
this error if you try to push another
program ID on the Quit Return Stack
(using the Quit command) when the stack is
already full.
$61 [not applicable] End of directory. This error can be
returned only by the GS/OS GetDirEntry
command.
$62 [not applicable] Invalid class number.
$64 [not applicable] Invalid file system ID code.
$65 [not applicable] Invalid FST operation.
NOTE: If the GS/OS Quit command results in an error, the error code is not returned to the application.
Instead, the code appears in an interactive dialog box on the screen.
Class 0 and Class 1 Output Buffers
Even though a pointer to a string or a buffer area may be marked as a result in a
parameter table, ProDOS 8 or GS/OS does not actually return the pointer. Instead, it
returns data in the buffer pointed to by the pointer.
For ProDOS 8, it is the responsibility of the application to preallocate a buffer of
the proper size and provide a pointer to it before calling a command. If you don't
allocate a large enough buffer, data immediately following the buffer will be overwrit-
ten. Such a buffer is called a class 0 output buffer.
GS/OS uses class 1 output buffers to avoid the possibility of the operating system
unexpectedly overwriting data areas if the preallocated output buffer is not big
enough. A class 1 output buffer begins with a length word that holds the number of
bytes in the buffer you've allocated (including the length word). When you call a
command that uses a class 1 output buffer, GS/OS inspects the length word to see if
Command Descriptions 87
the buffer is large enough; if it isn't, the command returns error code $4F ("buffer too
small") and returns the size of the buffer it does need in the word following the buffer
length word. If the buffer is large enough, the command returns data beginning at the
byte following the length word.
(There is an exception. The output buffer you provide to GetDirEntry for returning
a filename can be too small to hold the filename, but GetDirEntry does not return an
error. instead, it returns the actual length of the filename but puts only that portion of
the filename that will fit in the output buffer.)
Prefixes
Be aware that no default prefix is in effect when ProDOS 8 first boots up. (There is for
GS/OS.) This means any pathname specified in a ProDOS 8 MLI command parameter list
must be a full pathname and not a partial pathname or a simple filename. To simplify your
code, it is a good idea to use the SET - PREFIX command to set the prefix string to a
convenient name before calling other ProDOS 8 commands. If you simply want to set the
default prefix to the name of the volume directory on a given disk, use the ON - LINE
command to get its name before using SET - PREFIX. An example of how to do this is
included in the discussion of the SET - PREFIX command.
Access Code
Three of the commands, Create, GetFileInfo, and SetFileInfo, use a parameter called
access code that describes the types of I/O operations an application may perform on
a file as well as some other file attributes. Figure 2-10 in Chapter 2 shows the meaning
of each bit in the access code.
Time and Date
Many ProDOS 8 commands accept or return date and time values in their parameter
tables. These values are stored in the same special packed form used to store values in
the ProDOS 8 system global page TIME and DATE locations. (See Figure 8-1 in
Chapter 8 for a description of this format.)
GS/OS uses a different time and date format; it consists of eight bytes in the
following order:
seconds
minutes
hour in 24-hour military format
year year minus 1900
day day of month minus 1
month 0 = January, 1 = February, and so on
[not used]
weekday 1 = Sunday, 2 = Monday, and so on
88 GS/OS and ProDOS 8 Commands
This format is the same as the one used by the ReadTimeHex function in the IIgs's
Miscellaneous Tool Set.
File Type Code
Another common command parameter is the file type code. For the ProDOS file
system, this is a number from $00 to $FF that identifies the general file type. Table
2-5 in Chapter 2 gives the standard meanings of the ProDOS file type codes.
ProDOS 16 Considerations
The GS/OS commands described in this book are sometimes called class 1 commands.
GS/OS also has a set of class 0 commands that are the same as the ProDOS 16
commands documented in the Apple IIgs ProDOS 16 Reference. The class 0 com-
mands are not described here since they have been rendered almost obsolete by the
class 1 commands. The only good reason for continuing to use class 0 commands is if
you're writing a classic desk accessory - the CDA should be flexible enough to use
ProDOS 8, GS/OS, or ProDOS 16 commands, depending on what operating system is
active when it is called up.
Command Descriptions 89
ALLOCINTERRUPT
GS/OS ProDOS 8
Purpose:
To place the address of an interrupt-handling subroutine into the internal ProDOS 8
interrupt vector table. The interrupt vector table can hold up to four such subroutines.
Under GS/OS, use the BindInt command instead.
Parameter table:
ProDOS 8 Input
or
bet Symbolic Name Result
+0 numparms I
+ 1 intnum R
+2to +3 intcode I
Descriptions of parameters:
Description
Number of parameters (2)
Interrupt handler reference number
Pointer to interrupt handler
num - parms The number of parameters in the ProDOS 8 parameter table (always 2).
int - num The reference number ProDOS 8 assigns to the interrupt-handling
subroutine. Use this number when you remove the subroutine with
the DEALLOC - INTERRUPT command.
int - code A pointer to the beginning of the interrupt-handling subroutine.
ProDOS 8 passes control to this subroutine when an interrupt oc-
curs. The subroutine must begin with a CLD instruction. See Chap-
ter 8 for a discussion of other rules and conventions ProDOS 8
interrupt-handling subroutines must follow.
Important: Install an interrupt-handling subroutine before enabling interrupts on the
hardware device. If you don't, the system will crash if an interrupt occurs before
you've had a chance to install the handler.
Common error codes:
$25 The interrupt vector table is full. Solution: Remove one of the active
interrupt-handling subroutines (using DEALLOC - INTERRUPT)
and try again.
Other possible error codes are $04, $53.
90 GS/OS and ProDOS 8 Commands
Programming example:
In Chapter 6, we take a closer look at how ProDOS 8 deals with interrupts and how to
write interrupt-handling subroutines. Meanwhile, here's how to install a ProDOS 8
interrupt-handling subroutine that has been loaded into memory at location $300:
JSR MLI
DFB $40
DA PARMTBL
BCS ERROR
RTS
PARMTBL DFB 2
DS 1
DA $300
;ALLOCINTERRUPT
;Address of parameter table
;Branch if error occurred
;The # of parameters
;int_num is returned here
Address of interrupt subroutine
Your application should store the returned int_num in a safe place so that it will be
available when the interrupt-handling subroutine is removed with the DEALLOC -
INTERRUPT command.
Command Descriptions 91