BBC Microcomputer System

Technical Specification

































(c) Copyright BBC 1981

FINAL

The BBC Micro-computer





Outline specification of the
BASIC language interpreter






































© BBC 1981

Listed below are commands, statements and functions which form the 'common core'.

ABS
AND
ASC
ATN AUTO BEEP CALL CHAIN CHR$ CLEAR CLOSE# CLS COLOUR CONT COS
DATA DEF FN DELETE DIM
DRAW
ELSE
END
ERL
ERR
EXP
EXT#
FOR ... TO ...NEXT ... STEP GET
GOTO
GOSUB
GRAPHICS
IF ... THEN ... ELSE INKEY
INPUT
INPUT LINE INPUT# INSTR
INT LEFT$ LEN LET LIST LN
LOAD LOG LVAR MID$ MOVE NEW NEXT NOT
ON ERROR

ON X GOTO
ON X GOSUB
OPENIN#
OPENOUT#
OR
ORIGIN
PI
PLOT
POINT
POS
PRINT
PRINT#
PTR#
RANDOMIZE
READ
REM
RENUMBER
RESTORE
RESUME
RETUNR
RIGHT$
RND
RUN
SAVE
SGN
SIN
SPC
SQR
STEP
STOP
STR$
STRING$
TAB
TAN
THEN
TO
TRACE
USR
VAL
WIDTH
XOR

Extensions.
These extensions should be avoided in simple programs that are intended to be used on a variety of machines.
ACS
ADC
ASN BGET# BPUT# COUNT DEF PROC DEG ENDPROC EVAL FALSE HIMEM HTN
INKEY LOCAL LOMEM MOD
OLD
PAGE
RAD
REPEAT ... UNTIL REPORT
TIME
TOP
TRUE
VPOS
WHILE ... ENDWHILE

This document provides an outline of the facilities offered by the BASIC interpreter. Other documents will provide details of other aspects of the total system.

The BASIC interpreter works through one of three file systems: a cassette file system, a disk file system and a network file system. The user can easily move between file systems and can pass complicated commands direct to the file system while in BASIC or any other language or environment.

The BASIC interpreter will contain an assembler as in the ATOM computer except that different characters will be used for hexadecimal notation and for 'immediate'. A screen editor is incorporated.

Variables:
Variable names may be of unlimited length and all characters are significant. Variable names must start with a letter. They can only contain the characters A..Z, a..z, 0..9 and underline. Embedded keywords are allowed. Upper and lower case variables of the same name are different. The following types of variables are allowed:
A	real numeric
A%	integer numeric
A$	string
FNA	numeric function
FN$A	string function
PROCA	procedure

The variables A%..Z% are regarded as special in that they are not cleared by the commands or statements RUN, CHAIN and CLEAR. In addition A%, X% and Y% have special functions in CALL and USR routines.

The variables A%..Z% are called 'static variables'. All other varaibles are called 'dynamic variables'

Real variables have a range of +-10^38 and functions evaluate to 9 significant figure accuracy. Internally every real number is stored in 40 bits

Integer variables are stored in 32 bits and thus have a range of about +- 2000 million

String variables may contain up to 255 characters

All arrays must be dimensioned before use

All statements and functions can also be used as commands.

ABS
X=ABS(DEFICIT)
LENGTH=ABS(Xl-X2)
A function giving the absolute value of its argument.
ABS(4)=4
ABS(-4.6)=4.6


ACS
X=ACS(Y)
A function giving the arc cosine of its argument in radians.


ADC
X=ADC(INTENSITY)
A function which returns the last known value of analogue to digital channel N. The Analogue to Digital converter is cycled repeatedly and this function will therefore execute very quickly.


