forked from breakintoprogram/agon-bbc-basic
-
Notifications
You must be signed in to change notification settings - Fork 0
/
bbcbasic.txt
369 lines (280 loc) · 15 KB
/
bbcbasic.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
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