Sinclair BASIC reference

Every command, function and operator in Sinclair BASIC — ZX81 BASIC on the 1981 machine, and 48K and 128 Sinclair BASIC on the Spectrums that followed it.

The three machines share an ancestry and about half a vocabulary. Rows only the ZX81 has are badged ZX81 only, rows only the Spectrums have Spectrum only, and the two the 128 alone has keep their 128K only badge. Where all three have a row and behave differently — PLOT, THEN, CLEAR, INPUT, SAVE, USR — the row says how.

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

Notes and caveats

Shared by all three

• Variable names are single letters (A–Z, with a $ suffix for strings) for arrays and strings; the Spectrums allow longer names for simple numeric variables.
• Keywords are entered as whole words and stored as single-byte tokens; the character set has no lower case for keywords, and LET is required on every assignment.
• AND, OR and NOT are not bitwise. a AND b is a when b is non-zero and 0 otherwise, and a OR b is 1 when b is non-zero and a otherwise, so 5 AND 3 is 5 here and 1 on a Commodore. A true comparison is 1, not -1, which is what stops X=X+(A>B) counting the way it does elsewhere.
• The power operator folds left to right, so 2 to the 3 to the 2 is 64.

On the ZX81

• One numbered statement per line; line numbers run 1–9999 and must be strictly ascending. There are no multi-statement lines and no ELSE.
• The power operator is **.
• Graphics are the 64×44 grid of quarter-block pixels PLOT and UNPLOT set and clear. There is no colour and no sound.
• Machine code is kept in a REM line; USR takes an address and nothing else.

On the Spectrums

• Keywords tagged 128K only are available solely on the 128K models.
• The jumps are written GO TO and GO SUB, with a space, and CONT is CONTINUE. Everything after THEN on a line — including further :-separated statements — is conditional.
• Colour, sound and graphics statements drive the hardware described on the hardware page — including the Spectrum's per-cell colour attributes and their famous clash.
• The power operator is ↑, typed with the caret key and shown as an up arrow.
• Machine code lives in a separate CODE block rather than in a REM line, and USR also takes a single-letter string, giving that user-defined graphic's address.

Command Function Operator

	Syntax & description
