3. BASIC keywords

This section consists of a list of all BASIC keywords with descriptions and examples of use.

ABS A function giving the absolute value of its argument.
Example:
PRINT ABS(4),ABS(-3.2)
4	3.2
ACS A function giving the arc cosine of its argument in radians.
ADVAL Not implemented.
AND An operator that performs bit-by-bit ANDing of its two arguments. It can be used as a logical operator in TRUE/FALSE contexts.
Examples:
A%=X% AND 3
IF A%=2 AND B%=3 THEN 110
ASC A function returning the ASCII value of the first character of the argument string. If the string is null then -l will be returned.
ASN A function giving the arc sine of its argument in radians.
ATN A function giving the arc tangent of its argument in radians.
AUTO A command allowing the user to enter BASIC lines in sequence with the line numbers provided automatically. AUTO mode is left by pressing ESC. There are two optional arguments: the starting line number (default 10) and the step size (between 1 and 255, default 10).
Examples:
AUTO starts at 10 with step 10
AUTO 100 starts at 100 with step 10
AUTO 100,1 starts at 100 with step 1
AUTO ,2 starts at 10 with step 2
BGET# A function which gets a byte from the file whose channel number is the first argument. Note the normal ATOM COS constraints apply, i.e. there is no buffering and room must be allowed between bytes on PUTting to allow processing during GETting.
Example:
E=BGET#HANDLE%
BPUT# A statement which puts a byte to the file whose channel number is the first argument. The second argument's least significant byte is sent. Note the comments for BGET*.
Examples:
BPUT#HANDLE%,32
BPUT#HANDLE%,A%/256
CALL A statement to call a piece of machine code. CALL initialises a control block at address hex 0600 in store to contain the number of parameters and pointers to each parameter with an attached type. The processor's A, X, and Y registers and the C carry flag are initialised to the least-significant bytes of A%, X% and Y% respectively and the least-significant bit of C%. See also USR. Parameter types are:
0 byte e.g. ?A%
4 word e.g. !A% or A%
5 real e.g. A
128 fixed string e.g. $A% terminated by CHR$13
129 movable string e.g. A$

The value given is the absolute address of the item, except in the case of moveable strings (code 129) where the address is that of the start of a parameter block containing start address, maximum length, and current length of the string.
Examples:
CALL &FFE3
CALL MULDIV,A,B,C,D
CHAIN A statement which will load and run the program whose name is specified in the argument. All variables except @% to Z% are CLEARed.
Examples:
CHAIN "PROG1"
CHAIN A$
CHR$ A string function returning a string of length 1 containing the ASCII character specified by the least significant byte of the numeric argument.
Example:
PRINT CHR$(65)
A
CLEAR A statement which clears all the dynamic variables, including arrays. The variables A% to Z% and @% are static and are unaffected.
CLG A statement that clears the current graphics area.
It is equivalent to a MODE statement in the current mode.
CLOSE# A dummy statement whose normal function is not required by the ATOM COS.
CLS A statement that clears the current text area.
It is equivalent to PRINT CHR$12;
COLOUR Not implemented.
COS A function giving the cosine of its radian argument.
COUNT A function returning the number of characters printed since the last newline.
DATA A program object which must precede all lists of data for READ. String values may be quoted or unquoted as for INPUT, and the numeric values may include calculation so long as no reserved words are included.
Example:
DATA FRANCIS,16,"JOHN ",15,"JULIE ",15
DEF A program object which introduces the definition of a user function FN or a user procedure PROC. If encountered at execution then the rest of the line is ignored so that single-line definitions can be put anywhere in the program. Multiple-line definitions must not be executed: it is recommended that they are placed at the end of the main program text. There is no speed advantage gained in placing them at the start of the program.

