BBC BASIC for the Amstrad Colour Computers
(C) Copyright R.T.Russell 1986
This preliminary documentation accompanies the evaluation copy of Amstrad
BBC BASIC (Z80). It should be read in conjunction with the manual for the
Torch version of BBC BASIC (Z80), as only those features which differ
substantially from the Torch version are documented here. If you do not
have a manual for the Torch version this can be obtained from M-Tec (UK).
This version of BBC BASIC will run on the Amstrad CPC664 and CPC6128
machines, and also on the CPC464 if fitted with the optional disk drive.
It will not run on the PCW8256 and PCW8512 word processors. It runs under
CP/M 2.2 or CP/M Plus and is supplied on a 3" compact diskette.
To enter CP/M insert a suitable CP/M System disk and type:
To run BBC BASIC insert the enclosed disk (or a copy) and type:
After a couple of seconds the system will reply:
Amstrad BBC BASIC Version 2.30
(C) Copyright R.T.Russell 1986
2. Memory utilisation
BBC BASIC requires about 17K of code space and 3K of private RAM. When
run under CP/M 2.2 (e.g. on the CPC464 or CPC664) PAGE is set by default
to &5000 and HIMEM is set to &9F00, giving nearly 20K of user RAM for
program, variables and stack. If characters 128-255 are neither defined
nor used by the BASIC program to be run, PAGE may be lowered to &4C00
giving an extra 1K of user RAM; however this is not recommended.
When run under CP/M Plus (i.e. on the CPC6128) PAGE is set to &4800 and
HIMEM to &EE00, giving 41.5K of user RAM. PAGE must not be lowered by
Note that use of *EXEC and *SPOOL irreversibly lowers HIMEM to make room
for the appropriate file control block. As this space is not returned
when the *EXEC or *SPOOL file is finished with, these facilities should
be used sparingly if excessive loss of memory space is to be avoided. If
required, PAGE and HIMEM can be re-initialised by restarting the BASIC
3. Commands, statements and functions
The syntax of BASIC commands, statements and functions is in most cases
identical to that of the Torch version (2.3). The few differences are
The Amstrad machines do not have a true analogue input, instead they
support simple contact-closure style joysticks. ADVAL with a zero or
positive argument returns a 16-bit integer corresponding to the state of
these joysticks as follows:
Bit 13: Joystick 0 fire button 1
Bit 12: Joystick 0 fire button 2
Bit 11: Joystick 0 right
Bit 10: Joystick 0 left
Bit 9: Joystick 0 down
Bit 8: Joystick 0 up
Bit 5: Joystick 1 fire button 1
Bit 4: Joystick 1 fire button 2
Bit 3: Joystick 1 right
Bit 2: Joystick 1 left
Bit 1: Joystick 1 down
Bit 0: Joystick 1 up
ADVAL with a negative argument returns the number of free spaces in the
sound buffers as follows:
ADVAL(-6) Sound channel 1
ADVAL(-7) Sound channel 2
ADVAL(-8) Sound channel 3
This command has a special function when addresses in the range &FF00 to
&FFFF are used. See the section on Operating System Interface for
This does not move the graphics cursor to (0,0), contrary to the
information given in the Torch manual.
A single-line editor is provided. The following control functions are
LEFT move the cursor one character position to the left
RIGHT move the cursor one character position to the right
UP move the cursor up one line, or to the start of the line
DOWN move the cursor down one line, or to the end of the line
CTRL/LEFT move the cursor to the start of the line
CTRL/RIGHT move the cursor to the end of the line
CLR delete the character at the current cursor position
DEL backspace and delete the character to the left of the cursor
CTRL/U delete all characters to the left of the cursor
CTRL/X delete all characters from the cursor to the end of the line
Note that the COPY key is active at all times, as when running Amstrad
BASIC. SHIFT with the cursor keys moves the copy (read) cursor.
This statement is implemented as far as possible to be compatible with
the BBC Micro. However, although the hardware sound capabilities of the
machines are similar the Operating System support is somewhat different.
There are therefore differences in the detailed operation of the ENVELOPE
statement. In particular there is no "release" section of the amplitude
envelope and the pitch envelope may not give identical results. The most
important effect is that no sound is produced beyond the duration
specified in the SOUND statement, whereas on the BBC Micro the sound
continues indefinitely depending on the specification of the release
phase of the amplitude envelope.
Envelope numbers may be in the range 1 to 15.
The key codes used in conjunction with the INKEY function with a negative
argument (test a specific key) are those given in the Amstrad User
Instructions (e.g. Chapter 7 Page 23 of the CPC6128 manual). For
example, INKEY(-47) tests whether the SPACE bar is depressed.
When using the (default) VDU emulator (*OPT 0), LISTing may be paused by
holding down the CTRL and SHIFT keys together. "Paged" mode may also be
entered by typing CTRL/N (VDU 14) whereupon the screen will wait at the
end of each page until a SHIFT key is pressed. Paged mode is turned off
by typing CTRL/O (VDU 15).
Beware: Pressing ESC whilst pausing a listing with CTRL and SHIFT will
reset the computer!
The available display modes are as follows:
Mode Graphics Text Colours
0 640 x 200 80 x 25 2
1 320 x 200 40 x 25 4
2 160 x 200 20 x 25 16
3 640 x 200 80 x 25 2
4 320 x 200 40 x 25 4
5 160 x 200 20 x 25 16
6 320 x 200 40 x 25 4
7 320 x 200 40 x 25 4
Modes 0 & 3 are identical, as are modes 1, 4, 6 & 7 and modes 2 & 5. No
attempt is made to emulate the BBC Micro's Teletext mode (MODE 7). In
this respect the Amstrad machines behave more like the Acorn Electron.
A MODE change does not switch off paged mode (VDU 14).
The range of coordinates corresponding to positions on the screen is 0 to
1279 in the x-direction and 0 to 799 in the y-direction.
The range of coordinates corresponding to positions on the screen is 0 to
1279 in the x-direction and 0 to 799 in the y-direction.
The following PLOT codes are implemented:
PLOT 0 Move to a position relative to the last point.
PLOT 1 Draw line relative in graphics foreground colour.
PLOT 2 Draw line relative in logical inverse colour.
PLOT 3 Draw line relative in graphics background colour.
PLOT 4 Move to an absolute position.
PLOT 5 Draw line absolute in graphics foreground colour.
PLOT 6 Draw line absolute in logical inverse colour.
PLOT 7 Draw line absolute in graphics background colour.
PLOT 8-15 As PLOT 0-7 except that the last point is plotted twice.
PLOT 16-63 These codes are NOT IMPLEMENTED.
PLOT 64-71 As PLOT 0-7 but only a single point is plotted.
PLOT 72-79 These codes are NOT IMPLEMENTED.
PLOT 80-87 Plot and fill a triangle formed by the specfied position and
the last two points visited.
PLOT 88-95 These codes are NOT IMPLEMENTED.
Although the sound generator has a "noise" capability, it has not been
possible within the constraints of the Amstrad Operating System to
implement this in a way compatible with the BBC Micro's SOUND statement.
Consequently the use of channel zero has no effect.
The four parameters behave as follows:
Only bits 0, 1 & 4 have any effect. Bits 0 & 1 are the channel number (1-
3). If bit 4 is set, the sound queue is flushed and the new sound is
Values from -15 to -1 select a sound of amplitude 15 to 1 respectively
with constant pitch, zero selects silence and values from 1 to 15 select
an envelope (see ENVELOPE statement).
This selects the (initial) pitch as with the BBC Micro. The pitch can be
varied only in semitone increments, i.e. the least significant 2 bits are
ignored; Middle C is 52.
Values from 0 to 254 select the duration of the sound, in units of
approximately 1/20 second. The value -1 causes an indefinite sound, which
can be stopped only by issuing another SOUND statement with the "flush"
bit set or by pressing the ESCape key.
USR has a special function when addresses in the range &FF00 to &FFFF are
used. See the section on the OS Interface for details.
4. The Operating System Interface
The following resident Operating System ("star") commands are
implemented. They may be accessed directly (e.g. *BYE) or via the OSCLI
statement (OSCLI "BYE"). See the Torch manual for more details.
Returns control to CP/M.
This is synonymous with *BYE.
List the files which match the (optional) ambiguous filespec. If the
filespec is omitted, all .BBC files are listed. "Read only" files are
marked with an asterisk.
Select drive d as the default drive for subsequent disk operations.
Delete all files matching the ambiguous filespec.
*ESC OFF disables the abort action of the ESCape key; after *ESC OFF the
ESCape key simply returns the ASCII code ESC (27). *ESC ON, or *ESC,
restores the normal action of the ESCape key.
Accept console input from the specified file instead of from the
keyboard. If the extension is omitted, .BBC is assumed.
*KEY n [string]
Redefine a function key to return the specified string. The key number n
is from 0 to 31; note that key 10 is the full point (.) in the cursor
cluster, key 11 is the ENTER key and key 12 is CTRL/ENTER.
The string may contain the "escape" symbol | in order to insert non-
printing characters. For example, |M indicates CR (carriage return), !?
indicates DEL, || indicates the character | itself and |! causes bit 7 of
the following character to be set. If the string is enclosed in quotes
(which is optional) |" allows the character " to be included in the
If there is insufficient room for the string, the "Bad string" error will
occur and the key will be loaded with as much of the string as would fit.
*LOAD filespec aaaa
Loads the specfied file into memory at hexadecimal address aaaa. The load
address must be specified. If the extension is omitted, .BBC is assumed.
Set the specified file to "read-only" status. If the extension is
omitted, .BBC is assumed.
Select the destination for console output characters. The value n is in
the range 0 to 3, as follows:
0 Send characters to the VDU emulator (see later)
1 Send characters to the auxiliary output
2 Send characters to the printer output
3 Send characters to the standard console output
*OPT 0 is the default setting. Note that all characters sent to the
console output are vectored with *OPT, there is no filtering of graphics
commands etc. For example, the statement COLOUR 3 in a program will cause
the bytes 17 and 3 to be sent to the device selected by *OPT.
These commands rename oldfile as newfile. If the extension is omitted,
.BBC is assumed.
Resets the disk system. When used with CP/M 2.2 this command should be
issued after a disk is changed. This need not be done with CP/M Plus
(although it will do no harm).
*SAVE filespec aaaa bbbb
*SAVE filespec aaaa +llll
This command saves a specified range of memory to disk. The address range
is specified either as start address (aaaa) and end address +1 (bbbb) or
as start address (aaaa) and length (llll). If the extension is omitted,
.BBC is assumed.
Copy all subsequent console output to the specified file. If the filename
is omitted, any current spool file is closed and spooling is terminated.
If the extension is omitted, .BBC is assumed.
Type the specified file to the VDU screen. If the extension is omitted,
.BBC is assumed.
Set the specified file to "read/write" status. If the extension is
omitted, .BBC is assumed.
This is a comment line. Anything following the | is ignored.
In addition to the commands listed above, the OS Interface module
provides facilities for reading the character at the current text cursor
position and for reading the dot pattern of a given font character. These
are accessed by a USR or CALL to addresses &FFF4 and &FFF1 respectively:
The character at the current text cursor position is returned by:
(USR(&FFF4) AND &FF00) DIV 256
The dot pattern of a character can be read as follows:
DIM par 8
X%=par MOD 256:Y%=par DIV 256
where the character pattern will be returned in the eight bytes par?1 to
The reason for the rather "obscure" methods of accessing these functions
is to maintain maximum compatibility with the similar functions provided
on the BBC Microcomputer.
A user's machine code program may access the OSRDCH, OSWRCH, OSKEY and
OSCLI routines by using vectors provided in page 1:
OSRDCH: call &109 ;Waits for and returns character in A
OSWRCH: call &10C ;Sends character in A to VDU drivers
OSKEY: call &10F ;Time limit in HL, returns character
;in A, carry=0 if timeout occured
OSCLI: call &112 ;HL addresses command, terminated by CR
5. The VDU emulator
In the default state (*OPT 0) all console output is passed to a software
emulator of the BBC Micro's VDU drivers. VDU codes perform a function as
similar as possible to those of the BBC Micro, consistent with the
hardware and Operating System differences, as follows:
The following byte is sent to the printer, if enabled (with VDU 2). If
the printer is not enabled, the byte is ditched. Any 8-bit value (0-255)
can be sent. This works even when the VDU is disabled with VDU 21.
Enable the printer. Subsequent characters are sent both to the screen and
to the printer. The only control characters sent to the printer are BS
(8), HT (9), LF (10), VT (11), FF (12) and CR (13). Bytes which are
parameters for VDU commands are not sent to the printer, e.g. VDU 17,65
does not send "A" to the printer.
Disables the printer. Cancels the effect of VDU 2.
Causes text to be written at the text cursor position in the normal way.
Characters are "opaque" and can be positioned only at text coordinates
within the text window. The text window scrolls when necessary.
Causes text to be written at the graphics cursor position. Characters
have a "transparent" background and are plotted according to the current
foreground GCOL rules and colour (VDU 127, DEL, is an exception).
Characters can be positioned at any graphics coordinate within the
graphics window, the top left of the character cell is the reference
point; characters are NOT clipped to the window limits (this is a
limitation of the Amstrad Operating System). No scrolling takes place.
Enables the VDU screen. Cancels the effect of VDU 21.
Causes a "beep".
Moves the text cursor left one character. If it was at the left edge of
the window, it is wrapped to the end of the previous line (RH edge of
window). If it was also on the top line of the text window, the window
scrolls down (except when in VDU 5 mode).
Moves the text cursor right one character. If it was at the right hand
edge of the window, it is wrapped to the beginning of the next line (LH
edge of window). If it was also on the bottom line of the text window,
the window scrolls up (except when in VDU 5 mode).
Moves the text cursor down one line. If it was on the bottom line of the
text window, the window scrolls up (except when in VDU 5 mode). Scrolling
is inhibited if CTRL & SHIFT are both held down.
Moves the text cursor up one line. If it was on the top line of the text
window, the window scrolls down (except when in VDU 5 mode).
This is identical to CLS in BASIC. It clears the text window to the
current text background colour and moves the text cursor to the top-left
corner of the text window.
Moves the text cursor to the left-hand edge of the window, but does not
move it vertically.
Enter paged mode. Scrolling will stop after each page, unless SHIFT is
Stop paging. Cancels the effect of VDU 14.
This is identical to CLG in BASIC. It clears the graphics window using
the current background GCOL action and colour. It does not move the
This is identical to COLOUR n in BASIC. The next byte determines the text
colour, see COLOUR for details.
This is identical to GCOL a,c in BASIC. The next two bytes determine the
GCOL action and colour respectively.
Change the palette to select logical colour L as physical colour p. This
command works in a compatible fashion to the BBC Micro but has been
extended to give access to the Amstrad's enhanced facilities as follows:
Select physical colour p as the border colour.
Select logical colour L as alternating between Amstrad colour x and
Amstrad colour y.
Select the border colour to alternate between Amstrad colour x and
Amstrad colour y.
The physical colour p is mapped to the BBC Micro's physical colours (0-
15). The Amstrad colours x and y correspond to the 27 colours available
from the Amstrad machines.
Sets text and graphics colours to their default values (background black,
foreground white) and resets the palette. In 4-colour modes set the
colours to black, red, yellow and white.
Disable VDU output. All VDU commands except 1 and 6 are ignored. If the
printer is enabled, VDUs 8,9,10,11,12 and 13 will still be sent to the
This is identical to MODE n in BASIC, except that MODE zeros the value of
COUNT whereas VDU 22 does not. VDU 22 also resets all screen driver
variables (colours, palette, windows, cursor positions, graphics origin
etc.). In particular, VDU 22 performs the actions of VDU 4, VDU 12, VDU
20 and VDU 26. See MODE for further details.
Program user-defined graphics characters, enable/disable cursor or write
to 6845 CRT controller registers:
VDU 23,n,r1,r2,r3,r4,r5,r6,r7,r8 program character n (32-255)
VDU 23,1,0;0;0;0; disable cursor
VDU 23,1,1;0;0;0; enable cursor
VDU 23,0,r,x,0;0;0; write x to 6845 register r
Define graphics window. The coordinates are with respect to the current
graphics origin, so users are recommended to precede VDU 24 with VDU 26
to reset the origin first. The coordinates are not checked for valid
This is identical to PLOT n,x;y; in BASIC. See PLOT for more details.
Reset text and graphics windows to their default positions (filling the
whole screen), home text cursor, move graphics cursor to 0,0 and reset
the graphics origin to 0,0.
Send the next byte to the screen without interpreting it as a control
code. Allows graphics characters corresponding to VDU 0-31 and VDU 127 to
be displayed. Acts in a similar way to VDU 1 for the printer.
Set a text window. The text cursor is moved to the new home position.
Move the graphics origin to the specified coordinates.
Home the text cursor, to the top-left hand corner of the text window (or
the graphics window, when in VDU 5 mode).
Identical to PRINT TAB(x,y); in BASIC. Positions the text cursor
according to the next two bytes. The coordinates are with respect to the
edges of the current text window.
Backspace the cursor by one position and delete the character there. In
VDU 5 mode the character is "deleted" by writing character 143 (a solid
block) in the current graphics background colour and action.
6. Finally, a reminder that the ~ character (used with PRINT and STR$ to
give hexadecimal numbers) can be obtained by pressing CTRL/2.
R. T. Russell.
2nd April 1986.
Manual n° 3
This is version 2.30 of BBCBASIC(Z80) for the Amstrad Colour Computers
(CPC464, CPC664 and CPC6128). The files supplied are as follows:
BBCBASIC.COM The BBC BASIC (Z80) interpreter for Amstrad machines.
BBCBASIC.TXT A plain text documentation file for BBC BASIC (Z80).
CONVERT.COM A utility for converting .BBC files to/from .BAS files.
CRC.COM A program to test the integrity of the supplied files.
UNLIST.COM A utility which makes a BBC BASIC program unlistable.
CRCKLIST.CRC The data file for CRC.COM.
MERGE.BBC A BBC BASIC program for merging program files.
SORT.BBC A program using assembler code for a fast string sort.
SORTREAL.BBC A program using assembler code for a fast numeric sort.
F-????.BBC A set of example programs illustrating file input/output.
ANIMAL.BBC An example of a 'learning' program written in BBC BASIC.
ANIMAL.DAT The initial data file for ANIMAL.BBC
READ.ME This file!
To exit BBC BASIC (Z80) type *BYE
The Amstrad CP/M version of BBC BASIC (Z80) is made available for free
download on the condition that it always be distributed with the above
files. BBCBASIC (Z80) and the accompanying files remain the Copyright
(C) of R. T. Russell, 1982-2000.
Richard RUSSELL, 8th August 2000.
Email: email@example.com Web: http://www.rtrussell.co.uk/
Manual n° 4
AUTO Generate line numbers.
DELETE Delete program lines.
EDIT Edit a program line.
LIST List all or part of program.
LISTO Control indentation in LIST.
LOAD Load a program into memory.
NEW Delete current program & variables.
OLD Recover a program deleted by NEW.
RENUMBER Renumber the program lines.
SAVE Save the current program to disk.
CALL Call assembly language routine.
CHAIN Load and run a program.
CLEAR Clear dynamic variables.
CLS Clear the screen.
DEF Define a function.
DEF PROC Define a procedure.
DIM Dimension one or more arrays.
END Terminate program and close files.
ENDPROC Return from a procedure.
FOR Begin a FOR . . . NEXT loop.
GOSUB Call a Basic subroutine.
GOTO Branch to specified line.
IF..THEN Do statement(s) if exp non-zero.
LOCAL Declare variables local to procedure.
NEXT End FOR . . . NEXT loop.
ON..GOTO Computed GOTO.
ON..GOSUB Computed GOSUB.
ON ERROR Do statements) on error.
PROC Call a procedure.
REPEAT Begin a REPEAT . . . UNTIL loop.
REPORT Print error message for last error.
RESTORE Reset data pointer.
RETURN Return from subroutine.
RUN Run the current program.
STOP Stop program and print message.
TRACE ON Start trace mode.
TRACE OFF End trace mode.
UNTIL Terminate loop if exp is non-zero.
WIDTH Set terminal width.
BPUT Write LS byte of exp to disk file.
CLOSE Close disc file.
DATA Data for READ statement.
INPUT Request input from user.
INPUT LINE As INPUT but accept whole line.
INPUT# Read data from disk file.
OSCLI Pass string to "operating system".
PRINT Print data to console.
PRINT# Write data to disc file.
READ Read data from DATA statements).
VDU Send LS byte of exp to console.
ABS(exp) Absolute value of expression.
ACS(exp) Arc-cosine of expression, in radians.
ASN(exp) Arc-sine of expression, in radians.
ATN(exp) Arc-tangent of expression, in radians.
COS(exp) Cosine of radian expression.
DEG(exp) Value in degrees of radian expression.
EXP(exp) e raised to the power of expression.
INT(exp) Largest integer less than expression.
LN(exp) Natural logarithm of expression.
LOG(exp) Base-ten logarithm of expression.
PI Returns 3.14159265.
RAD(exp) Radian value of expression in degrees.
RND[(exp)l RND returns random 32-bit integer.
RND(-n) Seeds sequence.
RND(0) Repeats last value in RND(1) form.
RND(1) Returns number between 0 and 0.999999999
RND(n) Returns random integer between 1 and n.
SGN(exp) 1 if exp>0, 0 if exp=0, -1 if exp<0.
SIN(exp) Sine of radian expression.
SQR(exp) Square root of expression.
TAN(exp) Tangent of radian expression.
ASC(str) Returns ASCII value of first char of string.
CHR$(exp) Returns one-char ASCII string of exp.
EVAL(str) Evaluates str as an expression and returns resulting number or string.
GET Waits for keypress and returns ASCII value.
GET$ Waits for keypress and returns one-char string.
INKEY(exp) Waits exp centiseconds for keypress and returns Ascii value.
INKEY$(exp) Waits exp centiseconds for keypress and returns one-character string.
INSTR(r,s(,nl) Returns position of string s in string r, optionally starting at position n
LEFT$(str,exp) Returns leftmost exp characters of string.
LEN(str) Returns length of string (0-255).
MID$(str,m[,n]) Returns sub-string from position m, of length n or to end.
RIGHT$(str,exp) Returns rightmost exp characters of string.
STR$(exp) Returns string representation of exp in decimal (or hex).
STRING$(n,str) Returns a string consisting of n copies of str.
VAL(str) Returns numeric value of str.
BGET#chan Returns a single byte from a disc file.
COUNT Number of characters printed since last new line.
EOF#chan Returns TRUE if disc file is at its end.
ERL Line number of last error.
ERR Code of last error.
EXT#chan Returns virtual length of disk file.
FALSE Returns zero.
FNname User-defined numeric or string [(parameter list)] function.
GET(port) Returns contents of Z80 port.
OPENIN(str) Opens file for input/update and returns channel number.
OPENOUT(str) Opens file for output and returns channel number.
OPENUP(str) Same as OPENIN.
POS Returns current cursor column (LHS=0).
TOP Returns first address after end of user’s program.
USR(address) Calls machine-code routine and returns integer.
VPOS Returns current cursor line (top line=0).
PAGE Memory address of current user’s program.
PTR#chan File character pointer. Allows random access.
HIMEM Top of memory used by Basic.
LOMEM Start address of dynamic variable storage.
TIME Elapsed time clock, counts in