Atari BASIC

The 8K Atari BASIC cartridge

In September 1978, Shepardson Microsystems won the bid on completing BASIC[4] and was finishing Cromemco 16K Structured BASIC for the Z80-based Cromemco S-100 bus machines.[6][7] Developers Kathleen O'Brien and Paul Laughton used Data General Business Basic, an integer-only implementation, as the inspiration for their BASIC, given Laughton's experience with Data General on a time-sharing system.[8]

What became Atari BASIC is a pared-down version of Cromemco BASIC ported to the 6502. That needed 10K of code.[9] To make it fit in Atari's 8K cartridge, some of common routines were moved to the operating system ROMs. This included 1780 bytes for floating point support that were placed in a separate 2K ROM on the motherboard.[4]

Atari accepted the proposal, and when the specifications were finalized in October 1978, Paul Laughton and Kathleen O'Brien began work on the new language.[4] The contract specified the delivery date on or before 6 April 1979 and this also included a File Manager System (later known as DOS 1.0).[9] Atari's plans were to take an early 8K version of Microsoft BASIC to the 1979 CES and then switch to the new Atari BASIC for production. Development proceeded quickly, helped by a bonus clause in the contract, and an 8K cartridge was available just before the release of the machines. Atari took that version to CES instead of the MS version.[10] Atari Microsoft BASIC later became available as a separate product.[11]

The version Shepardson gave to Atari for the CES demo was not supposed to be the final version. Between the time they delivered the demo and the final delivery a few weeks later, Shepardson fixed several bugs in the code.[10] Unknown to Shepardson, Atari had already sent the CES version to manufacturing.[12]

This version was later known as Revision A. It contains a major bug in a subroutine that copies memory; deleting lines of code that were exactly 256 bytes long causes a lockup. This was sometimes known as the "two-line lockup" because it did not trigger until the next line of code or command was entered. It cannot be fixed by pressing the Reset key.[13]

Revision B attempted to fix all of the major bugs in Revision A and was released in 1983 as a built-in ROM in the 600XL and 800XL models. While fixing the memory copying bug, the programmer noticed the same pattern of code in the section for inserting lines, and applied the same fix. This instead introduced the original bug into this code. Inserting new lines is much more common than deleting old ones, so the change dramatically increased the number of crashes.[13] Revision B also contains a bug that adds 16 bytes to a program every time it is SAVEd and LOADed, eventually causing the machine to run out of memory for even the smallest programs.[14][15] Mapping the Atari described these as "awesome bugs" and advised Revision B owners "Don't fool around; get the new ROM, which is available on cartridge" from Atari.[15] The book provides a type-in program to patch Revision B to Revision C for those without the cartridge.[16]

Revision C eliminates the memory leaks in Revision B.[15] It is built-in on later versions of the 800XL[14] and all XE models including the XEGS. Revision C was also available as a cartridge.[15]

The version can be determined by typing PRINT PEEK(43234) at the READY prompt. The result is 162 for Revision A, 96 for Revision B, and 234 for Revision C.[17]

Syntax errors are reported immediately after a line is entered.

Atari BASIC uses a line editor like most home computer BASICs. Unlike most BASICs, Atari BASIC scans the just-entered program line and reports errors immediately. If an error is found, the editor re-displays the line, highlighting the text near the error in inverse video. Errors are displayed as numeric codes, with the descriptions printed in the manual.[18]

A line entered with a leading number, from 0 to 32767,[19] is inserted in the current program or replaces an existing line. If there's no line number, the commands are executed immediately. The RUN command executes the program from the lowest line number. Atari BASIC allows all commands to be executed in both modes. For example, LIST can be used inside a program.

LIST displays either the entire program or a range of lines separated with a comma. For instance, LIST 10,50 displays all lines from 10 to 50, inclusive. The output can be redirected by specifying the device identifier. LIST "P:" sends a program listing to the printer instead of the screen, LIST "C:" to the cassette.

Program lines can be up to three physical screen lines of 40 characters–120 characters total. The cursor can be moved freely, with the editor automatically tracking which BASIC program line the current screen line is part of. Pressing ↵ Enter tokenizes the current line. In the example pictured above (with PRUNT), the error can be fixed by moving the cursor over the U, typing I (the editor only has an overwrite mode), and hitting ↵ Enter.

