AUTORUN.SYS and Auto-Booting Programs
Put a file called AUTORUN.SYS on an Atari DOS 2 disk and it runs every time the disk boots. That simple convention gave thousands of disks their "insert and switch on" convenience: games that started by themselves, handlers loaded before BASIC, and magazine disks that opened straight into a menu. This guide covers what DOS actually does with the file, how to make a BASIC program start by itself (BASIC programs can't simply be renamed), and how the other popular DOSes do the same job.
What you'll learn: when and how AUTORUN.SYS is loaded, what happens before and after it, the classic E: hook trick for starting a BASIC program (with a tested assembly version), combining and skipping autoruns, and the MyDOS, SpartaDOS, BW-DOS and Turbo-BASIC conventions.
What you need: a DOS 2.0S or 2.5 disk, the MADS assembler for the example, and a way to copy files to the disk. The binary file format itself (segments, RUNAD and INITAD) is covered in Inside the XEX, and boot sectors in Writing a Bootable Disk Program.
1. What DOS 2 does at boot
- The OS reads the boot sectors, which load DOS.SYS (the file manager) and link
D:into the handler table. - As part of its initialisation, DOS looks on drive 1 for
AUTORUN.SYS. If the file exists, DOS binary-loads it exactly as the menu's L command would. Any INIT address (INITAD, $02E2) is called as soon as its segment loads, and the RUN address (RUNAD, $02E0) is called once the whole file is in memory. - When the autorun code returns with RTS, DOS finishes its setup and the OS continues the cold start. If a cartridge (or XL/XE built-in BASIC) wants to run, it starts now. Otherwise the OS jumps through DOSVEC, which brings up the DUP menu if DUP.SYS is on the disk.
Three consequences follow:
- AUTORUN.SYS runs before BASIC starts. Anything it changes, such as colours, margins, MEMLO or the handler table, is already in place when BASIC initialises. BASIC takes the start of its program memory from MEMLO at that point, so an AUTORUN handler that raises MEMLO is automatically protected.
- It runs only at power-up. A one-line AUTORUN.SYS that increments a byte in page 6 shows this: after a RESET, the counter still reads 1 under DOS 2.5. Code that must survive RESET has to hook DOSINI itself (see Writing Your Own CIO Device Handler).
- It's an ordinary binary file. Any XEX-style program renamed to AUTORUN.SYS will load. A program that never returns simply takes over the machine, which is how most games did it.
Typical AUTORUN.SYS files come in three kinds: small setup files that just change system settings, handlers (RS-232, printer and screen drivers) that install themselves and return, and BASIC program loaders. The last kind is the interesting one.
2. Why BASIC programs need a helper
A SAVEd BASIC program is tokenized data for the BASIC interpreter, not machine code, so DOS can't binary-load it. Something has to get BASIC to execute RUN "D:MENU.BAS" after BASIC has started, which is after AUTORUN.SYS has already finished. Some options:
- Stuff the keyboard. The OS keeps only one pending keystroke (CH, location 764), so you can't type a whole command that way.
- Print the command and force-read it. The screen editor's forced-read mode (AUX1 = 13 on IOCB 0) works inside BASIC, but BASIC's cold start clears the screen first.
- Hook the E: handler. This is the classic answer, used for example by Carl Evans's AUTOGO in Atari BASIC Faster and Better (1983), a BASIC program that writes such an AUTORUN.SYS for any file name.
The hook works like this. The AUTORUN code finds the E entry in HATABS ($031A), copies the editor's 16-byte vector table into RAM, replaces the GET BYTE vector with its own routine, and points the E entry at the copy. When BASIC starts and asks the editor for its first input line, CIO calls the fake GET routine, which returns the command one character at a time. When it hands over the final RETURN (EOL), the routine puts the original HATABS entry back, so the keyboard works normally from then on. As far as BASIC can tell, someone typed the command very quickly.
3. A tested AUTORUN.SYS for BASIC programs
; AUTORUN.SYS that makes BASIC run a program - mads autorun.asm -o:autorun.sys
HATABS = $031A
PTR = $CB ; temporary page-zero pointer
EOL = $9B
org $0600 ; dead once the command has been read
install ldx #0
find lda HATABS,x ; find the E: entry
cmp #'E'
beq found
inx
inx
inx
cpx #36
bcc find
rts ; no E: (can't happen)
found stx eslot
lda HATABS+1,x ; remember the ROM vector table address
sta PTR
sta oldtab
lda HATABS+2,x
sta PTR+1
sta oldtab+1
ldy #15 ; copy the 16-byte table into RAM
cp lda (PTR),y
sta etab,y
dey
bpl cp
lda #<(myget-1) ; replace GET BYTE (offset 4)
sta etab+4
lda #>(myget-1)
sta etab+5
lda #<etab ; point E: at the patched copy
sta HATABS+1,x
lda #>etab
sta HATABS+2,x
lda #0
sta pos
rts ; back to DOS, which carries on booting
myget ldy pos ; hand BASIC the next character
lda cmd,y
inc pos
cmp #EOL
bne ok
ldx eslot ; line complete: put the real E: back
lda oldtab
sta HATABS+1,x
lda oldtab+1
sta HATABS+2,x
lda #EOL
ok ldy #1 ; success
rts
cmd dta c'RUN "D:MENU.BAS"',EOL
eslot dta 0
oldtab dta a(0)
pos dta 0
etab .ds 16
ini install
Assemble it, copy autorun.sys to the disk as AUTORUN.SYS along with DOS.SYS and your MENU.BAS, and boot with BASIC enabled. The screenshot shows the result on a DOS 2.5 disk: the program ran without anyone typing anything, and MEMLO reads 7276 ($1C6C), DOS 2.5's value. Notes:
- The stub lives in page 6. It is only needed until BASIC has read the command line, after which your BASIC program may use page 6 freely. AUTOGO used the same arrangement.
- Change
cmdto run a different file, or to execute something else entirely.ENTER "D:SETUP.LST"would merge a listed file. A short string of statements such asPOKE 82,0:RUN "D:MENU.BAS"also works, since BASIC accepts anything you could type at the READY prompt. - The GET routine doesn't need to preserve X, because CIO reloads the IOCB index itself before every handler call. Handler conventions are covered in Writing Your Own CIO Device Handler.
- Without BASIC (an 800 with no cartridge, or an XL/XE booted with OPTION held), the DUP menu would receive the command instead. A careful loader checks first that a cartridge is present.
If you'd rather not assemble anything, DOS 2.5's SETUP.COM (option 3) builds an equivalent file from a menu, and can load the 850's R: handler at the same time. See Atari DOS 2.5: A Practical Guide.
4. More than one autorun, and skipping them
Because AUTORUN.SYS is a binary file, two programs can often be combined into one by appending binary files. DOS 2's copy command does this with the /A option. Antic's "AUTORUN Selector" (June 1989) used it to put a small prefix in front of an existing AUTORUN.SYS:
C
AUTORUN.SYS,SELECT.EXE/A
followed by deleting the old AUTORUN.SYS and renaming SELECT.EXE to take its place. Combining files works only if the parts don't load into the same memory, and if each part's INIT returns rather than taking over. A RUN address in the first part is replaced by any later one, since only the last RUNAD written counts.
The Selector prefix itself solved a common annoyance: DOS 2 has no way to bypass AUTORUN.SYS. The prefix reads CONSOL ($D01F). If SELECT is held during boot (bit 1 clear), it jumps through DOSVEC to the DOS menu instead of letting the rest of the file load. Antic's "Multi-AUTORUN" (March 1987) went the other way. It patched DOS.SYS to load AUTORUN.SYS, then AUTORUN1.SYS, AUTORUN2.SYS and so on, until one was missing.
On an XL/XE, holding OPTION during power-up disables the built-in BASIC. That matters both for autoruns that need the RAM at $A000–$BFFF and for BASIC loaders, which then have no BASIC to talk to.
5. Other DOSes
| DOS | Startup convention |
|---|---|
| Atari DOS 2.0S, 2.5 | AUTORUN.SYS (binary) on D1: |
| MyDOS 4.50 | AUTORUN.SYS, like DOS 2. Its utilities are shipped as .AUT files (e.g. ATARI850.AUT) for renaming |
| MyDOS 4.53 | *.AR0 to *.AR9, several at boot. Plain AUTORUN.SYS support was removed |
| SpartaDOS 3.2 | Both a STARTUP.BAT batch file and an AUTORUN.SYS |
| SpartaDOS X, DOS XE | AUTOEXEC.BAT (a text batch file of commands) |
| BW-DOS | STARTUP.BAT |
| Turbo-BASIC XL | Runs AUTORUN.BAS from the boot disk when it starts |
Under SpartaDOS X, starting a BASIC program needs no machine code. A text file holding the BASIC command is fed to BASIC with input redirection. Put RUN "D:START.BAS" in a text file called AUTOGO, then add this line to AUTOEXEC.BAT:
BASIC <<AUTOGO
The SDX manual also suggests renaming an old DOS 2-style BASIC loader to something like MENU.COM and running it with BASIC IN MENU. For AUTOEXEC.BAT basics and CONFIG.SYS's SET BATCH= alternative, see SpartaDOS X: Getting Started. Handler-type AUTORUN.SYS files can usually just be renamed to .COM and run from the SDX command line.
Troubleshooting
- Nothing happens at boot: the file isn't named exactly
AUTORUN.SYS, it isn't on the disk in drive 1, or the disk doesn't contain DOS.SYS (for example, the DOS files were never written to it). - Boots to the DOS menu instead of BASIC: BASIC is disabled (OPTION held, or no cartridge on an 800), or your AUTORUN code jumped through DOSVEC.
- ERROR 170 (file not found) right after boot: the BASIC loader worked, but the file name in its command doesn't match the disk.
- Machine locks up after loading: the AUTORUN code loads over DOS, its buffers or page zero still in use by DOS. Load above MEMLO (around $1C6C under DOS 2.5, more with extra buffers).
- Works until RESET: expected. AUTORUN.SYS isn't reloaded on RESET, so hook DOSINI.
Further reading
- De Re Atari (Atari, 1982), chapter 9: "The AUTORUN.SYS File". Note that it swaps the RUN and INIT addresses ($02E0 is RUN).
- Carl M. Evans, Atari BASIC Faster and Better (IJG, 1983), chapter 15: AUTOGO, a BASIC program that writes an E:-hooking AUTORUN.SYS.
- "AUTORUN Selector", Jason Strautman, Antic, June 1989. "Multi-AUTORUN", Bill Bodenstein, Antic, March 1987.
- SpartaDOS X Reference Manual (ICD): chapter 5, batch files and I/O redirection, and the appendix on running DOS 2 AUTORUN files.
- On this site: Inside the XEX, Atari DOS 2.5: A Practical Guide, MyDOS 4.5, Choosing a DOS and Saving and Loading BASIC Programs.
Credits
- Picture: A DOS 2.5 disk booted with BASIC: the 126-byte AUTORUN.SYS below fed RUN "D:MENU.BAS" to BASIC, and the program started on its own. — Program authors; screenshot by the site
- De Re Atari, Chapter 9: The AUTORUN.SYS File — AtariArchives.org
- Atari BASIC Faster and Better (Carl M. Evans, IJG 1983), chapter 15 — AUTOGO — Internet Archive, 1983
- Antic Vol. 8 No. 2 (June 1989) — AUTORUN Selector, Jason Strautman — AtariMagazines.com (Kevin Savetz), 1989
- Antic Vol. 5 No. 11 (March 1987) — Multi-AUTORUN, Bill Bodenstein — AtariMagazines.com (Kevin Savetz), 1987
- comp.sys.atari.8bit FAQ (Michael Current) — DOS 2.5 SETUP.COM, MyDOS 4.5x/4.53, SpartaDOS 3.2, DOS XE, BW-DOS startup files — Michael Current (comp.sys.atari.8bit FAQ)
- SpartaDOS X Reference Manual (ICD) — AUTOEXEC.BAT, I/O redirection (BASIC <<AUTOGO), BASIC command, running AUTORUN.SYS files — sdx.atari8.info
- Mapping the Atari — 764 CH, 54017 PORTB (OPTION disables BASIC), 794-831 HATABS — AtariArchives.org