-	<number> - <number> | -<number> Subtraction / negation.
*	<number> * <number> Multiplication.
**ZX81 only	<number> ** <number> Raises the left value to the power of the right. The ZX81 uses ** for exponentiation, not the ^ found on other machines.
/	<number> / <number> Division.
↑Spectrum only	<number> ↑ <number> Raises to a power. Typed with the caret key, and shown as an up arrow; folds left to right, so 2↑3↑2 is 64.
+	<number> + <number> | <string> + <string> Addition / string concatenation.
<	<number> < <number> | <string> < <string> Less than.
<=	<number> <= <number> Comparison operator, true (1) when the left value is less than or equal to the right. Tokenizes to a single byte, so type it without a space between the symbols.
<>	<number> <> <number> Comparison operator, true (1) when the two values are not equal. Tokenizes to a single byte, so type it without a space between the symbols.
=	<var> = <expr> | <expr> = <expr> Assignment / equality. A true comparison is 1.
>	<number> > <number> | <string> > <string> Greater than.
>=	<number> >= <number> Comparison operator, true (1) when the left value is greater than or equal to the right. Tokenizes to a single byte, so type it without a space between the symbols.
ABS	ABS <number> Returns the absolute value (magnitude) of the argument, without its sign.
ACS	ACS <number> Returns the arccosine (inverse cosine) in radians. The argument must be in the range -1 to 1.
AND	<number> AND <number> Logical and: a AND b yields a when b is non-zero (true), otherwise 0 — or "" where a is a string, on the Spectrums. So a AND b is true only when both operands are.
ASN	ASN <number> Returns the arcsine (inverse sine) in radians. The argument must be in the range -1 to 1.
AT	PRINT AT <row>, <col>; Used inside PRINT to position the cursor before printing: AT row,col with row 0-21 and column 0-31. Out-of-range coordinates raise an error.
ATN	ATN <number> Returns the arctangent (inverse tangent) in radians, in the range -pi/2 to pi/2.
ATTRSpectrum only	ATTR (<row>, <col>) Returns the attribute byte at a text cell, encoding its ink, paper, bright and flash settings as a single number.
BEEPSpectrum only	BEEP <duration>, <pitch> Produces a tone through the speaker; the first value is the duration in seconds and the second the pitch in semitones above (or below) middle C.
BINSpectrum only	BIN <bits> Interprets the following binary digits as a number, e.g. BIN 1010 is 10; handy for POKEing bit patterns.
BORDERSpectrum only	BORDER <colour> Sets the colour 0-7 of the screen border surrounding the main display area.
BRIGHTSpectrum only	BRIGHT <number> Turns the bright (high-intensity) attribute on (1) or off (0) for following output, or 8 to leave it unchanged.
CATSpectrum only	CAT Catalogues the files on a Microdrive (or other storage).
CHR$	CHR$ <number> Returns the single-character string for the given character code (0-255). The inverse of CODE. The codes are the machine's own: the ZX81's are nothing like ASCII, while the Spectrums follow ASCII from 32 to 126 and put the block graphics, user-defined graphics and keyword tokens above it.
CIRCLESpectrum only	CIRCLE <x>, <y>, <number> Draws a circle in the current ink centred at x,y with the given radius.
CLEAR	CLEAR [<number>] Deletes all variables and arrays, freeing their memory, and leaves the program itself intact. The optional address is the Spectrums’: it lowers RAMTOP to reserve space (for machine code, say) and clears the screen with it. The ZX81’s CLEAR takes no argument.
CLOSE #Spectrum only	CLOSE #<number> Closes a previously opened stream, freeing it for reuse.
CLS	CLS Clears the screen and homes the cursor — to blank on the ZX81, and to the current paper colour on the Spectrums. In games, prefer erasing single cells with PRINT AT rather than clearing every frame.
CODE	CODE <string> Returns the character code of the first character of the string, or 0 for the empty string. The inverse of CHR$, and in the machine's own codes — see CHR$.
CONTZX81 only	CONT Resumes a program that was halted by STOP or by the BREAK key, continuing from where it left off.
CONTINUESpectrum only	CONTINUE Resumes the program after a STOP, an error, or a break, picking up where it left off.
COPY	COPY Prints a copy of the current screen contents to the ZX Printer.
COS	COS <number> Returns the cosine of the angle, which is given in radians.
DATASpectrum only	DATA <expr>[, <expr>]… Holds a list of constants that READ consumes in sequence; the statement does nothing when execution runs over it.
DEF FNSpectrum only	DEF FN <name>([<param>[, <param>]…]) = <expr> Defines a user function with a single-letter name and optional parameters; the body is one expression, evaluated when called with FN. Add a $ suffix for a string function.
DIM	DIM <var>(<number>[, <number>]…) Declares a numeric or string array with the given dimensions, clearing any earlier array of that name; the name is a single letter and subscripts start at 1. A string array DIM A$(n,m) holds n fixed-length strings of m characters, space-padded.
DRAWSpectrum only	DRAW <dx>, <dy>[, <number>] Draws a line from the last plotted point by the given x,y offset; a third value bends it into an arc turning through that many radians.
ERASESpectrum only	ERASE <string>; <string> Deletes a named file from a Microdrive cartridge.
EXP	EXP <number> Returns e raised to the given power, the inverse of LN.
FASTZX81 only	FAST Switches to FAST mode: the CPU runs at full speed with the screen blanked, flickering on only during INPUT or PAUSE. Use SLOW to keep a steady picture.
FLASHSpectrum only	FLASH <number> Turns the flashing attribute on (1) or off (0) for following output, or 8 to leave it unchanged.
FNSpectrum only	FN <name>([<number>[, <number>]…]) Calls a user function previously declared with DEF FN, passing the given arguments. The function name is a single letter (add $ for a string-valued function).
FOR	FOR <numvar> = <number> TO <number> [STEP <number>] Begins a counting loop, initialising the single-letter control variable and running the lines up to the matching NEXT, which loops back until the TO limit is passed. The body always runs at least once.
FORMATSpectrum only	FORMAT <string>; <number> Formats a Microdrive cartridge or configures a channel, such as setting the RS232 port baud rate.
GO SUBSpectrum only	GO SUB <line> Calls the subroutine at the given line, remembering where to return; the matching RETURN resumes after the call. GOSUB is also accepted.
GO TOSpectrum only	GO TO <line> Jumps execution to the given line number, which may be a calculated expression. GOTO is also accepted.
GOSUBZX81 only	GOSUB <number> Calls the subroutine starting at the given line number; a RETURN sends control back to the statement after the GOSUB. Calls may be nested.
GOTOZX81 only	GOTO <number> Jumps to the given line number. The target can be a computed expression, e.g. GOTO 100+10*L; if no line matches, execution continues at the next existing line.
IF	IF <number> THEN <statement> Runs what follows THEN when the condition is non-zero (true). Conditions use =, <, >, <=, >=, <>, AND, OR and NOT; there is no ELSE. How much of the line is conditional differs — see THEN.
INSpectrum only	IN <number> Reads a byte from the given Z80 I/O port, used for hardware access and keyboard scanning.
INKSpectrum only	INK <colour> Sets the ink (foreground) colour 0-7 for following output; 8 keeps the existing colour and 9 picks black or white for contrast.
INKEY$	INKEY$ Returns the key currently held down as a one-character string, or "" if none. Non-blocking, so it is the heart of every real-time game loop, e.g. IF INKEY$="8" THEN LET X=X+1.
INPUT	INPUT [<prompt>;] <var> Stops and waits for a value to be typed, assigning it to the variable; a numeric variable rejects non-numeric input, and on the ZX81 a string variable expects a quoted entry. The prompt is the Spectrums’: the ZX81’s INPUT takes a variable and nothing else. It halts the program either way, so use INKEY$ in real-time game loops instead.
INT	INT <number> Returns the largest integer not greater than the argument, so it floors towards negative infinity: INT -2.5 is -3, not -2.
INVERSESpectrum only	INVERSE <number> When set to 1, swaps ink and paper for printed characters; 0 restores normal printing.
LEN	LEN <string> Returns the number of characters in the string.
LET	LET <var> = <expr> Assigns the value of an expression to a variable. LET is mandatory on both machines — an assignment without it is a syntax error.
LINESpectrum only	SAVE <string> LINE <line> | INPUT LINE <strvar> In SAVE … LINE it sets the line a reloaded program auto-runs from; in INPUT LINE it reads a whole line of text into a string without needing quotes.
LIST	LIST [<line>] Lists the program to the screen, optionally starting at the given line number, and sets that line as the current edit line.
LLIST	LLIST [<line>] Lists the program to the ZX Printer, optionally starting at the given line number.
LN	LN <number> Returns the natural (base-e) logarithm. The argument must be positive, otherwise the program stops with an error.
LOAD	LOAD <filename> Loads a program of the given name from tape into memory, replacing whatever is there; LOAD "" loads the first program found.
LPRINT	LPRINT [<expr>][;|,]… Like PRINT but sends output to the ZX Printer instead of the screen, using the same ; and , separators.
MERGESpectrum only	MERGE <filename> Loads a program from tape and merges its lines into the current program rather than replacing it; lines with matching numbers are overwritten.
MOVESpectrum only	MOVE <string> TO <string> Renames or moves a file between Microdrive channels.
NEW	NEW Erases the current program and all variables, resetting BASIC ready for a fresh program.
NEXT	NEXT <numvar> Marks the end of the FOR loop using the named control variable, adding the STEP and looping back if the limit has not been passed.
NOT	NOT <number> Logical negation: returns 1 if the argument is 0, otherwise 0. Binds more tightly than the comparison operators.
OPEN #Spectrum only	OPEN #<number>, <string> Attaches a stream number to a channel (such as "s" screen, "p" printer, or a Microdrive file) so PRINT and INPUT can use it.
OR	<number> OR <number> Logical or with a Sinclair twist: a OR b yields 1 when b is non-zero (true), otherwise it yields a. In practice a OR b is true if either operand is.
OUTSpectrum only	OUT <port>, <byte> Writes a byte to the given Z80 I/O port, used to drive hardware directly.
OVERSpectrum only	OVER <number> When set to 1, combines new output with existing pixels using XOR (so printing twice erases); 0 restores normal overwriting.
PAPERSpectrum only	PAPER <colour> Sets the paper (background) colour 0-7 for following output; 8 and 9 behave like INK’s transparent and contrast options.
PAUSE	PAUSE <number> Pauses for the given number of frames (50 per second), or until a key is pressed. Waiting indefinitely is PAUSE 0 on the Spectrums and any value of 32768 or more on the ZX81, where it is also worth following with POKE 16437,255 to avoid a known display glitch on real hardware.
PEEK	PEEK <addr> Reads and returns the byte (0-255) stored at the given memory address. On a ZX81, PEEK 16396+256*PEEK 16397 gives the start of the display file (D_FILE).
PI	PI The constant pi (3.14159265…). Handy for trigonometry, since SIN/COS/TAN work in radians.
PLAY128K only	PLAY <string>[, <string>]… Plays music strings on the AY-3-8912 sound chip, one string per channel. Only available in 128K mode.
PLOT	PLOT <x>, <y> Sets a single point at x,y with the origin at the bottom-left. The grid is the machine’s: 64 by 44 character-block pixels on the ZX81, where UNPLOT clears one, and 256 by 176 real pixels on the Spectrums (x 0-255, y 0-175), where OVER 1 or INVERSE 1 clears one instead.
POINTSpectrum only	POINT (<x>, <y>) Returns 1 if the pixel at x,y is set to ink, or 0 if it is paper (the origin is bottom-left).
POKE	POKE <addr>, <byte> Writes a byte value (0-255) directly to the given memory address. Useful for system pokes, but easy to crash the machine with if misused.
PRINT	PRINT [AT <row>, <col>;] [<expr>][;|,]… Writes text and numbers to the display. ";" joins items with no gap, "," tabs to the next 16-column field, and a trailing ";" suppresses the newline. AT positions the cursor at row 0-21, column 0-31, and TAB sets the column.
RANDZX81 only	RAND [<number>] Seeds the RND generator. RAND n with the same n gives a repeatable sequence; RAND 0 (or RAND with no argument) seeds from the frame counter for unpredictable results.
RANDOMIZESpectrum only	RANDOMIZE [<number>] Seeds the random number generator; with no argument (or 0) it seeds unpredictably from the frame counter, while a non-zero value gives a repeatable sequence.
READSpectrum only	READ <var>[, <var>]… Assigns the next unread DATA items, in order, to the listed variables.
REM	REM <comment> Marks the rest of the line as a comment, ignored when the program runs. On the ZX81 it is also the usual container for machine-code bytes; the Spectrums keep code in a separate CODE block instead.
RESTORESpectrum only	RESTORE [<line>] Resets the DATA read pointer so the next READ starts again, optionally from the DATA at a given line.
RETURN	RETURN Returns from a subroutine to the statement following the matching call. Calling it without a pending call stops the program with report 7.
RND	RND Returns a pseudo-random number in [0,1). Takes no argument; for a whole number use INT (RND*n)+1, e.g. INT (RND*6)+1 for a dice roll. Seed the generator with RAND on the ZX81 and RANDOMIZE on the Spectrums.
RUN	RUN [<line>] Clears all variables and runs the program from the start, or from the given line number if one is supplied.
SAVE	SAVE <filename> [LINE <line>] Saves the current program to tape under the given name. The LINE clause is the Spectrums’, and makes the program auto-run from that line when reloaded; a ZX81 image always restarts and runs by itself.
SCREEN$Spectrum only	SCREEN$ (<row>, <col>) Returns the character shown at a text row,col position, recognising the standard font; gives "" when the cell holds graphics it cannot match.
SCROLLZX81 only	SCROLL Scrolls the whole display up by one line, losing the top line and freeing the bottom one. Must be called before printing when the screen is full, or the program stops with report 5.
SGN	SGN <number> Returns the sign of the argument: -1 if negative, 0 if zero, 1 if positive.
SIN	SIN <number> Returns the sine of the angle, which is given in radians.
SLOWZX81 only	SLOW Switches to SLOW mode: the display stays on continuously but the CPU runs at about a quarter speed. Use FAST to blank the screen for full-speed computation.
SPECTRUM128K only	SPECTRUM Switches a 128K machine back into 48 BASIC mode. Only meaningful on the 128K models.
SQR	SQR <number> Returns the square root. The argument must not be negative, or the program stops with an error.
STEP	FOR <numvar> = <number> TO <number> STEP <number> Sets the amount added to a FOR loop variable each pass (default 1). May be negative or fractional, to count down or by partial steps.
STOP	STOP Halts the program with report 9. Execution can be resumed at the following statement — with CONT on the ZX81 and CONTINUE on the Spectrums.
STR$	STR$ <number> Returns the number formatted as a string, exactly as PRINT would display it. The inverse of VAL.
TAB	PRINT TAB <number>; Used inside PRINT to move the print position to a given column (taken modulo 32, wrapping to the next line if already past it). Only moves forward within the print position.
TAN	TAN <number> Returns the tangent of the angle, which is given in radians.
THEN	IF <number> THEN <statement> Introduces what runs when an IF condition is true, and how much that is differs: the ZX81 allows one statement and has no multi-statement lines at all, while on the Spectrums everything after THEN on the line — including further ":"-separated statements — is conditional. Neither has ELSE.
TO	FOR <numvar> = <number> TO <number> | <string>(<number> TO <number>) Gives the upper bound of a FOR loop range, and also slices strings, so A$(2 TO 4) returns the 2nd-to-4th characters. Either slice index may be omitted to mean the start or end of the string.
UNPLOTZX81 only	UNPLOT <x>, <y> Clears a single block pixel set by PLOT, using the same coordinate range: x 0–63, y 0–43, origin bottom-left.
USR	USR <addr> | USR <string> Calls machine code at the given address and returns the value of the BC register pair on RET — commonly as LET X=USR addr. The string form is the Spectrums’: a single-letter string gives the address of that user-defined graphic instead.
VAL	VAL <string> Evaluates the string as a numeric expression and returns the result, so VAL "2+3" gives 5. A malformed expression stops the program with an error.
VAL$Spectrum only	VAL$ <string> Evaluates the text held in a string as a string expression and returns the resulting string; errors if it is not a valid expression.
VERIFYSpectrum only	VERIFY <filename> Compares a recording on tape against memory to confirm that a SAVE was written correctly.

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

<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

<name>

a name the program defines for a function or procedure

<param>

a parameter, where the definition introduces it

<x>

a horizontal graphics coordinate

<y>

a vertical graphics coordinate

<dx>

a horizontal distance from the current position

<dy>

a vertical distance from the current position

<col>

a text column

<row>

a text row

<colour>

a colour, by number

<pitch>

how high a note sounds

<duration>

how long a sound lasts

<prompt>

text shown before the input; a literal, not an expression

<filename>

the name of a file on tape or disc

<addr>

a memory address

<port>

an input/output port, by number

<bits>

a binary literal, such as 10011

Showing 110 of 110 keywords