Atari BASIC reference

Every command, function and operator in Atari BASIC, shared by the Atari 800 and the Atari 400.

In this reference: Hardware · Escape codes · File formats · Argument notation

Notes and caveats

• A keyword is matched before a name, and matched greedily. LOGO is read as LOG followed by O, and LETTER = 1 assigns to a variable called TER. The machine reports nothing — it runs the line it read — so the editor flags a name that opens with a keyword instead.
• A program may name at most 128 variables, and a name is kept once it has been typed, even after the line using it is deleted. CLR forgets the values; only NEW gives the names back.
• Statements are separated by :, and everything after THEN belongs to the THEN. There is no ELSE, no WHILE and no REPEAT, so a statement written after an IF on the same line cannot be reached unconditionally.
• There are no string functions but LEN, and every string must be DIMensioned first, to a fixed size that never grows. A string is sliced by subscripting it — A$(3, 5) is characters 3 to 5 and A$(3) is from 3 to the end — and two are joined by assigning the second past the end of the first, A$(LEN(A$) + 1) = B$. + is arithmetic only, and there are no string arrays. Arrays need a DIM too.
• Numbers are ten-digit decimal floating point and there is no integer type. There is also no hexadecimal, which is why every address in the table below and everywhere else on this machine is written in decimal.
• COLOR and SETCOLOR are a pair, and the naming is the reverse of most machines here. COLOR chooses which of the five colour registers later drawing uses; SETCOLOR says what colour a register holds. See the hardware page.
• ? is accepted for PRINT and has a token of its own, but the machine lists it back as PRINT, so it is an entry spelling rather than a keyword and has no row below. The punctuation that separates the parts of a line — (, ), ,, ; and : — has no row either.

Command Function Operator

	Syntax & description