Atari BASIC's tokenizer parses the entire line when it is entered or modified. All keywords are converted into a one-byte token. Numeric constants are parsed into their 40-bit internal form and then placed in the line in that format, while strings are left in their original format, but prefixed with a byte describing their length. Variables have storage set aside as they are encountered, and their name is replaced with a pointer to their storage location in memory. Shepardson referred to this early-tokenizing concept as a "pre-compiling interpreter".[20]

The original text for the line is stored in the BASIC Input Line Buffer in memory between 580 and 5FF₁₆. The token output buffer (addressed by a pointer at LOMEM – 80, 81₁₆) is 256 bytes, and any tokenized statement larger than the buffer generates an error (14 – line too long). The output from the tokenizer is then moved into more permanent storage in various locations in memory. The program is stored as a parse tree.[lower-alpha 2]

A set of pointers (addresses) indicates various data: variable names are stored in the variable name table (VNTP – 82, 83₁₆) and their values are stored in the variable value table (pointed to at VVTP – 86, 87₁₆). By indirecting the variable names in this way, a reference to a variable needs only one byte to address its entry into the appropriate table. String variables have their own area (pointed to at STARP – 8C, 8D₁₆) as does the runtime stack (pointed to at RUNSTK – 8E, 8F₁₆) used to store the line numbers of looping statements (FOR...NEXT) and subroutines (GOSUB...RETURN). Finally, the end of BASIC memory usage is indicated by an address stored at MEMTOP – 90, 91₁₆) pointer.

Keywords can be abbreviated using the pattern set by Palo Alto Tiny BASIC, by typing a period at any point in the word. So L. is expanded to LIST, as is LI.. Only enough letters have to be typed to make the abbreviation unique, so PLOT requires PL. because the single letter P is not unique. To expand an abbreviation, the tokenizer searches through its list of reserved words to find the first that matches the portion supplied. More commonly used commands occur first in the list of reserved words, with REM at the beginning (it can be typed as .). When the program is later LISTed it will always write out the full words with three exceptions: PRINT has a synonym, ?; GOTO has a synonym, GO TO; and LET has a synonym which is the empty string (so 10 LET A = 10 and 10 A = 10 mean the same thing). These are separate tokens, and so will remain as such in the program listing. MS BASICs also allowed ? as a short-form for PRINT, but did expand it when listing, treating it as an abbreviation, not a synonym.

In the keywords for communicating with peripherals (see the Input/Output section, below) such as OPEN # and PRINT #, the " #" is actually part of the tokenized keyword and not a separate symbol. For example, "PRINT" and "PRINT #0" are the same thing,[lower-alpha 3] just presented differently.

Atari BASIC includes three trignometric functions: sine, cosine, and arc tangent. DEG and RAD set whether these functions use radians or degrees, defaulting to radians.

Eight additional functions include rounding, logarithms, and square root. The random function, RND, generates a number between 0 and 1, with the parameter to the function not being used.

Atari BASIC differs considerably from Microsoft-style BASICs in the way it handles strings. Microsoft BASIC mostly copied the string-handling system of DEC's BASIC-PLUS, in which strings are first-class types with variable lengths and bounds. This allows both string variables, as well as arrays of strings, as both are represented internally by a computer word pointing to storage on a heap.

In contrast, Atari BASIC copied the string-handling system of Hewlett-Packard BASIC, where the basic data type is a single character, and strings are arrays of characters. A string is represented by a pointer to the first character in the string and its length. To initialize a string, it must be DIMensioned with its maximum length, thereby setting aside the required amount of memory on the heap. For example:

10 DIM A$(20)
20 PRINT "ENTER MESSAGE: ";
30 INPUT A$
40 PRINT A$

In this program, a 20 character string is reserved, and any characters in excess of the string length will be truncated. The maximum possible length of a string in Atari BASIC is 32,768 characters.