Example:
DEF FNMEAN(Vl,V2)=(Vl,V2)/2
DEG A function which converts radians to degrees.
DELETE A command which deletes a group of lines from the program. The two arguments indicete the first and last lines of the group respectively.
Examples:
DELETE 10,15 delete lines 10 to 15
DELETE 0,20 delete up to line 20
DELETE 20,32767 delete all lines after 19
DIM A statement which declares arrays. Arrays must be declared before use. Integer, real and string arrays may be multi-dimensional. The extents in each dimension are specified as a bracketed list of values separated by commas. DIM sets all elements in the array to 0 or null, depending on type. Arrays may not be redimensioned. By following the integer name with an unbracketed extent value, DIM can also be used to dimension integers to point at an area of memory which the interpreter will not then use. This can be used for positioned strings, data structures, machine code etc.
Example:
DIM A(20),A$(2,4),A%(3,4,5,6),MC% 100
DIV A binary operation giving integer division.
DRAW A statement to draw a line to the point specified by its two arguments in the current graphics foreground colour. It is equivalent to PLOT5.
ELSE A statement indicating the start of instructions to be executed if, in an IF structure, the condition is FALSE, or in an ON structure, the tested value is out-of-range.
Examples:
IF A=B THEN B=C ELSE B=D
ON A% GOTO 100,110,130 ELSE 500
END A statement that terminates execution of the program and returns the interpreter to direct mode. There is no restriction on the number and position of END statements in a program.
ENDPROC A statement denoting the end of a procedure. The values of all LOCAL variables and the dummy arguments are restored at ENDPROC and the program returns to the statement after the calling statement.
ENVELOPE Not implemented.
EOF Not implemented.
EOR An operator that performs bit-by-bit exclusive-OR of its two arguments. It can also be used as a logical operator in TRUE/FALSE contexts.
Examples:
X% = B% EOR 4
IF A=2 EOR B=3 THEN 110
ERL A function returning the number of the line where the last error occurred.
Errors in direct mode give the value 0.
ERR A function returning the error code number of the last error.
ERROR See ON.
EVAL A function which applies the interpreter's expression evaluation program to the contents of the argument string.
EXP A function returning 'e' to the power of the argument.
EXT# Not implemented.
FALSE A pseudo-variable with the value -1, for use in logical expressions.
FN A reserved word used at the start of all user declared functions. A function may be defined with any number of arguments of any type, and may return (using =) a string or numeric quantity. A function definition is terminated by '=' used in the statement position. The values of the dummy arguments are set to those of the formal arguments when the function is called.
Examples:
DEF FNMEAN(Ql,Q2,Q3,Q4)=(Ql+Q2+Q3+Q4)/4

DEF FNFACTORIAL(N) IF N<2 THEN =1
ELSE =FNFACTORIAL(N-l )*N

DEF FNREVERSE(A$) LOCALB$,Z%
FOR Z% = l TO LEN (A$):
$=MID$(A$, Z%, l)+B$:NEXT:=B$
FOR A statement initialising a FOR ... NEXT loop. The loop is executed at least once. Any numeric assignable item may be used as the control variable. Integer control variables are three times quicker than real variables at the NEXT statement and also much faster when indexing an array.
Examples:
FOR A=0 TO 9
FOR A%=0 TO 9
FOR A(2,3,l) = 0 TO 9
GCOL Not implemented.
GET A function that returns the ASCII code of the next character from the input stream, waiting for a key-press if necessary.
GET$ A function that returns the next character from the input stream as a string, waiting for a key-press if necessary.
GOSUB As GOTO but allows RETURN. GOSUBs may be nested to a maximum depth of 26.
GOTO A statement which transfers execution to the line indicated by its argument, which may be a constant number or calculated value.
HIMEM A pseudo-variable which sets and gives the maximum address used by the interpreter.
IF Part of the conditional IF ... THEN ... ELSE statement. It introduces a logical expression, the value of which determines whether the following statements or those after the next optional ELSE, are to be executed.
Examples:
IF A=B THEN 110
IF A<C OR A>D GOTO 110
IF A>C AND C>=D THEN GOTO 110
IF A<Q PRINT "I THINK IT IS LESS"
IF A>Q THEN PRINT "I THINK IT IS GREATER"
IF A>=Q THEN PRINT "GREATER OR EQUAL" : END
INKEY A function that performs a GET but waits for a maximum of n clock ticks where n is the argument. At the end of this period, -l is returned. INKEY of negative numbers is not supported.
Examples:
NINKEY (0)
N$=INKEY$ (100)
INKEY$ A function that performs a GET$ but waits for a maximum of n clock ticks where n is the argument. At the end of this period, -l is returned. INKEY$ of negative numbers is not supported.
INPUT A statement to input values from the keyboard.
Example:
INPUT A,B,C,D$, "WHO ARE YOU", W$, "NAME" R$

