BASIC XL and BASIC XE: A Programmer's Guide

BASIC XL (1983) and BASIC XE (1985) are Optimized Systems Software's enhanced replacements for Atari BASIC. Their great trick is compatibility: they use the same tokens, so a program SAVEd from Atari BASIC LOADs and runs unchanged. You can start from what you already know and add features one at a time. This guide is a tour of those features for programmers. The software entries BASIC XL and BASIC XE cover their history and reception.

What you'll learn: the editing aids, FAST mode, structured IF/ELSE/ENDIF and WHILE, string arrays and string functions, memory and joystick helpers, the player/missile commands, the SET options, and BASIC XE's procedures and EXTEND mode.

What you need: the BASIC XL SuperCartridge (any 400, 800, XL or XE), or the BASIC XE cartridge plus its extensions disk (XL and XE machines only), or their images in an emulator such as Altirra, which supports the OSS cartridge types. The examples were checked line by line against the OSS reference manuals; they have not been run on a cartridge.

1. Editing aids

BASIC XL accepts programs typed in upper or lower case and converts keywords and variable names as you enter them; text inside quotes is left alone. LIST prints keywords with an initial capital and indents loops and IF blocks. Other conveniences:

Command What it does
NUM 100,10 Automatic line numbers (start, step). Press RETURN on an empty line to stop
RENUM 1000,10 Renumber the program, including constant GOTO/GOSUB targets
DEL 1000,1999 Delete a range of lines
LVAR List every variable and the lines that use it (LVAR P: prints it)
TRACE / TRACEOFF Show each line number in brackets as it runs
DIR, ERASE, RENAME, PROTECT Disk housekeeping without going to DOS

Error messages come with a short description as well as the number. RENUM can't fix computed line numbers such as GOTO 1000+10*X, and it stops renumbering a line's targets after the first computed one.

2. FAST

Without FAST, BASIC XL works like Atari BASIC: whenever it executes a GOTO, GOSUB, FOR or WHILE, it searches for the target line from the top of the program, which is why big programs slow down. FAST precompiles the program in memory and replaces every constant line-number reference with the address of the line, so jumps no longer search. Put FAST as an early line of your program, for example 10 FAST. RUN "D:PROGRAM" does a FAST automatically after loading. Computed targets (GOTO X*100) still search, so prefer constants in speed-critical code.

3. Structured statements

BASIC XL adds a block IF. The condition is followed by a colon, not THEN, and the block can span any number of lines:

100 IF A>B : REM SO FAR A IS BIGGER
110 IF A>C : PRINT "A BIGGEST"
120 ELSE : PRINT "C BIGGEST"
130 ENDIF
140 ELSE
150 IF B>C : PRINT "B BIGGEST"
160 ELSE : PRINT "C BIGGEST"
170 ENDIF
180 ENDIF

The colon is compulsory and must be followed by a statement (a REM will do). The old one-line IF … THEN still works as before.

WHILE … ENDWHILE loops while an expression is non-zero, testing it at the top of each pass, so a loop can run zero times. Don't GOTO out of a WHILE loop without a POP, or a nesting error follows. SET 3,1 makes FOR loops behave the same way (the ANSI rule) instead of always running at least once as in Atari BASIC.

4. Strings

Three changes make strings much easier.

String arrays. DIM W$(3,10) creates three strings of up to 10 characters each. An element is written with a semicolon, W$(2;), and you can take a substring of an element with W$(2;1,3). Elements count from 1.

Concatenation with commas. A$=B$," AND ",C$ joins strings in one assignment, and also works on a substring destination.

Functions. LEFT$, MID$ and RIGHT$ work like Microsoft BASIC's, alongside Atari BASIC's A$(start,end) substrings. FIND(string,target,start) returns the position of a substring, or 0. HEX$ converts a number to four hex digits. If you forget a DIM, BASIC XL dimensions a string at 40 characters for you (SET 11 changes the size, and SET 11,0 restores the Atari BASIC behaviour).

This program puts the pieces together:

10 DIM W$(3,10),A$(40)
20 W$(1;)="RED":W$(2;)="GREEN":W$(3;)="BLUE"
30 I=1
40 WHILE I<=3
50 IF FIND(W$(I;),"E",0):PRINT W$(I;);" HAS AN E"
60 ELSE:PRINT W$(I;);" HAS NO E"
70 ENDIF
80 I=I+1:ENDWHILE
90 A$="RED",",","GREEN",",","BLUE"
100 PRINT A$:PRINT LEFT$(A$,3);" ";MID$(A$,5,5)

It reports that RED, GREEN and BLUE each contain an E, then prints RED,GREEN,BLUE and RED GREEN.

5. Numbers and memory

Hexadecimal constants are written with a $ ($D000, up to $FFFF). Three new operators work bit by bit on positive integers up to 65535: & (AND), ! (OR) and % (exclusive OR). DPEEK and DPOKE read and write 16-bit values, so DPEEK(88) gives the screen address in one go.

MOVE from,to,length copies memory at machine-code speed with no address checking. A negative length copies from the top down, so overlapping blocks can be shifted in either direction. BGET and BPUT load and save raw blocks of memory through an open channel, and RGET/RPUT read and write fixed-length records.

All numbers are still six-byte BCD floating point (ten digits), as in Atari BASIC. BASIC XE's extensions add faster maths routines.

6. Joysticks and player/missile graphics