AND
X=9 AND Y
A binary operation which carries out the bitwise AND between its two arguments as 32 bit integers.
IF (X=9 AND Y=(O) THEN PRINT "hello"
logical AND as part of IF ... AND ... THEN ...


ASC
X=ASC(A$)
X=ASC("HELLO")
gives 72 the ASCII value of 'H'
A function returning the ASCII character value of the first character of the argument string. If the string is null then zero will be returned.


ASN
X=ASN(Y)
A function giving the arc sine of its argument in radians.


ATN
X=ATN(Y)
A function giving the arc tangent of its argument in radians.
AUTO
A command allowing the user to enter lines without first typing in the number of the line.
AUTO mode is left with <ESC> or with a line starting with EOT (ASCII code 4)
AUTO
automatically offers line numbers 10,20,30 Œ
AUTO 220
Offers 220,230,240, Œ


BEEP

BEEP X, Y 
BEEP QUAVER,MIDDLE_C
A statement causing a tone to be added to the BEEP queue for generation.
X=half-period, Y=duration.
Half-period between 1 and 65535 micro-seconds gives frequencies between 500 kHz and 7.6 Hz.
Duration is given in centi-seconds.
BGET#
BGET# N,X
A statement which gets a byte (X) from the file opened on channel number N.


BPUT#
BPUT# N,32
BPUT# STAFF_FILE,A/256
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.

CALL
CALL VIEW,J,K,L
CALL 12340,A$,M,J$
CALL &A43E,LENGTH,NAME$
A statement to call a piece of machine code.
The second example above calls the subroutine at location 12340 and passes the parameters to the subroutine. Parameters are passed in a "Parameter Block" the address of which is stored in a fixed location near the start of the BASIC interpreter. The number of parameters passed may be zero. On entry to the subroutine the Parameter Block contains the following values
Number of parameters - l byte
parameter type - 1 byte
parameter address - 2 bytes

parameter type	    ] repeated as often
parameter address ] as needed

The parameters are variable parameters and will be changed on execution of the subroutine.

Parameter types:
   0 - 8 bit byte
   1 - 32 bit integer variable (e.g. S%=5432)
   2 - 40 bit floating point number (e.g V=1234.567)
 128 - A string at a defined address
>128 - A string varaible such as A$
In the case of a string the parameter address is the address of a String Information Block which gives the the adaress of the string etc.
The processors A,X,Y registers are initialised to the least significant bytes of the integer variables A%, X%, Y%. See also USR.


CHAIN
CHAIN ”GAME1"
CHAIN A$
A statement which will load and run the program whose name is specified in the argument.
All variables except A% to Z% are cleared.

CHR$
A$=CHR$(72)
returns A$ = 'H'
A string function whose value is a string of length 1 containing the ASCII character specified by the least significant byte of the numeric argument.


CLEAR
A statement which clears all variables to zero (except A%..Z%) ano empties all strings.


CLOSE#
CLOSE# N
CLOSE# 0
A statement used to CLOSE a sequential file.
CLOSE# 0 will CLOSE all sequential files.


CLS
CLS
Clears the screen to the current background move the text cursor to top left (0,0) and the graphics pointer and origin to bottom left (0,0)


COLOUR
COLOUR 3
COLOUR N
A statement setting the current foreground colour mode for the "soft" displays. (See GRAPHICS for description of soft displays). All lines and characters for these displays will will be set in this colour.
All lines and characters for these displays will be set in this colour.

black
1	red
2	green
3	yellow
4	blue
5	magenta
6	cyan
7	white
8	flashing black
9	flashing red
10	flashing green
11	flashing yellow
12	flashing blue
13	flashing magenta
14	flashing cyan
15 flashing white

These colours are as defined for Viewdata and give


a correct grey scale on monochrome displays. This statement will be expanded to control other facilities.


CONT
A command used to restart execution after a break caused either by the word STOP or by pressing the <ESC> key. No program changes are allowed. A program cannot CONT into the body of a FOR ... NEXT loop, a REPEAT ... UNTIL loop, a WHILE ... ENDWHILE loop, a function or a procedure.


COS
X=COS(Y)
A function giving the cosine of its radian argument.


COUNT
A=COUNT
A function returning the number of characters printed since the last new line. See also POS
DATA
DATA 10,2,HELLO,"THIS IS A COMMA,"
DATA " LEADING SPACES"
String data not enclosed in quotes must not contain embedded keywords. The keyword DATA must be at the start of a line, not even preceded by spaces.


DEG
X=DEG(PI /2)
A function which converts radians to degrees.