If items are not immediately preceded by a printable string (even if null) then a "7" will be printed as a prompt. Items A, B, C, D$ in the above example can have their answers returned on one to four lines, separate items being separated by commas. Extra items will be ignored. Then WHO ARE YOU? is printed (the question mark comes from the comma) and W$ is input, then NAME is printed and R$ is input. The statement INPUT A is exactly equivalent to INPUT A$:A = VAL(A$). Leading spaces will be removed from input, but not trailing spaces. Strings in quoted form are taken as they are, with a possible error occurring for a missing closing quote.
INPUTLINE A statement of identical syntax to INPUT which uses a new line for each item to be input. The item input is taken as is.
INPUT# A statement which reads internal forms from tape and puts them in the specified items. The first argument is the channel number.
Example:
INPUT#E A,B,C,D$,E$,F$
LNSTR A function which returns the position of a sub-string within a string, optionally starting the search at a specified place in the string.
Examples:
INSTR(A$,B$)
INSTR(A$,B$,Z%)
INT A function truncating a real number to the lower integer.
LEFT$ A string function which returns the left n characters of the string. If there are insufficient characters in the string then all are returned.
Examples:
LEFT$(A$,2)
LEFT$(RIGHT$(A$,3),2)
LEN A function which returns the length of the argument string.
Examples:
LENA$
LEN$(A%+6)
LET An optional assignment statement.
LIST A command which causes lines of the current program to be listed out with the automatic formatting options specified by LISTO. The command can be followed by start and finish line numbers, separated by a comma.
Examples:
LIST
LIST ,l00
LIST 100,500
Note that L. is a convenient abbreviation for LIST.
LISTO A command which sets options for the format of a LISTed program. LISTO takes an integer in the range 0 to 7. The three bits have the following effects when set:
Bit Effect
0 A single space is printed after the line number on each line.
1 A double space is printed out n times after the line number,
where n is the current level of nested FOR ... NEXT loops.
2 A double space is printed out m times after the line number, where m is the current level of nested REPEAT ... UNTIL loops. Note that n and m are set according to the lines actually listed out so far. It is useful to set LISTO 0 when doing a lot of cursor editing.
LN A function giving the natural logarithm of its argument.
LOAD A command which loads a new program from a file and CLEARs the variables of the old program.
Example:
LOAD "PRIMES"
LOCAL A statement which saves the values of its arguments in such a way that they will be restored at = or ENDPROC. The arguments are set to zero or null. It can only be used inside a FN or PROC. See FN for an example.
LOG A function giving the common (base 10) logarithm of its argument.
LOMEM A pseudo-variable which controls where in memory dynamic variables and dimensioned arrays are to be placed. The default is TOP, the first free address after the end of the program.
MID$ A string function which extracts a sub-string from the middle of its argument string. The second argument specifies the start position of the sub-string, and the third its length. If the length is omitted or there are insufficient characters in the string then all from the start position onwards are returned.
Examples:
MID$( A$, Z, X)
MID$( A$, Z)
MOD A binary operation giving the signed remainder of the integer division. MOD is defined such that:
A MOD B = A - (A DIV B) * B
Example:
A% = B% MOD C%
MODE A statement which selects the specified display screen mode (0-7), and clears the screen. The relationship between BBC BASIC modes and the normal ATOM modes is as follows:
BBC ATOM
0-3 4
4 3
5 2
6 1
7 0

