Path: news.uiowa.edu!chi-news.cic.net!arclight.uoregon.edu!news.uoregon.edu!cie-2.uoregon.edu!nparker
From: nparker@cie-2.uoregon.edu (Neil Parker)
Newsgroups: comp.sys.apple2.programmer
Subject: Re: Help needed with various Apple II technical questions!
Date: 7 Jun 1996 07:38:46 GMT
Organization: University of Oregon Campus Information Exchange
Lines: 103
Message-ID: <4p8ma6$t34@pith.uoregon.edu>
References: <4p2r17$1t6@homer.alpha.net> <awerner-0606960745340001@mastiff.execpc.com>
NNTP-Posting-Host: cie-2.uoregon.edu

In article <awerner-0606960745340001@mastiff.execpc.com> awerner@execpc.com
(Andrew Werner) writes:
>(4) How do I access the ProDOS routines from machine language (as my
>ProDOS technical reference manual is wanting).

Egad.  This is a worse question than the one about the 6502 opcodes.  There
are 26 different functions that can be performed through the ProDOS
machine-language interface (MLI), and each one takes its own unique
parameter list.  That's far more typing that I'm willing to do tonight, but
the information below should at least give a taste of what's available.
For more information, you might want to check out your local used
bookstores for old Apple ProDOS manuals, or for some of the third-party
books that used to be available (I don't even have Apple's ProDOS manuals--
I get by just fine with _Beneath_Apple_ProDOS_ by Don Worth and Pieter
Lechner, and _Exploring_Apple_GS/OS_and_ProDOS_8_ by Gary B. Little).

Machine-language programs call ProDOS by doing a JSR to $BF00.  This entry
point is called the machine-language interface, or MLI, and it's
responsible for carrying out almost all of the functions tha ProDOS can
perform.

To determine what function to perform, ProDOS examines the byte immediately
following the JSR instruction.  Immediately after the command byte come two
more bytes that point to the command's parameter list.  When the call
completes, it returns to the code immediately following the parameter list
pointer.  Thus, a ProDOS call looks like this:

MLI     EQU     $BF00

        JSR     MLI
        DB      COMMAND_CODE
        DW      PARAM_LIST
        BCS     ERROR

The MLI returns with the carry flag set if an error occurred (hence the
"BCS ERROR" instruction in this example), and an error code in the
accumulator.

There are 26 command codes available:

     $40 ALLOC_INT     Set up an interrupt handler
     $41 DEALLOC_INT   Remove an interrupt handler
     $65 QUIT          Exit the current program and run the program launcher
     $80 READ_BLOCK    Read a block from a device
     $81 WRITE_BLOCK   Write a block to a device
     $82 GET_TIME      Get the time from a clock card (if any)
     $C0 CREATE        Create a new file
     $C1 DESTROY       Delete a file
     $C2 RENAME        Rename a file
     $C3 SET_FILE_INFO Change a file's charateristics
     $C4 GET_FILE_INFO Get a file's characteristics
     $C5 ONLINE        Find the name of a disk in a drive
     $C6 SET_PREFIX    Set the prefix to be added to partial pathnames
     $C7 GET_PREFIX    Get the current prefix
     $C8 OPEN          Open an existing file for I/O
     $C9 NEWLINE       Set the line-terminator character for an open file
     $CA READ          Read data from an open file
     $CB WRITE         Write data to an open file
     $CC CLOSE         Close an open file
     $CD FLUSH         Flush a file's block buffer to disk, but don't close
     $CE SET_MARK      Set the current file position
     $CF GET_MARK      Get the current file position
     $D0 SET_EOF       Set the length of a file
     $D1 GET_EOF       Get the length of a file
     $D2 SET_BUF       Set the location of an open file's block buffer
     $D3 GET_BUF       Get the location of an open file's block buffer

Each call expects a different parameter list.  Like I said earlier, the
list of parameter lists is too long for me to type in tonight.  But I can
include a couple of examples...here's how to rename a file, for example:

        JSR $BF00
        DB  $C2        ; $C2 = RENAME
        DW  REN_PARMS
        BCS ERROR

REN_PARMS DB 2         ; RENAME parm list contains 2 parms
        DW  OLD_NAME   ; 1st parm is ptr to old name
        DW  NEW_NAME   ; 2ns parm is ptr to new nme

OLD_NAME DB 8,"OLD.NAME" ; (name is count byte followed by ASCII chars)
NEW_NAME DB 8,"NEW.NAME"

And here's how to quit from a program and return to the ProDOS program
selector:

        JSR $BF00
        DB  $65        ; $65 = QUIT
        DW  QUIT_PARMS
        BRK            ; (QUIT doesn't return)

QUIT_PARMS DB 4        ; QUIT parm list contains 4 parms
        DB  0          ; All 4 parms normally null
        DW  0
        DB  0
        DW  0

                   - Neil Parker
-- 
Neil Parker, nparker@{cie-2,cie}.uoregon.edu, http://cie-2.uoregon.edu/~nparker

                     "Bad move, Neil!"  -- The Tick