forked from MirrorRepos/RomWBW
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
455 lines
18 KiB
455 lines
18 KiB
This is a RomWBW HBIOS adaptation of BBCBASIC v5.00. The
|
|
cursor and screen management assumes the use of an ANSI/VT-100 terminal
|
|
which is generally correct for RomWBW. Support for a hardware system
|
|
timer is also implemented. If your system does not have a hardware
|
|
timer, the TIME function will always return 0 and the timeout
|
|
parameter of the INKEY(n) function will not be observed (will never
|
|
timeout).
|
|
|
|
What follows is some basic information on BBCBASIC from the
|
|
distribution. Note that it starts with the v3.00 information and
|
|
later on provides information on the changes in v5.00.
|
|
|
|
-- WBW 1:15 PM 5/30/2024
|
|
|
|
|
|
|
|
|
|
BBC BASIC (Z80)
|
|
|
|
Generic CP/M Version 3.00
|
|
|
|
(C) Copyright R.T.Russell 1982-1999
|
|
|
|
1. INTRODUCTION
|
|
|
|
BBC BASIC (Z80) has been designed to be as compatible as possible with
|
|
Version 4 of the 6502 BBC BASIC resident in the BBC Micro Master series.
|
|
The language syntax is not always identical to that of the 6502 version,
|
|
but in most cases the Z80 version is more tolerant.
|
|
|
|
BBC BASIC (Z80) is as machine independent as possible and, as supplied,
|
|
it will run on any CP/M 2.2 (or later) system using a Z80 processor
|
|
(checks are carried out to ensure that the processor is a Z80 and that
|
|
the version of CP/M is at least 2.2). It is minimally configured for an
|
|
ADM3a-compatible VDU.
|
|
|
|
Few CP/M systems offer colour graphics of the quality provided as
|
|
standard on the BBC Microcomputer, and no software can provide colour
|
|
high-resolution graphics from a monochrome character-orientated computer.
|
|
However, many CP/M system users are interested in the advanced program
|
|
structures available from BBC BASIC and, within the limitations of the
|
|
host computer, BBC BASIC (Z80) provides the programming structures and
|
|
the non-graphic commands and functions specified for BBC BASIC.
|
|
|
|
In order to make full use of the facilities available in BBC BASIC (Z80)
|
|
it is necessary to install a small patch to adapt it to the capabilities
|
|
of the host computer. The source code of the patch present in the
|
|
distribution version is supplied as BBCDIST.MAC.
|
|
|
|
This documentation should be read in conjunction with a standard BBC
|
|
BASIC manual. Only those features which differ from the standard Acorn
|
|
versions are documented here.
|
|
|
|
|
|
2. MEMORY UTILISATION
|
|
|
|
BBC BASIC (Z80) requires about 16 Kbytes of code space, resulting in a
|
|
value of PAGE of about &3E00. The remainder of the user memory is
|
|
available for BASIC programs, variables (heap) and stack. Depending on
|
|
the system configuration, HIMEM can have a value up to &FE00.
|
|
|
|
|
|
3. COMMANDS, STATEMENTS AND FUNCTIONS
|
|
|
|
The syntax of BASIC commands, statements and functions is in most cases
|
|
identical to that of the BBC Micro version (BASIC 4). The few
|
|
differences are documented here:
|
|
|
|
ADVAL
|
|
This function is not implemented.
|
|
|
|
CALL
|
|
CALL sets up a table in RAM containing details of the parameters; the
|
|
processor's IX register is set to the address of this parameter table.
|
|
The other processor registers are initialised as follows:
|
|
|
|
A is initialised to the least significant byte of A%
|
|
B is initialised to the least significant byte of B%
|
|
C is initialised to the least significant byte of C%
|
|
D is initialised to the least significant byte of D%
|
|
E is initialised to the least significant byte of E%
|
|
F is initialised to the least significant byte of F%
|
|
H is initialised to the least significant byte of H%
|
|
L is initialised to the least significant byte of L%
|
|
|
|
The parameter types are:
|
|
|
|
Code No. Parameter Type Example
|
|
0 Byte (8 bits) ?A%
|
|
4 Word (32 bits) !A% or A%
|
|
5 Real (40 bits) A
|
|
128 Fixed string $A%
|
|
129 Movable string A$
|
|
|
|
On entry to the subroutine the parameter table contains the following
|
|
values:
|
|
|
|
Number of parameters 1 byte (at IX)
|
|
|
|
Parameter type 1 byte (at IX+1)
|
|
Parameter address 2 bytes (at IX+2, IX+3, LSB first)
|
|
|
|
Parameter type ) repeated as often as necessary
|
|
Parameter address )
|
|
|
|
Except in the case of a movable string (normal string variable), the
|
|
parameter address given is the absolute address at which the item is
|
|
stored. In the case of movable strings (type 129) it is the address of a
|
|
4-byte parameter block containing the current length, the maximum length
|
|
and the start address of the string (LSB first) in that order.
|
|
|
|
Integer variables are stored in twos complement form with their least
|
|
significant byte first.
|
|
|
|
Fixed strings are stored as the characters of the string followed by a
|
|
carriage return (&0D).
|
|
|
|
Floating point variables are stored in binary floating point format with
|
|
their least significant byte first; the fifth byte is the exponent. The
|
|
mantissa is stored as a binary fraction in sign and magnitude format.
|
|
Bit 7 of the most significant byte is the sign bit and, for the purposes
|
|
of calculating the magnitude of the number, this bit is assumed to be set
|
|
to one. The exponent is stored as an integer in excess 127 format (to
|
|
find the exponent subtract 127 from the value in the fifth byte).
|
|
|
|
If the exponent byte of a floating point number is zero, the number is an
|
|
integer stored in integer format in the mantissa bytes. Thus an integer
|
|
can be represented in two different ways in a real variable. For example
|
|
the value +5 can be stored as:
|
|
|
|
05 00 00 00 00 Integer 5
|
|
00 00 00 20 82 (0.5 + 0.125) * 2^3
|
|
|
|
COLOUR (COLOR)
|
|
This statement is not implemented.
|
|
|
|
DRAW
|
|
This statement is not implemented.
|
|
|
|
EDIT
|
|
A command to edit or concatenate and edit the specified program line(s).
|
|
The specified lines (including their line numbers) are listed as a single
|
|
line. By changing only the line number you can use EDIT to duplicate a
|
|
line.
|
|
|
|
EDIT 230
|
|
EDIT 200,230
|
|
|
|
The following control functions are active both in the EDIT mode and in
|
|
the immediate entry mode (i.e. at the BASIC prompt):
|
|
|
|
Move the cursor one character position to the left
|
|
Move the cursor one character position to the right
|
|
Move the cursor to the start of the line
|
|
Move the cursor to the end of the line
|
|
Insert a space at the current cursor position
|
|
Delete the character at the current cursor position
|
|
Backspace and delete the character to the left of the cursor
|
|
Delete all characters to the left of the cursor
|
|
Delete all characters from the cursor to the end of the line
|
|
|
|
The choice of which keys activate these functions is made when BBC BASIC
|
|
is configured for a particular system. The distribution version uses ^H,
|
|
^I, ^K, ^J, ^A, ^E, DEL (&7F), ^L and ^X.
|
|
|
|
To exit EDIT mode and replace the edited line, type RETURN (ENTER).
|
|
|
|
To abort the edit and leave the line unchanged, type ESCape.
|
|
|
|
ENVELOPE
|
|
This statement is not implemented.
|
|
|
|
GET
|
|
This function waits for a character to be typed at the keyboard, and
|
|
returns the ASCII code.
|
|
|
|
GET can also be used to read data from a processor I/O port; full 16-bit
|
|
port addressing is available:
|
|
|
|
N% = GET(X%) : REM input from port X%
|
|
|
|
INKEY
|
|
This function waits for a specified maximum number of centiseconds for a
|
|
character to be typed at the keyboard. If no character is typed in that
|
|
time, the value -1 is returned. In the distribution version the delay is
|
|
determined by a simple software timing loop, and may be very inaccurate.
|
|
The customisation patch allows this to be adjusted to suit the system in
|
|
use.
|
|
|
|
INPUT#
|
|
The format of data files is different from that used by the BBC Micro, in
|
|
part to improve compatibility with standard CP/M files. Numeric values
|
|
are stored as five bytes in the format documented under CALL; if the
|
|
fifth byte is zero the value is an integer. Strings are stored as the
|
|
characters of the string (in the correct order!) followed by a carriage
|
|
return (&0D).
|
|
|
|
MODE
|
|
This statement is not implemented.
|
|
|
|
MOVE
|
|
This statement is not implemented.
|
|
|
|
PLOT
|
|
This statement is not implemented.
|
|
|
|
POINT
|
|
This function is not implemented.
|
|
|
|
PRINT#
|
|
The format of data files is different from that used by the BBC Micro, in
|
|
part to improve compatibility with standard CP/M files. Numeric values
|
|
are stored as five bytes in the format documented under CALL; if the
|
|
fifth byte is zero the value is an integer. Strings are stored as the
|
|
characters of the string (in the correct order!) followed by a carriage
|
|
return (&0D).
|
|
|
|
PUT
|
|
A statement to output data to a processor port. Full 16-bit addressing
|
|
is available.
|
|
|
|
PUT A%,N% : REM Output N% to port A%
|
|
|
|
SOUND
|
|
This statement is not implemented.
|
|
|
|
TIME
|
|
This pseudo-variable is not implemented in the distribution version, but
|
|
can be supported by means of the customisation patch. See BBCDIST.MAC.
|
|
|
|
USR
|
|
As with CALL, the processor's registers are initialised as follows:
|
|
|
|
A is initialised to the least significant byte of A%
|
|
B is initialised to the least significant byte of B%
|
|
C is initialised to the least significant byte of C%
|
|
D is initialised to the least significant byte of D%
|
|
E is initialised to the least significant byte of E%
|
|
F is initialised to the least significant byte of F%
|
|
H is initialised to the least significant byte of H%
|
|
L is initialised to the least significant byte of L%
|
|
|
|
USR returns a 32-bit integer result composed of the processor's H, L, H'
|
|
and L' registers, with H being the most significant.
|
|
|
|
|
|
4. RESIDENT Z80 ASSEMBLER
|
|
|
|
The in-line assembler is accessed in exactly the same way as the 6502
|
|
assembler in the BBC Micro version of BBC BASIC. That is, '[' enters
|
|
assembler mode and ']' exits assembler mode.
|
|
|
|
All standard Zilog mnemonics are accepted: ADD, ADC and SBC must be
|
|
followed by A or HL. For example, ADD A,C is accepted but ADD C is not.
|
|
However, the brackets around the port number in IN and OUT are optional.
|
|
Thus both OUT (5),A and OUT 5,A are accepted. The instruction IN F,(C)
|
|
is not accepted, but the equivalent code is produced from IN (HL),C
|
|
|
|
The pseudo-ops DEFB, DEFW and DEFM are included. DEFM works like EQUS in
|
|
the 6502 version.
|
|
|
|
|
|
5. 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").
|
|
|
|
Control characters, lower-case characters, DEL and quotation marks may be
|
|
incorporated in filenames by using the 'escape' character '|'. However,
|
|
there is no equivalent to the BBC Microcomputer's '|!' to set bit 7.
|
|
|
|
*BYE
|
|
Returns control to the operating system (CP/M).
|
|
|
|
*CPM
|
|
Same as *BYE.
|
|
|
|
*. [filespec]
|
|
*DIR [filespec]
|
|
List the files which match the (optional) ambiguous filespec. If the
|
|
filespec is omitted, all .BBC files are listed:
|
|
*DIR List all .BBC files on the disk
|
|
*DIR B:*.* List all files on disk B:
|
|
*.*.* List all files on the current disk
|
|
|
|
*DRIVE d:
|
|
Select drive d as the default drive for subsequent disk operations.
|
|
|
|
*ERA filespec
|
|
Erase (delete) the specified disk file or files. The extension defaults
|
|
to .BBC if omitted.
|
|
|
|
*ESC [ON|OFF]
|
|
*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.
|
|
|
|
*EXEC filespec
|
|
Accept console input from the specified file instead of from the
|
|
keyboard. If the extension is omitted, .BBC is assumed.
|
|
|
|
*LOAD filespec aaaa
|
|
Loads the specified file into memory at address aaaa. The load address
|
|
must be specified. If the extension is omitted, .BBC is assumed.
|
|
|
|
*OPT [n]
|
|
Select the destination for console output characters. The value n is in
|
|
the range 0 to 2, as follows:
|
|
|
|
0 Send characters to the console output
|
|
1 Send characters to the auxiliary output
|
|
2 Send characters to the printer (list) output
|
|
|
|
*REN newfile=oldfile
|
|
*RENAME newfile=oldfile
|
|
Renames 'oldfile' as 'newfile'. If the extension is omitted, .BBC is
|
|
assumed.
|
|
|
|
*RESET
|
|
Rest the disk system (CP/M function 13). This command does not close any
|
|
files nor does it perform any other housekeeping function. You should
|
|
use *RESET after you have changed a disk.
|
|
|
|
*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 (aaaa) and end+1 (bbbb) or as start (aaaa)
|
|
and length (llll). If the extension is omitted, .BBC is assumed.
|
|
|
|
*SPOOL [filespec]
|
|
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 filespec
|
|
Type the specified file to the screen. If the extension is omitted, .BBC
|
|
is assumed.
|
|
|
|
*| comment
|
|
This is a comment line. Anything following the | is ignored.
|
|
|
|
|
|
6. ERROR MESSAGES AND CODES
|
|
|
|
Untrappable:
|
|
|
|
No room RENUMBER space
|
|
Silly LINE space
|
|
Sorry Bad program
|
|
|
|
Trappable - BASIC:
|
|
|
|
1 Out of range 24 Exp range
|
|
2 25
|
|
3 26 No such variable
|
|
4 Mistake 27 Missing )
|
|
5 Missing , 28 Bad HEX
|
|
6 Type mismatch 29 No such FN/PROC
|
|
7 No FN 30 Bad call
|
|
8 31 Arguments
|
|
9 Missing " 32 No FOR
|
|
10 Bad DIM 33 Can't match FOR
|
|
11 DIM space 34 FOR variable
|
|
12 Not LOCAL 35
|
|
13 No PROC 36 No TO
|
|
14 Array 37
|
|
15 Subscript 38 No GOSUB
|
|
16 Syntax error 39 ON syntax
|
|
17 Escape 40 ON range
|
|
18 Division by zero 41 No such line
|
|
19 String too long 42 Out of DATA
|
|
20 Too big 43 No REPEAT
|
|
21 -ve root 44
|
|
22 Log range 45 Missing #
|
|
23 Accuracy lost
|
|
|
|
Trappable - OS:
|
|
|
|
190 Directory full 214 File not found
|
|
192 Too many open files 222 Channel
|
|
196 File exists 253 Bad string
|
|
198 Disk full 254 Bad command
|
|
200 Close error 255 CP/M error
|
|
204 Bad name
|
|
|
|
|
|
New features in BBC BASIC (Z80) version 5.00, May 2024:
|
|
|
|
1. BASIC V statements
|
|
|
|
1.1 WHILE...ENDWHILE
|
|
1.2 Multi-line IF...THEN...ELSE...ENDIF
|
|
1.3 CASE...WHEN...OTHERWISE...ENDCASE
|
|
1.4 LOCAL DATA / RESTORE DATA
|
|
1.5 ON ERROR LOCAL / RESTORE ERROR
|
|
1.6 DIM var LOCAL size
|
|
1.7 ERROR err, message$
|
|
1.8 RESTORE +n
|
|
1.9 SWAP var1,var2
|
|
1.10 BPUT #file,string$[;]
|
|
1.11 QUIT
|
|
|
|
2. BASIC V functions
|
|
|
|
2.1 DIM(array()[,sub])
|
|
2.2 END (pointer to free space)
|
|
2.3 REPORT$
|
|
2.4 Binary constants
|
|
2.5 LEFT$ & RIGHT$ with last parameter omitted
|
|
2.6 MOD(array)
|
|
2.7 SUM(array)
|
|
2.8 SUMLEN(array)
|
|
2.9 GET$#file
|
|
|
|
3. BASIC V whole array operations
|
|
|
|
3.1 Pass a whole array to a FN/PROC
|
|
3.2 Pass a whole array to CALL
|
|
3.3 Whole array assignment
|
|
3.4 Whole array arithmetic *
|
|
3.5 Array dot-product operator
|
|
3.6 Array initialisation lists
|
|
3.7 Array compound assignment (+= etc.)
|
|
3.8 Make a whole array LOCAL
|
|
3.9 DIM a LOCAL array (on the stack) +
|
|
|
|
* String array expressions A$() = B$() + C$() are not currently supported.
|
|
+ LOCAL string arrays should be initialised to their maximum needed length
|
|
to eliminate the risk of a memory leak each time the PROC/FN is called:
|
|
LOCAL a$() : DIM a$(size%) : a$() = STRING$(max%, "a") : a$() = ""
|
|
|
|
4. Miscellaneous BASIC V features
|
|
|
|
4.1 Bit-shifts <<, >>, >>>
|
|
4.2 Floating-point indirection (|)
|
|
4.3 RETURNed parameters from FN/PROC
|
|
4.4 Compound assignment (+=, -=, *=, /= etc.)
|
|
4.5 Assigning to a sub-string: LEFT$()=, MID$()= , RIGHT$()=
|
|
4.6 Hooks for CIRCLE,ELLIPSE,FILL,LINE,MOUSE,ORIGIN,RECTANGLE,TINT,SYS,WAIT
|
|
4.7 Hooks for WIDTH function, TINT function, MODE function
|
|
|
|
5. Extensions to Acorn's BASIC V, compatible with BB4W, BBCSDL and BBCTTY
|
|
|
|
5.1 EXIT REPEAT / WHILE / FOR [var]
|
|
5.2 Address-of operator ^
|
|
5.3 Byte variables and arrays (& suffix)
|
|
5.4 'BY len' and 'TO term' qualifiers to GET$#file
|
|
5.5 ELSE IF <condition> THEN; (trailing semicolon)
|
|
5.6 == synonymous with = in comparisons
|
|
5.7 DIM a global array inside a FN/PROC (use RETURN)
|
|
|
|
Note: The token for PUT has changed from &CE in version 3 to &0E in version 5.
|
|
If this token is present in existing programs it will list as ENDWHILE rather
|
|
than PUT, and the programs will need to be modified to restore functionality.
|