View source for P8 Tech Ref Chapter 4a

= Chapter 4 - Calls to the MLI =

Page 27


This chapter is about the ProDOS Machine Language Interface (MLI),
which provides a simple way to use disk files from machine-language
programs. This chapter describes

* the organization of the MLI on a functional basis

* how to make calls to the MLI from machine-language programs

* the MLI calls themselves

* the MLI error codes.


== The Machine Language Interface ==

The ProDOS MLI is a complete, consistent, and interruptible interface between the machine-language programmer and files on disks. It is entirely independent of the ProDOS BASIC system program; thus, it serves as a base upon which other system programs can be written. Its filename is PRODOS. It consists of:

* the Command Dispatcher, which accepts and dispatches calls from a machine-language program. It validates each call's parameters, updates the system global page, and then jumps to the appropriate routine of the Block File Manager.

* the Block File Manager, which carries out all valid calls to the MLI. The Block File Manager keeps track of all mounted disks, manages the condition of all opened files, and does some simple memory mangagement. It performs all disk access (reads and writes) via calls to disk-driver routines.

* Disk Driver Routines, which perform the reading and writing of data.

* the Interrupt Handler, which allows up to four interrupt handling routines to be attached to ProDOS. The Interrupt Handler keeps four vectors to interrupt routines. When an interrupt occurs, these routines are called, in sequence, until one of them claims the interrupt.

Page 28




== Issuing a Call to the MLI ==

A program sends a call to the Machine Language Interface by executing a JSR (jump to subroutine) to address $BF00 (referred to below as MLI). The call number and a two-byte pointer (low byte first) to the call's parameter list must immediately follow the call. Here is an example of a call to the MLI:
<pre>
SYSCALL  JSR MLI         ;Call Command Dispatcher
         DB  CMDNUM      ;This determines which call is being made
         DW  CMDLIST     ;A two-byte pointer to the parameter list
         BNE ERROR       ;Error if nonzero
</pre>

Upon completion of the call, the MLI returns to the address of the JSR plus 3 (in the above example, the BNE statement); the call number and parameter list pointer are skipped. If the call is successful, the C-flag is cleared and the Accumulator is set to zero. If the call is unsuccessful, the C-flag is set and the Accumulator is set to the error code. The register status upon call completion is summarized below.

Note that the value of the N-flag is determined by the Accumulator and that the value of the V-flag is undefined.
<pre>
                    N  Z  C  D  V   Acc    PC    X  Y  SP
Successful call:    0  1  0  0  x    0    JSR+3  unchanged
Unsuccessful call:  x  0  1  0  x  error  JSR+3  unchanged
                                   code
</pre>

Page 29


Here is an example of a small program that issues calls to the MLI. It tries to create a text file named NEWFILE on a volume named TESTMLI. If an error occurs, the Apple II beeps and prints the error code on the screen. Both the source and the object are given so you can enter it from the Monitor if you wish (remember to use a formatted disk named /TESTMLI).
<pre>
 ------------------------------------------------------------------------
 SOURCE   FILE #01 =>TESTCMD
 ----- NEXT OBJECT FILE NAME IS TESTCMD.0
 2000:        2000    1         ORG  $2000
 2000:        2000    1         ORG  $2000
 2000:                2 *
 2000:        FF3A    3 BELL    EQU  $FF3A     ;Monitor BELL routine
 2000:        FD8E    4 CROUT   EQU  $FD8E     ;Monitor CROUT routine
 2000:        FDDA    5 PRBYTE  EQU  $FDDA     ;Monitor PRBYTE routine
 2000:        BF00    6 MLI     EQU  $BF00     ;ProDOS system call
 2000:        00C0    7 CRECMD  EQU  $C0       ;CREATE command number
 2000:                8 *
 2000:20 06 20        9 MAIN    JSR  CREATE    ;CREATE "/TESTMLI/NEWFILE"
 2003:D0 08   200D   10         BNE  ERROR     ;If error, display it
 2005:60             11         RTS            ;Otherwise done
 2006:               12 *
 2006:20 00 BF       13 CREATE  JSR  MLI       ;Perform call
 2009:C0             14         DFB  CRECMD    ;CREATE command number
 200A:17 20          15         DW   CRELIST   ;Pointer to parameter list
 200C:60             16         RTS
 200D:               17 *
 200D:20 DA FD       18 ERROR   JSR  PRBYTE    ;Print error code
 2010:20 3A FF       19         JSR  BELL      ;Ring the bell
 2013:20 8E FD       20         JSR  CROUT     ;Print a carriage return
 2016:60             21         RTS
 2017:               22 *
 2017:07             23 CRELIST DFB  7         ;Seven parameters
 2018:23 20          24         DW   FILENAME  ;Pointer to filename
 201A:C3             25         DFB  $C3       ;Normal file access permitted
 201B:04             26         DFB  $04       ;Make it a text file
 201C:00 00          27         DFB  $00,$00   ;AUX_TYPE, not used
 201E:01             28         DFB  $01       ;Standard file
 201F:00 00          29         DFB  $00,$00   ;Creation date (unused)
 2021:00 00          30         DFB  $00,$00   ;Creation time (unused)
 2023:               31 *
 2023:10             32 FILENAME DFB ENDNAME-NAME ;Length of name
 2024:2F 54 45 53    33 NAME    ASC  "/TESTMLI/NEWFILE" ;followed by the name
 2034:        2034   34 ENDNAME EQU  *
 ------------------------------------------------------------------------

