MirrorRepos/RomWBW
1
0
Fork 1
mirror of https://github.com/wwarthen/RomWBW.git synced 2026-02-06 14:11:48 -06:00
Code Issues Projects Releases Wiki Activity
Files
1f42d3748c5ef1786733972805476401e24a1e8d
RomWBW/Source/Apps/BBCBASIC/bbcbasic.txt
Wayne Warthen ad7d7638d3 Update BBC BASIC 
- Updated BBC BASIC (Z80) source from R.T.Russell's repository.
2025-02-17 17:21:44 -08:00

468 lines
18 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This is a RomWBW HBIOS adaptation of BBCBASIC v5.00 by R.T.Russell.
This implementation was adapted from the source code found at
https://github.com/rtrussell/BBCZ80.
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. Complete
documentation for the BBC BASIC (Z80) is found online at
https://www.bbcbasic.co.uk/bbcbasic/mancpm/index.html.
-- WBW 4:21 PM 2/17/2025
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, January 2025:
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 are not currently supported, instead of using
a$() = b$() + c$() use a$() = b$() : a$() += c$()
The use of EVAL with whole-array expressions is 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 Additional VDU delimiter '|'
4.4 RETURNed parameters from FN/PROC
4.5 Compound assignment (+=, -=, *=, /= etc.)
4.6 Assigning to a sub-string: LEFT$()=, MID$()= , RIGHT$()=
4.7 Hooks for CIRCLE, ELLIPSE, FILL, LINE, ORIGIN, RECTANGLE (graphics)
4.8 Hooks for MOUSE, OFF, ON, SYS, TINT, WAIT (statements)
4.9 Hooks for MODE function, TINT function, WIDTH 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 (unsigned 8-bit) 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)
5.8 DIM var LOCAL -1 returns the stack pointer, even outside a FN/PROC
5.9 RESTORE LOCAL restores local variables without exiting the FN/PROC
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.

Reference in New Issue View Git Blame Copy Permalink