Enhanced BASIC language reference by Lee Davison
[Back]

Numbers

Numbers may range from zero to plus or minus 1.70141173x10^38 and will have an accuracy of just under 1 part in 1.68 x 10^7.

Numbers can be preceded by a sign, + or -, and are written as a string of numeric digits with or without a decimal point and can also have a positive or negative exponent as a power of 10 multiplier e.g.

-142

96.3

0.25

-136.42E-3

-1.3E7

1

.. are all valid numbers.

Integer numbers, i.e. with no decimal fraction or exponent, can also be in either hexadecimal or binary. Hexadecimal numbers should be preceded by $ and binary numbers preceded by %, e.g.

%101010

-$FFE0

$A0127BD

-%10011001

%00001010

$0A

.. again are all valid numbers.

Strings are any string of printable characters enclosed in a pair of quotation marks. Non printing characters may be converted to single character strings using the CHR$() functions.

"Hello world"

"-136.42E-3"

"+----+----+"

"[Y/n]"

"Y"

Are all valid strings.

Variables of both numeric and string type are available. String variables are distinguished by the $ suffix. As well as simple variables arrays are also available and these may be either numeric or string and are distinguished by their bracketed indicies after the variable name.

Variable names may be any length but only the first two name characters are significant. The first character must be one of "A" to "Z" or "a" to "z". Later characters may also include numbers. E.g.

A

A$

NAME$

x2LIM

y

colour

s1

s2

Variable names are case sensitive so AB, Ab, aB and ab are all separate variables.

Variable names may not contain BASIC keywords. Keywords are only valid in upper case so 'PRINTER' is not allowed (it would be interpreted as PRINT ER) but 'printer' is.

Note that spaces in variable names are ignored so 'print e r', 'print er' and 'pri nter' will all be interpreted the same way.

BASIC Keywords

Here is a list of BASIC keywords. They are only valid when entered in upper case as shown and spaces may not be included in them. So GOTO is valid but GO TO is not.