</pre>
The parameters used in TESTCMD are explained in the following sections. The MLI error codes are summarized in Section 4.7. Page 30




=== Parameter Lists ===

As defined above, each MLI call has a two-byte pointer to a parameter list. A parameter list contains information to be used by the call and space for information to be returned by the call. There are three types of elements used in parameter lists: values, results, and pointers.

A value is a one or more byte quantity that is passed to the Block File Manager (BFM). Values help determine the action taken by the BFM.

A result is a one or more byte space in the parameter list into which the Block File Manager will place a value. From results, programs can get information about the status of a volume, file, or interrupt, or about the success of the call just completed.

A pointer is a two-byte memory address that indicates the location of data, code, or a space in which the Block File Manager can place or receive data. All pointers are arranged low byte first, high byte second. The first element in every parameter list is the parameter count, a one-byte value that indicates the number of parameters used by the call (not including the parameter count). This byte is used to verify that the call was not accidental.


=== The ProDOS Machine Language Exerciser ===

To help you learn to use the ProDOS Machine Language Interface, there is a useful little program called the ProDOS Machine Language Exerciser. It allows you to execute MLI calls from a menu; it has a hexadecimal memory editor for reviewing and altering the contents of buffers; and it has a catalog command.

Instructions for using the Machine Language Exerciser program are in Appendix D.

When you use it to make an MLI call, you request the call by its call number, then you specify its parameter list, just as if you were coding the call in a program. When you press [RETURN], the call is executed. Using the Exerciser, you can try out sequences of MLI calls before actually coding them.

Page 31




== The MLI Calls ==

The MLI calls can be divided into three groups: housekeeping calls, filing calls, and system calls.


=== Housekeeping Calls ===

The housekeeping calls perform operations such as creating, deleting, and renaming, which cannot be used on open files. They are used to change a file's status, but not the information that is in the file. They refer to files by their pathnames, and each requires a temporary buffer, which is used during execution of the call. The housekeeping calls are:

CREATE

Creates either a standard file or a directory file. An entry for the file is placed in the proper directory on the disk, and one block of disk space is allocated to the file.

DESTROY

Removes a standard file or directory file. The entry for the file is removed from the directory and all the file's disk space is released. If a directory is to be destroyed, it must be empty. A volume directory cannot be destroyed except by reformatting the volume.

RENAME

Changes the name of a file. The new name must be in the same directory as the old name. This call changes the name in the entry that describes that file, and if it is a directory file, also the name in its header entry.

SET_FILE_INFO

Sets the file's type, the way it may be accessed, and/or its modification date and time.

GET_FILE_INFO

Returns the file's type, the way it may be accessed, the way it is stored on the disk, its size in blocks, and the date and time at which it was created and last modified.

Page 32


ON_LINE

Returns the slot number, drive number, and volume name of one or all mounted volumes. This information is placed in a user-supplied buffer.

SET_PREFIX

Sets the pathname that is used by the operating system as a prefix. The prefix must indicate an existing directory on a mounted volume.

GET_PREFIX

Returns the value of the current system prefix.


