BBC BASIC Reference Manual Copyright © 1992 Acorn Computers Limited. All rights reserved. Updates and changes copyright © 2017 RISC OS Open Ltd. All rights reserved. Issue 1 published by Acorn Computers Technical Publications Department. Issues 2 and 3 published by RISC OS Open Ltd. No part of this publication may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, or stored in any retrieval system of any nature, without the written permission of the copyright holder and the publisher, application for which shall be made to the publisher. The product described in this manual is not intended for use as a critical component in life support devices or any system in which failure could be expected to result in personal injury. The product described in this manual is subject to continuous development and improvement. All information of a technical nature and particulars of the product and its use (including the information and particulars in this manual) are given by the publisher in good faith. However, the publisher cannot accept any liability for any loss or damage arising from the use of any information or particulars in this manual. If you have any comments on this manual, please complete the form at the back of the manual and send it to the address given there. Within this publication, the term ‘BBC’ is used as an abbreviation for ‘British Broadcasting Corporation’, however the BBC is not affiliated in any way with this manual. All trademarks are acknowledged as belonging to their respective owners. Published by RISC OS Open Ltd. Issue 1, October 1992 (Acorn part number 0470,280). Issue 2, October 2017 (updates by RISC OS Open Ltd). Issue 3, February 2021 (revised with minor corrections). ii Contents Part 1 – Overview 1 About the BBC BASIC Reference Manual 3 Intended readership 3 Structure of the manual 3 Conventions used in this manual 4 About BBC BASIC 5 The BASIC interpreter 5 BASIC V and BASIC VI 5 BASIC versions 6 Window managed programs 7 Part 2 – Programming techniques 9 Command mode 11 Entering BASIC 11 Leaving BASIC 12 Command mode 12 Simple programming 15 Entering a program 15 Altering a program 16 Deleting whole programs 19 Numbering lines in a program 20 Listing long programs 21 Comments 22 Multiple statements 23 Saving and recalling programs 24 Variables 27 Types of variables 27 Naming variables 27 iii Contents Numeric expressions 29 Integers and floating point numbers 29 Special integer variables 31 Arithmetic operators 31 Binary and logic 33 Binary numbers and bits 33 Hexadecimal numbers 33 Shift operators 34 AND, OR and EOR 36 TRUE and FALSE 37 String expressions 39 Assigning values to string variables 39 Joining strings together 40 Splitting strings 40 How characters are represented 43 Converting between strings and numbers 43 Arrays 47 The DIM statement 47 Two dimensional arrays 47 Finding the size of an array 49 Operating on whole arrays 49 Array operations 52 Outputting text 55 Print formatting 55 The text cursor 58 Defining your own characters 60 Inputting data 63 Inputting data from the keyboard 63 Including data as part of a program 65 Programming the keyboard 67 Using the mouse in programs 69 Programming function keys 71 iv Contents Control statements 73 IF... THEN... ELSE 73 Operators 74 IF... THEN... ELSE... ENDIF 75 FOR... NEXT 77 REPEAT... UNTIL 80 WHILE... ENDWHILE 81 CASE... OF... WHEN... OTHERWISE... ENDCASE 82 GOTO 84 GOSUB... RETURN 84 ON... GOTO/GOSUB 85 Procedures and functions 87 Defining and calling procedures 87 Parameters and local variables 88 ON... PROC 92 Recursive procedures 93 Functions 94 Function and procedure libraries 95 Data and command files 101 Data files 101 Writing or reading single bytes 102 Writing or reading ASCII strings 103 Command files 104 Screen modes 107 Changing screen modes 107 Numbered screen modes 108 Text size 109 Colour modes 110 Changing colours 111 Changing the colour palette 112 VIDC1-style 256-colour modes 113 Using the screen under the Wimp 115 v Contents Simple graphics 117 The graphics screen 117 The point command 118 The line command 119 Rectangle and rectangle fill 120 Circle and circle fill 121 Ellipse and ellipse fill 121 Graphics colours 122 The graphics cursor 124 Relative coordinates and BY 124 Printing text at the graphics cursor 125 Complex graphics 127 Plotting simple lines 129 Ellipses 133 Arcs 134 Sectors 135 Segments 136 Flood-fills 136 Copying and moving 137 Graphic patterns 139 Default patterns 139 Plotting using pattern fills 140 Defining your own patterns 140 Native mode patterns 141 BBC Master mode patterns 143 Giant patterns 144 Simple patterns 145 Viewports 147 Text viewports 147 Graphics viewports 149 Sprites 151 Loading a user sprite 151 Plotting a user sprite 152 vi Contents Teletext mode 153 Coloured text 153 Making text flash 154 Double-height text 154 Changing the background colour 154 Concealing and revealing text 155 Teletext graphics 155 Sound 159 Activating the sound system 159 Selecting sound channels 159 Allocating a wave-form to each channel 159 Setting the stereo position 160 Creating a note 161 Synchronising the channels 162 Finding the value of the current beat 163 Finding the current tempo 163 Executing a sound on a beat 164 Accessing memory locations 165 Reserving a block of memory 165 The ‘?’ indirection operator 166 The ‘!’ indirection operator 166 The ‘|’ indirection operator 167 The ‘$’ indirection operator 167 Error handling and debugging 169 Trapping an error 169 Generating errors 171 External errors 171 Local error handling 172 Debugging 174 VDU control 177 Editing BASIC files 191 Editing BASIC files with Edit 191 Editing BASIC files with the BASIC screen editor 193 vii Contents Part 3 – Reference 213 Keywords 215 * Commands 435 ARM assembler 441 Using the BASIC assembler 441 Saving machine code to file 445 Executing a machine code program 445 Format of assembly language statements 446 Recommended Books 447 Part 4 – Appendices 449 Appendix A – Numeric implementation 451 Numeric types 451 Effects of storage size 453 What is floating point arithmetic? 455 Implementation 455 Appendix B – Minimum abbreviations 459 Appendix C – Error messages 465 Appendix D – INKEY values 469 INKEY values by functional group 469 INKEY values by number 473 Appendix E – Specifying screen modes 477 Mode Strings 477 Mode Variables 479 Appendix F – Default palettes 481 Appendix G – Plot codes 483 Appendix H – VDU variables 485 Appendix I – BBC BASIC’s history 489 Index 503 viii Part 1 – Overview 1 2 1 About the BBC BASIC Reference Manual BC BASIC is one of the most popular and widely-used versions of the BASIC Bprogramming language. This manual provides a complete description of BBC BASIC for users of computers running RISC OS version 3.10 or later. Intended readership You should read this manual if you are ● a computer user who has never used BBC BASIC before, who wants an introduction to a new computer language; ● an experienced programmer in other computer languages, who wants an insight into BBC BASIC’s features without having to resort to a lengthy tutorial-type manual; ● an experienced BBC BASIC programmer, who needs specific information about the structure of BBC BASIC, and the use of its commands. Structure of the manual The manual is divided into the following parts: Part 1 – Overview — includes this chapter, and the chapter entitled About BBC BASIC, which gives an introduction to BASIC VI. It compares BASIC VI with BASIC V, and describes the benefits and effects of using both versions. Part 2 – Programming techniques — explains how to program in BBC BASIC, and introduces many of the commands (or keywords) provided by the language. The last chapter in this section describes the BASIC screen editor. Part 3 – Reference — contains a complete list of BBC BASIC keywords, in alphabetical order. It defines the syntax of all the keywords, and gives you examples of how to use them. Part 4 – Appendices — contains the appendices, which have useful reference material, such as numeric representation, error messages, keyword abbreviations and VDU variables. A brief history of BBC BASIC is also included. 3 Conventions used in this manual Conventions used in this manual The following conventions are applied throughout this manual: ● Specific keys to press are denoted as Ctrl, Delete and so on. ● Instructions which require you to press a combination of keys are shown thus: Shift-Home means hold down the Shift key and press and release the Home key. ● Text you type on the keyboard and text that is displayed on the screen appears as follows: PRINT "Hello" ● Classes of item are shown in italics: For example, in the descriptions of BASIC keywords, you might see something like: LET var = expression where var and expression are items you need to supply, for example: LET a$="hello" ● Items within square brackets [] are optional. For example, GCOL [expression2,] expression1 means that you must supply at least one expression. If you supply two, you must separate them with a comma. ● All interactive commands are entered by pressing the Return key. However, this is not actually shown in the examples or syntax of commands. ● Extra spaces are inserted into program listings to aid clarity, but need not be typed in. ● Program listings are indented to illustrate the structure of the programs. If at any time you wish to interrupt a program the computer is executing you can do so safely by pressing Esc. Feel free to experiment. Try modifying the programs listed in this manual and writing new ones of your own. 4 2 About BBC BASIC BC BASIC consists of special keywords with which you create sequences of Binstructions, called programs, to be carried out by the computer.