SAM BASIC reference

Every command, function and operator in SAM BASIC, the BASIC in the SAM Coupé's v3.0 ROM.

It looks Sinclair-ish and is not: SAM BASIC is Andy Wright's Beta BASIC line, with its own token table, line format and line-number ceiling. A ZX Spectrum program has to be run through MGT's BTRANS utility to become a SAM one.

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

Notes and caveats

• Line numbers 1–65279, strictly ascending, with several statements to a line separated by :. One line holds at most 16127 stored bytes; a longer one is No room for line. There is no ? shorthand for PRINT.
• LET is not optional. A bare A=1 opens a call to a procedure named A, because writing a procedure's name is how one is called — so every assignment needs its LET. This is the single difference that catches out a program arriving from anywhere else.
• Variable names run to 32 characters for a number and 10 for a string or an array (not counting the $ or the bracket), and every character is significant: a name over the limit is rejected rather than shortened. _ is a name character, spaces inside a name are ignored and letters fold to lower case, so hi score and hiscore are one variable. $ is the only type marker — there is no integer type.
• Keywords match as whole words, so PRINTER is a variable and not PRINT followed by ER. A name may be spelled around a keyword; it may not equal one.
• Numbers may be written in hex with & (&FE00), and BIN 10110 reads a run of binary digits. The operators include ↑ (power, typed with the caret key), MOD and DIV for the two halves of integer division, and BOR and BAND for the bitwise operations OR and AND deliberately do not do.
• The structured keywords are what make a listing read as SAM rather than Spectrum, and are the idiomatic way to write here: DO/LOOP with WHILE or UNTIL on either end, EXIT IF, block IF with ELSE and END IF, DEF PROC/END PROC called by writing the name, and LABEL for a named jump target that survives RENUM.

Command Function Operator

	Syntax & description