=== Filing Calls ===

The filing calls cause the transfer of data to or from files. The first filing call, OPEN, must be used before any of the others can be used. The OPEN call specifies a file by its pathname; the other filing calls refer to files by the reference number returned by the OPEN call. In addition, an input/output buffer (io_buffer), is allocated to the open file; subsequent data transfers go through this buffer. The reference number remains assigned and the buffer remains allocated until the file is closed. The filing calls are:

OPEN

Prepares a file to be accessed. This call causes a file control block (FCB) to be allocated to the file, and a reference number to be returned (A reference number is really a file control block number). In addition, an input/output buffer is allocated for data transfers to and from the file.

NEWLINE

Sets conditions for reading from the file. This call turns on and turns off the capability of read requests to terminate when a particular character (such as a carriage return) is read.

READ

Causes the transfer of a requested number of characters from a file to a specified memory buffer, and updates the current position (MARK) in the file. Characters are read according to the rules set by the NEWLINE call.

Page 33


WRITE

Causes the transfer of a requested number of characters from a specified buffer to a file, and updates the current position (MARK) in the file and the end of file (EOF), if necessary.

CLOSE

Transfers any unwritten data from a file's input/output buffer to the file, releases the file's io_buffer and file control block, and updates the file's directory entry, if necessary. The file's reference number is released for use by subsequently opened files.

FLUSH

Transfers any unwritten data from a file's input/output buffer to the file, and updates the file's directory entry, if necessary.

SET_MARK

Changes the current position in the file. The current position is the absolute position in the file of the next character to be read or written.

GET_MARK

Returns the current position in the file. The current position is the absolute position in the file of the next character to be read or written.

SET_EOF

Changes the logical size of the file (the end of file).

GET_EOF

Returns the logical size of the file.

SET_BUF

Assigns a new location for the input/output buffer of an open file.

GET_BUF

Returns the current location of the input/output buffer of an open file.

Page 34




=== System Calls ===

System calls are those calls that are neither housekeeping nor filing calls. They are used for getting the current date and time, for installing and removing interrupt routines, and for reading and writing specific blocks of a disk. The system calls are:

GET_TIME

If your system has a clock/calendar card, and if a routine that can read from the clock is installed, then it places the current date and time in the system date and time locations.

ALLOC_INTERRUPT

Places a pointer to an interrupt-handling routine into the system interrupt vector table.

DEALLOC_INTERRUPT

Removes a pointer to an interrupt handling routine from the system interrupt vector table.

READ_BLOCK

Reads one specific block (512 bytes) of information from a disk into a user specified data buffer. This call is file independent.

WRITE_BLOCK

Writes a block of information from a user specified data buffer to a specific block of a disk. This call is file independent.

Page 35


== Housekeeping Calls ==

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


=== CREATE ($C0) ===
<pre>
      7   6   5   4   3   2   1   0
    +---+---+---+---+---+---+---+---+
  0 | param_count = 7               |
    +---+---+---+---+---+---+---+---+
  1 | pathname               (low)  |
  2 | (2-byte pointer)       (high) |
    +---+---+---+---+---+---+---+---+
  3 | access         (1-byte value) |
    +---+---+---+---+---+---+---+---+
  4 | file_type      (1-byte value) |
    +---+---+---+---+---+---+---+---+
  5 | aux_type               (low)  |
  6 | (2-byte value)         (high) |
    +---+---+---+---+---+---+---+---+
  7 | storage_type   (1-byte value) |
    +---+---+---+---+---+---+---+---+
  8 | create_date          (byte 0) |
  9 | (2-byte value)       (byte 1) |
    +---+---+---+---+---+---+---+---+
  A | create_time          (byte 0) |
  B | (2-byte value)       (byte 1) |
    +---+---+---+---+---+---+---+---+

</pre>
Every disk file except the volume directory file must be created using this call. There are two organizationally distinct types of file storage: tree structure (storage_type = $1), used for standard files; and linked list (storage_type = $D), used for directory files.

Pathname specifies the name of the file to be created and the directory in which to insert an entry for the new file. One block (512 bytes) of disk space is allocated, and the entry's key_pointer field is set to indicate that block. Access, in most cases, should be set to $E3 (full access permitted). File_type and aux_type may be anything, but it is strongly recommended that conventions be followed (see below).