DEF
DEF FNMEAN
DEF PROChello
A program object which must precede declaration of a user function FN.
The keyword DEF must be at the start of a line not even preceded by spaces.


DELETE
DELETE 100,150
lines 100 to 150 inclusive
DELETE 4000,32767
lines 4000 to end of program
DELETE 0,120
lines from start of program to 120.


DIM
DIM X(12)
An array of 13 elements
DIM CUSTOMER$ (3, 2)
A four by three string array
A statement which dimensions arrays. Arrays must be predeclared before use. After dimensioning all elements of arrays are zero or null strings.


DRAW
DRAW X, Y
Draw a line to X,Y in the current foreground colour.
DRAW X,Y is equivalent to PLOT 5,X,Y.


END
Optional end of program may occur anywhere and as often as is required.


ENDPROC
Part of the DEF PROC ... ENDPROC structure.


ENDWHILE
Part of the WHILE ... ENDWHILE structure.


ELSE
IF A=B THEN C=D ELSE PRINT "We've got this one right!" 
Part of the IF..THEN..ELSE structure.

ERL
X=ERL
A function returning the line number of the line where the last error occurred.


ERR
X=ERR
Returns the error number of the last error which occurred.


EVAL
X=EVAL (A$)
A function which applies the interpreter's expression evaluation program to the characters held in the argument string.
An easy way to pass a function into a program from a user input.


EXP
Y=EXP(Z)
A function returning e to the power of its argument.


EXT#
L=EXT# N
A function which returns the length, in bytes, of the file opened on channel N.


FALSE
PRINT FALSE
would print 0.
A function returning 0.


FN
DEF FNMEAN(A,B,C)= (A+B+C)/3
A reserved word used at the start of all user defined string functions.

DEF FN$
A reserved word used at the start of all user defined procedures.
DEF FN$REV(A$) LOCAL B$,Z
B$= ""
FOR Z=1 TO LEN(A$): B$=MID$(A$,Z,1)+B$: NEXT =B$
The function is terminated and assigned a value by finding an = sign after a statement delimiter.


FOR
FOR X=1 TO 16 STEP 0.3: PRINT X: NEXT X
FOR A%=0 TO MAXIMUM_LENGTH
FOR TEMPERATURE=O TO 9
A statement initialising a FOR ... NEXT loop. Always executes at least once
Any numeric assignable item may be used as the control variable. Integer control variables are much faster than real variables.


GET
X=GET
will wait for a character from the current input stream and return the ASCII value. The input stream may or may not be the keyboard. See also INKEY.
A$=GET$
will wait for the next character from the current input stream and return it in A$.


GOTO
GOTO 100
GOTO X


GOS UB
GOSUB 400
GOSUB 4*ANSWER+6

GRAPHICS
GRAPHICS 1
GRAPHICS Mode,colour
A statement which clears the screen and initiates operation in the specified graphics mode, Mode, in the range 0-7 and with optional coloured background, colour, in the range 0-15.

0.	640x256 2 colour graphics and 80x32 text	(20K)
1.	320x256 4 colour graphics and 40x32 text	(20K)
2.	160x256 16 colour graphics and 20x32 text	(20K)
3.	80x 25  2 colour text	(16K)
4.	320x256 2 colour graphics and 40x32 text	(10K)
5.	160x256 4 colour graphics and 20x32 text	(10K)
6.	40x 25  2 colour text	( 8K)
7.	40x 25  teletext	( 1K)

Graphics modes 0 to 3 will not be available on the unexpanded machine since they require more than 16K of memory.
Graphics modes 0 to 6 are referred to as SOFT displays since in these modes the character set is entirely user defined.

For text characters the origin (0,0) is at the top left of the screen. The screen is 40 or 80 characters wide and 25 or 32 lines high.

For graphics commands the origin is at the bottom left. Regardless of the graphics mode the screen is addressed as 640 horizontal points and 512 vertical points. Internal scaling is applied to suit the selected graphics mode.