-	<number> - <number> | -<number> Subtraction, and negation.
*	<number> * <number> Multiplication.
/	<number> / <number> Division. There is no integer division and no remainder operator; INT(A/B) and A-B*INT(A/B) are how both are written.
#	#<file> Marks a channel number rather than an ordinary value. It is what tells PRINT, INPUT, GET and PUT to work on an open channel instead of the screen and the keyboard.
^	<number> ^ <number> Raise to a power, computed through the logarithm — so it is slow, and it is inexact for cases that ought to be whole numbers.
+	<number> + <number> | +<number> Addition. It does not join strings: two strings are joined by assigning the second one past the end of the first, A$(LEN(A$)+1)=B$.
<	<number> < <number> | <string> < <string> Less than. A true comparison is 1 and a false one 0, so a comparison can be used directly in arithmetic.
<=	<number> <= <number> | <string> <= <string> Less than or equal. It must be written in this order — =< is not accepted.
<>	<number> <> <number> | <string> <> <string> Not equal.
=	<var> = <expr> | <expr> = <expr> Assignment, and equality. Which one it is depends on where it appears, and the cartridge stores a different token for each — for a numeric assignment, a string assignment, a numeric comparison and a string comparison.
>	<number> > <number> | <string> > <string> Greater than.
>=	<number> >= <number> | <string> >= <string> Greater than or equal.
ABS	ABS(<number>) The value without its sign.
ADR	ADR(<string>) The address the string’s characters are stored at. This is how a machine-code routine is handed something to work on, and how a program POKEs bytes into a string it has DIMensioned as a buffer.
AND	<number> AND <number> True when both operands are non-zero. Logical, not bitwise: there is no bitwise operator in this BASIC at all, and a true result is 1 rather than -1.
ASC	ASC(<string>) The ATASCII code of the first character. An empty string is an error rather than zero.
ATN	ATN(<number>) Arctangent, in radians unless DEG has been used. There is no ASN or ACS.
BYEB.	BYE Leaves BASIC for the Memo Pad, the machine’s typewriter mode. The program is still in memory; pressing SYSTEM RESET comes back to it.
CHR$	CHR$(<number>) The one-character string for an ATASCII code. Adding 128 to a code gives its inverse-video twin, which is how a text-mode game draws a solid block: CHR$(160) is an inverse space.
CLOADCLOA.	CLOAD Loads a tokenized program from the cassette recorder. The machine beeps once and waits for RETURN, so that playback can be started first.
CLOG	CLOG(<number>) Logarithm to base 10. LOG is the natural one here, which is the opposite of the Acorn machines’ naming.
CLOSECL.	CLOSE #<file> Closes one of the eight I/O channels and flushes anything still buffered on it. END closes them all.
CLR	CLR Forgets every variable, array and string, and un-DIMensions them. It is also the only way to give back one of the 128 variable-name slots a program may use, because a name is kept once it has been typed.
COLORC.	COLOR <colour> Chooses what later PLOT and DRAWTO statements draw with. In a graphics mode this selects one of the colour registers; in a text mode it is the ATASCII code of the character to draw. SETCOLOR is the statement that says what colour a register holds.
COM	COM <numvar>(<number>[, <number>]) | COM <strvar>(<length>) A second spelling of DIM, inherited from the Data General BASIC this cartridge descends from. It does exactly what DIM does.
CONTCON.	CONT Carries on after STOP or BREAK. Execution resumes at the next line, not at the rest of the line it stopped in.
COS	COS(<number>) Cosine, in radians unless DEG has been used.
CSAVECS.	CSAVE Saves the tokenized program to the cassette recorder. The machine beeps twice and waits for RETURN, so that RECORD and PLAY can be pressed first.
DATAD.	DATA <constant>[, <constant>]… Constants for READ to walk through. The rest of the line is stored exactly as typed, so quotation marks are neither needed nor stripped and a comma always ends an item.
DEGDE.	DEG Makes SIN, COS and ATN work in degrees. It stays in force until RAD or a RUN, which resets to radians.
DIMDI.	DIM <numvar>(<number>[, <number>]) | DIM <strvar>(<length>) Reserves space for an array or a string. Everything must be dimensioned before use — including every string, which is a fixed buffer of the declared length rather than something that grows — and dimensioning the same name twice is an error until CLR.
DOSDO.	DOS Leaves BASIC for the disk operating system’s menu. With no disk system loaded it drops into the Memo Pad, exactly as BYE does.
DRAWTODR.	DRAWTO <x>, <y> Draws a straight line from the last plotted point to this one, in the colour COLOR selected, and leaves the graphics cursor at the end of it.
END	END Stops the program, closes every open channel and silences all four sound voices. STOP does none of those three things.
ENTERE.	ENTER <filespec> Reads an ATASCII listing back a line at a time, exactly as if it had been typed. Unlike LOAD it merges into the program already in memory rather than replacing it, which is how two listings are joined.
EXP	EXP(<number>) e raised to the power given.
FORF.	FOR <numvar> = <number> TO <number> [STEP <number>] Begins a counting loop. The body always runs once, because the limit is tested at the NEXT rather than on the way in.
FRE	FRE(0) Bytes still free between the program and the screen. The argument is ignored but must be there.
GETGE.	GET [#<file>,] <numvar> Reads one byte from a channel and waits until there is one. Opening a channel on the "K:" device makes this the blocking keyboard read; PEEK(764) is the non-blocking one.
GO TO	GO TO <line> GOTO with a space in it. The cartridge holds it as a separate token and lists it back the way it was typed, so the two spellings are told apart in a listing but do the same thing.
GOSUBGOS.	GOSUB <line> Calls a subroutine, which comes back with RETURN. Only the line number may be given — there is no computed GOSUB other than ON … GOSUB.
GOTOG.	GOTO <line> Jumps to a line. The destination must be a plain number: this BASIC has no GOTO to an expression.
GRAPHICSGR.	GRAPHICS <mode> Selects a display mode, clears the screen and rebuilds the display list from the top of memory downwards. Adding 16 to the mode drops the four-line text window at the foot of the screen, and adding 32 keeps the screen contents instead of clearing them.
IF	IF <number> THEN <line> | IF <number> THEN <statement> Runs the rest of the line when the condition is non-zero. There is no ELSE, and everything after THEN belongs to the THEN — a statement written after it on the same line cannot be reached unconditionally.
INPUTI.	INPUT [#<file>;] <var>[, <var>]… Reads a line from the keyboard, or from a channel. It takes no prompt string, so the wording is PRINTed first; with no channel it shows a question mark and echoes what is typed.
INT	INT(<number>) The largest whole number not above the value, so it rounds a negative number away from zero: INT(-2.5) is -3.
LEN	LEN(<string>) How many characters the string currently holds, which is not the length it was DIMensioned to. Assigning to a string sets this; it is also the position a further piece is appended at.
LETLE.	LET <var> = <expr> Assigns a value. The keyword is optional and almost always left out, though writing it is the way to assign to a name that begins with a keyword.
LISTL.	LIST [<line>[, <line>]] | LIST <filespec>[, <line>, <line>] Prints the program as ATASCII text, optionally one line or a range of them, and optionally to a device rather than the screen. LIST "C:" writes a listing to cassette that ENTER reads back; this is the untokenized counterpart of SAVE.
LOADLO.	LOAD <filespec> Reads back a tokenized program written by SAVE, replacing whatever was in memory. It cannot read a LIST listing — that is what ENTER is for.
LOCATELOC.	LOCATE <x>, <y>, <numvar> Reads back what is already on the screen at a point: the colour register number in a graphics mode, the character’s code in a text one. This is how a game finds out what it is about to move into. It leaves the cursor at that point.
LOG	LOG(<number>) Natural logarithm. CLOG is the base-10 one; the Acorn machines use these two names the other way round.
LPRINTLP.	LPRINT [<expr>][;|, <expr>]… Prints to the printer, opening and closing the channel around each statement. Nothing else needs to be opened first.
NEW	NEW Erases the program, its variables and the whole name table. This is the only way to forget a variable name short of switching off — CLR forgets the values but keeps the names.
NEXTN.	NEXT <numvar> Closes the innermost FOR loop. The variable must be named, and it must be the right one: this BASIC will not close several loops from one NEXT.
NOT	NOT <number> Gives 1 for zero and 0 for anything else. Logical rather than bitwise, like AND and OR.
NOTENO.	NOTE #<file>, <numvar>, <numvar> Reads back where an open disk file has got to, as a sector and a byte within it, so that POINT can come back to the same place later.
ON	ON <number> GOTO <line>[, <line>]… | ON <number> GOSUB <line>[, <line>]… Jumps to the nth line in the list, counting from 1. A value of zero, or one past the end of the list, falls through to the next statement instead of failing.
OPENO.	OPEN #<file>, <aux1>, <aux2>, <filespec> Opens one of the eight I/O channels on a device. Channel 0 is the screen editor and channel 6 the graphics screen, so a program opens 1 to 5 or 7; "K:" is the keyboard, "S:" the screen, "P:" the printer, "C:" the cassette and "D:" a disk file.
OR	<number> OR <number> True when either operand is non-zero. Logical, not bitwise, and a true result is 1.
PADDLE	PADDLE(<paddle>) How far a paddle controller is turned, 1 at the clockwise end and 228 at the other. Two paddles share each of the machine’s ports.
PEEK	PEEK(<addr>) The byte at an address, written in decimal — this BASIC has no hexadecimal at all. PEEK(764) is the last key pressed, PEEK(53279) the console keys, and PEEK(88)+256*PEEK(89) where the screen currently starts.
PLOTPL.	PLOT <x>, <y> Draws one point in the colour COLOR selected, and leaves the graphics cursor there so that DRAWTO can carry on from it.
POINTP.	POINT #<file>, <number>, <number> Moves an open disk file to a sector and a byte within it, which NOTE recorded earlier. This is the whole of random access on this machine.
POKEPOK.	POKE <addr>, <byte> Writes one byte to an address, in decimal. Many of the machine’s hardware registers are written through a shadow address in low memory that the vertical blank copies out fifty times a second; POKEing the chip directly is undone at the next frame.
POP	POP Throws away the innermost entry on the runtime stack: the pending RETURN of a GOSUB, or a FOR that is being abandoned. Leaving a subroutine or a loop by GOTO without this eventually fills the stack.
POSITIONPOS.	POSITION <x>, <y> Moves the cursor for the next PRINT, in text cells in GRAPHICS 0 and in pixels in a graphics mode. Follow the PRINT with a semicolon, or the cursor drops to the next row afterwards.
PRINTPR.	PRINT [#<file>;] [<expr>][;|, <expr>]… Prints to the screen, or to a channel. A trailing semicolon holds the cursor where it is and a comma moves it to the next ten-column field; anything else ends the line. Never print into column 39: the screen editor reads a character written there as the end of a logical line and pushes the rest of the screen down a row.
PTRIG	PTRIG(<paddle>) A paddle’s button: 0 while it is held, 1 otherwise.
PUTPU.	PUT [#<file>,] <byte> Writes one byte to a channel. PUT to the screen editor sends the code straight through, which is how a control code is written without embedding it in a string.
RADRA.	RAD Puts SIN, COS and ATN back into radians after DEG. This is also the state a RUN starts in.
READREA.	READ <var>[, <var>]… Takes the next constants from the DATA statements. Reading past the last one gives error 8 rather than the error 6 the Atari BASIC manual documents.
REMR.	REM <comment> A comment. The rest of the line is kept exactly as typed rather than tokenized, so a long remark costs its own length in program memory.
RESTORERES.	RESTORE [<line>] Sends READ back to the first DATA statement, or to the one at a given line — which is how one program reads several independent tables.
RETURNRET.	RETURN Goes back to the statement after the matching GOSUB.
RND	RND(<number>) A random number from 0 up to but not including 1, taken from POKEY’s own noise register. The argument is ignored, and there is no way to seed the sequence or to repeat one.
RUNRU.	RUN [<filespec>] Clears the variables and starts at the lowest line. Given a file it loads that program first, which is how one program chains to the next.
SAVES.	SAVE <filespec> Writes the program in its tokenized form — the pointer header, the variable tables and the statement table. LOAD reads it back; LIST writes the text form instead.
SETCOLORSE.	SETCOLOR <register>, <hue>, <luminance> Says what colour one of the five registers holds, as a hue and a brightness rather than a single number. In GRAPHICS 0 register 2 is the background and register 1 supplies the characters’ luminance, so the whole text screen is one colour.
SGN	SGN(<number>) -1, 0 or 1 according to the sign.
SIN	SIN(<number>) Sine, in radians unless DEG has been used.
SOUNDSO.	SOUND <voice>, <pitch>, <distortion>, <volume> Plays a tone on one of POKEY’s four voices until it is changed. A lower pitch number is a higher note; distortion 10 is a pure tone and the lower even values are noise; volume runs 0 to 15, and four voices at full volume distort. SOUND with a volume of 0 stops a voice, and END stops all four.
SQR	SQR(<number>) Square root.
STATUSST.	STATUS #<file>, <numvar> Reads a channel’s status byte without disturbing it: 1 means the last operation succeeded, and the error codes are the ones a failed operation would have reported.
STEP	FOR <numvar> = <number> TO <number> STEP <number> The stride of a FOR loop. It may be fractional or negative; left out, it is 1.
STICK	STICK(<port>) Which way a joystick is pushed, as four bits that are 0 when the switch is closed: 15 centred, 14 up, 13 down, 11 left, 7 right, and the diagonals are the two combined.
STOPSTO.	STOP Halts and reports the line it stopped at, leaving everything open so that CONT can carry on. END is the tidy way to finish.
STR$	STR$(<number>) The number written out as a string, with no leading space for the sign — unlike Microsoft BASIC, which reserves one.
STRIG	STRIG(<port>) A joystick’s button: 0 while it is held, 1 otherwise.
THEN	IF <number> THEN <line> | IF <number> THEN <statement> The consequent of an IF. A bare line number is a jump; anything else is the rest of the line, which runs only when the condition holds.
TO	FOR <numvar> = <number> TO <number> The limit of a FOR loop, tested at the NEXT.
TRAPT.	TRAP <line> Sends the next error to a line instead of stopping. It fires once and then clears itself, so the handler sets it again; a line number above the highest in the program turns trapping off. PEEK(195) is the error code afterwards and PEEK(187)*256+PEEK(186) the line it happened on.
USR	USR(<addr>[, <number>]…) Calls a machine-code routine at an address and takes its answer from locations 212 and 213. Every argument after the first is pushed as two bytes, and a count of them is pushed on top — so the routine must PLA that count before anything else, or its RTS returns into nothing.
VAL	VAL(<string>) The number a string spells. Anything that does not begin with a number is error 18 rather than zero, so a string from INPUT is worth checking first.
XIOX.	XIO <number>, #<file>, <aux1>, <aux2>, <filespec> Sends any command to a device, for the operations with no keyword of their own: 18 fills an area of the graphics screen, and on a disk 32 renames, 33 deletes, 35 locks and 36 unlocks.

Argument notation

Anything in <angle brackets> is a value you supply; everything else is typed exactly as shown. [square brackets] mark an optional part, | separates alternatives, and … means the part before it can repeat. The arguments on this page are:

<number>

a numeric expression

<string>

a string expression

<expr>

a value of either type, where the keyword takes both

<byte>

a value from 0 to 255

<constant>

a literal number or string, not an expression

<var>

a variable of either type

<numvar>

a numeric variable

<strvar>

a string variable

<line>

a line number

<statement>

one BASIC statement

<comment>

free text, to the end of the line

<length>

how many characters

<x>

a horizontal graphics coordinate

<y>

a vertical graphics coordinate

<mode>

a screen mode

<colour>

a colour, by number

<pitch>

how high a note sounds

<file>

an open file, by the number it was opened on

<addr>

a memory address

<port>

an input/output port, by number

<filespec>

a device or file, as a quoted string: "C:", "P:", "D:GAME"

<aux1>

what to open a channel for: 4 read, 8 write

<aux2>

a second, device-specific option byte

<register>

one of the five colour registers, 0 to 4

<hue>

a hue, 0 to 15

<luminance>

a brightness, an even number from 0 to 14

<voice>

one of the four sound voices, 0 to 3

<distortion>

how noisy a voice sounds, an even number

<volume>

how loud a sound is

<paddle>

a paddle controller, 0 to 7

Showing 95 of 95 keywords