Page 36


Parameters

param_count

(1-byte value)

Parameter count: 7 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. The pathname string is not changed.

access

(1-byte value)

Access permitted: This byte defines how the file will be accessible. Its format is:

   7  6  5  4  3  2  1  0
 +--+--+--+--+--+--+--+--+
 |D |RN|B |Reserved|W |R |
 +--+--+--+--+--+--+--+--+

 D:   Destroy enable bit
 RN:  Rename enable bit
 B:   Backup needed bit
 W:   Write enable bit
 R:   Read enable bit

For all bits, 1 = enabled, 0 = disabled. Bits 2 through 4 are reserved for future definition and must always be disabled. Usually access should be set to $C3.

If the file is destroy, rename, and write enabled, it is unlocked. If all three are disabled, it is locked. Any other combination of access bits is called restricted access.

The backup bit (B) is always set by this call.

file_type

(1-byte value)

File type: This byte describes the contents of the file. The currently defined file types are listed below.

Page 37


 File Type       Preferred Use
 
 $00             Typeless file (SOS and ProDOS)
 $01             Bad block file
 $02 *           Pascal code file
 $03 *           Pascal text file
 $04             ASCII text file (SOS and ProDOS)
 $05 *           Pascal data file
 $06             General binary file (SOS and ProDOS)
 $07 *           Font file
 $08             Graphics screen file
 $09 *           Business BASIC program file
 $0A *           Business BASIC data file
 $0B *           Word Processor file
 $0C *           SOS system file
 $0D,$0E *       SOS reserved
 $0F             Directory file (SOS and ProDOS)
 $10 *           RPS data file
 $11 *           RPS index file
 $12 *           AppleFile discard file
 $13 *           AppleFile model file
 $14 *           AppleFile report format file
 $15 *           Screen library file
 $16-$18 *       SOS reserved
 $19             AppleWorks Data Base file
 $1A             AppleWorks Word Processor file
 $1B             AppleWorks Spreadsheet file
 $1C-$EE         Reserved
 $EF             Pascal area
 $F0             ProDOS added command file
 $F1-$F8         ProDOS user defined files 1-8
 $F9             ProDOS reserved
 $FA             Integer BASIC program file
 $FB             Integer BASIC variable file
 $FC             Applesoft program file
 $FD             Applesoft variables file
 $FE             Relocatable code file (EDASM)
 $FF             ProDOS system file

Note: The file types marked with a * in the above list apply to Apple III SOS only; they are not used by ProDOS. For the file_types used by Apple III SOS only, refer to the SOS Reference Manual.

Page 38


aux_type

(2-byte value)

Auxiliary type: This two-byte field is used by the system program. The BASIC system program uses it (low byte first) to store text-file record size or binary-file load address, depending on the file_type.

storage_type

(1-byte value)

File kind: This byte describes the physical organization of the file. storage_type = $0D is a linked directory file; storage_type = $01 is a standard file.

create_date

(2-byte value)

This 2-byte field may contain the date on which the file was created. Its format is:

       byte 1            byte 0

  7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 |    Year     |  Month  |   Day   |
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

create_time

(2-byte value)

This 2-byte field may contain the time at which the file was created. Its format is:

       byte 1            byte 0

  7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 |0 0 0|  Hour   | |0 0|  Minute   |
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

See Chapter 6 for information about the use of ProDOS with a clock/calendar card.

Page 39


Possible Errors
$27 - I/O error
$2B - Disk write protected
$40 - Invalid pathname syntax
$44 - Path not found
$45 - Volume directory not found
$46 - File not found
$47 - Duplicate filename
$48 - Overrun error: not enough disk space
$49 - Directory full
-- ProDOS can have no more than 51 files in a volume directory.
$4B - Unsupported storage_type
$53 - Invalid parameter
$5A - Bit map disk address is impossible


=== DESTROY ($C1) ===

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

Deletes the file specified by pathname by removing its entry from the directory that owns it, and by returning its blocks to the volume bit map. Volume directory files and open files cannot be destroyed. Subdirectory files must be empty before they can be destroyed.

Page 40


Parameters

param_count

(1-byte value)

