Locomotive BASIC reference

Every command, function and operator in Locomotive BASIC, the full-featured BASIC of the Amstrad CPC — with real structured keywords such as IF … THEN … ELSE, WHILE … WEND and the AFTER/EVERY interrupt timers.

Three machines run it here: the CPC 464 with BASIC 1.0, and the CPC 664 and CPC 6128 with BASIC 1.1, which adds eleven keywords to the same language.

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

Notes and caveats

• ' opens a comment as REM does, and is shown beside it in the table below; the search box finds the keyword by it.
• Line numbers 1–65535, strictly ascending; multiple statements per line with :. ? is shorthand for PRINT, ' for REM, and LET is optional.
• Variable names are up to 40 characters, all significant, with $ (string), % (integer) and ! (real) type suffixes.
• Numbers may be written in decimal, hex (&7F00) or binary (&X1010); operators include ^ (power, folding left to right so 2^3^2 is 64), \ (integer divide), MOD and XOR. AND, OR and NOT are bitwise, and a true comparison is -1.
• Read the keyboard in games with INKEY(n) — it returns -1 while a key is up. The cursor keys are INKEY(0) up, INKEY(2) down, INKEY(8) left and INKEY(1) right. JOY(0) returns the joystick as a bit mask (bit 0 up, 1 down, 2 left, 3 right, 4 fire 2, 5 fire 1).
• Entries tagged BASIC 1.1 only are the additions Locomotive BASIC 1.1 (the CPC 664 and CPC 6128) brings; the BASIC 1.0 464 rejects them. Everything untagged works on all three machines and produces the same program on each, so a listing that avoids the tagged entries moves between them unchanged.

Command Function Operator

	Syntax & description
