P8 Tech Ref Chapter 4b - wiki.apple2.org

P8 Tech Ref Chapter 4b

Jump to: navigation, search

Filing Calls

Each of the following sections contains a description of a filing command, including its parameters and the possible errors that may be returned.


OPEN ($C8)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 3               |
   +---+---+---+---+---+---+---+---+
 1 | pathname               (low)  |
 2 | (2-byte pointer)       (high) |
   +---+---+---+---+---+---+---+---+
 3 | io_buffer              (low)  |
 4 | (2-byte pointer)       (high) |
   +---+---+---+---+---+---+---+---+
 5 | ref_num       (1-byte result) |
   +---+---+---+---+---+---+---+---+

OPEN prepares a file to be read or written. It creates a file control block that keeps track of the current (open) characteristics of the file specified by pathname, it sets the current position in the file to zero, and it returns a reference number by which the other commands in this section must refer to the file.

The I/O buffer is used by the system for the entire time the file is open. It contains information about the file's structure on the disk, and it contains the current 512-byte block being read or written. It is used until the file is closed, and therefore should not be modified directly by the user. A maximum of eight files can be open at a time.

When a file is opened it is assigned a level, from 0 to $F, depending on the current value of the LEVEL location ($BF94) in the system global page. When the CLOSE command is issued with a ref_num of 0, all files at or above the current level are closed. Thus, a CLOSE with a ref_num of 0 and a level of 0 will close all open files.

Refer to Section 2.1.7, "File Levels," for an example of the use of level.

Warning

Once a file has been opened, that file's disk must not be removed from its drive and replaced by another. The system does not check the identity of a volume before writing on it. A system program should check a volume's identity before writing to it.

Page 56


Parameters

param_count

(1-byte value)

Parameter count: 3 for this call.

pathname

(2-byte pointer)

Pathname pointer: A two-byte address (low byte first) that points to an ASCII string. The string consists of a count byte, followed by the pathname (up to 64 characters). If the pathname begins with a slash ( / ), it is treated as a full pathname. If not, it is treated as a partial pathname and the prefix is attached to the front to make a full pathname.

io_buffer

(2-byte pointer)

Buffer address pointer: This two byte-address (low byte first) indicates the starting address of a 1024-byte input/output buffer. The buffer must start on a page boundary (a multiple of $100) that is not already used by the system.

If a standard file is being accessed, the first 512 bytes of io_buffer contain the current block of data being read or written; the second 512 bytes contain the current index block, if there is one. If a directory file is being accessed, the first 512 bytes contain the current directory file block; the rest are unused.

ref_num

(2-byte result)

Reference number: When a file is opened, the filing system assigns this one-byte value. All subsequent commands to the open file use this reference number.

Refer to Appendix B for more information on directory file blocks, index blocks, and data blocks.

Possible Errors
$27 - I/O error
$40 - Invalid pathname syntax
$42 - File Control Block table full
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
$4B - Unsupported storage_type
$50 - File is open
$53 - Invalid value in parameter list
$56 - Bad buffer address
$5A - Bit map disk address is impossible

Page 57


NEWLINE ($C9)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 3               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 | enable_mask    (1-byte value) |
   +---+---+---+---+---+---+---+---+
 3 | newline_char   (1-byte value) |
   +---+---+---+---+---+---+---+---+

This call allows you to enable or disable newline read mode for any open file. When newline is disabled, a read request terminates when the requested number of characters has been read, or when the end of file is encountered. When newline is enabled, a read request will also terminate if the newline character (newline_char) is read.

Each character read is first transferred to the user's data buffer. Next it is ANDed with the enable_mask and compared to the newline_char. If there is a match, the read is terminated. For example, if enable_mask is $7F and newline_char is $0D (ASCII CR), either a $0D or $8D matches and terminates input. This process does not change the character.

Parameters

param_count

(1-byte value)

Parameter count: 3 for this call.

ref_num

(1-byte value)

Reference number: This is the filing reference number that was assigned to the file when it was opened.

enable_mask

(1-byte value)

Newline enable and mask: A value of $00 disables newline mode; a nonzero value enables it. When the mode is enabled, each incoming byte is ANDed with this byte before it is compared to newline_char (below). A match causes the read request to terminate. A value of $FF makes all bits significant, a value of $7F causes only bits 0 through 6 to be tested, etc.

newline_char

(1-byte value)