Parameter count: 1 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.

 Possible Errors
 $27 - I/O error
 $2B - Disk write protected
 $40 - Invalid pathname syntax
 $44 - Path not found
 $45 - Volume directory not found
 $46 - File not found
 $4A - Incompatible file format 
 $4B - Unsupported storage_type
 $4E - Access error: destroy not enabled
 $50 - File is open: request denied
 $5A - Bit map disk address is impossible

Page 41




=== RENAME ($C2) ===

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

Changes the name of the file specified by pathname to that specified by new_pathname. Both pathname and new_pathname must be identical except for the rightmost filename (they must indicate files in the same directory). For example, the path /EGG/ROLL can be renamed /EGG/PLANT, but not /JELLY/ROLL or /EGG/DRUM/ROLL.

Parameters

param_count

(1-byte value)

Parameter count: 2 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.

new_pathname

(2-byte pointer)

New pathname pointer: This two-byte pointer

(low byte first) indicates the location of the new pathname. It has the same syntax as pathname.

 Possible Errors
 $27 - I/O error
 $2B - Disk write protected
 $40 - Invalid pathname syntax
 $44 - Path not found
 $45 - Volume directory not found
 $46 - File not found

Page 42

 $47 - Duplicate filename
 $4A - Incompatible file format
 $4B - Unsupported storage_type
 $4E - Access error: rename not enabled
 $50 - File is open: request denied
 $57 - Duplicate volume


=== SET_FILE_INFO ($C3) ===

      7   6   5   4   3   2   1   0
    +---+---+---+---+---+---+---+---+
  0 | param_count = 7               |
    +---+---+---+---+---+---+---+---+
  1 | pathname               (low)  |
  2 | (2-byte pointer)       (high) |
    +---+---+---+---+---+---+---+---+
  3 | access         (1-byte value) |
    +---+---+---+---+---+---+---+---+
  4 | file_type      (1-byte value) |
    +---+---+---+---+---+---+---+---+
  5 | aux_type               (low)  |
  6 | (2-byte value)         (high) |
    +---+---+---+---+---+---+---+---+
  7 |                               |
  8 | null_field          (3 bytes) |
  9 |                               |
    +---+---+---+---+---+---+---+---+
  A | mod_date             (byte 0) |
  B | (2-byte value)       (byte 1) |
    +---+---+---+---+---+---+---+---+
  C | mod_time             (byte 0) |
  D | (2-byte value)       (byte 1) |
    +---+---+---+---+---+---+---+---+

Modifies information in the specified file's entry field. This call can be performed when the file is either open or closed. However, new access attributes are not used by an open file until the next time the file is opened (that is, this call doesn't modify existing file control blocks). You should use the GET_FILE_INFO call to read a file's attributes into a parameter list, modify them as needed, and then use the same parameter list for the SET_FILE_INFO call.

Page 43


Parameters

param_count

(1-byte value)

Parameter count: 7 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.

access

(1-byte value)

Access permitted: This byte determines how the file may be accessed. Its format is:

   7  6  5  4  3  2  1  0
 +--+--+--+--+--+--+--+--+
 |D |RN|B |Reserved|W |R |
 +--+--+--+--+--+--+--+--+

 D:   Destroy enable bit
 RN:  Rename enable bit
 B:   Backup needed bit
 W:   Write enable bit
 R:   Read enable bit

For all bits, 1 = enabled, 0 = disabled. Bits 2 through 4 are used internally and should be set to 0. Usually access should be set to $C3. If the file is destroy, rename, and write enabled it is unlocked. If all three are disabled, it is locked. Any other combination of access bits is called restricted access. The backup bit (B) is set by this call.

file_type

(1-byte value)

File type: This byte describes the contents of a file. The currently defined file types are listed below.