HSTICK(n) returns −1, 0 or +1 for left, centre and right on joystick port n, and VSTICK(n) returns +1 for up and −1 for down. Together with the player/missile commands, they make movement code very short:

Command Purpose
PMGRAPHICS 2 (PMG.) 0 = off, 1 = single-line, 2 = double-line resolution
PMCOLOR p,hue,lum Colour of player p and its missile
PMCLR p Erase a player (4–7 erase all missiles)
PMADR(p) Address of player p's memory, for POKE, MOVE or BGET
PMMOVE p,x;dy Absolute horizontal position, relative vertical move (+ = up)
PMWIDTH p,w Width 1, 2 or 4
MISSILE p,y,h Draw (or erase, by exclusive OR) a missile
BUMP(p,q) Collision test: players 0–3, missiles 4–7, playfields 8–11
10 GRAPHICS 3
20 PMGRAPHICS 2:PMCLR 0
30 PMCOLOR 0,13,8
40 FOR I=0 TO 7:READ D:POKE PMADR(0)+48+I,D:NEXT I
50 DATA 24,60,126,255,255,126,60,24
60 X=120:PMMOVE 0,X
70 X=X+HSTICK(0)
80 PMMOVE 0,X;VSTICK(0)
90 GOTO 70

The joystick steers a diamond around the screen. Set PMCOLOR before you expect to see anything: player colours have no defaults. SET 7,1 makes players and missiles wrap from the bottom of the screen to the top instead of scrolling off. In BASIC XL, clear the collision registers with POKE 53278,0; BASIC XE adds a HITCLR statement for this.

7. The SET options

SET option,value changes system behaviour. Some useful ones, with their defaults in brackets:

SET Effect
0 (0) BREAK: 0 normal, 1 raises a trappable error, 128 ignored
1 (10) Tab stop for commas in PRINT
2 (63) The INPUT prompt character (63 = ?)
3 (0) 1 = FOR loops may run zero times
5 (1) 1 = convert lower case on entry; 0 = leave it alone
6 (0) 1 = error numbers only
9 (0) 1 = ENTER jumps to the TRAP line at end of file (for overlays)
11 (40) Automatic string DIM size; 0 = off
12 (1) 0 = no indentation in LIST

NEW resets everything to the defaults. Options 9 and DEL together allow program overlays: delete a block of lines and ENTER a replacement from disk while the program runs.

8. BASIC XE: procedures and the 130XE

BASIC XE runs BASIC XL programs and adds more. Several features (PROCEDURE, LOCAL, EXIT, FAST, MOVE, RENUM, DEL, LVAR, the fast maths and all P/M commands except HITCLR) live in the extensions file BASICXE.OSS, which loads from disk at power-up. Copy that file to your own boot disk.

Named procedures with parameters:

10 CALL "SQUARE" USING 7 TO R
20 PRINT R
30 END
100 PROCEDURE "SQUARE" USING N
110 LOCAL T
120 T=N*N
130 EXIT T

CALL passes the values after USING into the procedure's variables, which are restored afterwards (an automatic LOCAL), and EXIT hands values back to the variables after TO. LOCAL makes ordinary numeric variables private until the next EXIT, which matters because BASIC XE, like Atari BASIC, allows only 128 variable names. A PROCEDURE must be the first statement on its line, and the program must never run into one by accident: end the main program with END or a GOTO first. Arrays and strings are passed with a ! prefix.

More statements: SORTUP and SORTDOWN sort numeric or string arrays (optionally a range of elements, or by a substring key), and INVERSE/NORMAL switch the PRINT style.

EXTEND (direct mode only) moves your program into the 130XE's extra 64K. The prompt changes to XE Ready, and main memory is left free for strings and arrays. FRE(0) then reports data space and FRE(1) program space. A program SAVEd in extended mode re-enters it when loaded. If the extra banks are missing, or already used by something such as DOS 2.5's RAMdisk, you get error 60. See Memory Expansions Beyond the 130XE for what else may be using those banks.

Troubleshooting

  • A typed-in Atari BASIC line misbehaves. A variable name starts with a BASIC XL keyword: NUMBER=7 is read as NUM BER=7. Write LET NUMBER=7, or rename arrays that clash with new functions (BUMP becomes BUMPS).
  • Lower-case text in DATA or REM lines turned into capitals. That's SET 5,1 at work. Put the text in quotes, or use SET 5,0.
  • ELSE gives an error. You wrote IF X THEN. Block IFs use a colon and no THEN.
  • The program needs BASIC XL to run. Anything that uses the new statements does. For listings that also work in Atari BASIC, stick to its statements and LIST them with SET 5,0.
  • BASIC XE's PROCEDURE or FAST gives an error. The extensions file did not load. Boot from a disk containing BASICXE.OSS.
  • An old game runs too fast. It relied on Atari BASIC's slowness for timing. Add delays based on the system clock.

Further reading

  • A Reference Manual for BASIC XL (OSS, 1983; reprinted by 8-Bit Classics) and A Reference Manual for BASIC XE (OSS).
  • Bill Wilkinson and Diane Goldstein, 30 Days to Understanding BASIC XL: the tutorial that accompanied BASIC XL.
  • On this site: the software entries BASIC XL and BASIC XE, Atari BASIC Essentials, Turbo-BASIC XL: A Practical Guide, Player/Missile Graphics in BASIC and Using the 130XE's Extra 64K.

Credits