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