Page 44


 File Type       Preferred Use
 
 $00             Typeless file (SOS and ProDOS)
 $01             Bad block file
 $02 *           Pascal code file
 $03 *           Pascal text file
 $04             ASCII text file (SOS and ProDOS)
 $05 *           Pascal data file
 $06             General binary file (SOS and ProDOS)
 $07 *           Font file
 $08             Graphics screen file
 $09 *           Business BASIC program file
 $0A *           Business BASIC data file
 $0B *           Word Processor file
 $0C *           SOS system file
 $0D,$0E *       SOS reserved
 $0F             Directory file (SOS and ProDOS)
 $10 *           RPS data file
 $11 *           RPS index file
 $12 *           AppleFile discard file
 $13 *           AppleFile model file
 $14 *           AppleFile report format file
 $15 *           Screen library file
 $16-$18 *       SOS reserved
 $19             AppleWorks Data Base file
 $1A             AppleWorks Word Processor file
 $1B             AppleWorks Spreadsheet file
 $1C-$EE         Reserved
 $EF             Pascal area
 $F0             ProDOS added command file
 $F1-$F8         ProDOS user defined files 1-8
 $F9             ProDOS reserved
 $FA             Integer BASIC program file
 $FB             Integer BASIC variable file
 $FC             Applesoft program file
 $FD             Applesoft variables file
 $FE             Relocatable code file (EDASM)
 $FF             ProDOS system file

Note: The file types marked with a * in the above list apply to Apple III SOS only; they are not used by ProDOS. For the file_types used by Apple III SOS only, refer to the SOS Reference Manual.

Page 45


aux_type

(2-byte value)

Auxiliary type: This two-byte field is used by the system program. The BASIC system program uses it (low byte first) to store record size or load address, depending on the file_type.

null_field

(3 bytes)

Null field: These three bytes preserve symmetry between this and the GET_FILE_INFO call. mod_date

(2-byte value)

This 2-byte field should contain the current date.

It has this format:

       byte 1            byte 0
 
  7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 |    Year     |  Month  |   Day   |
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

mod_time

(2-byte value)

This 2-byte field should contain the current time.

It has this format:

       byte 1            byte 0
 
  7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 |0 0 0|  Hour   | |0 0|  Minute   |
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 
See Chapter 6 for information about the use or ProDOS with a clock/calendar card.

 Possible Errors
 $27 - I/O error
 $2B - Disk write protected
 $40 - Invalid pathname syntax
 $44 - Path not found
 $45 - Volume directory not found
 $46 - File not found
 $4A - Incompatible file format
 $4B - Unsupported storage_type
 $4E - Access error: file not write enabled 
 $53 - Invalid value in parameter list
 $5A - Bit map disk address is impossible

Page 46


=== GET_FILE_INFO ($C4) ===

      7   6   5   4   3   2   1   0
    +---+---+---+---+---+---+---+---+
  0 | param_count = $A              |
    +---+---+---+---+---+---+---+---+
  1 | pathname               (low)  |
  2 | (2-byte pointer)       (high) |
    +---+---+---+---+---+---+---+---+
  3 | access        (1-byte result) |
    +---+---+---+---+---+---+---+---+
  4 | file_type     (1-byte result) |
    +---+---+---+---+---+---+---+---+
  5 | aux_type               (low)  | *
  6 | (2-byte result)        (high) |
    +---+---+---+---+---+---+---+---+
  7 | storage_type  (1-byte result) |
    +---+---+---+---+---+---+---+---+
  8 | blocks used            (low)  | *
  9 | (2-byte result)        (high) |
    +---+---+---+---+---+---+---+---+
  A | mod_date             (byte 0) |
  B | (2-byte result)      (byte 1) |
    +---+---+---+---+---+---+---+---+
  C | mod_time             (byte 0) |
  D | (2-byte result)      (byte 1) |
    +---+---+---+---+---+---+---+---+
  E | create_date          (byte 0) |
  F | (2-byte result)      (byte 1) |
    +---+---+---+---+---+---+---+---+
 10 | create_time          (byte 0) |
 11 | (2-byte result)      (byte 1) |
    +---+---+---+---+---+---+---+---+

* When file information about a volume directory is requested, the total number of blocks on the volume is returned in the aux_type field and the total blocks for all files is returned in blocks_used. GET_FILE_INFO returns the information that is stored in the specified file's entry field. This call can be performed whether the file is open or closed. If the SET_FILE_INFO call is used to change the access while the file is open, the change does not take effect until the file has been closed and reopened.

Page 47


Parameters

param_count

(1-byte value)

Parameter count: $A 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.

access

(1-byte result)

Access permitted: This byte determines how the file may be accessed. Its format is:

   7  6  5  4  3  2  1  0
 +--+--+--+--+--+--+--+--+
 |D |RN|B |Reserved|W |R |
 +--+--+--+--+--+--+--+--+
 
 D:   Destroy enable bit
 RN:  Rename enable bit
 B:   Backup needed bit
 W:   Write enable bit
 R:   Read enable bit