ABS	AND	ASC	ATN	BIN$	BITCLR	BITSET
BITTST	CALL	CHR$	CLEAR	CONT	COS	DATA
DEC	DEEK	DEF	DIM	DO	DOKE	END
EOR	EXP	FN	FOR	FRE	GET	GOSUB
GOTO	HEX$	IF	INC	INPUT	INT	IRQ
LCASE$	LEFT$	LEN	LET	LIST	LOAD	LOG
LOOP	MAX	MID$	MIN	NEW	NEXT	NMI
NOT	NULL	OFF	ON	OR	PEEK	PI
POKE	POS	PRINT	READ	REM	RESTORE	RETIRQ
RETNMI	RETURN	RIGHT$	RND	RUN	SADD	SAVE
SIN	SGN	SPC(	SQR	STEP	STOP	STR$
SWAP	TAB(	TAN	THEN	TO	TWOPI	UCASE$
UNTIL	USR	VAL	VARPTR	WAIT	WHILE	WIDTH
+	-	*	/	^	<<	>>
>	=	<

• Anything in upper case is part of the command/function structure and must be present
• Anything in lower case enclosed in < > is to be supplied by the user
• Anything enclosed in [ ] is optional
• Anything enclosed in { } and separated by | characters are multi choice options
• Any items followed by an ellipsis, ... , may be repeated any number of times
• Any punctuation and symbols, except those above, are part of the structure and must be included

var	is a valid variable name
var$	is a valid string variable name
var()	is a valid array name
var$()	is a valid string array name
expression	is any expression returning a result
expression$	is any expression returning a string result
addr	is an unsigned integer in the range +/- 16777215 that will be wrapped to the range 0 to 65535
b	is a byte value 0 to 255
n	is an integer in the range 0 to 63999
w	is an integer in the range -32768 to 32767
i	is a +ve integer value
r	is real number
+r	is a +ve value real number (0 is considered +ve)
$	is a string literal

BASIC Commands

END

Terminates program execution and returns control to the command line (direct mode). END may be placed anywhere in a program and any number, including none, is allowed.

Note. CONT may be used after and END to resume execution from the next statement.

FOR <var> = <expression> TO <expression> [STEP expression]

Assigns a variable to a loop counter and optionally sets the step size. If STEP expression is omitted then a default step size of +1 will be assumed.

NEXT [var[,var]...]

Increments a loop variable and checks for the terminating condition. If the terminating condition has been reached then execution continues with the next command, else execution continues with the command after the FOR assignment. (See FOR).

DATA [{r|$}[,{r|$}]...]

Defines a constant or series of constants. Real constants are held as strings in program memory and can be read as numeric values or string values. String constants may contain spaces but if they need to contain commas then they must be enclosed in quotes.

INPUT ["$";] <var>[,var]...

Get a variable, or list of variables from the input stream. A question mark, "?", is always output (after the string if there is one) and if further input is required i.e. there are more variables in the list than the user entered values, then a double question mark, "??", will be output until enough values have been entered.

There are two possible messages that may appear during the execution of an input statement:

Extra ignored

The user has attempted to enter more values than are required. Program execution will continue but the extraneous data entered has been discarded.

Redo from start

The user has attempted to enter a string where a number was expected. The reverse never causes an error as numbers are also valid strings.

DIM <var[$](i1[,i2[,i3]])>[,var[$](i1[,i2[,i3]])]...

Dimension arrays. Creates arrays of either string or numeric variables. The arrays can have one, two or three dimensions. The lower limit is always zero and the upper limit is i. If you do not explicitly dimension an array then it's number of dimensions will be set when you first access it and the upper bound will be set to 10 for each dimension.

READ <var>[,var]...

Reads values from DATA statements and assigns them to variables. Trying to read a string literal into a numeric variable will cause a syntax error.

LET <var> = <expression>

Assign the value of expression to var. Both var and expression bust be of the same type. The LET command word is optional and just <var> = <expression> will give exactly the same result. It is only maintained for historical reasons.

DEC <var>[,var]...

Decrement variables. The variables listed will have their values decremented by one. Trying to decrement a string variable will give a type mismatch error. DEC A is much faster than doing A=A-1 and DEC A,A is slightly faster than doing A=A-2.

SWAP <var[$]>,<var[$]>

Swap two variables. The variables listed will have their values exchanged. Both must be of the same type, numeric or string, and either, or both, may be array elements. Trying to swap a numeric and string variable will give a type mismatch error.

GOTO <n>

Continue execution from line number n

RUN [n]

Begins execution of the program currently in memory at the lowest numbered line. RUN erases all variables and functions, resets FOR .. NEXT, GOSUB .. RETURN and DO ..LOOP states and sets the data pointer to the program start.

If n is specified then programme execution will start at the specified line number.

IF <expression>[relation expression] THEN<{{statement|n}|{GOTO|GOSUB}n}>

Evaluates expression. If the result of expression is non zero then the statement(s) after the THEN or the GOTO or GOSUB are executed. If the result of expression is zero then execution continues with the next line.

RESTORE [n]

Reset the DATA pointer. If n is specified then the pointer will be reset to the beginning of line n else it will be reset to the start of the program. If n is specified but doesn't exist an error will be generated.

GOSUB <n>

Call a subroutine at line n. Program execution is diverted to line n but the calling point is remembered. Upon encountering a RETURN statement program execution will continue with the next statement (line) after the GOSUB.

RETIRQ

Returns program execution to the next statement after an interrupt, automatically restores the IRQ enabled flag. See ON IRQ.

RETNMI

Returns program execution to the next statement after an interrupt, automatically restores the NMI enabled flag. See ON NMI.

RETURN

Returns program execution to the next statement (line) after the last GOSUB encountered. See GOSUB. Also returns program execution to the next statement after an interrupt but does not restore the enabled flags.

REM

Everything following this statement on this program line will be ignored, even colons.

STOP

Halts program execution and generates a "Break in line n" message where n is the line in which the STOP was encountered.

OFF

See IRQ or NMI.

ON <expression> {GOTO|GOSUB} <n>[,n]...

The integer value of expression is calculated and then the nth number after the GOTO or GOSUB is taken (where n is the result of expression). Note that valid results for expression range only from zero to 255. Any result outside this range will cause a Function call error.

ON {IRQ|NMI} <n>

Set up the IRQ or NMI routine pointers. This sets up the effective GOSUB line that is taken when an interrupt happens. When the effective GOSUB is taken the interrupt, IRQ or NMI, is turned off. This can be turned back on with the interrupt on command or by using the matching special return. The normal program flow is resumed by any of RETIRQ, RETNMI or RETURN.

NULL <n>

Sets the number of null characters printed by BASIC after every carriage return. n may be specified in the range 0 to 255.

INC <var>[,var]...

Increment variables. The variables listed will have their values incremented by one. Trying to increment a string variable will give a type mismatch error. INC A is much faster than doing A=A+1 and INC A,A is slightly faster than doing A=A+2.

WAIT <addr,b1>[,b2]

Program execution will wait at this point until the value of the location addr exclusive ORed with b2 then ANDed with b1 is non zero. If b2 is not defined then it is assumed to be zero. Note b1 and b2 must both be byte values.

LOAD

Does nothing in this version but does it via a vector in RAM so is easily patched.

SAVE

Does nothing in this version but does it via a vector in RAM so is easily patched.

DEF FN <name>(<var>) = <statement>

Defines <statement> as function <name>. <name> can be any valid numeric variable name of one or more characters. <var> must be a simple variable and is used to pass a numeric argument into the function. Note that the value of <var> will be unchanged by it's use in the function so <var> should be considered to be a local variable name.

POKE <addr,b>

Writes the byte value b into the address addr.

DOKE <addr,w>

Writes the word value w into the addresses addr and addr+1, the lower byte of w is in addr. Note if addr = 65535 ($FFFF) then the high byte will be written to address zero.

CALL <addr>

CALLs a user subroutine at address addr. No values are passed or returned and so this is much faster than using USR()

DO

Marks the beginning of a DO .. LOOP loop (See LOOP). No parameters. This command can be nested like FOR .. NEXT or GOSUB .. RETURN.

LOOP [{UNTIL|WHILE} expression]

Marks the end of a DO .. LOOP loop. There are three possible variations on the LOOP command ..

LOOP

Repeats forever. With just this command control is passed back to the next command (line) after the DO.

LOOP UNTIL expression

This loop will repeat until the value of expression is non zero. Once that occurs execution will continue with the next command (line) after this one.

LOOP WHILE expression

This loop will repeat while the value of expression is non zero. Once expression=0 execution will continue with the next command (line) after this one.

PRINT [expression][{;|,}expression]...[{;|,}]

Outputs the value of each expressions. If the list of expressions to be output does not end with a comma or a semi-colon, then a carriage return and linefeed is output after the values.

Expressions on the line can be separated with either a semi-colon, causing the next expression to follow immediately, or a comma which will advance the output to the next tab stop before continuing to print. If there are no expressions and no comma or semi-colon after the PRINT statement then a carriage return and linefeed is output.

When entering a program line, or immediate statement, PRINT can be abbreviated to ? .

CONT

Continues program execution after CTRL-C has been typed, a STOP has been encountered during program execution or a null input was given to an INPUT request.

LIST [n1][-n2]

Lists the entire program held in memory. If n1 is specified then the listing will start from line n1 and run to the end of the program. If -n2 is specified then the listing will terminate after line n2 has been listed. If n1 and -n2 are specified then all the lines from n1 to n2 inclusive will be listed.

Note. If n1 does not exist then the list will start from the next line numbered after n1. If n2 does not exist then the listing will stop with the last line numbered before n2.

Also note. LIST can be executed from within a program, first a [CR][LF] is printed and then the specified lines, if any, each terminated with another [CR][LF]. Program execution then continues as normal.

CLEAR

Erases all variables and functions and resets FOR .. NEXT, GOSUB .. RETURN and DO ..LOOP states.

NEW

Deletes the current program and all variables from memory.

WIDTH {b1|,b2|b1,b2}

Sets the terminal width and TAB spacing. b1 is the terminal width and b2 is the tab spacing (default is 80 and 14). Width can be zero, for "infinite" terminal width, or from 16 to 255. The tab size is from 2 to width-1 or 127, whichever is smaller.

GET <var[$]>

Gets a key, if there is one, from the input device. If there is no key waiting then var will be set to 0 and var$ will return a null string "". GET does not halt and execution will continue.

IRQ {ON|OFF|CLEAR}

Enables or disables the IRQ handling subroutine. Note that turning the handler off does not suppress the interrupt detection and if an interrupt occurs while handling is off it will be actioned as soon as handling is turned back on. Using CLEAR clears the interrupt assignment and it can only be restarted with an ON IRQ command

NMI {ON|OFF|CLEAR}

Enables or disables the NMI handling subroutine. Note that turning the handler off does not suppress the interrupt detection and if an interrupt occurs while handling is off it will be actioned as soon as handling is turned back on. Using CLEAR clears the interrupt assignment and it can only be restarted with an ON NMI command

TAB(<expression>)

Sets the cursor position to <expression>. If the cursor is already beyond that point then the cursor will be left where it is. This command is only valid in a PRINT statement.

TO

Sets the range in a FOR .. NEXT loop. See FOR.

FN<name>(<expression>)

See DEF.

SPC(<expression>)

Prints <expression> spaces. This command is only valid in a PRINT statement.

THEN

See IF.

NOT <expression>

Generates the bitwise NOT of then signed integer value of <expression>.

STEP

Sets the step size in a FOR .. NEXT loop. See FOR.

UNTIL

See DO and LOOP.

WHILE

See DO and LOOP.

BITCLR <addr>,<b>

Clears bit b of address addr. Valid bit numbers are 0, the least significant bit, to 7, the most significant bit. Values outside this range will cause a function call error.

BITSET <addr>,<b>

Sets bit b of address addr. Valid bit numbers are 0, the least significant bit, to 7, the most significant bit. Values outside this range will cause a function call error.

BASIC Operators

Operators perform mathematical or logical operations on values and return the result. The operation is usually preceded by a variable name and equality sign or is part of an IF .. THEN statement.

+	Add. c = a + b will assign the sum of a and b to c.
-	Subtract. c = a - b will assign the result of a minus b to c.
*	Multiply. c = a * b will assign the product of a and b to c.
/	Divide. c = a / b will assign the result of a divided by b to c.
^	Raise to the power of. c = a ^ b will assign the result of a raised to the power of b to c.
AND	Logical AND. c = a AND b will assign the logical AND of a and b to c
EOR	Logical Exclusive OR. c = a EOR b will assign the logical exclusive OR of a and b to c.
OR	Logical OR. c = a OR b will assign the logical inclusive OR of a and b to c.
<<	Shift left. c = a << b will assign the result of a shifted left by b bits to c.
>>	Shift right. c = a >> b will assign the result of a shifted right by b bits to c.
=	Equals. c = a = b will assign the result of the comparison a = b to c.
>	Greater than. c = a < b will assign the result of the comparison a > b to c.
<	Less than. c = a < b will assign the result of the comparison of a < b to c.

The three comparison operators can be mixed to provide further operators ..

>= or =>	Greater than or equal to.
<= or =<	Less than or equal to.
<> or ><	Not equal to (greater than or less than).
<=> any order	Always true (greater than or equal to or less than).

Functions always return a value, be it numeric or string, so are used on the right hand side of the = sign or in commands requiring an expression e.g. after PRINT, within expressions, or in other functions.

SGN(<expression>)

Returns the sign of <expression>. If the value is +ve SGN returns +1, if the value is -ve then SGN returns -1. If expression=0 then SGN returns 0.

INT(<expression>)

Returns the integer of <expression>.

ABS(<expression>)

Returns the absolute value of <expression>.

USR(<expression>)

Takes the value of <expression> and places it in FAC1 and then calls the USeR routine pointed to by the vector at $0B,$0C. What the routine does with this value is entirely up to the user, it can even be safely ignored if it isn't needed. The routine, after the user code has done an RTS, takes whatever is in FAC1 and returns that. Note it can be either a numeric or string value.

If no value needs to be passed or returned then CALL is a better option.

FRE(<expression>)

Returns the amount of free program memory. The value of expression is ignored and can be numeric or string.

POS(<expression>)

Returns the POSition of the cursor on the terminal line. The value of expression is ignored.

SQR(<expression>)

Returns the square root of <expression>.

RND(<expression>)

Returns a random number in the range 0 to 1. If the value of <expression> is non zero then it will be used as the seed for the returned pseudo random number otherwise the next number in the sequence will be returned.

LOG(<expression>)

Returns the natural logarithm (base e) of <expression>.

EXP(<expression>)

Returns e^<expression>. (natural antilog)

COS(<expression>)

Returns the cosine of <expression>.

SIN(<expression>)

Returns the sine of <expression>.

TAN(<expression>)

Returns the tangent of <expression>.

ATN(<expression>)

Returns the arctangent of <expression>.

PEEK(<addr>)

Returns the byte value of <addr>.

DEEK(<addr>)

Returns the word value of <addr> and addr+1. Addr holds the word low byte.

SADD(<{var$|var$()|expression$}>)

Returns the address of var$, var$() or expression$. This returns a pointer to the actual string in memory not the descriptor.

LEN(<expression$>)

Returns the length of <expression$>.

STR$(<expression>)

Returns the result of <expression> as a string.

VAL(<expression$>)

Returns the value of <expression$>.

ASC(<expression$>)

Returns the ASCII value of the first character of <expression$>.

LCASE$(<expression$>)

Returns <expression$> with all the alpha characters in lower case.

UCASE$(<expression$>)

Returns <expression$> with all the alpha characters in upper case.

CHR$(b)

Returns single character string of character <b>.

HEX$(<expression>[,b])

Returns <expression> as a hex string. If b is omitted, or if b = 0, then the string is returned with all leading zeroes removed and is of variable length. If b is set (permissible set values are 1 to 6) then a string of length b will be returned. The result is always unsigned and calling this function with expression>2^24-1 or b>6 will cause a function call error.

BIN$(<expression>[,b])

Returns <expression> as a binary string. If b is omitted, or if b = 0, then the string is returned with all leading zeroes removed and is of variable length. If b is set (permissible set values are 1 to 24) then a string of length b will be returned. The result is always unsigned and calling this function with expression>2^24-1 or b>24 will cause a function call error.

BITTST(<addr>,<b>)

Tests bit b of address addr. Valid bit numbers are 0, the least significant bit, to 7, the most significant bit. Values outside this range will cause a function call error. Returns zero if the bit was zero, returns -1 if the bit was 1.

MAX(<expression>[,<expression>]...)

Returns the maximum value from a list of numeric expressions. There must be at least one expression but the upper limit is dictated by the line length. Each expression is evaluated in turn and the largest of them returned.

MIN(<expression>[,<expression>]...)

Returns the minimum value from a list of numeric expressions. There must be at least one expression but the upper limit is dictated by the line length. Each expression is evaluated in turn and the smallest of them returned.

PI

Returns the value of pi as 3.14159274 (closest floating value).

TWOPI

Returns the value of 2*pi as 6.28318548 (closest floating value).

VARPTR(<var[$]>)

Returns a pointer to the variable memory space. If the variable is numeric, or a numeric array element, then VARPTR returns the pointer to the packed value of that variable in memory. If the variable is a string, or a string array element, then VARPTR returns a pointer to the descriptor for that string.

LEFT$(<expression$,b>)

Returns the leftmost b characters of <expression$>.

RIGHT$(<expression$,b>)

Returns the rightmost b characters of <expression$>.

MID$(<expression$,b1>[,b2])

Returns the substring string from character b1 of expression$ of length b2. The characters of expression$ are numbered from 1 starting with the leftmost.

These will all be followed by the word Error and, if the error occurred while executing a program, will be followed by "in line " where is the number of the line in which the error occurred.

NEXT without FOR

NEXT has been encountered and no matching FOR could be found.

Syntax

Just generally worng. 8^)=

RETURN without GOSUB

RETURN has been encountered and no matching GOSUB could be found.

Out of DATA

A READ has tried to read data beyond the last item. Usually because you either mistyped the DATA lines, miscounted the DATA, RESTOREd to the wrong place or just plain forgot to restore.

Function call

Some parameter of a function was outside it's limits. E.g. Trying to POKE a value of less than 0 or greater than 255.

Overflow

The result of a calculation has exceeded the numerical range of BASIC. This is plus or minus 1.7014117+E38

Out of memory

Anything that uses memory can cause this but mostly it's writing and running programmes that does it.

Undefined statement

Either a GOTO, GOSUB, RUN or RESTORE was attempted to a line that doesn't exist or the line referred to in an ON <expression> {GOTO|GOSUB} or ON {IRQ|NMI} doesn't exist.

Array bounds

An attempt was made to access an element of an array that was outside it's bounding dimensions.

Double dimension

An attempt has been made to dimension an already dimensioned array. This could be because the array was accessed previously causing it to be dimensioned by default.

Divide by zero

The right hand side of an A/B expression was zero.

Illegal direct

An attempt was made to execute a function in direct mode which is disallowed in that mode e.g. INPUT or DEF.

Type mismatch

An attempt was made to pass a numeric value to a string, a string value to a numeric variable or an attempt at a relational operation between a string and a number was made.

String too long

String lengths can be from zero to 255 characters, more than that and you will see this.

String too complex

A string expression caused an overflow on the descriptor stack. Try splitting the expression into smaller pieces.

Can't continue

Execution can't be continued because either the program execution ended because an error occurred, NEW or CLEAR have been executed since the program was interrupted or the program has been edited.

Undefined function

FN <var> was called but not found.

LOOP without DO

LOOP has been encountered and no matching DO could be found.

e-mail me