The BASIC XL ToolKit

Year
1984
Publisher
Optimized Systems Software, Inc. (OSS)
Type
Utility
Category
Runtime, language extensions and example programs for BASIC XL
Developer
Optimized Systems Software, Inc.
Language
6502 machine language; examples in BASIC XL
Requirements
Atari with at least 40K and a disk drive; BASIC XL SuperCartridge (the extended statements need cartridge version 1.02; later disks were marked for 1.02 and 1.03). The RunTime itself needs no cartridge.
Yellow OSS package reading The BASIC XL Toolkit, Including the BASIC XL Runtime Package, with Precision Software Tools repeated in the background

Overview

The BASIC XL ToolKit was OSS's add-on disk for its BASIC XL cartridge, published in 1984. The back of the package calls it "The Go Everywhere Package", and its main selling point was a way to give BASIC XL programs to people who did not own the cartridge. Inside were three things:

  1. RunTime BASIC XL. BASICXL.COM contains the execution parts of the cartridge, so finished programs run without it.
  2. Six extended statements loaded from disk: PROCEDURE, CALL, LOCAL and EXIT for named subroutines with parameters, and SORTUP and SORTDOWN for sorting string arrays.
  3. Example programs showing keyed file access, player-missile graphics, direct sector I/O and more.

RunTime BASIC XL

Buying the ToolKit gave you the right to distribute the RunTime with your own BASIC XL programs, free or commercially, without paying OSS any royalty. In return you had to send OSS a signed licence agreement and put an OSS copyright label on every copy you distributed.

The RunTime is an ordinary binary file that works under DOS XL, Atari DOS or other compatible DOSes. When it starts it looks for D1:AUTORUN.BXL and runs it as if you had typed RUN "D:AUTORUN.BXL". The manual's recipe for a turnkey disk is short: format a disk with DOS, copy BASICXL.COM to it as AUTORUN.SYS, copy your program as AUTORUN.BXL, and boot. For a disk of several programs, make AUTORUN.BXL a menu. The supplied MENU.BXL does this job.

Things to know:

  • Development statements are left out: LIST, ENTER, NEW, DEL, RENUM, TRACE, TRACEOFF and LVAR stop with "Unimplemented statement". END and STOP wait for START, which does a "RunTime Restart" (it reruns AUTORUN.BXL). DOS cannot return to the program.
  • Errors that are not trapped show the line number and wait for START. The user cannot list or change the program.
  • If AUTORUN.BXL is missing, the RunTime keeps retrying forever. The manual says to eject the disk, switch off and try again.
  • The RunTime cannot bank-switch like the 16K SuperCartridge, so it uses about 11K of RAM where the cartridge uses 8K of address space. Very large programs may not fit.

The extended statements

BASIC XL was designed so that new keywords could be added, and the ToolKit was the first package to use this. The flip side of the disk holds EXTEND.COM. The simplest way to use it is to boot a copy of that side. Its AUTORUN.SYS loads the extensions and runs EXTEND.BXE, a four-line program whose key line is:

30 MOVE $56A,$C4,4

That MOVE copies the pointers to the new statement and syntax tables into $C4–$C7. It has to be done again after any coldstart of BASIC XL, because BASIC XL clears those locations. From DOS XL or OS/A+ you can instead type EXTEND then CARTRIDGE, and do the MOVE yourself at the READY prompt.

Procedures fix two weaknesses of GOSUB: line-number targets are unreadable, and naming subroutines with variables uses up BASIC's 128 variable names. A procedure is named by a quoted string, takes parameters with USING, and can return values with TO:

30 CALL "Get In Range" USING 10,90 TO RESULT1
...
1000 PROCEDURE "Calculate Pay" USING HOURS,RATE,!TAXTABLE()

When a procedure is called, the current values of its parameter variables are pushed onto BASIC's run-time stack, the same stack that GOSUB, FOR and WHILE use, and restored on EXIT. The parameters therefore behave as local copies. The ! prefix passes a string or array by name. LOCAL declares further variables to be saved and restored in the same way.

SORTUP and SORTDOWN sort a string array in place, optionally on just part of each element, such as the name part of a name-and-phone-number record. The manual warns that the order is strict ATASCII, so "ZOO" sorts before "apple". Keep the sort keys in one case.

Example programs

The examples include MENU, a SNAILS trails game, a lunar lander (LEM), a tiny adventure (PICOADVenture), a GTIA graphics-mode test, CIRCLES, a sector-level DISKIO program, a drive configuration program, a PHONE "little black book", and MAKEAUTO, which builds an AUTORUN.SYS that runs a chosen program. FACTOR, SORTDIR and SORTNUM show off the new statements.

Using it today

You need BASIC XL itself. Cartridge images are common in emulator collections, and the extended statements need a cartridge version that matches the ToolKit disk (the manual insists on 1.02). The RunTime is still a practical way to make a bootable disk for a BASIC XL program. Later, OSS's BASIC XE cartridge built procedures, LOCAL and sorting into the language itself.

Credits