For all bits, 1 = enabled, 0 = disabled. Bits 2 through 4 are not used. Usually access should be set to $C3.

If the file is destroy, rename, and write enabled it is unlocked. If all three are disabled, it is locked. Any other combination of access bits is called restricted access.

file_type

(1-byte result)

File type: This byte describes the contents of a \file. The currently defined file types are listed below.

Page 48


 File Type       Preferred Use
 
 $00             Typeless file (SOS and ProDOS)
 $01             Bad block file
 $02 *           Pascal code file
 $03 *           Pascal text file
 $04             ASCII text file (SOS and ProDOS)
 $05 *           Pascal data file
 $06             General binary file (SOS and ProDOS)
 $07 *           Font file
 $08             Graphics screen file
 $09 *           Business BASIC program file
 $0A *           Business BASIC data file
 $0B *           Word Processor file
 $0C *           SOS system file
 $0D,$0E *       SOS reserved
 $0F             Directory file (SOS and ProDOS)
 $10 *           RPS data file
 $11 *           RPS index file
 $12 *           AppleFile discard file
 $13 *           AppleFile model file
 $14 *           AppleFile report format file
 $15 *           Screen library file
 $16-$18 *       SOS reserved
 $19             AppleWorks Data Base file
 $1A             AppleWorks Word Processor file
 $1B             AppleWorks Spreadsheet file
 $1C-$EE         Reserved
 $EF             Pascal area
 $F0             ProDOS added command file
 $F1-$F8         ProDOS user defined files 1-8
 $F9             ProDOS reserved
 $FA             Integer BASIC program file
 $FB             Integer BASIC variable file
 $FC             Applesoft program file
 $FD             Applesoft variables file
 $FE             Relocatable code file (EDASM)
 $FF             ProDOS system file

Note: The file types marked with a * in the above list apply to Apple III SOS only; they are not used by ProDOS. For the file_types used by Apple III SOS only, refer to the SOS Reference Manual.

Page 49


aux_type

(2-byte result)

Auxiliary type: This two-byte field is used by the system program. The BASIC system program uses it (low byte first) to store record size or load address, depending on the file_type. If this call is used on a volume directory file, aux_type will contain the total number of blocks on the volume.

storage_type

(1-byte result)

File kind: This byte describes the physical organization of the file. storage_type = $0F is a volume directory file; storage_type = $0D is a directory file; storage_type = $01, $02, and $03 are seedling, sapling, and tree files, respectively (see Appendix B). All other values are reserved for future use.

blocks_used

(2-byte result)

Blocks used by the file: These two bytes contain the total number of blocks used by the file, as stored in the blocks_used parameter of the file's entry. If this call is used on a volume directory file blocks_used contains the total number of blocks used by all the files on the volume.

mod_date

(2-byte result)

This 2-byte field returns the date on which the file was last modified. It has this format:

       byte 1            byte 0
 
  7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 |    Year     |  Month  |   Day   |
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

mod_time

(2-byte result)

This 2-byte field returns the time at which the file was last modified. It has this format:

       byte 1            byte 0
 
  7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 |0 0 0|  Hour   | |0 0|  Minute   |
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

Page 50


create_date

(2-byte result)

This 2-byte field returns the date on which the file was created. It has this format:

       byte 1            byte 0
 
  7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 |    Year     |  Month  |   Day   |
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

create_time

(2-byte result)

This 2-byte field returns the time at which the file was created. It has this format:

       byte 1            byte 0
 
  7 6 5 4 3 2 1 0   7 6 5 4 3 2 1 0
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+
 |0 0 0|  Hour   | |0 0|  Minute   |
 +-+-+-+-+-+-+-+-+ +-+-+-+-+-+-+-+-+

See Chapter 6 for information about the use of ProDOS with a clock/calendar card.

 Possible Errors
 $27 - I/O error
 $40 - Invalid pathname syntax
 $44 - Path not found
 $45 - Volume directory not found
 $46 - File not found
 $4A - Incompatible file format
 $4B - Unsupported storage_type
 $53 - Invalid value in parameter list
 $5A - Bit map address is impossible