-	<number> - <number> Subtracts, and negates when it stands in front of a single value.
*	<number> * <number> Multiplies.
/	<number> / <number> Divides, in floating point: 7/2 is 3.5. For a whole quotient use DIV.
↑	<number> ↑ <number> Raises to a power. Typed with the caret key and drawn as an up arrow, character code 94; the same glyph the Spectrum uses for the same job.
+	<number> + <number> | <string> + <string> Adds two numbers, or joins two strings end to end. There is no separate concatenation operator.
<	<expr> < <expr> Less than. Strings compare by character code.
<=	<expr> <= <expr> Less than or equal. Strings compare by character code.
<>	<expr> <> <expr> Not equal. Compares two numbers or two strings and yields 1 or 0.
=	<expr> = <expr> Equal, yielding 1 or 0. The same character assigns in LET, DEF FN and DEFAULT, where it is not a comparison.
>	<expr> > <expr> Greater than. Strings compare by character code.
>=	<expr> >= <expr> Greater than or equal. Strings compare by character code.
ABS	ABS <number> Absolute value: the number with any sign removed.
ACS	ACS <number> Arccosine, in radians. The argument must be between -1 and 1.
AND	<number> AND <number> | <string> AND <number> Logical AND: 1 when both operands are non-zero. With a string on the left it yields that string, or "" when the right-hand side is zero — the Sinclair idiom for a conditional piece of text.
ASN	ASN <number> Arcsine, in radians. The argument must be between -1 and 1.
AT	PRINT AT <row>, <col>; <expr> Positions the print position, counting from 0. Rows 0 to 18 are the upper window; rows 19 and 20 are the lower window where reports and INPUT live, and asking for one is "Off screen".
ATN	ATN <number> Arctangent, in radians.
ATTR	ATTR(<row>, <col>) The attribute byte of a character cell — its ink, paper, bright and flash bits. A mode 1 reading: in any other mode it answers "Invalid screen mode", there being no attribute to read.
AUTO	AUTO [<line>[, <number>]] Numbers lines automatically as they are typed, from a starting line and in steps. A typing aid at the machine; the IDE numbers lines for you.
BAND	<number> BAND <number> Bitwise AND, the partner of BOR. Use it to mask bits out of a byte read with PEEK or IN.
BEEP	BEEP <duration>, <pitch> Sounds one note for a length in seconds at a pitch in semitones from middle C, exactly as the Spectrum’s BEEP does.
BIN	BIN <bits> The value of a run of binary digits written out in full, as BIN 10110. Handy for POKEing a bit pattern you want to be able to read on the page.
BIN$	BIN$ <number> A number as binary digits — eight for a value that fits a byte, sixteen otherwise.
BLITZ	BLITZ <string> Runs a string of packed drawing commands in one go, which is far quicker than the same figure drawn statement by statement. Malformed contents are "Invalid BLITZ code".
BLOCKS	BLOCKS <number> Chooses what codes 128 to 143 draw: 1 for the built-in 2×2 block graphics, 0 for the second bank of user-defined shapes.
BOOM	BOOM A built-in explosion. Takes no arguments.
BOOT	BOOT Loads and runs the boot file from the current device — what the machine does itself when a disc is in the drive at reset.
BOR	<number> BOR <number> Bitwise OR. The B is what distinguishes it from OR, which is the logical one — a distinction the Microsoft BASICs do not draw.
BORDER	BORDER <colour> Sets the colour of the surround, from the same sixteen slots. A value above 15 is "Invalid colour".
BRIGHT	BRIGHT <number> Selects the bright half of the colour pair: 1 bright, 0 normal. An attribute bit, so it works in mode 1 only.
BUTTON	BUTTON <number> The state of mouse button 1 to 3: 1 while it is held, 0 otherwise. No mouse is fitted here.
CALL	CALL <addr>[, <arg>]… Calls machine code at an address, optionally passing arguments to it. This is how a program reaches a code block the IDE has loaded for it.
CHR$	CHR$ <number> The one-character string with the given code. Codes 128 to 143 are the block graphics and 144 to 168 the user-defined graphics.
CIRCLE	CIRCLE <x>, <y>, <radius> Draws a circle centred on a point. It is clipped rather than refused where it runs off the screen.
CLEAR	CLEAR [<addr>] Erases the variables. With an address it also lowers RAMTOP to it, reserving the memory above for machine code; an address outside the BASIC area is "Invalid CLEAR address".
CLOSE	CLOSE #<file> Closes a stream, or a screen opened with OPEN SCREEN. Closing one that was never opened is "Stream is not open".
CLS	CLS [#] Clears the screen and homes the print position. With the # it clears the current window only, leaving the rest of the screen alone.
CODE	CODE <string> The character code of the first character, the inverse of CHR$. An empty string gives 0.
CONTINUE	CONTINUE Resumes where the program stopped, at the statement after the STOP or the break. Editing a line first loses the resume point.
COPY	COPY <filename> TO <filename> Copies a file. Refused as "Not understood" without a disc operating system.
COS	COS <number> Cosine of an angle in radians.
CSIZE	CSIZE <width>, <height> Sets the character cell. The width is 6 or 8 pixels and the height 6 to 32 scanlines; anything else is "Integer out of range". The machine boots on an 8 by 9 cell, which is what makes its screen 32 by 21 rather than 32 by 24.
DATA	DATA <expr>[, <expr>]… Values for READ to consume in program order. The items are expressions evaluated when they are read, not text stored as typed, so a DATA item may name a variable.
DEF FN	DEF FN <name>(<param>[, <param>]…) = <expr> Defines a one-expression function, called with FN. The name may be as long as any variable name, and a $ on the end makes it string-valued.
DEF KEYCODE	DEF KEYCODE <keycode> = <string> Makes a key produce a string rather than its own character, so a keystroke can type a whole command.
DEF PROC	DEF PROC <name> [<param>[, <param>]…] Opens a procedure, closed by END PROC and called by writing its name as a statement. Parameters are named without brackets and are local to the call; this is why SAM BASIC has no implied LET, a bare name being a call rather than an assignment.
DEFAULT	DEFAULT <param> = <expr> Gives a procedure parameter a value to use when the call leaves it out. Written inside the DEF PROC, before the body.
DELETE	DELETE <line> TO <line> Deletes a whole range of lines in one statement.
DEVICE	DEVICE T | DEVICE D1 | DEVICE N Chooses where SAVE and LOAD go: T the tape, D1 (or D2) a disc drive, N the network. A number after the T sets the tape speed, the ROM’s own default being 112.
DIM	DIM <var>(<number>[, <number>]…) Creates an array with the given bounds, subscripts counting from 1. A string array takes an extra last dimension for the fixed length of each slot, which is why TRUNC$ exists to read one back without its padding.
DIR	DIR [<string>] Lists a disc directory, optionally matching a pattern. One of the words the ROM tokenizes but cannot run: without a disc operating system it is refused as "Not understood".
DISPLAY	DISPLAY <screen> Shows a screen, which need not be the one being drawn on — draw on one and display another and the picture appears complete rather than being built up in view.
DIV	<number> DIV <number> Integer division, discarding the remainder. Faster and clearer than INT(a/b).
DO	DO | DO WHILE <number> | DO UNTIL <number> Opens a loop closed by LOOP. The test may go on either end or on neither: a bare DO … LOOP repeats until an EXIT IF or a jump leaves it.
DPEEK	DPEEK <addr> Reads a two-byte little-endian word, the pair of PEEKs a machine-code address usually wants written as one.
DPOKE	DPOKE <addr>, <word> Writes a two-byte little-endian word — the low byte at the address and the high byte above it.
DRAW	DRAW <dx>, <dy>[, <angle>] Draws from the graphics position by a distance, not to a coordinate — PLOT first to say where a line starts. A third argument bends the line into an arc turning through that many radians.
DUMP	DUMP Prints the screen on the printer as a picture. Nothing is fitted here, so it goes nowhere.
DVAR	DVAR <sysvar> The address of a disc-operating-system variable. Answers "No DOS" without one loaded.
ELSE	IF <number> THEN <statement>: ELSE <statement> The other branch, of a single-line IF or of a block one. In a block IF it stands alone on its own line, between the IF and its END IF.
END IF	END IF Closes a block IF. Leaving it out stops the program with "Missing END IF" when the block is reached.
END PROC	END PROC Closes a procedure and returns to the statement after the call.
EOF	EOF <file> True once an open file has been read to its end. Needs a disc operating system; without one it answers "No DOS".
ERASE	ERASE <filename> Deletes a file. Refused as "Not understood" without a disc operating system.
EXIT IF	EXIT IF <number> Leaves the enclosing DO loop from the middle when the condition is true, carrying on after its LOOP. This is the structured way out; a GO TO out of a loop leaves its frame on the BASIC stack.
EXP	EXP <number> e raised to the given power, the inverse of LN.
FATPIX	FATPIX <number> Draws mode 2 pixels at double width (1) or single (0), which trades resolution for speed on the mode whose attributes change every scanline.
FILL	FILL <x>, <y> Flood-fills the area around a point in the current pen, out to whatever encloses it. An unenclosed area fills the screen.
FLASH	FLASH <number> Alternates pen and paper: 1 flashing, 0 steady. An attribute bit, so it works in mode 1 only.
FN	FN <name>(<arg>[, <arg>]…) Calls a function declared with DEF FN. Reaching one with no definition stops the program with "FN without DEF FN".
FOR	FOR <numvar> = <number> TO <number> [STEP <number>] Opens a counting loop that runs to the matching NEXT. The step may be negative or fractional, and the control variable is an ordinary variable the body can read.
FORMAT	FORMAT <string> Formats a disc. Refused as "Not understood" without a disc operating system.
FREE	FREE The bytes still free for the program, its variables and its strings — RAMTOP less the top of everything in use. A cold machine reports 57545.
GET	GET <var>[, <var>]… Waits for a single keypress and stores it — its code in a numeric variable, its character in a string one. Unlike INKEY$ it blocks until a key arrives.
GO SUB	GO SUB <line> Calls a subroutine, which returns with RETURN. GOSUB is the same keyword and lists back as two words. Prefer DEF PROC for anything with parameters or local variables.
GO TO	GO TO <line> Jumps to a line. GOTO written as one word is the same keyword and lists back as two, and the destination may be a LABEL name or an expression rather than a literal line number.
GRAB	GRAB <strvar>, <x>, <y>, <width>, <height> Copies a rectangle of screen into a string, which PUT draws back. This pair is how a SAM program animates a sprite.
HEX$	HEX$ <number> A number as hex digits: two, four or six according to its size. The & prefix reads one back.
HIDE	HIDE <filename> Hides a file from the directory listing. Refused as "Not understood" without a disc operating system.
IF	IF <number> THEN <statement> | IF <number> The conditional, in two shapes. With THEN it runs the rest of the line; without, it opens a multi-line block that ELSE divides and END IF closes. The ROM stores the two forms as different tokens and rewrites the one you typed when it sees which follows.
IN	IN <port> Reads a byte from a Z80 input port. The port is the whole sixteen-bit address, which the SAM’s hardware needs: the palette port is selected by the high byte.
INKEY$	INKEY$ The key held down right now as a one-character string, or "" when none is. Non-blocking, which makes it the heart of every real-time game loop.
INPUT	INPUT [<prompt>;] <var>[, <var>]… Waits for a line to be typed in the lower window and stores it. The prompt is printed first; without one the machine shows nothing but the cursor.
INSTR	INSTR(<string>, <string>) The position of the second string inside the first, counting from 1, or 0 when it is not there.
INT	INT <number> The integer part, rounding towards minus infinity — so INT -1.5 is -2, not -1.
INVERSE	INVERSE <number> Swaps pen and paper while printing: 1 inverse, 0 normal. Unlike FLASH and BRIGHT this is done as the characters are drawn, so it works in every mode.
ITEM	ITEM The type of the next DATA item: 0 when none is left, 1 for a string and 2 for a number. Lets a READ loop stop at the end of the data rather than at a count it was told.
KEY	KEY <number>, <number> Programs one of the ten function keys. Both operands are numbers; the string a key produces is set with DEF KEYCODE.
KEYIN	KEYIN <string> Executes a string as though it had been typed at the prompt, so a program can write and enter its own lines. This is where self-modifying SAM programs live.
LABEL	LABEL <name> Names this line so GO TO and GO SUB can name it instead of a number. A labelled program survives RENUM and reads as its own documentation.
LEN	LEN <string> How many characters a string holds.
LENGTH	LENGTH(<action>, <target>) The size or the address of a variable, an array or a procedure, the first argument choosing which — so LENGTH(1,a$) measures a string where LENGTH(0,a$) finds it.
LET	LET <var> = <expr> Assigns a value, and is not optional: a bare A=1 opens a call to a procedure named A. A string variable can be assigned through a slice, so LET a$(2 TO 3) = "xy" overwrites part of it in place.
LINE	SAVE <filename> LINE <line> Gives a saved program an auto-run line, so loading it starts it. The IDE exports "load only" tapes, and runs the program itself.
LIST	LIST [<line>] Lists the program from a line, a screenful at a time. The listing shows the keywords in the ROM’s own spelling, so GOTO comes back as GO TO.
LLIST	LLIST [<line>] Lists the program to the printer. Nothing is fitted here, so it goes nowhere.
LN	LN <number> Natural logarithm. For another base, divide: LN x / LN 10 is the common logarithm.
LOAD	LOAD <filename> | LOAD <filename> CODE | LOAD <filename> SCREEN$ Loads a program, replacing what is in memory. CODE loads a memory block back where it was saved from and SCREEN$ loads a saved picture straight into the display.
LOCAL	LOCAL <var>[, <var>]… Gives a procedure its own copies of these variables, restored when it returns. Named inside a DEF PROC, alongside the parameters that are already local.
LOOP	LOOP | LOOP WHILE <number> | LOOP UNTIL <number> Closes a DO loop, optionally with the test on this end so the body always runs at least once. A LOOP with no DO above it stops with "LOOP without DO".
LOOP IF	LOOP IF <number> Closes a DO loop and repeats while the condition is true — LOOP WHILE written as one keyword.
LPRINT	LPRINT [<expr>][;|,|' <expr>]… Prints to the printer instead of the screen, taking the same separators as PRINT. Nothing is fitted here, so it goes nowhere.
MEM$	MEM$(<addr> TO <addr>) A slice of memory as a string, in the address space PEEK reads — so it is a bulk PEEK, and assigning to it is a bulk POKE. The slice is required: MEM$ with a single subscript is not a complete expression.
MERGE	MERGE <filename> Loads a program without erasing the one in memory, line numbers in the file replacing lines of the same number.
MOD	<number> MOD <number> The remainder after integer division. Pairs with DIV, which gives the quotient.
MODE	MODE <mode> Selects one of the four screen modes and clears the screen. Modes 1 and 2 are 256×192 with attributes, mode 3 is 512×192 in four colours and mode 4 is 256×192 in sixteen; anything outside 1 to 4 is "Invalid screen mode".
MOVE	MOVE <file> TO <file> Copies between streams, which is how a file is sent to the printer or the network. Refused as "Not understood" without a disc operating system.
NEW	NEW Erases the program and its variables and resets the interpreter. Memory above RAMTOP survives, which is how a code block outlives the program that loaded it.
NEXT	NEXT [<numvar>] Closes a counting loop and jumps back to it. Naming the variable closes that loop specifically, which is how nested loops are unwound in the right order.
NOT	NOT <number> Logical NOT: 1 when the argument is zero, 0 otherwise. For the bitwise complement of a byte, subtract it from 255.
OFF	ON ERROR OFF A qualifier turning a setting off. Its one use in the bare ROM is cancelling an error handler.
ON	ON <number> GO TO <line>[, <line>]… Branches to the nth destination in the list, counting from 1. GO SUB works in the same position, and a value outside the list falls through to the next statement.
ON ERROR	ON ERROR <statement> | ON ERROR OFF Runs a statement instead of stopping when an error occurs — usually a GO TO to a handler. OFF puts the normal reporting back.
OPEN	OPEN #<file>; <string> | OPEN SCREEN <screen>, <mode> Opens a stream on a device or a file, or opens a second screen in a given mode for SCREEN and DISPLAY to use. The file form needs a disc operating system and answers "No DOS" without one.
OR	<number> OR <number> Logical OR: 1 when either operand is non-zero. For bits, use BOR.
OUT	OUT <port>, <byte> Writes a byte to a Z80 output port. This is how the video and paging registers are reached, and how a program can page itself out of existence.
OVER	OVER <number> Combines what is drawn with what is already there rather than replacing it: 1 over, 0 normal. Drawing the same thing twice in OVER 1 erases it, which is how a sprite is moved without a background copy.
PALETTE	PALETTE <index>, <colour> Points one of the sixteen colour-lookup slots at one of the 128 palette colours, so PEN 5 means whatever slot 5 was last told. A slot above 15 is "Invalid colour" and a colour above 127 "Invalid palette colour".
PAPER	PAPER <colour> Sets the background colour that printing lays its characters on and CLS clears to.
PATH$	PATH$ The current directory path. Needs a disc operating system; without one it answers "No DOS".
PAUSE	PAUSE <number> Waits the given number of frames — fifty to the second — or until a key is pressed, whichever comes first. PAUSE 0 waits for a key with no timeout.
PEEK	PEEK <addr> Reads one byte. Addresses run past 0xFFFF here: the space PEEK sees is ROM 0 and then BASIC’s four pages one after another, up to 0x1FFFF.
PEN	PEN <colour> Sets the foreground colour for printing and plotting, as one of the sixteen palette slots. INK is accepted as a spelling of it and lists back as PEN.
PI	PI The constant pi, 3.14159265…. The trigonometric functions work in radians, so it is the unit of a whole turn divided by two.
PLOT	PLOT <x>, <y> Plots a point and moves the graphics position to it. The origin is the bottom left; x runs 0 to 255 (0 to 511 in mode 3) and y 0 to 173 in every mode, the lower window not being plottable.
POINT	POINT(<x>, <y>) The colour of the pixel at a graphics coordinate, as a palette slot number.
POKE	POKE <addr>, <byte> Writes one byte, in the same address space PEEK reads. A POKE into ROM 0 is discarded rather than refused.
POP	POP [<numvar>] Discards the top GO SUB return address, optionally storing the line it named. With nothing to discard the program stops with "No POP data".
POW	POW A built-in thump. Takes no arguments.
PRINT	PRINT [#<file>;] [<expr>][;|,|' <expr>]… Prints to the current screen, or to a stream when one is named. A semicolon runs items together, a comma tabs to the next field and an apostrophe starts a new line; a trailing separator suppresses the newline.
PROTECT	PROTECT <filename> Write-protects a file. Refused as "Not understood" without a disc operating system.
PTR	PTR <file> The current position within an open file. Needs a disc operating system; without one it answers "No DOS".
PUT	PUT [OVER <number>;] <x>, <y>, <string>[, <string>] Draws a grabbed rectangle back at a position, optionally through a second string used as a mask. A qualifier such as OVER goes in front of the coordinates, not after them.
RAMTOP	RAMTOP The highest address BASIC will use. It boots at the top of the fourth page of the BASIC area; CLEAR with an address lowers it.
RANDOMIZE	RANDOMIZE [<number>] Seeds RND. With no argument it seeds from the frame counter, which is what makes a game different each time; with one, the same seed gives the same sequence, which is what makes a bug reproducible.
READ	READ <var>[, <var>]… Reads the next DATA items into variables. ITEM says what the next one is — 0 when the list is exhausted — so a read loop can end without counting.
RECORD	RECORD TO <strvar> | RECORD STOP Records everything typed into a string until RECORD STOP. KEYIN plays it back, which together make a keyboard macro.
REF	DEF PROC <name> REF <param> Marks a procedure parameter as passed by reference, so assigning to it inside the procedure changes the caller’s variable. The ROM alone refuses it; the parser that reads it arrives with a disc operating system.
REM	REM <comment> A comment: the rest of the line is stored exactly as typed and never run. Unlike the Spectrum, machine code does not live here — it goes in a block above RAMTOP.
RENAME	RENAME <filename> TO <filename> Renames a file. Refused as "Not understood" without a disc operating system.
RENUM	RENUM [LINE <line> TO <line>] [STEP <number>] Renumbers the program and fixes every GO TO, GO SUB and RESTORE that names a line. A jump to a computed line number cannot be fixed, which is one more reason to use LABEL.
RESTORE	RESTORE [<line>] Sets READ back to the first DATA item, or to the first one at or after the given line.
RETURN	RETURN Returns to the statement after the matching GO SUB. Without one the program stops with "RETURN without GOSUB".
RND	RND A pseudo-random number in [0,1). Takes no argument; for a whole number use INT(RND*n)+1. RANDOMIZE reseeds it.
ROLL	ROLL <direction>[, <number>[, <x>, <y>, <width>, <height>]] Shifts the screen, or a rectangle of it, wrapping what falls off one edge round to the other. The direction is 1 to 4 and the second argument is how many pixels.
RUN	RUN [<line>] Clears the variables and runs from the first line, or from the line given. Use GO TO to start without clearing them.
SAVE	SAVE <filename> [LINE <line>] Saves the program to the current device, asking you to start the tape first. LINE makes the saved copy run itself from that line when it is loaded.
SCREEN	SCREEN <screen> Directs printing and plotting to one of the machine’s screens. Screen 1 is the one it boots with; naming one that has not been opened is "Invalid screen number".
SCREEN$	SCREEN$(<row>, <col>) The character showing at a screen position, recognised by comparing the pixels against the font — so it reads back what was drawn, not a character map the machine does not keep.
SCROLL	SCROLL <direction>[, <number>[, <x>, <y>, <width>, <height>]] The same shift as ROLL, but losing what falls off the edge instead of wrapping it round.
SGN	SGN <number> The sign of a number: -1, 0 or 1.
SIN	SIN <number> Sine of an angle in radians.
SOUND	SOUND <hwreg>, <byte> Writes a value straight into one of the sound chip’s registers, 0 to 31. This is not a note: it is the only way to reach the SAA 1099’s noise generators, envelopes and stereo, and needs the register map on the hardware page.
SQR	SQR <number> Square root. A negative argument is an error.
STEP	FOR <numvar> = <number> TO <number> STEP <number> Sets a loop increment other than 1, and the increment RENUM numbers by. A step of 0 loops forever.
STOP	STOP Stops the program and reports "STOP statement" with the line it stopped on. CONTINUE resumes from there, which is what makes STOP a debugging tool rather than an ending.
STR$	STR$ <number> A number as the string PRINT would have shown.
STRING$	STRING$(<length>, <string>) The string repeated (and cut) to exactly the given number of characters, so STRING$(32,"-") is a rule across the screen.
SVAR	SVAR <sysvar> The address of a system variable, by number, so a program can read the interpreter’s own state without a table of addresses that a new ROM would move.
TAB	PRINT TAB <col>; <expr> Moves the print position to a column on the current line, wrapping to the next line when it is already past it.
TAN	TAN <number> Tangent of an angle in radians.
THEN	IF <number> THEN <statement> Introduces the body of a single-line IF. Everything after it on the line is conditional, including statements after further colons.
TO	FOR <numvar> = <number> TO <number> Separates the two ends of a range. The same word slices a string (a$(2 TO 5)), bounds MEM$ and joins the two halves of COPY and RENAME.
TRUNC$	TRUNC$ <string> The string with its trailing spaces removed. Its reason for existing is the string array, whose slots are a fixed width and are padded out with spaces.
UDG	UDG <string> The address of the eight bytes that define a character’s shape, named by a one-character string. POKE them to redraw the glyph.
UNTIL	DO UNTIL <number> | LOOP UNTIL <number> Repeats until the condition holds — the negation of WHILE, and legal in the same two places.
USING	PRINT USING <picture>; <number> Formats a number to a picture of hashes and a decimal point, for columns that line up. The ROM alone refuses it, as it does the rest of the vocabulary a disc operating system fills in.
USR	USR <addr> Calls machine code and returns the BC register it leaves. Takes the address itself — there is no USR "a" form for a user-defined graphic, UDG doing that job here.
USR$	USR$ <string> Calls an external command by name, the hook a disc operating system hangs its own commands on.
VAL	VAL <string> Evaluates a string as a numeric expression — not merely a number, so VAL "2*a" reads the variable a.
VAL$	VAL$ <string> Evaluates a string as a string expression, the string-valued twin of VAL.
VERIFY	VERIFY <filename> Reads a saved file back and compares it against memory without loading it, which is how a tape save was checked before the machine was switched off.
WHILE	DO WHILE <number> | LOOP WHILE <number> Repeats while the condition holds. Legal on either end of a DO … LOOP, and the choice decides whether the body can run zero times.
WINDOW	WINDOW <left>, <right>, <top>, <bottom> | WINDOW Limits printing and scrolling to part of the screen, in character cells. Written bare it restores the whole screen.
WRITE	FILL WRITE <x>, <y> A qualifier selecting the writing form of a command. The ROM alone refuses it, along with the rest of the vocabulary a disc operating system fills in.
XMOUSE	XMOUSE The mouse’s horizontal position. No mouse is fitted here, so it does not move.
XPEN	XPEN The light pen’s horizontal position. No light pen is fitted here.
YMOUSE	YMOUSE The mouse’s vertical position. No mouse is fitted here, so it does not move.
YPEN	YPEN The light pen’s vertical position. No light pen is fitted here.
ZAP	ZAP One of the four built-in effects, a rising zap. Takes no arguments.
ZOOM	ZOOM A built-in falling sweep. Takes no arguments.

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

<arg>

a value, where the call passes it

<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

<action>

which of several things the keyword should do

<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

<file>

an open file, by the number it was opened on

<filename>

the name of a file on tape or disc

<addr>

a memory address

<port>

an input/output port, by number

<angle>

an angle, in radians

<bits>

a binary literal, such as 10011

<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

<direction>

which way something moves, 1 to 4

<width>

how wide something is, in pixels

<height>

how tall something is, in pixels

<hwreg>

a hardware register, by number

<index>

a colour-lookup slot, 0 to 15

<target>

a variable, array or procedure, by name

<keycode>

a key code, as CODE returns it

<picture>

a formatting pattern a number is printed to

<radius>

the radius of a circle, in pixels

<screen>

one of the machine’s screens, by number

<sysvar>

a system variable, by number

<word>

a value from 0 to 65535

Showing 181 of 181 keywords

What this machine does not run

A group of keywords is in the ROM's token table but not in the ROM. DIR, ERASE, FORMAT, MOVE, COPY, RENAME, PROTECT, HIDE, REF, USING and WRITE all tokenize and are then refused as Not understood, because the parser that would read them arrives with a disc operating system. EOF, PTR, PATH$, DVAR and the file form of OPEN get as far as running and answer No DOS instead.

LPRINT, LLIST and DUMP want a printer, and the mouse and light-pen readings (XMOUSE, YMOUSE, XPEN, YPEN, BUTTON) want hardware that is not fitted. None of them is an error; they simply do nothing.