MS BASIC includes functions for accessing bits of strings, for instance, LEFT$(A$,10) returns the leftmost 10 characters of A$. These functions create new strings on the heap and return a pointer to the start of the new string. In Atari BASIC the string is represented by an array, and was accessed using array indexing functions, or "slicing". The equivalent statement in Atari BASIC would be A$(1,11); the arrays are 1-indexed, not 0-indexed, so a string of length 10 starts at 1 and ends at 11. Because the slicing syntax was the same as the syntax for selecting a string in a two-dimensional array in other BASICs, there was no way to define or work with arrays of strings.

A major advantage of this style of access is that the slicing functions do not create new strings, they simply set pointers to the start and end points within the existing allocated memory. MS BASIC was known for running out of heap space in such programs and entering lengthy memory collection delays while former temporary strings were removed from memory. Atari BASIC creates new heap entries only with the explicit DIM commands, so memory management is eliminated. This offers a major advantage in terms of performance and memory use in programs with significant amounts of string processing.

Atari BASIC does not initialize array variables, and a string or numeric array will contain whatever data was present in memory when it was allocated. The following trick allows fast string initialization, and it is also useful for clearing large areas of memory of unwanted garbage. Numeric arrays can only be cleared with a FOR...NEXT loop:

10 REM Initialize A$ with 1000 characters of X
20 DIM A$(1000)
30 A$="X":A$(1000)=A$:A$(2)=A$

String concatenation in Atari BASIC works as in the following example. The target string must be large enough to hold the combined string or an error will result:

10 DIM A$(12),B$(6)
20 A$="Hello ":B$="there!"
30 A$(LEN(A$)+1)=B$
40 PRINT A$

The INPUT statement cannot be used with a prompt nor with array variables. The latter must be filled indirectly via a statement like 20 INPUT A:B(1)=A. Array variables in Atari BASIC also may contain two subscripts.

Strings included in DATA statements do not have to be enclosed in quote marks in Atari BASIC, as a result, it is also not possible for data items to contain a comma. The READ statement also cannot be used with array variables.

Arrays have a base index of 0, so a statement such as DIM A(10) actually creates an 11-element array (elements 0-10).

The Atari OS includes a subsystem for peripheral device input/output (I/O) known as CIO (Central Input/Output). Most programs can be written independently of what device they might use, as they all conform to a common interface; this was rare on home computers at the time. New device drivers could be written fairly easily that would automatically be available to Atari BASIC and any other program using the Atari OS, and existing drivers could be supplanted or augmented by new ones. A replacement E:, for example could displace the one in ROM to provide an 80-column display, or to piggyback on it to generate a checksum whenever a line is returned (such as used to verify a type-in program listing).

Atari BASIC supports CIO access with reserved words OPEN #, CLOSE #, PRINT #, INPUT #, GET #, PUT #, NOTE #, POINT # and XIO #. There are routines in the OS for graphics fill and draw, but they are not all available as specific BASIC keywords. PLOT and DRAWTO for line drawing are supported while a command providing area fill is not. The fill feature can be used through the general CIO entry point, which is called using the BASIC command XIO.

The BASIC statement OPEN # prepares a device for I/O access:

10 REM Opens the cassette device on channel 1 for reading in BASIC
20 OPEN #1,4,0,"C:MYPROG.DAT"

Here, OPEN # means "ensure channel 1 is free," call the C: driver to prepare the device (this will set the cassette tape spools onto tension and advance the heads keeping the cassette tape player "paused". The 4 means "read" (other codes are 8 for write and 12 = 8 + 4 for "read-and-write"). The third number is auxiliary information, set to 0 when not needed. The C:MYPROG.DAT is the name of the device and the filename; the filename is ignored for the cassette driver. Physical devices can have numbers (mainly disks, printers and serial devices), so "P1:" might be the plotter and "P2:" the daisy-wheel printer, or "D1:" may be one disk drive and "D2:" and so on. If not present, 1 is assumed.

The LPRINT statement is used to output strings to the printer.