HIMEM
HIMEM = HIMEM-40
HIMEM contains the address of the first free byte that BASIC does not use. This cannot be used inside a FOR ... NEXT, REPEAT ... UNTIL, WHILE ... ENDWHILE structure, a function or a procedure. The user is cautioned to use this facility with care!.

 HTN
X=HTN (Y)
A function which returns the hyperbolic tangent of its argument.


IF
IF X=5 THEN Y=6:Z=8 ELSE PRINT "STRUCTURED BASIC"
IF X>5 GOTO 100
IF LENGTH=5 THEN 2000
IF A=1 PRINT "HELLO".


INKEY
X=INKEY(0)
tests the keyboard to see if a key is pressed. The function returns -1 if no key is pressed, or the ASCII value of the key pressed.
X=INKEY (100)
Waits for up to 100 centi-seconds for a key to be pressed. If a key is pressed during this time then the functions returns immediately with a number representing the ASCII value of the key pressed. If no key is pressed in the specified time then the function returns zero.
X$=INKEY$
returns a null string if no key is pressed or a single character string if a key has been pressed.
X$=INKEY$ (100 )
as for	X=INKEY (100 )


INPUT
INPUT X,Y,Z
default input is from keyboard
INPUT "length of rod";X
Prints the prompt 'length of rod' on the screen and then waits for a valid numeric reply.
INPUT "length of rod",X
Prints the prompt 'length of rod?' on the screen and then waits for a valid numeric reply.
INPUT strips leading spaces off strings.
An invalid reply produces a standard error message and then issues a question mark. This condition can be trapped with ON ERROR GOTO.

INPUT LINE
INPUT LINE A$
accepts the whole of the INPUT including commas, inverted commas and leading spaces.


INPUT#
INPUT# N,X,Y,A$,Z
A statement which reads data in internal format from a file and places the data in the stated variables.


INSTR
X=INSTR(A$,B$)
The position of B$ in A$
Y=INSTR(A$,B$,Z)
start search at position Z. Returns 0 if not found.


INT
X=INT(Y)
INT(99.8)=99
INT(-12.1) =-13
INT is a function truncating a real number to the lower integer.
LEFT$
A$=LEFT$(B$,3)
gives the LEFT 3 characters of B$.


LEN
size=LEN("HELLO")
would give size=5, the length of the word "HELLO" X=LEN (A$ )


LET
Optional.


LIST
LIST
List the complete program
LIST 10
Lists line 10 only
LIST	10,40
Lists lines 10 to 40.
LIST	100,
Lists from line 100 to the end of the porgram.


LN
X=LN (Y)
A function giving the natural log of Y.


LOAD
LOAD "PROG1" LOAD A$
This command loads internal format files from the current file system.


LOCAL
LOCAL A$,X,Y%
Declares variables for local use. May be used in functions and procedures.


LOG
X = LOG (Y)
A function giving the LOG to base 10 of Y.


LOMEM
LOMEM = LOMEM+100
LOMEM gives the first location in memory above which all dynamic variables are stored. The default is TOP - the first free address after the end of the user program. Moving LOMEM causes loss of all dynamic variables.
This must not be used inside a FOR ... NEXT, REPEAT ... UNTIL, WHILE ... ENDWHILE structure, a function or a procedure.


LVAR
Lists all variables and their current values (except arrays).


MID$
C$=MID$(A$,4,3)
takes the fourth, fifth and sixth letters from A$ into C$.

MOD
X=A% MOD B%
A binary operation giving the binary unsigned remainder of an integer division.


MOVE
MOVE X,Y
move the graphics pointer to X,Y.
Equivalent to PLOT 4,X,Y.


NEW
Erases the current program.
The program may be recovered with OLD.


NEXT
Part of the FOR ... NEXT structure.


NOT
IF NOT (RATE>5 AND TIME<100) THEN ...


OLD
recovers the file deleted by NEW.


ON
ON ERROR GOTO 100
Suppresses error messages and passes control to line 100
ON ERROR END
turns off user handling of error conditions.
ON X GOTO 100,120,130 ELSE PRINT "HELP":GOTO 100
notice the ELSE option.
ON Y GOSUB 100,200,300 ELSE GOTO 9000.