MODE cannot be used inside a PROC or FN
Examples:
MODE 7
MODE A
MOVE A statement to move the graphics cursor to the specified co-ordinates.
It is equivalent to PLOT4.
NEW A command which initialises the interpreter for a new program to be typed in.
The old program may be recovered with the OLD command provided no errors have occurred and no new lines have been typed in.
NEXT The statement terminating FOR ... NEXT loops. NEXT takes an optional control variable: if present then FOR ... NEXT loops may be 'popped' in an attempt to match to the correct FOR statement.
NOT A high priority unary operator equivalent to unary minus.
Examples:
IF NOT(A=B AND C=D) THEN 2100
A% = NOT B% AND C%
OFF A program object used to re-enable the default error handler.
Example:
ON ERROR OFF
See ON.
OLD A command which undoes the effect of NEW, provided no new lines have been typed in and no new variables have been created.
ON A statement controlling a multi-way switch or error trapping. When used in one of the forms:
ON <expression> GOTO ...
ON <expression> GOSUB ...
the structure is followed by a list of line numbers separated by commas, optionally followed by ELSE and one or more statements. The integer value of the expression selects the line number to be used, with the ELSE statements being executed if the corresponding line number is not provided. The values in the list are skipped without calculation but it will get confused by ASC"," appearing.
ON can also be used to trap errors:

ON ERROR ...

The statements following ON ERROR are executed whenever a BASIC error occurs.

ON ERROR OFF re-enables the default error handler.
Examples:
ON A% GOTO 10,20,30,30:ELSE PRINT "Illegal"
ON B% GOSUB 100,20a,C+200:ELSE PRINT "What? "
ON ERROR PRINT "Suicide": END
ON ERROR GOTO 100
ON ERROR OFF
OPENIN A dummy function which normally opens the named file for input and updating and returns the channel number of the file. The ATOM COS only allows one open file (for input or output), and this function just returns 13 as the channel number.
Example:
H%=OPENIN "DATA"
OPENOUT A dummy function which normally opens the named file for output and returns the channel number of the file. The ATOM COS only allows one open file, and this function just returns 13 as the channel number.
Example:
H%=OPENOUT "DATA"
OPT An assembler pseudo-operation controlling output to the screen during assembly. OPT is followed by an expression, the two least-significant bits of which have the following effects when set:
Bit Effect
0 assembler listing on
1 assembler errors on

The default OPT is 3.
OR An operator that performs bit-by-bit ORing of its arguments.
It can be used as a logical operator in TRUE/FALSE contexts.
Examples:
IF A=2 OR B=3 THEN 110
X% = B% OR 4
PAGE A pseudo-variable controlling the starting page of the current text area. With careful use, several programs can be held in RAM memory without the need for saving them.
Examples:
PAGE=&1900
PAGE=PAGE+&100
PI A pseudo-variable with the value 3.14159265.
PLOT A multi-purpose graphics statement. The first argument selects the function, and the second and third arguments are x and y co-ordinates for that function. The lower seven bits of the first argument have the following meanings:
Bit Value Function
0,1 00 No change in memory while plotting (e.g. MOVE)
01 Plot in graphics foreground colour
10 Plot inverting colour
11 Plot in graphics background colour
2 0 Relative plot co-ordinates
1 Absolute plot co-ordinates
3-5 0 Must be 0
6 0 Line (continuous, with both endpoints)
1 Point

The maximum x and y co-ordinates are 1280 and 1024 respectively in all modes.
Example:

PLOT&45,X,Y (plots a point in the graphics foreground colour at X,Y)
POINT Not implemented.
POS Not implemented.
PRINT A statement that prints numbers, characters and strings on the display. PRINT is followed by a list of variables and constants to be printed, with special items to control the format and position of printing. The width of the print field, and the number of figures and decimal places printed for numbers, are controlled by the variable @%. The four bytes of the value have the following functions:
Byte Function
0 print field width
1 Maximum total number of digits printed
2 Numeric format:0 General format
1 Exponent format
2 Fixed format
3 STR$ format:
0 Ignore bytes 0-2
1 Use bytes 0-2