Newline character: When newline is enabled, a read request terminates if the input character, having been ANDed with the enable_mask equals this value.

Possible Error
$43 - Invalid reference number

Page 58

READ ($CA)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 4               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 | data_buffer            (low)  |
 3 | (2-byte pointer)       (high) |
   +---+---+---+---+---+---+---+---+
 4 | request_count          (low)  |
 5 | (2-byte value)         (high) |
   +---+---+---+---+---+---+---+---+
 6 | trans_count            (low)  |
 7 | (2-byte result)        (high) |
   +---+---+---+---+---+---+---+---+

Tries to transfer the requested number of bytes (request_count), starting at the current position (MARK) of the file specified by ref_num to the buffer pointed to by data_buffer. The number of bytes actually transferred is returned in trans_count.

If newline read mode is enabled and a newline character is encountered before request_count bytes have been read, then the trans_count parameter is set to the number of bytes transferred, including the newline byte.

If the end of file is encountered before request_count bytes have been read, then trans_count is set to the number of bytes transferred. The end of file error ($4C) is returned if and only if zero bytes were transferred (trans_count = 0).

Page 59


Parameters

param_count

Parameter count: 4 for this call.

ref_num

(1-byte value)

Reference number: This is the filing reference number that was assigned to the file when it was opened.

data_buffer

(2-byte pointer)

Data address pointer: This two-byte address (low byte first) points to the destination for the data to be read from the file.

request_count

(2-byte value)

Transfer request count: This two-byte value (low byte first) specifies the maximum number of bytes to be transferred to the data buffer pointed to by data_buffer. The maximum value is limited to the number of bytes between the start of data_buffer and the nearest used page of memory.

trans_count

(2-byte result)

Transferred: This two-byte value (low byte first) indicates the number of bytes actually read. It will be less than request_count only if EOF was encountered, if the newline character was read while newline mode was enabled, or if some other error occurred during the request.

Possible Errors
$27 - I/O error
$43 - Invalid reference number
$4C - End of file has been encountered
$4E - Access error: file not read enabled
$56 - Bad buffer address
$5A - Bit map address is impossible

Page 60


WRITE ($CB)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 4               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 | data_buffer            (low)  |
 3 | (2-byte pointer)       (high) |
   +---+---+---+---+---+---+---+---+
 4 | request_count          (low)  |
 5 | (2-byte value)         (high) |
   +---+---+---+---+---+---+---+---+
 6 | trans_count            (low)  |
 7 | (2-byte result)        (high) |
   +---+---+---+---+---+---+---+---+

Tries to transfer a specified number of bytes (request_count) from the buffer pointed to by data_buffer to the file specified by ref_num starting at the current position (MARK) in the file. The actual number of bytes transferred is returned in trans_count.

The file position is updated to position + trans_count. If necessary, additional data and index blocks are allocated to the file, and EOF is extended.

See Appendix B for an explanation of data and index blocks.

Page 61


Parameters

param_count

(1-byte value)

Parameter count: 4 for this call.

ref_num

(1-byte value)

Reference number: This is the filing reference number that was assigned when the file was opened.

data_buffer

(2-byte pointer)

Data address pointer: This two-byte address (low byte first) points to the beginning of the data to be transferred to the file.

request_count

(2-byte value)

Transfer request count: This two-byte value (low byte first) specifies the maximum number of bytes to be transferred from the buffer pointed to by data_buffer to the file.

trans_count

(2-byte result) Bytes transferred: This two-byte value (low byte first), indicates the number of bytes actually transferred. If no error occurs, this value should always be equal to request_count.

Possible Errors
$27 - I/O error
$2B - Disk write protected
$43 - Invalid reference number
$48 - Overrun error: not enough disk space
$4E - Access error: file not write enabled
$56 - Bad buffer address
$5A - Bit map disk address is impossible

Page 62


CLOSE ($CC)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 1               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+

This call is used to release all resources used by an open file. The file control block is released. If necessary, the file's buffer (io_buffer) is emptied to the file and the directory entry for the file is updated. Until that ref_num is assigned to another open file, subsequent filing calls using that ref_num will fail.

If ref_num equals zero ($0), all open files at or above the current level are closed. For example, if you open files at levels 0, 1, and 2, set the level to 1, and then use CLOSE with ref_num set to 0, the files at level 1 and 2 are closed, but the ones at level 0 are not. The level is a value from 0 to $F that is stored in the LEVEL location ($BFD8) of the system global page. It is only changed by system programs, and it is used by OPEN and CLOSE.