OPENIN#
X=OPENIN#("DATAFIL")
A function which returns the channel number allocated to the file. The file is opened for input and updating (random access). If the file does not exist then 0 is returned.

OPENOUT#
X=OPENOUT#(A$)
C=OPENOUT#("DATAFILE")
A function which returns the channel number of the file which is to be opened for output.


OR
X=7 OR Y
Bitwise logical OR
IF (X=9 OR Y=10) THEN PRINT "HELLO"
Logical bitwise OR between the two arguments.


ORIGIN
ORIGIN X,Y
Moves the effective origin of all graphics commands to X,Y.


PAGE
PAGE=6
PAGE=PAGE+2
The starting 'page' of the current program where 'page' refers to 256 bytes.
Programs always start on a 'page' boundary and the '2' in the above example refers to 2 'pages' of 256 bytes.


PI
X=PI
assign X the value 3.14159265.
Yes 9 significant figures.

PLOT
PLOT K,X,Y
plots to the point at X,Y with the attribute K. The effect of each value of K will be:

0	move	relative to last point
1	draw	line relative in foreground colour
2	draw	line relative in complemetary colour to present
3	draw	line relative in background colour
4	move	to absolute position
5	draw	line absolute in foreground colour
6	draw	line absolute in complementary colour
7	draw	line absolute in background colour
8	move	relative
9	plot	point relative in foreground colour
10	plot	point relative in complementary colour
11	plot	point relative in background colour
12	move	absolute
13	plot	point absolute in foreground colour
14	plot	point absolute in complementary colour
15	plot	point absolute in background colour

is is easy to plot strings starting
 at a specific location.


POINT
X=POINT(X,Y)
returns the colour of point X,Y on the screen, or -1 if the point is off the screen.


POS
X= POS
the horizontal position of the cursor. The left position is 0 and the right position is 39 or 79

PRINT
PRINT A$,N;C$
PRINT "HELLO";Y$,"GOODBYE";X$ PRINT 1'2;3
PRINT X Y A$ 'B$
The position of each printed item is determined by the punctuation used to separate the items in the list. A comma causes the next numeric value to be printed right hand justified in the next zone. A semicolon causes the next value to follow the previous one with no extra spaces. Typing one or more spaces between expressions has the same effect as typing a comma.

If a semicolon terminates the print list then the next PRINT statement will begin printing on the same line. An apostrophe in the print list forces a new line at that point. If the print list terminates without a semicolon, then a carriage return is printed at the end of the line.

Numbers are printed right justified in each zone. Negative numbers start with a - sign. Numbers less that 1 will be printed with a zero before the decimal point. Real numbers that are integers will be printed as integers.


PRINT#
PRINT# N,A,B,A$
writes data in internal format to the file opened as channel N. All numerics are written as 5 bytes and all strings as the bytes in the string plus <CR>.


PROC
A reserved word used at the start of all user defined procedures, which may then be called by name. Any number of parameters, including zero, may be passed. The parameters are variable parameters. The procedure does not have to be declared before it is called.
DEF PROChello(X)
LOCAL Z
FOR Z=0 TO X
PRINT "Hello - how about this for BASIC!"
NEXT Z
ENDPROC

PTR#
PTR# (N) =20
PTR#(COSTFILE)=PTR#(COSTFILE)+30
PTR# moves a byte pointer to a file opened on channel COSTFILE and thus enables random access.


RAD
X=RAD (Y)
converts Y degrees to X radians.


RANDOMIZE
Reinitializes the random number generator.


READ
READ C,D,A$
used in conjunction with DATA.


REM
Remark.


RENUMBER
RENUMBER
renumbers starting with line 10 and an increment of 10
RENUMBER 1000
renumbers starting with line 1000 and incrementing by 10
RENUMBER 1000,5
as above but with an increment of 5.


REPEAT
REPEAT
X =X +10
PRINT "Hello Roy, what do you think of it so far?"
UNTIL X>45


REPORT
Prints the error message associated with the last error.


RESTORE
RESTORE
RESTORE 100
RESTORE 5*ITEM_TYPE
resets the DATA pointer to the specified line.


