COMMANDS1

Table 4-3 A standard ProDOS 8 MLI error-handling subroutine

2 *************************************

3 * General-Purpose MLI Error Handler

7 * Last modified: August 26, 1988

9 *************************************

10 CMDADR EQU $BF9C ;Return address for MLI call

12 CROUT EQU $FD8E Print a CR

13 PRHEX EQU $FDDA

14 COUT EQU $FDED

16 ORG $300

0300: 48 18 ERROR PHA

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

030E: 68 27 :2 PLA

030F: 20 DA FD 28 JSR PRHEX

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

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

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

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

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