bbcbasic.txt

                              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