This call causes the backup bit to be set.

Parameters

param_count

(1-byte value)

Parameter count: 1 for this call.

ref_num

(1-byte value)

Reference number: The filing reference number that was assigned to the file when it was opened. CLOSE releases this reference number. If ref_num = 0, all open files at or above the current level are closed.

Possible Errors
$27 - I/O error
$2B - Disk write protected
$43 - Invalid reference number
$5A - Bit map disk address is impossible

Page 63


FLUSH ($CD)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 1               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+

The file's write buffer (io_buffer) is emptied to the file, and the file's directory is updated. If ref_num equals zero ($0), then all open files at or above the current level are flushed. The backup bit is set by this call.

FLUSH is further explained in Chapter 2, section "Closing and Flushing Files."

Parameters

param_count

(1-byte value)

Parameter count: 1 for this call.

ref_num

(1-byte value)

Reference number: This is the filing reference number that was assigned to the file when it was opened. If ref_num = 0 all open files at or above the current level are flushed.

Possible Errors
$27 - I/O error
$2B - Disk write protected
$43 - Invalid reference number
$5A - Bit map disk address is impossible

Page 64


SET_MARK ($CE)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 2               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 |                        (low)  |
 3 | position       (3-byte value) |
 4 |                        (high) |
   +---+---+---+---+---+---+---+---+

Changes the current position (MARK) in the file to that specified by the position parameter. Position may not exceed the end of file (EOF) value.

See the example of SET_MARK in Chapter 2, section "The EOF and MARK."

Parameters

param_count

(1-byte value)

Parameter count: 2 for this call.

ref_num

(1-byte value)

Reference number: The filing reference number that was assigned to the file when it was opened.

position

(3-byte value)

File position: This three-byte value (low bytes first) specifies to the File Manager the absolute position in the file at which the next read or write should begin (the MARK). The file position cannot exceed the file's EOF.

Possible Errors
$27 - I/O error
$43 - Invalid reference number
$4D - Position out of range
$5A - Bit map disk address is impossible

Page 65


GET_MARK ($CF)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 2               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 |                        (low)  |
 3 | position      (3-byte result) |
 4 |                        (high) |
   +---+---+---+---+---+---+---+---+

Returns the current position (MARK) in an open file.

Parameters

param_count

(1-byte value)

Parameter count: 2 for this call.

ref_num

(1-byte value)

Reference number: The filing reference number that was assigned to the file when it was opened.

position

(3-byte result)

File position: This three-byte value (low bytes first) is the absolute position in the file at which the next read or write will begin, unless it is changed by a subsequent SET_MARK call.

Possible Error
$43 - Invalid reference number

Page 66

SET_EOF ($D0)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 2               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 |                        (low)  |
 3 | EOF            (3-byte value) |
 4 |                        (high) |
   +---+---+---+---+---+---+---+---+

Sets the logical size of the file specified by ref_num to EOF. If the new EOF is less than the current EOF, then blocks past the new EOF are released to the system. If the new EOF is greater than or equal to the current EOF, no blocks are allocated. If the new EOF is less than the current position, the value of the position is set to the EOF. The EOF cannot be changed unless the file is write enabled. The logical size of a file is the number of bytes that can be read from it.

Parameters

param_count

(1-byte value)

Parameter count: 2 for this call.

ref_num

(1-byte value)

Reference number: The filing reference number that was assigned to the file when it was opened.

EOF

(3-byte value)

End Of File: This three-byte value (low bytes first) represents the logical end of a file. It can be greater or less than the current value of EOF. If it is less, blocks past the new EOF are released to the system.

Possible Errors
$27 - I/O error
$43 - Invalid reference number
$4D - Position out of range
$4E - Access error: File not write enabled
$5A - Bit map disk address is impossible

Page 67

GET_EOF ($D1)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 2               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 |                        (low)  |
 3 | EOF           (3-byte result) |
 4 |                        (high) |
   +---+---+---+---+---+---+---+---+

Returns the number of bytes that can be read from the open file.

Parameters

param_count

(1-byte value)

Parameter count: 2 for this call.

ref_num

(1-byte value)

Reference number: The filing reference number that was assigned to the file when it was opened.

EOF

(3-byte result)

End Of File: This three-byte result (low bytes first) contains the value of the logical end of file. This value is the maximum number of bytes that can be read from the file.