Byte 1 controls the number of digits in a mode. If it is out of range then 9 is assumed. In G mode it specifies the maximum number of digits to be printed between 1 and 9. In E mode it specifies the exact number of digits to be printed between 1 and 9. In F mode it specifies the number of digits to follow the decimal point, between 0 and 9.

E mode will print an optional - sign, one digit, a decimal point, <Byte 1>-l digits, an E and an exponent field in 3 characters, padded with trailing spaces if necessary. The G mode will print integral values as integers, numbers in the range 0.1 to 1 as 0.1 etc., numbers less than .1 or greater than 1E<Byte 1> with an exponent of as few characters as possible.

F mode will print numbers with <Byte 1> digits after the decimal point unless the total number would then have more than nine digits in which case G mode is used.
Examples (all shown right justified):

Number G2 G9 F2 E2
.1 0.1 0.1 0.10 1.0E-l
.01 1E-2 1E-2 0.01 1.0E-2
.001 1E-3 1E-3 0.00 1.0E-3
.005 5E-3 5E-3 0.01 5.0E-3
1 1 1 1.00 1.0E0
10 10 10 10.00 1.0E1
100 1E2 100 100.00 1.0E2

The following characters have special functions in PRINT:

Character Function
' Causes the next item to be printed in the next field
; Separates items without the effect of ,
. Suppresses the new line at the end of the PRINT statement.
~ Causes all numbers to be printed in hex until ' or is reached
’ Prints new line

Examples Result
@%=&00090A

PRINT 1,2 1 2
PRINT 10,200 10 200
PRINT 10;200 10200
PRINT "Answer ";A Answer 42
PRINT "Answer "A Answer 42
PRINT "Answer ",A Answer 42
PRINT "Hi", "Hi" Hi Hi
PRINT "Hi ~; "Hi" HiHi
PRINTl'20 1
20
PRINT# A statement which writes the internal form of a value out to tape. The first argument is the channel number. All numeric constants are written as five bytes of binary real data. All strings are written as the bytes in the string plus a carriage return.
Example:
PRINT#E,A,B,C,D$,E$,F$
PROC A reserved word used at the start of all user-declared procedures. The arguments in the body of the procedure are set to the values of the arguments in the call.
Example:
INPUT "Number of discs "F
PROCHANOI(F,l,2,3)
END
DEF PROCHANOI (A, B,C, D) IFA=0 ENDPROC
PROCHANOI (A-l,B,D,C)
PRINT "Move disk ";A" from pile ";B" to pile ";C
PROCHANOI (A-l,D,C,B)
ENDPROC
PTR# Not implemented.
RAD A function which converts degrees to radians.
Example:
S%=SINRAD(90)
READ A statement which will set variables to values read from the DATA statements in the program. Strings may be enclosed in double quotes unless they have leading spaces or contain commas.
REM A statement that causes the rest of the line to be ignored, allowing comments in the program.
RENUMBER A command which will renumber the lines and correct the cross references inside a program accordingly. Options are as for AUTO. RENUMBER produces messages when a cross reference fails.
REPEAT A statement which is the starting point of a REPEAT ... UNTIL loop. The statements inside the loop are executed and repeated until the expression after UNTIL is true. A single REPEAT may have more than one UNTIL. These loops may be nested up to a maximum depth of 20.
Example:
REPEAT A%=A%+RND(3)-l: UNTIL A%>B%
REPORT A statement which prints out a newline followed by the last-made error string.
RESTORE A statement that can be used at any time in a program to set the place where DATA comes from. The optional parameter for RESTORE can specify a calculated line number.
Examples:
RESTORE
RESTORE 100
RESTORE (l0*A+20)
RETURN A statement causing execution to return to the statement after the most recently executed GOSUB statement.
RIGHT$ A string function which returns the right n characters of the string. If there are insufficient characters in the string then all are returned.
Examples:
RIGHT$(A$,2)
RIGHT$(LEFT$(A$,3)12)
RND A function with optional parameter that provides random numbers. RND(l) returns a real number in the range 0.0 to .99999999. RND returns a random integer 0 -&FFFFFFFF. RND(n) returns an integer in the range 1 to n. If n is negative the pseudo-random sequence generator is set to a number based on n and n is returned. If n is 0 the last RND(1) random number is returned. The argument to RND must always be bracketed and there must be no spaces between RND and the left bracket.
RUN A statement that runs the program in the current PAGE.
All variables except @% to Z% are CLEARed.
SAVE A statement which saves the current program area to a file.
Example:
SAVE "PRIMES"
SGN A function returning -l for negative argument, 0 for 0 argument and +1 for positive argument.
SIN A function giving the sine of its radian argument.
SOUND A statement that produces a sound from the ATOM's internal loudspeaker. Four arguments are required: the first two are ignored, the third controls the period of the tone, and the fourth sets the duration in 10 ms units.
Example:
SOUND 0,0,300,100
SPC A function which outputs n MOD 256 spaces where n is the argument. It can only be used in PRINT or INPUT.
SQR A function returning the square root of its argument.
STEP Part of the FOR statement, this optional section specifies step sizes other than 1.
STOP Syntactically identical to END, STOP also prints a message to the effect that the program has stopped.
STR$ A string function which returns the string form of the numeric argument as it would have been printed. If the most-significant byte of @% is 1, STR$ uses the current @% description for printing numbers, and if zero (the initial value) the G9 format (see PRINT) is used.
STR$~ A string function that returns the string form of the numeric argument as it would have been printed in hex.
STRING$ A function returning n concatenations of a string, where n is the argument.
Example:
STRING$ (10, "*--*")
TAB A function that changes the position of printing, only available in PRINT or INPUT. TAB(X) will attempt to make COUNT equal to X by printing a newline if required plus some spaces. TAB(X,Y) will perform a cursor move on the screen to character cell X,Y if possible. The leftmost column is column 0.
TAN A function returning the tangent of its radian argument.
THEN The part of the IF statement that precedes the statements to be executed if the IF condition is TRUE. It may be replaced by : or a space.
TIME A pseudo-variable which reads and sets the lower four bytes of the computational real-time clock.
TO The part of the FOR statement that precedes the loop limit.
TOP A pseudo-variable which returns the value of the first free location after the end of the current text.
TRACE A statement that displays line numbers as they are executed for debugging purposes. TRACE ON causes the interpreter to print executed line numbers when it encounters them. TRACE X sets a limit on the size of line numbers which may be printed out:
only those less than X will appear. Thus a careful user with all subroutines at the end of the main program can stop traced output of subroutine calls. TRACE OFF turns TRACE off. Note that the interpreter does not execute line numbers very often:
Program TRACE output

