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:

  1. Insert (or mount) the Turbo-BASIC XL disk in drive 1.
  2. Hold OPTION while switching on, so that the built-in Atari BASIC is disabled.
  3. Wait for the READY prompt.

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).
  • LIST indents the bodies of loops automatically (*L - turns this off), so structure is visible.
  • Hexadecimal constants are allowed: POKE $D01A,0.
  • %0, %1, %2 and %3 are compact constants for 0–3, each saving six bytes.
  • CLOSE with no channel closes all channels; SOUND with no arguments silences all voices; RND needs no dummy argument; GET K reads a key without opening K:.

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,r draws a circle, or an ellipse with a second, vertical radius.
  • FCOLOR n sets a fill colour and FILLTO x,y performs the same fill as XIO 18, starting from a point inside the shape (line 30 is the documentation's own circle example); PAINT x,y is a recursive flood fill for any closed shape.
  • TEXT x,y,A$ draws text into a graphics screen.
  • DSOUND n,f,d,v pairs channels for a wider frequency range; DSOUND alone 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:

  1. Prepare a blank DOS 2.5 disk (with DOS.SYS and DUP.SYS) for the output, and a disk holding your program.
  2. Boot the compiler disk, type DOS, and use option L to load COMPILER.COM. (Its menu is in German; Control-D returns to DOS — answer J for Ja.)
  3. Press 1 (or 2 for drive 2), choose your program from the list with the arrow keys and press RETURN.
  4. Save the result under a name ending in .CTB — the compiler insists on it. Name it AUTORUN.CTB to run at boot.
  5. Copy RUNTIME.COM from the compiler disk to the output disk and rename it AUTORUN.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/50 instead.

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