Possible Error
$43 - Invalid reference number

Page 68

SET_BUF ($D2)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 2               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 | io_buffer              (low)  |
 3 | (2-byte pointer)       (high) |
   +---+---+---+---+---+---+---+---+

This call allows you to reassign the address of the input/output buffer that is used by the file specified by ref_num (assigned when the file was opened). The MLI checks to see that the specified buffer is not already used by the system, then it moves the contents of the old buffer into the new buffer.

Parameters

param_count

(1-byte value)

Parameter count: 2 for this call.

ref_num

(1-byte value)

Reference number: The filing reference number that was assigned to the file when it was opened.

io_buffer

(2-byte pointer)

Buffer address pointer: This two-byte address (low byte first) indicates the starting address of a 1024 byte I/O buffer. The buffer must start on a page boundary (multiple of $100) and it must not already be used by the system.

Possible Errors
$43 - Invalid reference number
$56 - Bad buffer address

Page 69

GET_BUF ($D3)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 2               |
   +---+---+---+---+---+---+---+---+
 1 | ref_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 | io_buffer              (low)  |
 3 | (2-byte result)        (high) |
   +---+---+---+---+---+---+---+---+

Returns the address of the input/output buffer currently being used by the file specified by ref_num.

Parameters

param_count

Parameter count: 2 for this call.

ref_num

(1-byte value)

Reference number: The filing reference number that was assigned to the file when it was opened.

io_buffer

(2-byte result)

Buffer address pointer: This two-byte address (low byte first) indicates the starting address of a 1024 byte I/O buffer. The buffer starts on a page boundary (multiple of $100).

Possible Error
$43 - Invalid reference number

Page 70

System Calls

Each of the following sections describes a system command, including any parameters and possible errors.


GET_TIME ($82)

This call has no parameter list, and it cannot generate an error. It calls a clock/calendar routine, if there is one, which returns the current date and time to the system date and time locations ($BF90-BF93). If there is no clock/calendar routine, the system date and time locations are left unchanged.

Here is the layout of the four bytes that make up the system date and time.

         49041 ($BF91)     49040 ($BF90)
 
        7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
       +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
DATE:  |    year     |  month  |   day   |
       +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 
        7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
       +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
TIME:  |    hour       | |    minute     |
       +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 
         49043 ($BF93)     49042 ($BF92)

When ProDOS starts up, it looks for a clock/calendar card in one of the Apple II's slots. If it recognizes one, ProDOS installs a routine that can read the date and time from the card and place them in the system date and time locations. Otherwise, no routine is installed. Note that the GET_TIME call number for ProDOS is different from the GET_TIME call number for SOS.

Chapter 5 explains the use of the date and time locations by the system.

Chapter 6 explains the installation of clock/calendar routines.

Page 71

ALLOC_INTERRUPT ($40)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 2               |
   +---+---+---+---+---+---+---+---+
 1 | int_num       (1-byte result) |
   +---+---+---+---+---+---+---+---+
 2 | int_code               (low)  |
 3 | (2-byte pointer)       (high) |
   +---+---+---+---+---+---+---+---+

This call places the address of an interrupt receiving routine int_code into the interrupt vector table. It should be made before you enable the hardware that could cause this interrupt. It is your responsibility to make sure that the routine is installed at the proper location and that it follows interrupt conventions.

The int_num that is returned gives an indication of what priority the interrupt is given (1, 2, 3, or 4). Routines that are installed first are given the highest priority. You must use this number when you remove the routine from the system.

Interrupt receiving routines are described in Chapter 6.

Parameters

param_count

(1-byte value)

Parameter count: 2 for this call.

int_num

(1-byte result)

Interrupt vector number: This value, from 1 to 4 is assigned by the MLI to int_num when this call is made. This number must be retained by the calling routine and used when removing an interrupt routine.

int_code

(2-byte pointer)

Interrupt handler code entry address: This is a pointer (low byte first) to the first byte of a routine that is to be called when the system is polling in response to an interrupt.

Possible Errors
$25 - Interrupt vector table full
$53 - Invalid parameter

Page 72

DEALLOC_INTERRUPT ($41)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 1               |
   +---+---+---+---+---+---+---+---+
 1 | int_num        (1-byte value) |
   +---+---+---+---+---+---+---+---+