10 FORZ = O TO 100
20 Q=Q*Z:NEXT [ 10] f 20] [ 30]
30 END

But things would be different were NEXT on line 25. Then TRACE output would be:
[ 10] [ 20] [ 25] [ 25] [ 25]
[ 25] [ 25] [ 25] [ 25] [ 25] …
[ 30]
TRUE A pseudo-variable having the value -1.
UNTIL A part of the REPEAT ... UNTIL loop. The statements inside the loop are executed until the expression following UNTIL yields TRUE.
USR A function allowing machine code to return a value directly for applications which do not require the facilities of CALL. USR calls the machine-code subroutine whose address is it's argument, with the processor’s A, X and Y registers and the C carry flag initialised as in CALL, and returns a 32 bit integer composed of PYXA (msb to lsb).
VAL A function which converts a character string representing a number into numeric form. If the argument does not represent a unary signed decimal constant, VAL returns 0.
VDU A statement which takes a list of numeric arguments and sends them to OSWRCH. The arguments are normally separated by commas, whereupon the least-significant byte of each is sent, but a semicolon will cause the two least-significant bytes to be sent. The bytes sent DO NOT contribute to the value of COUNT.
Examples:
VDU28,0,31,32,0:REM define window
VDU27,0;0;1280;1024;
VPOS Not implemented.
WIDTH A statement controlling the overall screen width for printing. The initial value is WIDTH 0 when the interpreter will not attempt to control the overall field width. WIDTH n will cause the interpreter to force a newline after n MOD 256 characters have been printed.

Next Chapter