How can I run a machine language program off the disk drive on an Apple II?

Question

Apple II was the first computer I used and programmed on, but only in BASIC, and back in 1979. I learned machine code on my ZX Spectrum which was tape only.

On Apple II how do you load/run a machine code program from the disk from the BASIC prompt?

• Do you just type the program file's name?
• Do you first load it and then run it?
• Does the system know which files are machine code? From a file extension, file header, or metadata in the filesystem/catalog/directory?
• Does it require a BASIC launch program that knows what address to load it in ram and the start executing machine code with a command that takes that address as an argument?
• Some other way?
• Is it different between Apple DOS vs ProDOS?
• It it different between Integer BASIC and Applesoft BASIC?

This is surprisingly resisting my Googling efforts. I thought it would be trivial to find.

(I'm only interested in the "original" Apple II models, not the IIGS, which is surely different.)

Answer 1

In Apple DOS simply

BRUN nameoffile

if it is an executable binary (type B in CATALOG) it will load and call the machine language at the address that was used to save the binary. If it is just a blob of binary (not code) it will of course crash with BRK call and land in the monitor. Following options are possible Dn to choose the disk, Ss slot number for the disk controller, Vn to select the volume, Aa to load at a specific address (which is commonly not a good idea for programs, as 6502 code is rarely position independant).

It is also possible to just load the binary with the BLOAD command and then call the binary with CALL if you know where the binary was loaded.

EDIT: On normally loaded DOS 3.3 the last BLOAD/BRUN address is in $AA72.$AA73 and the lengths in $AA60.$AA61.

In BASIC

?PEEK(43616)+PEEK(43617)*256
?PEEK(43634)+PEEK(43635)*256

Answer 2

Technically, you don't.

You're running programs (and generally doing everything that requires disk access) from DOS or ProDOS - Without a DOS booted, there is no way to access the disk drive on an Apple II - it just looks as not connected. You will thus not find any disk-related commands in the BASIC manuals - you need to consult the DOS3.3 and ProDOS manuals.

After booting to a DOS (via autoboot or the proper PR# command), BASIC seems to know a number of additional commands (which are, in fact, DOS commands). There are some subtile differences in these new commands (you can, for example, not squeeze multiple DOS commands into a single line, and not all of them can be executed from a program - which is a bit special, anyhow, requiring escaped PRINT instructions). Explaining all of the commands for both DOSs here would reproduce what you can read in a DOS or ProDOS manual and doesn't make much sense.

File information is stored differently between DOS and ProDOS. DOS puts a simple 4-byte header in front of the file containing load address and load length. BRUN uses this information to load the file to the proper place. ProDOS has a much more complicated file header (that you might want to look up in a ProDOS manual), but essentially, it stores load address and length as well for BRUN. BRUN starts the file from its load address.

Answer 3

Partial ProDOS answer.

Thanks to the information in the other answers which are more about Apple DOS, I was able to find (some of?) the information for ProDOS which differs.

ProDOS file header:

UPDATE: It turns out that this metadata is stored in the directory structure of the files, not as a header in the first bytes of the files' data: Apple II Binary File Format

         +----------------------------+
 1 byte  | storage_type | name_length | $00
         |----------------------------|
         |                            | $01
         /                            /
15 bytes /         file_name          /
         |                            | $0F
         |----------------------------|
 1 byte  |         file_type          | $10
         |----------------------------|
         |                            | $11
 2 bytes |        key_pointer         | $12
         |----------------------------|
         |                            | $13
 2 bytes |        blocks_used         | $14
         |----------------------------|
         |                            | $15
 3 bytes |            EOF             |
         |                            | $17
         |----------------------------|
         |                            | $18
         |          creation          |
 4 bytes |        date & time         |
         |                            | $1B
         |----------------------------|
 1 byte  |          version           | $1C
         |----------------------------|
 1 byte  |        min_version         | $1D
         |----------------------------|
 1 byte  |           access           | $1E
         |----------------------------|
         |                            | $1F
 2 bytes |          aux_type          | $20
         |----------------------------|
         |                            | $21
         |                            |
 4 bytes |          last mod          |
         |                            | $24
         |----------------------------|
         |                            | $25
 2 bytes |       header_pointer       | $26
         +----------------------------+

At offset $1f:

aux_type (2 bytes): A general-purpose field in which a system program can store additional information about the internal format of a file. For example, the ProDOS BASIC system program uses this field to record the load address of a BASIC program or binary file, or the record length of a text file. I'd assume a binary file that is machine code just works with BRUN and BLOAD by loading at this address and jumping to the same address to execute, and will probably crash for binary files which are not machine code.

There is also a longer list of file types than with Apple DOS. I removed the ones from the chart which only pertain to the Apple III.

File Type      Preferred Use
$00            Typeless file
$01            Bad block file
$04            ASCII text file
$06            General binary file
$08            Graphics screen file
$0F            Directory file
$19            AppleWorks Data Base file
$1A            AppleWorks Word Processor file
$1B            AppleWorks Spreadsheet file
$1C-$EE        Reserved
$EF            Pascal area
$F0            ProDOS CI 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

I'm not sure if this applies only/both to $06 General binary file and $FC Applesoft program file. The types are probably somewhat like a suggestion and might behave the same.

But then there's $FE Relocatable code file (EDASM), which will surely have a more complicated file format for the reloc info. They require the special tools RBOOT and RLOAD.