=== ON_LINE ($C5) ===

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

This command can be used to determine the names of all ProDOS (or SOS) volumes that are currently mounted (such as disks in disk drives), or it can be used to determine the name of a disk in a specified slot and drive.

Page 51


When unit_num is 0, this command places a list of the volume names, slot numbers, and drive numbers of all mounted disks into the 256 byte buffer pointed to by data_buffer. When a specific unit_num is requested, only 16 bytes need be set aside for the buffer. The format of the returned information is described below.

The volume names are placed in the list in volume search order, as described in section 3.2.

Parameters

param_count

(1-byte value)

Parameter count: Must be 2 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   |
 +--+--+--+--+--+--+--+--+

For drive 1, Dr = 0; for drive 2, Dr = 1. Slot specifies the device's slot number (1-7). If unit_num is 0, all mounted disks are scanned. Here are possible values for unit_num:

 Slot:      7   6   5   4   3   2   1
 Drive 1:  70  60  50  40  30  20  10
 Drive 2:  F0  E0  D0  C0  B0  A0  90

data_buffer

(2-byte pointer)

Data address pointer: This two-byte address (low byte first) points to a buffer for returned data, which is organized into 16 byte records. If unit_num is 0, the buffer should be 256 bytes long, otherwise 16 bytes is enough.

Page 52



The first byte of a record identifies the device and the length of its volume name:

   7  6  5  4  3  2  1  0
 +--+--+--+--+--+--+--+--+
 |dr|  slot  | name_len  |
 +--+--+--+--+--+--+--+--+

Bit 7 specifies drive 1 (Dr = 0) or drive 2 (Dr = 1). Bits 6-4 specify the slot number (1 through 7). Bits 3-0 specify a valid name_length if nonzero. The next 15 bytes of the record are for a volume name.

If name_length = 0, then an error was detected in the specified slot and drive. The error code is present in the second byte of the record. If error $57 (duplicate volume) is encountered, the third byte contains the unit number of the duplicate. When multiple records are returned, the last valid record is followed by one that has unit_num and name_length set to 0.

Remember: ON_LINE returns volume names that are not preceded by slashes. Remember to put a slash in front of the name before you use it in a pathname.

 Possible Errors
 $27 - I/O error
 $28 - Device not connected
 $2E - Disk switched: File still open on other disk
 $45 - Volume directory not found
 $52 - Not a ProDOS disk
 $55 - Volume Control Block full
 $56 - Bad buffer address
 $57 - Duplicate volume

When an error pertains to a specific drive, the error code is returned in the second byte of the record corresponding to that drive, as described above. In such cases, the call completes with the accumulator set to 0, and the carry flag clear. Only errors $55 and $56 are not drive specific.

Page 53


=== SET_PREFIX ($C6) ===

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

Sets the system prefix to the indicated directory. The pathname may be a full pathname or a partial pathname. The system prefix can be set to null by indicating a pathname with a count of zero. The prefix must be no longer than 64 characters. When ProDOS is started up, the system prefix is set to the name of the volume in the startup drive. The MLI verifies that the requested prefix directory is on an on-line volume before accepting it.

Parameters

param_count

(1-byte value)

Parameter count: 1 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 current prefix is attached to the front to make a full pathname. A slash at the end of the pathname is optional.

 Possible Errors
 $27 - I/O error
 $40 - Invalid pathname syntax
 $44 - Path not found
 $45 - Volume directory not found
 $46 - File not found
 $4A - Incompatible file format
 $4B - Unsupported storage_type
 $5A - Bit map disk address is impossible

Page 54

=== GET_PREFIX ($C7) ===

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

Returns the current system prefix. If the system prefix is set to null (no prefix), then a count of 0 is returned. Otherwise the returned prefix is preceded by a length byte and bracketed by slashes. Examples are $7/APPLE/ and $D/APPLE/BYTES/. Each character in the prefix is returned with its high bit cleared. The buffer pointed to by data_buffer is assumed to be 64 bytes long.

Parameters

param_count

(1-byte value)

Parameter count: Must be 1 for this call.

data_buffer

(2-byte pointer)

Data address pointer: This two-byte address (low byte first) points to the buffer into which the prefix should be placed. It should be at least 64 bytes long.

 Possible Error 
 $56 - Bad buffer address

Page 55