-	<number> - <number> | -<number> Subtraction / negation.
'	' Comment shorthand (same as REM).
*	<number> * <number> Multiplication.
/	<number> / <number> Division.
\	<number> \ <number> Integer division.
^	<number> ^ <number> Exponentiation.
+	<number> + <number> | <string> + <string> Addition / concatenation.
<	<number> < <number> | <string> < <string> Less than.
<=	<number> <= <number> | <string> <= <string> Less than or equal.
<>	<number> <> <number> | <string> <> <string> Not equal.
=	<var> = <expr> | <expr> = <expr> Assignment / equality.
>	<number> > <number> | <string> > <string> Greater than.
>=	<number> >= <number> | <string> >= <string> Greater than or equal.
ABS	ABS(<number>) Absolute value.
AFTER	AFTER <number>[, <timer>] GOSUB <line> Call a subroutine after a delay (1/50s units).
AND	<number> AND <number> Bitwise/logical AND.
ASC	ASC(<string>) Character code of the first character.
ATN	ATN(<number>) Arctangent.
AUTO	AUTO [<line>][, <number>] Automatic line numbering (editor command).
BIN$	BIN$(<number>[, <number>]) Number as a binary string.
BORDER	BORDER <colour>[, <colour>] Set the border colour (two colours flash).
CALL	CALL <addr>[, <arg>]… Call a machine-code routine.
CAT	CAT Catalogue the cassette/disc.
CHAIN	CHAIN <filename>[, <line>] Load and run another program.
CHAIN MERGE	CHAIN MERGE <filename>[, <line>] Load and merge another program, then run.
CHR$	CHR$(<number>) Character with code n.
CINT	CINT(<number>) Round to a 16-bit integer.
CLEAR	CLEAR Clear all variables.
CLEAR INPUTBASIC 1.1 only	CLEAR INPUT Discard pending keyboard input.
CLG	CLG [<pen>] Clear the graphics screen.
CLOSEIN	CLOSEIN Close the input file.
CLOSEOUT	CLOSEOUT Close the output file.
CLS	CLS [#<stream>] Clear the screen (or a window).
CONT	CONT Continue after break or STOP.
COPYCHR$BASIC 1.1 only	COPYCHR$(#<stream>) Character under the text cursor.
COS	COS(<number>) Cosine.
CREAL	CREAL(<number>) Convert to a real number.
CURSORBASIC 1.1 only	CURSOR [<number>][, <number>] Switch the text cursor on or off.
DATA	DATA <constant>[, <constant>]… Inline data for READ.
DEC$BASIC 1.1 only	DEC$(<number>, <string>) Number formatted to a template.
DEF	DEF FN<name>[(<param>[, <param>]…)] = <expr> Define a function.
DEFINT	DEFINT <letter>[-<letter>] Default listed initial letters to integer type.
DEFREAL	DEFREAL <letter>[-<letter>] Default listed initial letters to real type.
DEFSTR	DEFSTR <letter>[-<letter>] Default listed initial letters to string type.
DEG	DEG Degrees mode for trigonometry.
DELETE	DELETE <line>-<line> Delete a range of lines (editor command).
DERRBASIC 1.1 only	DERR Disc error number of the last error.
DI	DI Disable timer interrupts.
DIM	DIM <var>(<number>[, <number>]…) Dimension an array.
DRAW	DRAW <x>, <y>[, <pen>] Draw a line to graphics point x,y.
DRAWR	DRAWR <dx>, <dy>[, <pen>] Draw a line relative to the graphics cursor.
EDIT	EDIT <line> Edit a program line (editor command).
EI	EI Enable timer interrupts.
ELSE	IF <number> THEN <statement> ELSE <statement> Alternative branch of IF…THEN.
END	END End the program.
ENT	ENT <envelope>[, <section>]… Defines a tone envelope, numbered 1 to 15, that SOUND can use to sweep a note in pitch. Takes up to five sections, each of a step count, a step size and a pause; a negative envelope number makes the sweep absolute rather than relative.
ENV	ENV <envelope>[, <section>]… Defines a volume envelope, numbered 1 to 15, that SOUND can use to shape a note over time. Takes up to five sections, each of a step count, a step size and a pause.
EOF	EOF True at end of the input file.
ERASE	ERASE <var>[, <var>]… Erase arrays.
ERL	ERL Line number of the last error.
ERR	ERR Error number of the last error.
ERROR	ERROR <number> Raise an error.
EVERY	EVERY <number>[, <timer>] GOSUB <line> Call a subroutine repeatedly (1/50s units).
EXP	EXP(<number>) e to the power n.
FILLBASIC 1.1 only	FILL <pen> Flood-fill from the graphics cursor.
FIX	FIX(<number>) Truncate towards zero.
FN	FN<name>[(<arg>[, <arg>]…)] Call a user-defined function.
FOR	FOR <numvar> = <number> TO <number> [STEP <number>] Start a counted loop.
FRAMEBASIC 1.1 only	FRAME Wait for a display frame flyback.
FRE	FRE(0) | FRE("") Free BASIC memory.
GOSUB	GOSUB <line> Call a subroutine by line number.
GOTO	GOTO <line> Jump to a line number.
GRAPHICSBASIC 1.1 only	GRAPHICS PEN [<pen>][, <number>] GRAPHICS PEN / PAPER prefix.
GRAPHICS PAPERBASIC 1.1 only	GRAPHICS PAPER <pen> Set the graphics background ink.
GRAPHICS PENBASIC 1.1 only	GRAPHICS PEN [<pen>][, <number>] Set the graphics drawing ink.
HEX$	HEX$(<number>[, <number>]) Number as a hex string.
HIMEM	HIMEM Top of BASIC memory.
IF	IF <number> THEN <statement> [ELSE <statement>] Conditional execution.
INK	INK <pen>, <colour>[, <colour>] Assign a colour to a pen (two colours flash).
INKEY	INKEY(<key>) Test a key by key number (-1 if up).
INKEY$	INKEY$ Read a key as a string ("" if none).
INP	INP(<port>) Read a byte from an I/O port.
INPUT	INPUT [#<stream>,] [<prompt>;] <var>[, <var>]… Read values from the keyboard or a file.
INSTR	INSTR([<start>,] <string>, <string>) Find b$ within a$.
INT	INT(<number>) Round towards minus infinity.
JOY	JOY(<number>) Read a joystick (bit mask).
KEY	KEY <number>, <string> Define an expansion (function-key) string.
KEY DEF	KEY DEF <key>, <number>[, <number>[, <number>[, <number>]]] Redefine a key of the keyboard.
LEFT$	LEFT$(<string>, <length>) Leftmost n characters.
LEN	LEN(<string>) String length.
LET	LET <var> = <expr> Assignment (LET is optional).
LINE	LINE INPUT [#<stream>,] <strvar> LINE INPUT reads a whole line of text.
LINE INPUT	LINE INPUT [#<stream>,] <strvar> Read a whole line of text.
LIST	LIST [<line>-<line>][, #<stream>] List the program.
LOAD	LOAD <filename>[, <addr>] Load a program.
LOCATE	LOCATE [#<stream>,] <col>, <row> Move the text cursor.
LOG	LOG(<number>) Natural logarithm.
LOG10	LOG10(<number>) Base-10 logarithm.
LOWER$	LOWER$(<string>) Lower-case copy of a string.
MASKBASIC 1.1 only	MASK [<mask>][, <number>] Set the line-drawing dot pattern.
MAX	MAX(<number>[, <number>]…) Largest of its arguments.
MEMORY	MEMORY <addr> Set the top of BASIC memory (HIMEM).
MERGE	MERGE <filename> Merge a program from tape/disc.
MID$	MID$(<string>, <start>[, <length>]) Substring (also assignable as a statement).
MIN	MIN(<number>[, <number>]…) Smallest of its arguments.
MOD	<number> MOD <number> Integer remainder.
MODE	MODE <mode> Select screen mode 0-2.
MOVE	MOVE <x>, <y> Move the graphics cursor.
MOVER	MOVER <dx>, <dy> Move the graphics cursor relatively.
NEW	NEW Erase the current program.
NEXT	NEXT [<numvar>] End of a FOR loop.
NOT	NOT <number> Bitwise/logical NOT.
ON	ON <number> GOTO <line>[, <line>]… | ON <number> GOSUB <line>[, <line>]… Jumps to the line at the given position in the list, counting from 1; falls through to the next statement when the value is 0 or past the end of the list.
ON BREAK	ON BREAK GOSUB <line> Trap the ESC (break) key.
ON BREAK CONTBASIC 1.1 only	ON BREAK CONT Ignore the ESC (break) key.
ON BREAK GOSUB	ON BREAK GOSUB <line> Call a subroutine when ESC breaks.
ON BREAK STOP	ON BREAK STOP Restore normal ESC (break) handling.
ON ERROR GOTO	ON ERROR GOTO <line> Trap runtime errors.
OPENIN	OPENIN <filename> Open a file for input.
OPENOUT	OPENOUT <filename> Open a file for output.
OR	<number> OR <number> Bitwise/logical OR.
ORIGIN	ORIGIN <x>, <y>[, <left>, <right>, <top>, <bottom>] Set the graphics origin (and window).
OUT	OUT <port>, <byte> Write a byte to an I/O port.
PAPER	PAPER [#<stream>,] <pen> Set the text background pen.
PEEK	PEEK(<addr>) Read a byte of memory.
PEN	PEN [#<stream>,] <pen> Set the text foreground pen.
PI	PI The constant π.
PLOT	PLOT <x>, <y>[, <pen>] Plot a graphics point.
PLOTR	PLOTR <dx>, <dy>[, <pen>] Plot relative to the graphics cursor.
POKE	POKE <addr>, <byte> Write a byte of memory.
POS	POS(#<stream>) Text cursor column.
PRINT	PRINT [#<stream>,] [<expr>][;|,]… Print to the screen or a stream.
RAD	RAD Radians mode for trigonometry.
RANDOMIZE	RANDOMIZE [<number>] Seed the random number generator.
READ	READ <var>[, <var>]… Read the next DATA item(s).
RELEASE	RELEASE <mask> Release held sound channels.
REM'	REM <comment> Comment line.
REMAIN	REMAIN(<timer>) Read and disable a delay timer.
RENUM	RENUM [<line>][, <line>][, <number>] Renumber the program.
RESTORE	RESTORE [<line>] Reset the DATA pointer.
RESUME	RESUME [<line> | NEXT] Resume after an error.
RETURN	RETURN Return from a GOSUB.
RIGHT$	RIGHT$(<string>, <length>) Rightmost n characters.
RND	RND[(<number>)] Random number 0..1.
ROUND	ROUND(<number>[, <number>]) Round to a number of decimals.
RUN	RUN [<line> | <filename>] Run the program (or load and run).
SAVE	SAVE <filename>[, <letter>] Save the program.
SGN	SGN(<number>) Sign of n (-1, 0, 1).
SIN	SIN(<number>) Sine.
SOUND	SOUND <channel>, <period>[, <duration>[, <volume>[, <volenv>[, <toneenv>[, <noise>]]]]] Make a sound.
SPACE$	SPACE$(<number>) A string of n spaces.
SPC	SPC(<number>) Print n spaces.
SPEED	SPEED WRITE <number> SPEED WRITE / INK / KEY settings.
SPEED INK	SPEED INK <number>, <number> Set the flash rate of flashing colours.
SPEED KEY	SPEED KEY <number>, <number> Set the keyboard auto-repeat rates.
SPEED WRITE	SPEED WRITE <number> Set the cassette write speed (0 or 1).
SQ	SQ(<channel>) Sound-queue state of a channel.
SQR	SQR(<number>) Square root.
STEP	FOR <numvar> = <number> TO <number> STEP <number> Loop increment in FOR.
STOP	STOP Stop with a break report.
STR$	STR$(<number>) Number as a string.
STRING$	STRING$(<length>, <number> | <string>) A character repeated n times.
SWAP	WINDOW SWAP <stream>, <stream> WINDOW SWAP - exchange two streams.
SYMBOL	SYMBOL <number>, <byte>[, <byte>]… Redefines the shape of one character, given its code and up to eight bytes — one per pixel row, most significant bit leftmost. Only characters at or above the SYMBOL AFTER threshold can be redefined.
SYMBOL AFTER	SYMBOL AFTER <number> Reserve memory for redefined characters.
TAB	TAB(<col>) Position the cursor within PRINT.
TAG	TAG [#<stream>] Write text at the graphics cursor.
TAGOFF	TAGOFF [#<stream>] Return text to the text cursor.
TAN	TAN(<number>) Tangent.
TEST	TEST(<x>, <y>) Ink at graphics point x,y.
TESTR	TESTR(<dx>, <dy>) Ink at a relative graphics point.
THEN	IF <number> THEN <statement> Follows the condition in IF.
TIME	TIME Elapsed time (1/300s units).
TO	FOR <numvar> = <number> TO <number> Loop limit in FOR.
TROFF	TROFF Turn off line tracing.
TRON	TRON Trace line numbers as they execute.
UNT	UNT(<addr>) Address as a signed integer.
UPPER$	UPPER$(<string>) Upper-case copy of a string.
USING	PRINT USING <string>; <expr> Format printed values.
VAL	VAL(<string>) Numeric value of a string.
VPOS	VPOS(#<stream>) Text cursor row.
WAIT	WAIT <port>, <mask>[, <number>] Wait for an I/O port state.
WEND	WEND End of a WHILE loop.
WHILE	WHILE <number> Loop while a condition holds.
WIDTH	WIDTH <number> Set the printer line width.
WINDOW	WINDOW [#<stream>,] <left>, <right>, <top>, <bottom> Define a text window.
WINDOW SWAP	WINDOW SWAP <stream>, <stream> Exchange two text streams.
WRITE	WRITE [#<stream>,] <expr>[, <expr>]… Write values to the screen or a file.
XOR	<number> XOR <number> Bitwise/logical exclusive OR.
XPOS	XPOS Graphics cursor x position.
YPOS	YPOS Graphics cursor y position.
ZONE	ZONE <number> Set the print comma-column width.

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

<letter>

a single letter

<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

<arg>

a value, where the call passes it

<start>

the position something starts at, counting from 1

<length>

how many characters

<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

<mode>

a screen mode

<colour>

a colour, by number

<channel>

a sound channel

<duration>

how long a sound lasts

<envelope>

an envelope, by number

<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

<mask>

a bit mask, one bit per item

<pen>

a pen number in the current palette

<stream>

one of the eight screen windows, #0 to #7

<timer>

one of the four delay timers, 0 to 3

<key>

a key, by its key number

<period>

a tone period: 62500 divided by the frequency

<volume>

how loud a sound is

<volenv>

a volume envelope, by number, as defined by ENV

<toneenv>

a tone envelope, by number, as defined by ENT

<noise>

a noise period, 0 to 31

<section>

one envelope section: step count, step size and pause

<left>

the left edge of a window or clipping area

<right>

the right edge of a window or clipping area

<top>

the top edge of a window or clipping area

<bottom>

the bottom edge of a window or clipping area

Showing 192 of 192 keywords