RESUME
RESUME
is used after ON ERROR GOTO to retry the line which caused the error. This cannot be used inside a FOR ... NEXT, REPEAT ... UNTIL, WHILE ... ENDWHILE structure, a function or a procedure. An alternative exit would be with GOTO.


RETURN
Used after GOSUB.
RIGHT$
A$=RIGHT$(B$,4)
the rightmost four characters of B$ are returned.


RND
X=RN D
Get the next random number in the range 0-0.9999
X=RND (0 )
Get the last random number again
X=RND (-1 )
Resets the random number generator
X=RND (1)
Behaves like X=RND
X =RND (6 )
Gets a random integer in the range 1-6.
X %=RND
Gets a random 32 bit integer value.


RUN
Sets all dynamic variables to zero and starts execution of the program.

SAVE
SAVE "FRED" SAVE A$
Saves the program on the current file system.


SGN
X = SGN(Y)
returns -1 for a negative number
0 for zero
+1 for a positive number.


SIN
X = SIN (Y)
The sin of Y.


SPC
PRINT DATE;SPC(6);SALARY
Insert 6 extra spaces between A and B
Only works on INPUT and PRINT.


SQR
X = SQR(Y)
The square root of Y.


STEP
Used with FOR ... NEXT.


STOP
Stops execution of the program and prints
STOP AT LINE 100.


STR$
A$=STR$(X)
produces a string representing the number X.


STRING$
A$=STRING$(10,•-*-”)
C$=STRING$(5,"END")
B$=STRING$(N,S$)
produces a concatenation of N copies of S$.

TAB
PRINT TAB(10);A$
prints spaces to move to position 10. If the cursor is beyond the position requested then a new line will be issued and the cursor will then move to the correct column (as per ANSI). The left position is 0.
PRINT TAB(X,Y);B$
move directly to X,Y and then print B$. This will not work with a printer.
0,0 is at top left of the screen.


TAN
X= TAN(Y)
The tangent of Y.


THEN
Part of IF ... THEN ... ELSE.


TIME
X=TIME
TIME=100
The elapsed time in centi-seconds.


TO
Used in FOR ... TO ... STEP.


TOP
PRINT TOP
The first free location after the end of the current program. Thus the length of the program is given by TOP-PAGE *256 .


TRACE
TRACE ON
turns TRACE on
TRACE OFF
turns TRACE off
TRACE N
Trace N (1-32767) lines of BASIC prog.

TRUE
PRINT TRUE
wou1d print -1.


UNTIL
Used in the REPEAT ... UNTIL structure.


USR
X=USR(LIFT_DOWN)
passes A%, X% and Y% in the A,X and Y registers and returns a 24 bit integer composed of registers Y,X and A (msb to lsb).


VAL
X=VAL(A$)
If A$ does not start with a space, a number, a plus or a minus sign, then zero is returned.


VPOS
X=VPOS
returns the vertical position of the cursor.
Line 0 is the top line on the display, line 24 or 31 is the bottom line.


WHILE
WHILE X>5:PRINT X:GOSUB 1000:ENDWHILE
It is not certain that this structure will be incorporated in the initial release but we hope to do so.


WIDTH
WIDTH=60
will cause a newline to be output when column 60 is reached.


XOR
J=5 XOR B
A binary operation which carries out the bitwise exclusive OR between its two arguments as 32 bit integers.


Operators and special symbols


+ - * / ^ ( )
< <= = >= <> 	these may also be used with strings
=			assignment
+			string concatenation
*			pass the command line to the operating system
[			start assembler code
]			end of assembler code
&			hexadecimal numbers
#			immediate value for assembler
?			8 bit indirection
!			32 bit indirection
;			stay on same line
:			multiple statement separator
			force new line in print statement
<CR>			enter line
<ESC>			interrupt BASIC program
”			string delimiter
,			delimiter
~			print value in hexadecimal


Precedence.


The following defines the overall order of precedence, items in one group will be executed in the order they are met.

1. 	unary minus NOT functions procedures () brackets indirection
2.	^
3.	* / MOD
4.	+ -

6.	AND
7.	OR
XOR