Atari BASIC does not include an equivalent of the Microsoft BASIC GET or INKEY$ commands to detect a keypress, this can be simulated either by POKEing the keyboard driver directly or opening it as a file (e.g. OPEN 1,4,0,"K:":GET #1,A$) although the latter will wait for a keypress unlike GET or INKEY$.

Typing DOS from BASIC will exit to the Atari DOS command menu. Any unsaved programs will be lost. There is no command to display a disk directory from within BASIC and this must be done by exiting out to DOS.

DOS occupies roughly 5k of memory, thus a cassette-based Atari machine (48k or greater) will have around 37,000 bytes of free BASIC program memory and 32,000 bytes if DOS is present. BASIC cannot use the extra RAM on XL and XE machines.

Atari BASIC has built-in support of sound, (via the SOUND statement), setting up the screen graphics (GRAPHICS, SETCOLOR, drawing graphics COLOR, PLOT, DRAWTO), joysticks (STICK, STRIG), and paddles (PADDLE, PTRIG). The underlying operating system included a routine to fill arbitrary shapes, but BASIC did not have a PAINT command and it instead had to be called with the XIO command.[21]

There is no dedicated command for clearing the screen in Atari BASIC, this is usually done with PRINT CHR$(125), which PRINTs the clear screen control code (analogous to PRINT CHR$(147) in Commodore BASIC). Atari BASIC does not include a TAB function; this can be simulated by either POKEing the cursor column position at $55 or the tab position at $C9, which has a default value of 10. The changed values will not take effect until a PRINT statement is executed. There is also no SPC function in Atari BASIC.

Advanced aspects of the hardware such as player/missile graphics (sprites), redefined character sets, scrolling, and custom graphics modes are not supported by BASIC; these will require machine language routines or PEEK/POKE statements. A few graphics modes cannot be accessed from BASIC on the Atari 400/800 as the OS ROMs do not support them; the only way to access them is in machine language by setting the ANTIC registers and Display List manually. The OS ROMs on the XL/XE added support for these modes.[22]

Bitmap modes in BASIC are normally set to have a text window occupying the last three rows at the bottom of the screen so the user may display prompts and enter data in a program. If a 16 is added to the mode number invoked via the GRAPHICS statement, the entire screen will be in bitmap mode (e.g. GRAPHICS 8+16). If bitmap mode in full screen is invoked, Atari BASIC will automatically switch back into text mode when program execution is terminated unlike many other BASICs which leave the user in bitmap mode and have an unreadable screen that can only be switched out of via typing a blind command or resetting the computer.

Bitmap coordinates are calculated in the range of 1 to maximum row/column minus one, thus in Mode 6 (160x192), the maximum coordinates for a pixel can be 159 and 191. If the user goes over the allowed coordinates for the mode, BASIC will exit out with an error.

Atari BASIC allows numeric variables and expressions to be used to supply line numbers to GOTO and GOSUB commands. For instance, a subroutine that clears the screen can be written as GOSUB CLEARSCREEN, which is easier to understand than GOSUB 10000.

Most BASICs of the era allow the LIST command to send the source code to a printer or other device. Atari BASIC also includes the ENTER command, which reads source code from a device and merges it back into the program, as if the user had typed it in. This allows programs to be saved out in sections, reading them in using ENTER to merge or replace existing code. By carefully using blocks of line numbers that do not overlap, programmers can build libraries of subroutines and merge them into new programs as needed.

Atari BASIC can call machine code subroutines. The machine code is generally stored in strings, which can be anywhere in memory so the code needs to be position independent, or in the 256-byte Page 6 area (starting at address 1536₁₀, 600₁₆), which is not used by BASIC or the operating system. Code can be loaded into Page 6 by reading it from DATA statements.

Machine code is invoked with the USR function. The first parameter is the address of the machine code routine and the following values are parameters. For example, if the machine language code is stored in a string named ROUTINE$ it can be called with parameters as ANSWER=USR(ADR(ROUTINE$),VAR1,VAR2).

Parameters are pushed onto the hardware stack as 16-bit integers in the order specified in the USR function in low byte, high byte order. The last value pushed to the stack is a byte indicating the number of arguments. The machine language code must remove all of these values before returning via the RTS instruction. A value can be returned to the BASIC program by placing it in addresses 212₁₀ and 213₁₀ (D4₁₆ and D5₁₆) as a 16-bit integer.