This call clears the entry for int_num from the interrupt vector table. You must disable interrupt hardware before you make this call. If you don't, and the hardware interrupts after the vector table has been updated, a SYSTEM FAILURE will occur (see Section 4.8.1). Interrupt receiving routines are described in Chapter 6.

Parameters

param_count

(1-byte value)

Parameter count: 1 for this call.

int_num

(1-byte value)

Interrupt vector number: A value from 1 to 4 that was assigned by the MLI to int_num when ALLOC_INTERRUPT was called.

Possible Error $53 - Invalid parameter


Direct Disk Access Calls

The direct disk access commands READ_BLOCK and WRITE_BLOCK, allow you to read from or write to any logical block on a disk. They are intended to be used by utility (such as copying) and diagnostic programs.

Warning

Application programs should not use these commands: they can very easily damage the data integrity of the ProDOS file structure. All necessary functions can be performed without these calls.

These calls will also read and write blocks (not tracks and sectors) from DOS 3.3 disks. A mapping of tracks and sectors on a DOS 3.3 disk to blocks read or written by ProDOS is given in Section B.5.

ProDOS BLOCK_READ and BL0CK_WRITE calls can access DOS 3.3 disks: see Appendix B, Section "DOS 3.3 Disk Organization."

Page 73

READ_BLOCK ($80)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 3               |
   +---+---+---+---+---+---+---+---+
 1 | unit_num       (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 | data_buffer            (low)  |
 3 | (2-byte pointer)       (high) |
   +---+---+---+---+---+---+---+---+
 4 | block_num              (low)  |
 5 | (2-byte value)         (high) |
   +---+---+---+---+---+---+---+---+

This call reads one block from the disk device specified by unit_num into memory starting at the address indicated by data_buffer. The buffer must be 512 or more bytes in length.

Parameters

param_count

(1-byte value)

Parameter count: 3 for this call.

unit_num

(1-byte value)

Device slot and drive number: This one-byte value specifies the hardware slot location of a disk device. The format is:

  7  6  5  4  3  2  1  0
+--+--+--+--+--+--+--+--+
|Dr|  Slot  |  Unused   |
+--+--+--+--+--+--+--+--+

The Dr bit specifies either drive 1 (Dr = 0) or drive 2 (Dr = 1). Slot must contain a slot number between 1 and 7, inclusive.

data_buffer

(2-byte pointer)

Data address pointer: This two-byte address (low byte first) points to the destination for data. The buffer must be at least 512 bytes long.

Page 74


block_num

(2-byte value)

Logical block number: This two-byte value (low byte first) specifies the logical address of a block of data to be read. Disk II's, for example, have block addresses ranging from $0 to $117. There is no general connection between block numbers and the layout of tracks and sectors on the disk. The translation from logical to physical block is done by the device driver.

Possible Errors
$27 - I/O error
$28 - No device connected


WRITE_BLOCK ($81)

     7   6   5   4   3   2   1   0
   +---+---+---+---+---+---+---+---+
 0 | param_count = 3               |
   +---+---+---+---+---+---+---+---+
 1 | unit_num       (1-byte value) |
   +---+---+---+---+---+---+---+---+
 2 | data_buffer            (low)  |
 3 | (2-byte pointer)       (high) |
   +---+---+---+---+---+---+---+---+
 4 | block_num              (low)  |
 5 | (2-byte value)         (high) |
   +---+---+---+---+---+---+---+---+

This call transfers one block of data from the memory buffer indicated by data_buffer to the disk device specified by unit_num. The block of data is placed in the logical block specified by block_num. It is assumed that the data buffer is at least 512 bytes long.

Page 75


Parameters

param_count

(1-byte value)

Parameter count: 3 for this call.

unit_num

(1-byte value)

Device slot and drive number: This one-byte value specifies the hardware slot location of a disk device. The format is:

  7  6  5  4  3  2  1  0
+--+--+--+--+--+--+--+--+
|Dr|  Slot  |  Unused   |
+--+--+--+--+--+--+--+--+

The Dr bit specifies either drive 1 (Dr = 0) or drive 2 (Dr = 1). Slot must contain a slot number between 1 and 7, inclusive.

data_buffer

(2-byte pointer)

Data address pointer: This two-byte address (low byte first) points to the source of data to be transferred. It is assumed that the data buffer is at least 512 bytes in length.

block_num

(2-byte value)

Logical block number: This two-byte value (low byte first) specifies the logical address on a disk of the block to be written. Disk II's, for example, have block addresses ranging from $0 to $117.

There is no general connection between block numbers and the layout of tracks and sectors on the disk. The translation from logical to physical block is done by the device driver.

An out-of-range block_num returns an I/O error. The number of blocks on a volume is returned in the aux_type field of the GET_FILE_INFO call of a volume directory file.

Possible Errors
$27 - I/O error
$28 - No device connected
$2B - Disk write protected

Page 76

MLI Error Codes

This is a summary of the ProDOS error codes. If there is no error, the C-flag is clear, and the Accumulator contains $00. If there is an error, the C-flag is set, and the Accumulator contains the error code.

$00 - No error.

$01 - Bad system call number. A non-existent command was issued.

$04 - Bad system call parameter count. This error will occur only if the call parameter list is not properly constructed.

$25 - Interrupt vector table full. Only four routines can be activated for interrupt processing at a time. One must be deactivated before another one may be enabled.

$27 - I/O error. This catch-all error is reported when some hardware failure prevents proper transfer of data to/from the disk device.

$28 - No device detected/connected. Will occur if, for example, drive 2 is specified for Disk II when only one drive is connected.

$2B - Disk write protected. Hardware write-inhibit is enabled, write request cannot be processed.

$2E - Disk switched: A WRITE, FLUSH, or CLOSE operation cannot be accomplished because a disk containing an open file has been removed from its drive.

$40 - Invalid pathname syntax. The pathname contains illegal characters.

$42 - File Control Block table full. The FCB can contain a maximum of eight entries. Thus, a maximum of eight files can be open concurrently.

$43 - Invalid reference number. The value parameter given as a reference number does not match the reference number of any currently open file.

$44 - Path not found. A filename in the specified pathname (which refers to a subdirectory) does not exist. The pathname's syntax is legal.

$45 - Volume directory not found. The volume name in the specified pathname does not exist. The pathname's syntax is otherwise legal.

Page 77


$46 - File not found. The last filename of the pathname does not exist. The syntax of the pathname is legal.

$47 - Duplicate filename. An attempt was made to create a file that already exists or to rename a file with an already used name.

$48 - Overrun error. An attempt to allocate blocks on a block device during a CREATE or WRITE operation failed due to lack of space on the device. This error also is returned on an invalid EOF parameter. Data is written until the disk is full, but you will always be able to close the file.

$49 - Volume directory full. No more entries are left in the volume directory. In ProDOS 1.0, a volume directory can hold no more than 51 entries. No more files can be added (using CREATE) in this directory until others are destroyed.

$4A - Incompatible file format. The file is not backward compatible with this version of ProDOS. Storage_type is recognized, but the File Manager may not support that storage_type in a fully compatible fashion. This error is likely to occur when data written by a future version of the BFM is read back using an earlier version of the BFM.

$4B - Unsupported storage_type. File is of an organization unknown to the executing File Manager. This error may be reported if the directory is tampered with by the user. This error is also returned if you attempt to set the prefix to a nondirectory file.

$4C - End of file has been encountered. This error is returned after a READ call when the file position is equal to EOF and no data can be read.

$4D - Position out of range. Returned when the position parameter is greater than current EOF.

$4E - Access error. The file's access attribute forbids the RENAME, DESTROY, READ or WRITE operation that was attempted.

$50 - File is open. An attempt was made to OPEN, RENAME or DESTROY an open file.

$51 - Directory count error: The number of entries indicated in the directory header does not match the number of entries actually found in the file.

Page 78


$52 - Not a ProDOS disk. The specified disk does not contain a ProDOS (or SOS) directory format.

$53 - Invalid parameter. The value of one or more parameters in the parameter list is out of range.

$55 - Volume Control Block table full. More than eight volumes on line. The VCB table can contain a maximum of eight entries. This error occurs only if eight files, on eight volumes, are open and the ON_LINE command is requested for a device having no open files.

$56 - Bad buffer address. The data_buffer or io_buffer specified conflicts with memory currently in use by the MLI.

$57 - Duplicate volume. This is a Warning that two or more volume directory names are the same.

$5A - Bit map disk address is impossible. The volume bit map indicates that the volume contains blocks beyond the block count for that volume.

Note: System failure errors should never occur. They indicate that the system has encountered a situation that should not have happened, and it has no available means of recovery.

Possible causes include

  • bad RAM
  • disk failure
  • operating system bug
  • unclaimed interrupt.

Page 79


Page 80

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