Turbo-BASIC XL: A Practical Guide
Turbo-BASIC XL, written by Frank Ostrowski and copyrighted 1985, is the BASIC many XL/XE owners switched to and never left. It was distributed as public domain software — English documentation came from Dave and Laura Yearke of the Western New York Atari Users Group, later expanded by Ron Fetzer — and it remains hugely popular, not least in today's BASIC ten-liner competitions. It keeps full compatibility with Atari BASIC while adding structured programming, faster execution and dozens of conveniences, and a companion compiler speeds programs up further still.
You will learn: how to load Turbo-BASIC XL, its structured loops and procedures, labels, the most useful new statements and functions, its graphics and disk commands, the extra error codes, and how to compile a program.
You need: an XL or XE computer, or an emulator set up as one, and a Turbo-BASIC XL disk image. It does not run on the 400 or 800.
1. Loading it
Turbo-BASIC XL loads from disk rather than cartridge. Its disk boots DOS 2.5, which loads Turbo-BASIC as its AUTORUN.SYS:
- Insert (or mount) the Turbo-BASIC XL disk in drive 1.
- Hold OPTION while switching on, so that the built-in Atari BASIC is disabled.
- Wait for the
READYprompt.
The documentation quotes 34,021 bytes free for your program — 1,747 more than Atari BASIC — and claims programs run about three times faster. Typing DOS leaves Turbo-BASIC for the DOS 2.5 menu, so save your work first; to return, use DOS option L to load AUTORUN.SYS again.
Turbo-BASIC accepts Atari BASIC programs: LOAD, ENTER and RUN them exactly as before. By convention, programs saved from Turbo-BASIC use the extension .TUR and compiled programs .CTB.
2. What changes at once
Even before you use a new keyword, a few things are different:
- Errors are reported in English, not just as numbers.
- Most keywords may be typed in lower case or inverse.
- You can have up to 256 variable names, and names may contain the underscore (
HIGH_SCORE). LISTindents the bodies of loops automatically (*L -turns this off), so structure is visible.- Hexadecimal constants are allowed:
POKE $D01A,0. %0,%1,%2and%3are compact constants for 0–3, each saving six bytes.CLOSEwith no channel closes all channels;SOUNDwith no arguments silences all voices;RNDneeds no dummy argument;GET Kreads a key without openingK:.
Atari BASIC also executes a FOR X=2 TO 1 loop once even though the start is past the limit; *F makes Turbo-BASIC skip such loops instead.
3. Structured loops
Three new loop forms join FOR/NEXT, and EXIT leaves any of them:
10 A=0
20 REPEAT
30 A=A+1:? A;" ";
40 UNTIL A=10
50 ?
60 WHILE A>0
70 A=A-1
80 WEND
90 DO
100 GET K
110 IF K=27 THEN EXIT
120 ? CHR$(K);
130 LOOP
140 ? :? "ESC PRESSED"
REPEAT ... UNTIL tests at the bottom, WHILE ... WEND at the top, and DO ... LOOP runs forever until EXIT. When you LIST this, Turbo-BASIC indents lines 30, 70 and 100–120 for you.
4. IF ... ELSE ... ENDIF
The multi-line IF has no THEN; it ends with ENDIF and may include ELSE:
10 INPUT "NUMBER >",N
20 IF N MOD 2=0
30 ? "EVEN"
40 ELSE
50 ? "ODD"
60 ENDIF
It can also go on one line, with colons around ELSE: IF X>3:? "TOO LARGE":ELSE:? "OK":ENDIF. The ordinary Atari BASIC IF ... THEN still works as before.
Note INPUT "prompt",var: Turbo-BASIC allows a prompt in INPUT. With a comma, nothing is added after the prompt; with a semicolon, the usual ? is printed.
5. Procedures and labels
Named procedures replace numbered GOSUBs:
10 GRAPHICS 7+16:COLOR 1
20 FOR R=5 TO 45 STEP 5:CIRCLE 80,48,R:NEXT R
30 PAUSE 120
40 GRAPHICS 0:EXEC REPORT
50 END
100 PROC REPORT
110 ? "SCREEN MEMORY AT $";HEX$(DPEEK(88))
120 ? "17 DIV 5 = ";17 DIV 5;" 17 MOD 5 = ";17 MOD 5
130 ENDPROC
PROC name ... ENDPROC defines it, EXEC name calls it, and ON X EXEC A,B,C picks one by number. Keep an END before your procedures so the main program does not fall into them.
Any line can also carry a label with #: after 200 # GAME_OVER, you can write GO# GAME_OVER, TRAP #GAME_OVER or RESTORE #GAME_OVER. Labels survive renumbering, which line numbers in GOTO X*10 style expressions do not.
6. Handy statements and functions
Memory: DPOKE/DPEEK read and write two-byte values (no more PEEK(88)+256*PEEK(89)); MOVE from,to,length copies a block of memory, and -MOVE copies starting from the last byte, for overlapping moves upwards.
Files: BPUT #n,adr,len and BGET #n,adr,len write and read whole blocks — ideal for saving a screen; %PUT #n,A and %GET #n,A store numbers in binary form, faster than PRINT # and INPUT #.
Strings: INSTR(X$,A$,start) finds a substring and UINSTR does the same ignoring case and inverse; INKEY$ returns the last key pressed; HEX$(n) and DEC(A$) convert to and from hexadecimal (use upper-case hex digits for DEC).
Maths: integer division DIV, remainder MOD, FRAC and TRUNC, RAND(n) (an integer from 0 to n−1), and bitwise & (AND), ! (OR) and EXOR on positive integers — something Atari BASIC sorely lacks.
Timing: PAUSE n waits n jiffies (about 1/60 s each); TIME returns the jiffy counter and TIME$ the time as HHMMSS. Note that TIME$ assumes a 60 Hz machine and so runs fast on 50 Hz PAL computers.
Debugging: TRACE shows each line number in brackets as it executes (TRACE - stops); DUMP lists all variables and their values (or DUMP "P:" to the printer); RENUM start,new,step renumbers (but not computed line references); DEL a,b deletes a range of lines; ERR and ERL give the last error number and line; *B lets TRAP catch the BREAK key.
7. Graphics and sound
10 GRAPHICS 7+16:DIM A$(5):A$="TURBO"
20 COLOR 1:CIRCLE 80,48,45
30 FCOLOR 3:FILLTO 80,48
40 COLOR 2:CIRCLE 80,48,20,15
50 TEXT 4,4,A$
60 PAUSE 300
CIRCLE x,y,rdraws a circle, or an ellipse with a second, vertical radius.FCOLOR nsets a fill colour andFILLTO x,yperforms the same fill asXIO 18, starting from a point inside the shape (line 30 is the documentation's own circle example);PAINT x,yis a recursive flood fill for any closed shape.TEXT x,y,A$draws text into a graphics screen.DSOUND n,f,d,vpairs channels for a wider frequency range;DSOUNDalone turns it off.
8. Disk commands without DOS
DIR, DIR "D2:*.BAS", DELETE, RENAME "D:OLD,NEW", LOCK and UNLOCK all work directly from Turbo-BASIC, with wildcards. In a program line they must be the last statement. BLOAD "D:FILE" loads a binary file and BRUN loads and runs it. A program named AUTORUN.BAS on the boot disk is run automatically.
9. New error codes
| Code | Meaning |
|---|---|
| 22 | Loops not properly nested |
| 23 | WEND with no matching WHILE |
| 24 | UNTIL with no matching REPEAT |
| 25 | LOOP with no matching DO |
| 26 | EXIT outside a loop |
| 27 | Error executing a procedure |
| 28 | ENDPROC with no matching EXEC |
| 29 | PROC does not exist |
| 30 | Label does not exist |
10. The Turbo-BASIC XL compiler
The companion compiler (also by Frank Ostrowski) turns Turbo-BASIC or Atari BASIC programs into compiled files that run several times faster — its documentation claims 3–5 times faster than Turbo-BASIC itself and 10–15 times faster than Atari BASIC. Compiled programs also need an XL/XE. The procedure:
- Prepare a blank DOS 2.5 disk (with DOS.SYS and DUP.SYS) for the output, and a disk holding your program.
- Boot the compiler disk, type
DOS, and use option L to loadCOMPILER.COM. (Its menu is in German; Control-D returns to DOS — answer J for Ja.) - Press 1 (or 2 for drive 2), choose your program from the list with the arrow keys and press RETURN.
- Save the result under a name ending in
.CTB— the compiler insists on it. Name itAUTORUN.CTBto run at boot. - Copy
RUNTIME.COMfrom the compiler disk to the output disk and rename itAUTORUN.SYS. The runtime is what actually loads and executes the compiled program.
The compiler documentation reports two problem cases: the END statement, and FOR loops with more than one NEXT, such as IF X=3 THEN NEXT X inside the loop. Restructure those before compiling.
Troubleshooting
- It will not load / crashes at boot: you are on a 400/800, or BASIC was not disabled — hold OPTION, or turn off the internal BASIC in your emulator.
- A program behaves differently than in Atari BASIC: check for backwards FOR loops (
*F) or variable names that are now keywords (ERR, TIME, DIV and friends). - DIR or DELETE gives an error mid-program: disk commands must be the last statement on their line.
- TIME$ drifts on a PAL machine: expected; calculate time from
TIME/50instead.
Further reading
- The Turbo-BASIC XL Expanded Documentation PDF (Ron Fetzer's text, reformatted with a memory map and compiler notes), posted on AtariAge in 2014.
- The German ABBUC Turbo-BASIC XL 1.5 Handbuch.
- Your Atari Computer — Lon Poole, Martin McNiff and Steven Cook (McGraw-Hill, 1982), which the Turbo-BASIC documentation itself recommends for background on graphics modes and colours.
Credits
- Turbo-BASIC XL Expanded Documentation (Ron Fetzer; reformatted by MrFish), incl. Compiler instructions by Dave Arlington — Turbo-BASIC XL Expanded Documentation (Ron Fetzer); AtariAge forum members
- AtariAge — Turbo-BASIC XL - Expanded Documentation thread — Turbo-BASIC XL Expanded Documentation (Ron Fetzer); AtariAge forum members
- comp.sys.atari.8bit FAQ — 7.3.5 filename extensions (.TUR, .CTB) — Michael Current (comp.sys.atari.8bit FAQ)
