TRS-80 Level II BASIC reference

Every command, function and operator in TRS-80 Level II BASIC.

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

Notes and caveats

• ? stands for PRINT and ' opens a comment as REM does. Both are shown beside their keyword in the table below, and the search box finds a keyword by either.
• Multiple statements per line are allowed with :; ? is shorthand for PRINT and ' for REM.
• Variable names may be any length but only the first two characters are significant, with $ (string), % (integer), ! (single) and # (double) type suffixes; DEFSTR/DEFINT/DEFSNG/DEFDBL set the default type per initial letter.
• The power operator is ↑, with the caret key accepted for it when typing. It folds left to right, so 2↑3↑2 is 64.
• AND, OR and NOT combine their operands bit by bit — 5 AND 3 is 1 — and a true comparison is -1. There is no integer-division, remainder or exclusive-OR operator: use INT(a/b) and a-b*INT(a/b).
• PRINT @ n, moves the cursor to one of the 1024 screen cells before printing, and PRINT USING formats values against a template. The E-notation marker in a USING template is four carets (^^^^): the up-arrow the manuals draw is the power operator, and the machine has no character for it to store inside a string.

Command Function Operator

	Syntax & description
-	<number> - <number> Subtracts the second number from the first, or negates a value.
*	<number> * <number> Multiplies two numbers.
/	<number> / <number> Divides the first number by the second, giving a floating-point result.
↑	<number> ↑ <number> Raises the first number to the power of the second; entered with the up-arrow key on the TRS-80 keyboard.
+	<number> + <number> | <string> + <string> Adds two numbers, or concatenates (joins) two strings end to end.
<	<number> < <number> Less-than comparison, returning -1 for true and 0 for false; also compares strings by character code.
<=	<number> <= <number> | <string> <= <string> Less than or equal.
<>	<number> <> <number> | <string> <> <string> Not equal.
=	<var> = <expr> | <expr> = <expr> Assigns a value to a variable, or in a comparison tests for equality (returning -1 for true, 0 for false).
>	<number> > <number> Greater-than comparison, returning -1 for true and 0 for false; also compares strings by character code.
>=	<number> >= <number> | <string> >= <string> Greater than or equal.
ABS	ABS(<number>) Returns the absolute (unsigned) value of a number.
AND	<number> AND <number> Bitwise/logical AND on 16-bit integers; in conditions both operands must be true (non-zero) for the result to be true.
ASC	ASC(<string>) Returns the ASCII code of the first character of a string; errors on an empty string. CHR$ reverses it.
ATN	ATN(<number>) Returns the arctangent of x, as an angle in radians.
AUTO	AUTO [<line>][, <number>] Turns on automatic line numbering, generating numbers from a start value by an increment (both default to 10) as you type; BREAK stops it.
CDBL	CDBL(<number>) Converts a number to double precision (about 16 significant digits) for higher-accuracy arithmetic.
CHR$	CHR$(<number>) Returns the one-character string for an ASCII or control code (0–255); codes 128–191 select block-graphics characters.
CINT	CINT(<number>) Rounds a number to the nearest integer and returns it as the integer type; errors if outside the range -32768 to 32767.
CLEAR	CLEAR [<number>] Erases all variables and arrays; an optional argument sets how many bytes are reserved for string storage (default 50).
CLOAD	CLOAD [<filename>] Loads a BASIC program from cassette; an optional one-letter file name selects which program on the tape.
CLOSE	CLOSE [<file>[, <file>]…] Closes the listed open files (or all of them if none is given), flushing any buffered data (Disk BASIC).
CLS	CLS Clears the whole 64×16 screen and homes the cursor to the top-left (cell 0).
CMD	CMD<string> Passes a command to the disk operating system (Disk BASIC); e.g. CMD"S" exits to DOS. Has no effect without a DOS present.
CONT	CONT Resumes a program halted by STOP or a BREAK key, continuing from where it stopped (provided the program was not edited).
COS	COS(<number>) Returns the cosine of an angle given in radians.
CSAVE	CSAVE <filename> Saves the current program to cassette under a one-letter file name.
CSNG	CSNG(<number>) Converts a number to single precision (about 6 significant digits).
CVD	CVD(<string>) Converts an 8-byte string (as stored by MKD$) back into a double-precision number, for reading random-file fields (Disk BASIC).
CVI	CVI(<string>) Converts a 2-byte string (as stored by MKI$) back into an integer, for reading random-file fields (Disk BASIC).
CVS	CVS(<string>) Converts a 4-byte string (as stored by MKS$) back into a single-precision number, for reading random-file fields (Disk BASIC).
DATA	DATA <constant>[, <constant>]… Stores a list of numeric or string constants in the program for READ to consume in order; the values are held verbatim to the end of the statement.
DEF	DEF FN<name>(<var>) = <expr> Defines a single-line user function called as FNname(x); the parameter is local to the expression. Also forms DEFINT/DEFSNG/DEFDBL/DEFSTR and DEF USR.
DEFDBL	DEFDBL <letter>[-<letter>] Makes variables whose names begin with the given letter(s) default to double precision (#) for ~16-digit accuracy.
DEFINT	DEFINT <letter>[-<letter>] Makes variables whose names begin with the given letter(s) default to integer (%), which is faster and more compact than floating point.
DEFSNG	DEFSNG <letter>[-<letter>] Makes variables whose names begin with the given letter(s) default to single precision (!) - the normal numeric type.
DEFSTR	DEFSTR <letter>[-<letter>] Makes variables whose names begin with the given letter(s) default to the string type, removing the need for a $ suffix.
DELETE	DELETE <line>[-<line>] Removes a line or an inclusive range of lines from the program.
DIM	DIM <var>(<number>[, <number>]…) Declares one or more arrays with the given upper bounds; subscripts start at 0, so DIM A(10) gives 11 elements. Undeclared arrays default to a bound of 10.
EDIT	EDIT <line> Enters the ROM line editor on the given program line for character-by-character editing.
ELSE	IF <number> THEN <statement> | <line> ELSE <statement> | <line> Supplies the alternative branch of an IF…THEN, run when the condition is false.
END	END Stops the program cleanly and returns to READY without printing a BREAK message; unlike STOP, execution cannot be resumed with CONT.
EOF	EOF(<file>) Returns true (-1) when the end of the given file has been reached, so a read loop can stop (Disk BASIC).
ERL	ERL Returns the line number where the most recent error occurred, for use inside an ON ERROR handler.
ERR	ERR Returns a value related to the most recent error code (ERR/2+1 gives the error number), for use inside an ON ERROR handler.
ERROR	ERROR <number> Forces the error with the given code, as if it had really occurred - handy for testing an ON ERROR routine.
EXP	EXP(<number>) Returns e raised to the power of x, the inverse of LOG.
FIELD	FIELD <file>, <length> AS <strvar>[, <length> AS <strvar>]… Divides a random-access file buffer into named string fields of fixed width for GET/PUT (Disk BASIC).
FIX	FIX(<number>) Truncates a number toward zero, dropping the fractional part (FIX(-1.5) is -1, unlike INT).
FN	FN<name>(<number>) Calls a single-line user function previously created with DEF FN, substituting the argument for the parameter.
FOR	FOR <numvar> = <number> TO <number> [STEP <number>] Opens a counting loop that runs up to the matching NEXT; STEP sets the increment (default 1, may be negative or fractional). The body always runs at least once.
FRE	FRE(<number> | <string>) Returns free memory: with a numeric argument the free bytes, with a string argument the free string space (also forces string garbage collection).
GET	GET <file>[, <record>] Reads a record from a random-access file into its buffer; an optional record number selects which (Disk BASIC).
GOSUB	GOSUB <line> Calls the subroutine at the given line, saving the return address so a later RETURN resumes after the GOSUB.
GOTO	GOTO <line> Jumps unconditionally to the given line number.
IF	IF <number> THEN <statement>|<line> [ELSE <statement>|<line>] Tests a condition (any non-zero value is true); runs the THEN branch when true and the optional ELSE branch when false. Level II supports ELSE, unlike Commodore BASIC.
INKEY$	INKEY$ Returns the character of a key pressed at that instant, or an empty string if none is down. It never waits, making it the input of choice for games.
INP	INP(<port>) Reads and returns a byte (0–255) from the given Z80 I/O port (0–255).
INPUT	INPUT [<prompt>;] <var>[, <var>]… Prints a "?" prompt (with optional message) and halts until the user types values and presses ENTER. Multiple variables are filled from comma-separated input.
INSTR	INSTR([<start>,] <string>, <string>) Returns the position of the first occurrence of the second string within the first (starting at an optional offset), or 0 if not found.
INT	INT(<number>) Returns the largest integer not greater than x (rounds toward minus infinity, so INT(-1.5) is -2).
KILL	KILL <string> Deletes the named file from disk (Disk BASIC).
LEFT$	LEFT$(<string>, <length>) Returns the leftmost n characters of a string.
LEN	LEN(<string>) Returns the number of characters in a string (0 for an empty string).
LET	[LET] <var> = <number> | <string> Assigns a value to a variable. The keyword is optional in Level II, so X=5 and LET X=5 are equivalent.
LINE	LINE INPUT [<string>;] <strvar> Reads an entire input line into a string variable, including commas and leading spaces, without printing a "?" prompt.
LIST	LIST [<line>][-[<line>]] Lists program lines to the screen - all of them, a single line, or a range; keywords are shown detokenized in their long form.
LLIST	LLIST [<line>][-[<line>]] Lists program lines to the line printer, like LIST but on paper.
LOAD	LOAD <filename> Loads a BASIC program from disk, replacing the current program (Disk BASIC).
LOC	LOC(<file>) Returns the current record number last read or written on the given file (Disk BASIC).
LOF	LOF(<file>) Returns the number of the last (highest) record in the given file - its length in records (Disk BASIC).
LOG	LOG(<number>) Returns the natural (base-e) logarithm of a positive number.
LPRINT	LPRINT [<expr>][;|,]… Prints to the line printer; takes the same item list, "," print-zone spacing, and ";" joining as PRINT.
LSET	LSET <strvar> = <string> Stores a string into a random-file field, left-justified and padded or truncated to the field width (Disk BASIC).
MEM	MEM Returns the number of free bytes of program/variable memory remaining.
MERGE	MERGE <filename> Loads a program from disk and merges its lines into the program in memory, overwriting any with matching line numbers (Disk BASIC).
MID$	MID$(<string>, <start>[, <length>]) Returns a substring starting at position i (1-based) for n characters; without n it returns the rest of the string.
MKD$	MKD$(<number>) Packs a double-precision number into an 8-byte string for storage in a random-file field; CVD reverses it (Disk BASIC).
MKI$	MKI$(<number>) Packs an integer into a 2-byte string for storage in a random-file field; CVI reverses it (Disk BASIC).
MKS$	MKS$(<number>) Packs a single-precision number into a 4-byte string for storage in a random-file field; CVS reverses it (Disk BASIC).
NAME	NAME <string> AS <string> Renames a disk file from the first name to the second (Disk BASIC).
NEW	NEW Erases the program in memory and clears all variables, leaving a blank workspace.
NEXT	NEXT [<numvar>[, <numvar>]…] Marks the end of a FOR loop, adding STEP and testing the limit. The variable is optional; listing several closes nested loops in one statement.
NOT	NOT <number> Bitwise/logical NOT on a 16-bit integer; note NOT 0 is -1 (true) and NOT -1 is 0 (false).
ON	ON <number> GOTO <line>[, <line>]… | ON <number> GOSUB <line>[, <line>]… Branches to the n-th line in the list based on the value of the expression (1 selects the first); falls through if the value is 0 or past the end. ON ERROR GOTO sets an error handler.
OPEN	OPEN <string>, <file>, <filename> Opens a disk file under a buffer number for input, output, or random access (Disk BASIC); the mode is "I", "O", or "R".
OR	<number> OR <number> Bitwise/logical OR on 16-bit integers; in conditions the result is true if either operand is true (non-zero).
OUT	OUT <port>, <byte> Sends a byte (0–255) to the given Z80 I/O port (0–255) for direct hardware access.
PEEK	PEEK(<addr>) Returns the byte (0–255) stored at the given memory address (0–65535).
POINT	POINT(<x>, <y>) Returns true (-1) if the block-graphics cell at (x, y) is lit, false (0) otherwise - used for reading the screen back, e.g. collision detection.
POKE	POKE <addr>, <byte> Writes a byte (0–255) to the given memory address (0–65535) for direct memory or hardware manipulation.
POS	POS(<number>) Returns the current cursor column (0–63) on the screen; the argument is a required dummy value.
PRINT?	PRINT [@ <cell>,] [<expr>][;|,]… Writes to the screen; "PRINT @ n," positions output at screen cell n (0–1023 on the 64×16 display). "," advances to the next print zone, ";" joins items. "?" is shorthand for PRINT.
PUT	PUT <file>[, <record>] Writes the buffer of a random-access file out as a record; an optional record number selects which (Disk BASIC).
RANDOM	RANDOM Reseeds the random-number generator from a hardware timer so RND produces a different sequence each run.
READ	READ <var>[, <var>]… Assigns the next constant(s) from DATA statements to the given variables, advancing the data pointer; runs out with an Out of Data error.
REM'	REM <comment> Marks a comment; everything to the end of the line is ignored. The apostrophe ' is a shorthand for REM.
RESET	RESET(<x>, <y>) Clears the block-graphics cell at (x, y) - x 0–127, y 0–47 on the 128×48 grid. SET lights it; POINT tests it.
RESTORE	RESTORE Resets the DATA read pointer to the first DATA item so subsequent READs start again from the beginning.
RESUME	RESUME [<line>|0|NEXT] Ends an error-handling routine and continues the program - at the line that erred (default or 0), the line after it (NEXT), or a specified line.
RETURN	RETURN Returns from a subroutine to the statement following the most recent GOSUB.
RIGHT$	RIGHT$(<string>, <length>) Returns the rightmost n characters of a string.
RND	RND(<number>) RND(0) returns a fraction 0 ≤ r < 1; RND(n) with n ≥ 1 returns a whole number from 1 to n. Use RANDOM to reseed.
RSET	RSET <strvar> = <string> Stores a string into a random-file field, right-justified and padded or truncated to the field width (Disk BASIC).
RUN	RUN [<line>] Clears all variables and starts the program, optionally from a given line number instead of the first.
SAVE	SAVE <filename> Saves the current program to disk; add ,A to save as plain ASCII text (Disk BASIC).
SET	SET(<x>, <y>) Lights the block-graphics cell at (x, y) - x 0–127, y 0–47 on the 128×48 grid (each 64×16 text cell is a 2×3 block). RESET clears it; POINT tests it.
SGN	SGN(<number>) Returns the sign of a number: -1 if negative, 0 if zero, 1 if positive.
SIN	SIN(<number>) Returns the sine of an angle given in radians.
SQR	SQR(<number>) Returns the square root of a non-negative number.
STEP	STEP <number> Sets the increment added to the FOR variable at each NEXT; may be negative to count down or fractional.
STOP	STOP Halts the program and prints a "BREAK IN <line>" message; execution can be resumed with CONT.
STR$	STR$(<number>) Returns the string form of a number, as PRINT would show it (with a leading space for non-negative values); VAL reverses it.
STRING$	STRING$(<length>, <number> | <string>) Builds a string of n copies of a character, given either as an ASCII code or as the first character of a string - handy for drawing bars and rules.
SYSTEM	SYSTEM Enters the SYSTEM monitor to load machine-code (object) programs from cassette by file name.
TAB(	TAB(<number>) Used inside PRINT to advance to absolute print column n (0-based); it never moves the cursor backwards on the current line.
TAN	TAN(<number>) Returns the tangent of an angle given in radians.
THEN	THEN Introduces the consequent of an IF; a line number after THEN acts as a GOTO.
TIME$	TIME$ Returns the current date and time as a string ("MM/DD/YY HH:MM:SS") maintained by the system clock (Disk BASIC).
TO	TO Separates the start and limit values in FOR…TO (and the byte range in some commands); not used on its own.
TROFF	TROFF Turns off the line-number trace enabled by TRON.
TRON	TRON Turns on the trace, printing each line number in brackets as it executes - useful for debugging flow.
USING	PRINT USING <string>; <expr>[, <expr>]… Formats output against a template string: "#" is a digit position, "." fixes the decimal point, "," groups thousands, "**" pads with asterisks, "$$" floats a currency sign, a leading or trailing "+"/"-" places the sign, and "^^^^" selects E notation. For strings, "!" takes the first character and "%" with spaces between makes a field that wide. The template repeats if there are more values than fields, and a value too wide for its field prints after a "%" marker.
USR	USR(<addr>) Calls a user machine-code routine at the address set up by POKE/DEF USR, passing the argument and returning its result.
VAL	VAL(<string>) Reads a number from the start of a string, returning 0 if it does not begin with a numeric value.
VARPTR	VARPTR(<var>) Returns the memory address of a variable's value, used to reach its bytes via PEEK/POKE or to pass data to machine code.

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

<start>

the position something starts at, counting from 1

<length>

how many characters

<x>

a horizontal graphics coordinate

<y>

a vertical graphics coordinate

<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

<cell>

one of the 1024 screen cells, 0 to 1023

<record>

a record number in a random-access file

Showing 126 of 126 keywords

What this machine does not run

The TRS-80 runs on a BASIC interpreter rather than an emulated CPU, so a few keywords are accepted but do nothing:

• Error trapping — ON ERROR GOTO, RESUME and ERROR do not take effect, and ERL/ERR read as zero. A runtime error stops the program and is reported in the IDE instead.
• Machine-level access — USR and VARPTR have no address space to work with, and INP/OUT have no ports; MEM and FRE report fixed figures, as there is no real memory allocator to ask.
• Peripherals — LPRINT and LLIST are accepted and discarded (there is no printer), and TIME$ is empty.
• Random-access disk files — FIELD, GET, PUT, LSET and RSET are accepted and ignored. Sequential files (OPEN, PRINT#, INPUT#, LINE INPUT#, CLOSE, KILL, EOF, LOC, LOF) work against the project's files.
• Editing and listing commands — LIST, EDIT, AUTO, DELETE, NEW, CONT, TRON and TROFF belong to the machine's own prompt; use the IDE's editor and debugger instead.