                             BBC BASIC (86) Plus

                       IBM PC Compatible Version 4.82

                    (C) Copyright R.T.Russell 1985-1999

1. INTRODUCTION

   BBC  BASIC (86) is fully configured for the IBM PC and  compatibles,  and 
   all  the statements and functions specified for BBC BASIC are  available.  
   It  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 80x86 version is more tolerant.

   BBC BASIC (86) is supplied in four versions:

          BBCBASIC.EXE   The standard 'small memory model' interpreter
          BIGBASIC.EXE   The 'large memory model' interpreter
          BBCRUN.EXE     The 'small memory model' run-only version
          BIGRUN.EXE     The 'large memory model' run-only version

   You  can use the run-only versions to combine a BBC BASIC program with  a 
   cut-down  version of the interpreter to create a single  executable  file 
   which  may be run directly from the DOS prompt (or from Windows)  without 
   it  necessarily  being apparent that BBC BASIC is  involved.   Executable 
   files  created  this way may be distributed freely  without  any  royalty 
   for BBCBASIC being due.

   The 'small memory model' versions allocate 64 Kbytes (when available) for 
   the user's program and variable space; the 'large memory model'  versions 
   allow  the variable storage area (the 'heap') to exceed 64 Kbytes, up  to 
   the  limit  of  low  memory in the machine (normally  a  maximum  of  640 
   Kbytes).   The large memory model versions run slightly more slowly  than 
   the  standard versions when performing the same operations, and use  more 
   code  and  data  memory than the standard versions  for  the  same  BASIC 
   program.   The  small  memory  model versions  are  also  generally  more 
   appropriate  when  it is necessary to 'shell out' from BBC BASIC  to  run 
   another DOS utility.

   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 (86) requires about 32 Kbytes of code space.  When available, a 
   full 64K segment is used for data (small memory model version), resulting 
   in PAGE having a value of &900 and HIMEM a value of &10000.  If less than 
   64K is available HIMEM will be set at a lower value.  BBC BASIC  releases 
   any memory surplus to its requirements so that other programs may be  run 
   from  within BBC BASIC (using a "star" command). If you  have  sufficient 
   memory you can even run BBC BASIC from BBC BASIC (although this is hardly 
   useful)!

   When  running BBC BASIC (86) the user only "sees" the data  segment;  for 
   example,  indirection  operators (?, !) only access this  64K  region  of 
   memory.


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 returns information about the analogue to digital converter 
   channels on the Games Adapter card (if fitted).  The information returned 
   depends on the argument passed to ADVAL:

     If  the  argument  is  positive  (1  to  4),  ADVAL  returns  a   value 
     proportional to the resistance of the joysticks or games paddles.   The 
     value is scaled to the range 0 to 65280.  However, the number  returned 
     depends  upon  the  processor clock frequency and  its  absolute  value 
     cannot be relied upon. 

          adcval = ADVAL(3)
          level = ADVAL(chnumber)

     If  the  argument is zero, ADVAL returns a value in the range 0  to  15 
     corresponding to the state of the 4 fire buttons.  Zero is returned  if 
     no buttons are pressed and 15 is returned if all 4 buttons are pressed.

     If the argument is negative, ADVAL returns the number of free spaces in 
     the  sound  queue.  If the sound queue is empty, the value 14  will  be 
     returned;  if the queue is (nearly) full, zero will be returned.   Note 
     that any negative argument will return the number of free spaces in the 
     sound queue, but for maximum compatibility with the BBC Micro the value 
     -6 should be used.

   CALL
   CALL  sets  up a table in RAM containing details of the  parameters;  the 
   processor's  BP register is set to the address of this  parameter  table.  
   The other processor registers are initialised as follows:

               AX is initialised to the least significant 16 bits of A%
               BX is initialised to the least significant 16 bits of B%
               CX is initialised to the least significant 16 bits of C%
               DX is initialised to the least significant 16 bits of D%
            FLAGS is initialised to the least significant 16 bits of F%

   The four segment registers (CS, DS, SS, ES) are all set to the address of 
   BASIC's data segment (small memory model version).

   Note  that  you cannot disable interrupts or enter  single-step  mode  by 
   setting F% to an appropriate value, as this could be dangerous.

   The  user's machine-code routine must return to BASIC with a  far  return 
   (RETF) instruction, not a simple RET instruction.

   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 (small memory model version only):

          Number of parameters     1 byte (at BP)

          Parameter type           1 byte (at BP+1)
          Parameter address        2 bytes (at BP+2, BP+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

   CALL  and  USR operate differently when addresses in the range  &FF00  to 
   &FFFF are used. See the Operating System Interface section for details.

   COLOUR (COLOR)
   The colours available on the IBM PC are dependent on the selected  screen 
   mode,  as follows; the first column indicates foreground colour  and  the 
   second column indicates background colour:

   In the 2-colour graphics mode (mode 0):

   COLOUR 0  COLOUR 128  black
   COLOUR 1  COLOUR 129  white

   You can change the physical to logical colour mapping (palette) using the 
   VDU 19 command.

   In the 4-colour graphics mode (mode 1):

   COLOUR 0  COLOUR 128  black
   COLOUR 1  COLOUR 129  magenta
   COLOUR 2  COLOUR 130  cyan
   COLOUR 3  COLOUR 131  white
   
   You can change the physical to logical colour mapping (palette) using the 
   VDU 19 command.

   In 16-colour graphics modes (modes 8,9,16,18):

   COLOUR 0  COLOUR 128  black
   COLOUR 1  COLOUR 129  red
   COLOUR 2  COLOUR 130  green
   COLOUR 3  COLOUR 131  yellow
   COLOUR 4  COLOUR 132  blue
   COLOUR 5  COLOUR 133  magenta
   COLOUR 6  COLOUR 134  cyan
   COLOUR 7  COLOUR 135  white
   COLOUR 8  COLOUR 136  intensified black
   COLOUR 9  COLOUR 137  intensified red
   COLOUR 10 COLOUR 138  intensified green
   COLOUR 11 COLOUR 139  intensified yellow
   COLOUR 12 COLOUR 140  intensified blue
   COLOUR 13 COLOUR 141  intensified magenta
   COLOUR 14 COLOUR 142  intensified cyan
   COLOUR 15 COLOUR 143  intensified white

   You can change the physical to logical colour mapping (palette) using the 
   VDU 19 command.

   In text-only modes (3,6):

   COLOUR 0  COLOUR 128  black
   COLOUR 1  COLOUR 129  red
   COLOUR 2  COLOUR 130  green
   COLOUR 3  COLOUR 131  yellow
   COLOUR 4  COLOUR 132  blue
   COLOUR 5  COLOUR 133  magenta
   COLOUR 6  COLOUR 134  cyan
   COLOUR 7  COLOUR 135  white
   COLOUR 8  COLOUR 136  intensified black
   COLOUR 9  COLOUR 137  intensified red
   COLOUR 10 COLOUR 138  intensified green
   COLOUR 11 COLOUR 139  intensified yellow
   COLOUR 12 COLOUR 140  intensified blue
   COLOUR 13 COLOUR 141  intensified magenta
   COLOUR 14 COLOUR 142  intensified cyan
   COLOUR 15 COLOUR 143  intensified white
   COLOUR 16 COLOUR 144  black
   COLOUR 17 COLOUR 145  flashing red
   COLOUR 18 COLOUR 146  flashing green
   COLOUR 19 COLOUR 147  flashing yellow
   COLOUR 20 COLOUR 148  flashing blue
   COLOUR 21 COLOUR 149  flashing magenta
   COLOUR 22 COLOUR 150  flashing cyan
   COLOUR 23 COLOUR 151  flashing white
   COLOUR 24 COLOUR 152  flashing intensified black
   COLOUR 25 COLOUR 153  flashing intensified red
   COLOUR 26 COLOUR 154  flashing intensified green
   COLOUR 27 COLOUR 155  flashing intensified yellow
   COLOUR 28 COLOUR 156  flashing intensified blue
   COLOUR 29 COLOUR 157  flashing intensified magenta
   COLOUR 30 COLOUR 158  flashing intensified cyan
   COLOUR 31 COLOUR 159  flashing intensified white  

   Flashing colours alternate between the colour specified and black.  There 
   is no conventional palette in these modes (although VDU 19 may be used to 
   change the extended palette on an EGA, VGA or SVGA card).

   DRAW
   The range of coordinates corresponding to positions on the screen depends 
   on the screen mode, as follows (assuming the origin has not been moved):

     MODE 16   X in the range 0 to 1279 and Y in the range 0 to 1399
     MODE 18   X in the range 0 to 1279 and Y in the range 0 to 959
     Others    X in the range 0 to 1279 and Y in the range 0 to 799

   In the text-only modes (3,6) DRAW has no effect.
 
   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):

     LEFT       move the cursor one character position to the left
     RIGHT      move the cursor one character position to the right
     UP         move the cursor up one line
     DOWN       move the cursor down one line
     CTRL/LEFT  move the cursor to the start of the line
     CTRL/RIGHT move the cursor to the end of the line
     INS        toggle between insert and overtype modes
     DEL        delete the character at the current cursor position
     BACKSPACE  backspace and delete the character to the left of the cursor
     CTRL/U     delete all characters to the left of the cursor
     CTRL/ENTER delete all characters from the cursor to the end of the line
     CTRL/P     toggle output to the printer
     ENTER      enter the line and exit edit mode
     ESC        abort and leave the line unchanged
     TAB        enter 'copy key' editing mode

   A full-screen editor is also provided.  See *EDIT in the Operating System 
   Interface section.

   ENVELOPE
   This  statement  is  implemented  to  the same extent  as  on  the  Acorn 
   Electron,  that  is the pitch envelope is implemented but  the  amplitude 
   envelope  is not.  The last six parameters of the ENVELOPE statement  are 
   ignored,  but  for  compatibility with the BBC Micro are best set to  the 
   values 126,0,0,-126,126,126.

   Envelope numbers 1 to 4 may be freely used.  Envelope numbers 5 to 16 may 
   be  used  if  no file-related operations (including  star  commands)  are 
   performed.  If a file operation is performed it will work correctly,  but 
   the envelope data may be corrupted.

   GET
   The  values  returned  from the function and cursor control keys  are  as 
   follows (unless redefined using *KEY):

     Home  130    f1  145    Shift/f1  161    Ctrl/f1  177    Alt/f1  193
     End   131    f2  146    Shift/f2  162    Ctrl/f2  178    Alt/f2  194
     PgUp  132    f3  147    Shift/f3  163    Ctrl/f3  179    Alt/f3  195
     PgDn  133    f4  148    Shift/f4  164    Ctrl/f4  180    Alt/f4  196
     Ins   134    f5  149    Shift/f5  165    Ctrl/f5  181    Alt/f5  197
     Del   135    f6  150    Shift/f6  166    Ctrl/f6  182    Alt/f6  198
     Left  136    f7  151    Shift/f7  167    Ctrl/f7  183    Alt/f7  199
     Right 137    f8  152    Shift/f8  168    Ctrl/f8  184    Alt/f8  200
     Down  138    f9  153    Shift/f9  169    Ctrl/f9  185    Alt/f9  201
     Up    139    f10 154    Shift/f10 170    Ctrl/f10 186    Alt/f10 202

   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
   The  returned values for function and cursor keys are as for GET,  above. 
   The INKEY(-n) facility is not implemented.

   INPUT#
   The format of data files is different from that used by the BBC Micro, in 
   part  to improve compatibility with standard DOS 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).

   LIST
   When using the (default) VDU emulator (*OPT 0),  LISTing may be paused by 
   holding down the CTRL and SHIFT keys together.  "Paged" mode may also  be 
   entered  by typing CTRL/N (VDU 14) whereupon the screen will wait at  the 
   end  of each page until a SHIFT key is pressed.  Paged mode is turned off 
   by typing CTRL/O (VDU 15).

   MODE
   The available display modes are as follows:

          Mode      Graphics       Text      Colours

            0       640 x 200     80 x 25       2
            1       320 x 200     40 x 25       4

            3          none       80 x 25      16 (text only)
            6          none       40 x 25      16 (text only)

            8       640 x 200     80 x 25      16
            9       320 x 200     40 x 25      16
           16       640 x 350     80 x 25      16
           18       640 x 480     80 x 30      16

   A cursor is generated only in the text-only modes (3,6).

   MOVE
   The range of coordinates corresponding to positions on the screen depends 
   on the screen mode, as follows (assuming the origin has not been moved):

     MODE 16   X in the range 0 to 1279 and Y in the range 0 to 1399
     MODE 18   X in the range 0 to 1279 and Y in the range 0 to 959
     Others    X in the range 0 to 1279 and Y in the range 0 to 799

   In the text-only modes (3,6) MOVE has no effect.

   PLOT
   The range of coordinates corresponding to positions on the screen depends 
   on the screen mode, as follows (assuming the origin has not been moved):

     MODE 16   X in the range 0 to 1279 and Y in the range 0 to 1399
     MODE 18   X in the range 0 to 1279 and Y in the range 0 to 959
     Others    X in the range 0 to 1279 and Y in the range 0 to 799

   In the text-only modes (3,6) PLOT has no effect.

   The following PLOT codes are implemented:

   PLOT 0       Move to a position relative to the last point.
   PLOT 1       Draw line relative in graphics foreground colour.
   PLOT 2       Draw line relative in logical inverse colour.
   PLOT 3       Draw line relative in graphics background colour.
   PLOT 4       Move to an absolute position.
   PLOT 5       Draw line absolute in graphics foreground colour.
   PLOT 6       Draw line absolute in logical inverse colour.
   PLOT 7       Draw line absolute in graphics background colour.

   PLOT 8-15    As PLOT 0-7 except that the last point is plotted twice.

   PLOT 16-31   As PLOT 0-15 except that the line is drawn dotted (......).
   PLOT 32-47   As PLOT 0-15 except that the line is drawn dashed (------).
   PLOT 48-63   As PLOT 0-15 except that the line is drawn broken (.-.-.-).

   PLOT 64-71   As PLOT 0-7 but only a single point is plotted.

   PLOT 72-79   Draw a horizontal line from the given point, left and right, 
                until the first non-background coloured pixel is found.

   PLOT 80-87   Plot  and fill a triangle formed by the given point and  the 
                last two points visited.

   PLOT 88-95   Draw  a  horizontal line from the given point to  the  right 
                until the first background-coloured pixel is found.

   PLOT 96-103  Plot  and  fill  an axis-aligned  rectangle  whose  opposite 
                corners are the given point and the last point visited.

   PLOT 104-111 Draw a horizontal line from the given point, left and right, 
                until the first foreground-coloured pixel is found.

   PLOT 112-119 Plot and fill a parallelogram whose vertices are defined  by 
                the point specified and the previous two points visited.

   PLOT 120-127 Draw  a  horizontal line from the given point to  the  right 
                until the first non-foreground coloured pixel is found.

   PLOT 128-135 Flood fill starting at the given point and continuing  until 
                non-background  coloured  pixels are found.  This  may  fail 
                with a 'No room' error if the area to fill is too complex or 
                the colour being used to fill can itself be filled.

   PLOT 136-143 Flood fill starting at the given point and continuing  until 
                foreground coloured pixels are found.  This may fail with  a 
                'No  room' error if the area to fill is too complex  or  the 
                colour being used to fill can itself be filled.

   PLOT 144-151 Draw  a circle centered on the last visited point  and  with 
                the given point on its circumference.

   PLOT 152-159 Plot  a  solid disc centered on the last visited  point  and 
                with the given point on its circumference.

   PRINT#
   The format of data files is different from that used by the BBC Micro, in 
   part  to improve compatibility with standard DOS 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
   There is only one sound channel,  and there is no "noise" capability. The 
   amplitude  of the sound cannot be controlled.  The four parameters behave 
   as follows:

                    SOUND channel,loudness,pitch,duration

   channel
   Only bit 4 has any effect. If set, the sound queue is flushed and the new 
   sound is started immediately. The channel number as such is ignored.   In 
   order  to maximize compatibility with the BBC Micro, the  channel  number 
   used should be the same throughout the program.

   loudness
   Values  from  -15 to -1 select a sound of constant amplitude  and  pitch, 
   zero selects silence and values from 1 to 16 select a pitch envelope (see 
   ENVELOPE  statement).   In order to maximize compatibility with  the  BBC 
   Micro,  a  value of -15 should be used if you do not with to  specify  an 
   envelope.

   pitch
   This selects the (initial) pitch as with the BBC Micro.  The pitch can be 
   varied in quarter-semitone increments; Middle C is 52.

   duration
   Values  from  0  to 254 select the duration of the  sound,  in  units  of 
   approximately 1/18 second. The value -1 causes an indefinite sound, which 
   can  be stopped only by issuing another SOUND statement with the  "flush" 
   bit set or by pressing the ESCape key.

   TIME
   The  value of the elapsed time clock is returned in centiseconds,  and it 
   is quite accurate.  However, the clock is only updated about 18 times per 
   second - each adding 5 or 6 to the elapsed time count.  For this reason a 
   delay  loop such as REPEAT UNTIL TIME=T is quite likely to fail  and  the 
   alternative REPEAT UNTIL TIME>=T should always be used.

   USR
   As with CALL, the processor's registers are initialised as follows:

               AX is initialised to the least significant 16 bits of A%
               BX is initialised to the least significant 16 bits of B%
               CX is initialised to the least significant 16 bits of C%
               DX is initialised to the least significant 16 bits of D%
            FLAGS is initialised to the least significant 16 bits of F%

   USR returns a 32-bit integer result composed of the processor's DX and AX 
   registers, with DX being the most significant.

   The  user's  assembly language program must return to BASIC with  a  RETF 
   instruction, not a RET instruction.

   CALL  and  USR operate differently when addresses in the range  &FF00  to 
   &FFFF are used. See the section on the OS Interface for details.


4. RESIDENT 80x86 ASSEMBLER

   The  in-line  assembler is accessed in exactly the same way as  the  6502 
   assembler  in  the BBC Micro version of BBC BASIC.  However there  are  a 
   number  of  minor differences from the official Intel  assembly  language 
   syntax, as follows:

   a) Short (8-bit displacement) jumps,  far (intersegment) calls, far jumps 
      and  far returns must be explicitly specified by using  the  following 
      mnemonics: JMPS, CALLF, JMPF and RETF.

   b) Memory  operands  must  be  placed  in square  brackets  in  order  to 
      distinguish them from immediate operands. For example:
               MOV  AX,[store]     ;Load AX from memory location "store"
               MOV  AX,start       ;Load AX with the immediate value "start"

   c) The  string  operations  must  have  the  data  size  (byte  or  word) 
      explicitly specified in the instruction mnemonic,  i.e.  CMPSB, CMPSW, 
      LODSB, LODSW, MOVSB, MOVSW, SCASB, SCASW, STOSB, STOSW.

   d) Segment overrides, when needed, must always be entered explicitly; the 
      assembler will not insert them automatically. For example:
               MOV  AX,cs:[data]   ;Load AX from "data" in the code segment
      Note that segment overrides will rarely be required as BBC BASIC  sets 
      all  segment  registers  to  the same value  on  entering  the  user's 
      assembly language code with CALL or USR (small memory model version).

   e) Certain  assembly language instructions are ambiguous as to whether  a 
      byte  or  word value is to be acted upon.  In such cases  an  explicit 
      "byte ptr" or "word ptr" operator must be supplied. For example:
               INC  byte ptr [bx]
               MOV  word ptr [count],0
      If omitted, BASIC will issue the "Size needed" error (error code 2).

   f) The   composite  based-indexed  operands  are  only  accepted  in  the 
      preferred forms, i.e. [bp+di], [bp+si], [bx+di], [bx+si].

   g) Indexed  memory  operands  with constant offset are  accepted  in  the 
      following forms:
                    [index]+offset
                    [index+offset]
                    offset[index]
      where "index" is an index or base register such as bx,  bp+si etc. and 
      "offset" is a numeric expression.

   h) When multiple assembly language statements are separated by colons, be 
      careful  to  leave a space between the colon and a  preceding  segment 
      register  name  otherwise  the assembler will mis-interpret  it  as  a 
      segment override. For example:
               push cs:mov ax,0         will give an error, but
               push cs :mov ax,0        will be accepted.

   i) The pseudo-ops provided are DB (define byte),  DW (define word) and DD 
      (define  doubleword)  which create a 1-byte,  2-byte and  4-byte  item 
      respectively. DB may alternatively be followed by a string operand, in 
      which  case the bytes comprising the string are placed at the  current 
      program counter location.

   j) The  only assembler directive is OPT, which behaves exactly as in  the 
      6502 version.  OPT may be used to implement a MACRO facility.

   k) Unlike  the  6502 assembler, the 80x86 assembler  attempts  to  detect 
      multiply-defined labels. If, during the first pass of an assembly (OPT 
      0 or 1), a label is found to have an existing non-zero value then  the 
      "Multiple label" error is issued (error code 3).

   l) Assembly  language instructions for the 80186 (and  later)  processors 
      are accepted, but only by the large-memory-model versions BIGBASIC and 
      BIGRUN.

   Assembly language programs may access the OSRDCH, OSWRCH, OSKEY and OSCLI 
   routines via vectors provided as follows:

     OSRDCH:   CALLF [&300] ; Waits for and returns a character in AL
     OSWRCH:   CALLF [&304] ; Sends the character in AL to the VDU driver
     OSKEY:    CALLF [&308] ; Waits for the time limit passed in AX and
                            ; returns a character in AL with the carry set
                            ; or the carry cleared to indicate a time-out
     OSCLI:    CALLF [&30C] ; Executes the CR-terminated command at DX


5. OPERATING SYSTEM INTERFACE

   The   following   resident  Operating  System   ("star")   commands   are 
   implemented. They may be accessed directly (e.g. *HELP) or via the  OSCLI 
   statement (OSCLI "HELP").
    
   All  OS  commands  requiring a filename (filespec)  will  accept  a  full 
   pathname (e.g. c:bbcbasic\doug\wombat.bak).

   *BYE
   Returns control to the program which invoked BBC BASIC.

   *CD directory
   *CHDIR directory
   Change the current directory.

   *DEL filespec
   *DELETE filespec
   Delete  the  specified file. The extension defaults to .BBC  if  omitted. 
   Note  that  this  command will delete only one file:  wildcards  are  not 
   permitted.

   *. [filespec]
   *DIR [filespec]
   List  the  files  in  the current directory which  match  the  (optional) 
   ambiguous  filespec.  If  the filespec is omitted,  all  .BBC  files  are 
   listed. "Read only" files are marked with an asterisk.

   *DRIVE d:
   Select drive d as the default drive for subsequent disk operations.

   *EDIT [linenumber]
   Enter  the full-screen editor with the specified line number (if any)  as 
   the  first  line  displayed on the screen.  Pressing Esc  will  exit  the 
   screen editing mode (it is not possible to abandon changes).  The control 
   keys have the following effect:

     Up         Move up to the previous screen line
     Down       Move down to the following screen line
     Left       Move the cursor left one character
     Right      Move the cursor right one character
     Ctrl/Left  Move the cursor to the start of the program line
     Ctrl/Right Move the cursor to the end of the program line
     Enter      Move the cursor to the start of the next program line
     Backspace  Backspace and delete
     Del        Delete the character at the cursor position
     Ins        Toggle between insert and overwrite modes
     Tab        Insert a new line following the current line
     Ctrl/U     Clear the current line; the line number is not deleted
     Ctrl/Enter Delete the current line, including the line number
     PgUp       Display the previous 12 lines, and move the cursor there
     PgDn       Display the next 12 lines, and move the cursor there
     Home       Move the cursor to the start of the program
     End        Move the cursor to the end of the program

   If the cursor is in the top line of the screen, pressing the Up key  will 
   cause  the  display  to scroll down one line.  If the cursor  is  in  the 
   bottom line of the screen, pressing Down will cause the display to scroll 
   up one line.

   It is not possible to edit line numbers with the full-screen editor;  use 
   the EDIT command to do that.

   *ERA filespec
   *ERASE filespec
   These commands are synonymous with *DEL.

   *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.

   *HELP
   This causes the name and version number of BBC BASIC to be displayed.

   *KEY n [string]
   Redefine a function key or cursor key to return the specified string. The 
   key number n is as follows:

                1   f1             12   Left
                2   f2             13   Right
                3   f3             14   Down      
                4   f4             15   Up
                5   f5             18   Home
                6   f6             19   End
                7   f7             20   PgUp
                8   f8             21   PgDn
                9   f9             22   Ins
               10   f10            23   Del

   The  string  may contain the "escape" symbol | in order  to  insert  non-
   printing characters.  For example,  |M indicates CR (carriage return), !? 
   indicates DEL, || indicates the character | itself and |! causes bit 7 of 
   the  following character to be set.  If the string is enclosed in  quotes 
   (which  is  optional)  |" allows the character " to be  included  in  the 
   string.

   If there is insufficient room for the string, the "Bad string" error will 
   occur and the key will be loaded with as much of the string as would fit.

   *KEY  n <RETURN> will empty the specified key and return it to its normal 
   code (see GET).

   *LOAD filespec aaaa
   Loads the specified file into memory at hexadecimal offset aaaa. The load 
   address must be specified. If the extension is omitted, .BBC is assumed.

   *LOCK filespec
   Set  the  specified  file to "read-only"  status.  If  the  extension  is 
   omitted, .BBC is assumed.

   *MD directory
   *MKDIR directory
   Creates a new directory with the given name.

   *OPT [n]
   Select  the destination for console output characters.  The value n is in 
   the range 0 to 4, as follows:
               
          0    Send characters to the VDU emulator (see later)
          1    Send characters to the auxiliary output
          2    Send characters to the printer output
          3    Send characters to the standard output
          4    Send characters to the error output

   *OPT  0  is  the default setting.  Note that all characters sent  to  the 
   console output are vectored with *OPT,  there is no filtering of graphics 
   commands etc. For example, the statement COLOUR 3 in a program will cause 
   the bytes 17 and 3 to be sent to the device selected by *OPT.

   *QUIT
   This is synonymous with *BYE.

   *RD directory
   *RMDIR directory
   These  commands  delete (remove) the specified directory.  This  is  only 
   permitted when all files in the directory have also been deleted.

   *REN newfile=oldfile
   *REN oldfile newfile 
   *RENAME newfile=oldfile
   *RENAME oldfile newfile
   These  commands  rename  oldfile as newfile.  Both  the  MSDOS  and  CP/M 
   formats are accepted.  If the extension is omitted, .BBC is assumed.  The 
   rename command can be used to move a file from one directory to another.

   *RUN filename
   */ filename

   These   commands   cause  the  program  filename.EXE,   filename.COM   or 
   filename.BAT  to be executed. For this to work there must be  a  suitable 
   copy of COMMAND.COM on the current disk and there must be sufficient  RAM 
   to load the required program whilst BBC BASIC remains in memory.

   *SAVE filespec aaaa bbbb
   *SAVE filespec aaaa +llll
   This command saves a specified range of memory (in BASIC's data  segment) 
   to disk. The address range is specified either as start offset (aaaa) and 
   end offset +1 (bbbb) or as start offset (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.

   *SPOOLON filespec
   Appends  all subsequent console output to the specified file, which  must 
   exist.  If the extension is omitted, .BBC is assumed.

   *TYPE filespec
   Type  the specified file to the VDU screen.  If the extension is omitted, 
   .BBC is assumed.

   *UNLOCK filespec
   Set  the  specified  file to "read/write" status.  If  the  extension  is 
   omitted, .BBC is assumed.

   *| comment
   This is a comment line. Anything following the | is ignored.

   If the OS command is not one of the above resident commands, it is passed 
   to COMMAND.COM for execution.  This will work only if there is a suitable 
   copy of COMMAND.COM on the default disk and there is sufficient RAM.  For 
   example,  you can copy files between disks by issuing the *COPY  command, 
   which will be processed by COMMAND.COM:

          *COPY sourcefile destfile [/v]

   If  you  want  to  execute a command with the same  name  as  a  built-in 
   command, then precede it with a second "star":

          **DIR /w

   If  a command passed to COMMAND.COM is not found,  the error message "Bad 
   command or file name" will be displayed. This error cannot be detected or 
   trapped by BASIC,  and execution of the BASIC program will continue.  For 
   this reason the commands *FX and *TV,  commonly found in programs for the 
   BBC Micro, are trapped by BASIC and produce the "Bad command" error. They 
   are not passed to COMMAND.COM.

   In  addition  to  the  commands listed above,  the  OS  Interface  module 
   provides facilities for reading the character at the current text  cursor 
   position and for reading the dot pattern of a given font character. These 
   are accessed by a USR or CALL to addresses &FFF4 and &FFF1 respectively.

   The character at the current text cursor position is returned by:

                    (USR(&FFF4) AND &FF00) DIV 256

   The dot pattern of a character can be read as follows:

                    DIM par 8
                    ?par=character
                    CALL &FFF1

   where  the character pattern will be returned in the eight bytes par?1 to 
   par?8.

   The reason for the rather "obscure" methods of accessing these  functions 
   is  to maintain maximum compatibility with the similar functions provided 
   on the BBC Microcomputer.


6. VDU EMULATOR

   In  the default state (*OPT 0) all console output is passed to a software 
   emulator of the BBC Micro's VDU drivers.  VDU codes perform a function as 
   similar  as  possible  to those of the BBC  Micro,  consistent  with  the 
   hardware differences, as follows:

   VDU 0
   Ignored

   VDU 1
   VDU 1,n
   The  following byte is sent to the printer,  if enabled (with VDU 2).  If 
   the printer is not enabled,  the byte is ditched. Any 8-bit value (0-255) 
   can be sent. This works even when the VDU is disabled with VDU 21.

   VDU 2
   Enable the printer. Subsequent characters are sent both to the screen and 
   to  the printer.  The only control characters sent to the printer are  BS 
   (8), HT (9), LF (10), FF (12) and CR (13). Bytes which are parameters for 
   VDU commands are not sent to the printer,  e.g.  VDU 17,65 does not  send 
   "A" to the printer.

   VDU 3
   Disables the printer. Cancels the effect of VDU 2.

   VDU 4
   Causes text to be written at the text cursor position in the normal  way. 
   Characters  are  "opaque" and can be positioned only at text  coordinates 
   within the text window. The text window scrolls when necessary.

   VDU 5
   In graphics modes only,  causes text to be written at the graphics cursor 
   position.  Characters  have  a "transparent" background and  are  plotted 
   according to the current foreground GCOL rules and colour (VDU 127,  DEL, 
   is an exception). Characters can be positioned at any graphics coordinate 
   within  the  graphics window,  the top left of the character cell is  the 
   reference  point;   characters  are  clipped  to  the  window  limits  if 
   necessary. No scrolling takes place.

   VDU 6
   Enables the VDU screen. Cancels the effect of VDU 21.

   VDU 7
   Causes a "beep".

   VDU 8
   Moves the text cursor left one character.  If it was at the left edge  of 
   the   window,  it is wrapped to the end of the previous line (RH edge  of 
   window).  If  it was also on the top line of the text window,  the window 
   scrolls down (except when in VDU 5 mode).

   VDU 9
   Moves  the text cursor right one character.  If it was at the right  hand 
   edge of the window,  it is wrapped to the beginning of the next line  (LH 
   edge  of window).  If it was also on the bottom line of the text  window, 
   the window scrolls up (except when in VDU 5 mode).

   VDU 10
   Moves the text cursor down one line.  If it was on the bottom line of the 
   text window, the window scrolls up (except when in VDU 5 mode). Scrolling 
   is inhibited if CTRL & SHIFT are both held down.

   VDU 11
   Moves the text cursor up one line.  If it was on the top line of the text 
   window, the window scrolls down (except when in VDU 5 mode).

   VDU 12
   This  is  identical to CLS in BASIC.  It clears the text  window  to  the 
   current  text background colour and moves the text cursor to the top-left 
   corner of the text window.

   VDU 13
   Moves the text cursor to the left-hand edge of the window,  but does  not 
   move it vertically.

   VDU 14
   Enter  paged mode.  Scrolling will stop after each page, unless SHIFT  is 
   pressed.

   VDU 15
   Stop paging. Cancels the effect of VDU 14.

   VDU 16
   This is identical to CLG in BASIC.  In graphics modes only, it clears the 
   graphics  window using the current background GCOL action and colour.  It 
   does not move the graphics cursor.

   VDU 17
   VDU 17,n
   This is identical to COLOUR n in BASIC. The next byte determines the text 
   colour, see COLOUR for details.

   VDU 18
   VDU 18,a,c
   This is identical to GCOL a,c in BASIC.  The next two bytes determine the 
   GCOL  action and colour respectively (has no effect in text-only  modes). 

   VDU 19
   VDU 19,l,p,0,0,0
   Controls the palette.  Control of the 'normal' palette is as follows:
          VDU 19,logical,physical,0,0,0
   where  the logical colour is the colour specified by the COLOUR  or  GCOL 
   command,  and the physical colour is the actual colour  displayed,  using 
   the same colour numbers as specified for the COLOUR command.  Control  of 
   the 'enhanced palette' is available if a VGA or SVGA card is in use.  The 
   format is one of the following:
          VDU 19,logical+128,colour,0,0,0
          VDU 19,logical+128,-1,red,green,blue
   where  the first form is appropriate for an EGA card with a  6-bit  input 
   'digital'  monitor  (2 bits each of red, green and blue) and  the  second 
   form for an EGA, VGA or SVGA card with an 'analogue' monitor (8 bits each 
   or red, green and blue).

   In some modes it is possible to change the border colour, using the form:
          VDU 19,-1,physical,0,0,0

   VDU 20
   Sets text and graphics colours to their default values (background black, 
   foreground white) and resets the palette.

   VDU 21
   Disable VDU output.  All VDU commands except 1 and 6 are ignored.  If the 
   printer  is  enabled,  VDUs 8,9,10,12 and 13 will still be  sent  to  the 
   printer.

   VDU 22
   VDU 22,n
   This is identical to MODE n in BASIC, except that MODE zeros the value of 
   COUNT  whereas  VDU 22 does not.  VDU 22 also resets  all  screen  driver 
   variables (colours,  palette,  windows, cursor positions, graphics origin 
   etc.).  In particular,  VDU 22 performs the actions of VDU 4, VDU 12, VDU 
   20 and VDU 26. See MODE for further details.

   VDU 23
   Program user-defined graphics characters,  enable/disable cursor or write 
   to 6845 CRT controller registers:
       VDU 23,n,r1,r2,r3,r4,r5,r6,r7,r8 program character n (128-255)
       VDU 23,1,0;0;0;0;                disable cursor
       VDU 23,1,1;0;0;0;                enable cursor
       VDU 23,0,r,x,0;0;0;              write x to 6845 register r
   Note  that user defined characters are available only in graphics  modes, 
   and  that  only character codes 128 to 255 may be  programmed.  VDU  23,0 
   should  be  used  with  care and only with a good  understanding  of  the 
   functions of the registers in the CRT controller.

   VDU 24
   VDU 24,leftx;bottomy;rightx;topy;
   In graphics modes only,  define graphics window. The coordinates are with 
   respect  to the current graphics origin.  If any of the edges of the  new 
   graphics  window would be off the screen,  the command is ignored.  Users 
   are recommended to precede VDU 24 with VDU 26 to reset the origin first. 

   VDU 25
   VDU 25,n,x;y;
   This  is identical to PLOT n,x;y;  in BASIC.  It is ignored in  text-only 
   modes. See PLOT for more details.

   VDU 26
   Reset  text and graphics windows to their default positions (filling  the 
   whole screen),  home text cursor,  move graphics cursor to 0,0 and  reset 
   the graphics origin to 0,0.

   VDU 27
   VDU 27,n
   Send  the  next byte to the screen without interpreting it as  a  control 
   code. Allows graphics characters corresponding to VDU 0-31 and VDU 127 to 
   be displayed. Acts in a similar way to VDU 1 for the printer.

   VDU 28
   VDU 28,leftx,bottomy,rightx,topy
   Set a text window. If the text cursor is currently outside the new window 
   it is moved to the new home position.  If it is inside the new window, it 
   is  not  moved.  If any of the edges of the new text window are  off  the 
   screen, the command is ignored.

   VDU 29
   VDU 29,x;y;
   In  graphics  modes  only,  move the graphics  origin  to  the  specified 
   coordinates.

   VDU 30
   Home the text cursor,  to the top-left hand corner of the text window (or 
   the graphics window, when in VDU 5 mode).

   VDU 31
   VDU 31,x,y
   Identical  to  PRINT  TAB(x,y);  in  BASIC.  Positions  the  text  cursor 
   according to the next two bytes.  The coordinates are with respect to the 
   edges of the current text window.

   VDU 127
   Backspace the cursor by one position and delete the character there.


7. 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   Size needed              25   
      3   Multiple label           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            98   Wrap (BIGBASIC and BIGRUN only)

   Trappable - OS:

     189  Access denied            205  Bad drive
     192  Too many open files      206  Bad directory
     196  File exists              214  File not found
     198  Disk full                222  Channel
     199  Disk fault               251  Bad key
     201  Disk read only           253  Bad string
     202  Device fault             254  Bad command
     204  Bad name


8. BIGBASIC

   BIGBASIC  is  the 'large memory model' version of BBC BASIC  (86),  which 
   allows the "heap" (where BASIC stores its variables and arrays) to exceed 
   64  Kbytes.   A  BASIC program can therefore  store  and  manipulate,  in 
   memory, an amount of data limited only by the RAM capacity of the machine 
   (and by the MS-DOS limit of 640 Kbytes).

   To  the user BIGBASIC appears to work just the same as BBCBASIC; only  in 
   rare  circumstances  will  he need to be aware of  the  differences  (see 
   later).   The  most  obvious distinction is  that  HIMEM,  and  addresses 
   returned  by  DIM,  may well have values in excess  of  &FFFF  (HIMEM  is 
   typically about &79000 in a 640K machine).

   The  user does not need to understand the segmented architecture  of  the 
   80x86  processor's  address  space.  In the same way as  BBC  BASIC  (86) 
   presents  the  user  with a virtual address space from  &0000  to  &FFFF, 
   BIGBASIC  provides  a virtual address space from &00000 to a  maximum  of 
   about  &89000 in a 640K machine.  The exact value of the highest  address 
   depends  on  the  version  of  DOS,  what  memory-resident  programs  are 
   installed etc.

   Apart from the values of the pseudo-variables PAGE, TOP, LOMEM and HIMEM, 
   the  only  occasions  when  the BASIC programmer needs  to  be  aware  of 
   (virtual) addresses within the data area are when he has reserved a block 
   of  memory  with DIM.  Locations within this block  may  be  subsequently 
   accessed  by  indirection  (?, ! and $), by *LOAD and  *SAVE  or  by  the 
   assembler.

   The  indirection  operators  will accept 20-bit addresses  in  the  range 
   &00000  to  &FFFFF, although it must again be made clear that  these  are 
   virtual  addresses  (offsets from the base of BASIC's data  area)  rather 
   than true machine addresses.  

   *LOAD and *SAVE will accept 20-bit (5 digit) virtual addresses.  As  with 
   BBCBASIC (86), specifying a full eight digits for the address causes  the 
   first  four  digits to be interpreted as the segment value and  the  last 
   four as the offset, overriding the virtual address mapping.

   Use of the assembler in BIGBASIC is documented later.

   NOTES:

   a. The value of TOP (the first free byte above the user's BASIC  program) 
      cannot exceed &0FFFF, therefore with PAGE set to its default value  of 
      &900  the user's program cannot exceed &F6FF (63231) bytes in  length.  
      Attempting  to  load a program which would cause TOP to  exceed  &FFFF 
      will result in the "No room" error.

   b. PAGE and LOMEM must be in the range &00400 to &0FFFF (i.e. the  bottom 
      64  Kbytes of the virtual address space).  Attempting to set  PAGE  or 
      LOMEM to a larger value will result in the "Too big" error.

   c. BIGBASIC's stack, which grows down from HIMEM, cannot exceed 64 Kbytes 
      in   size,  thus  limiting  the  depth  of  nesting   of   FOR...NEXT, 
      REPEAT...UNTIL,  GOSUB...RETURN, functions and procedures.   Using  up 
      all   the  available  stack  will  result  in  the  "No  room"   error 
      (untrappable).

   d. Variables and arrays created by the user's BASIC program, and areas of 
      memory reserved with DIM (for assembler routines etc.) can use all  of 
      the available memory between LOMEM and the bottom of the stack.   This 
      is in excess of about 500,000 bytes in a 640K machine.  If this  space 
      is filled, the "No room" error results.

   e. Very  large  arrays  can  be created, although  the  total  number  of 
      elements cannot exceed 65536 (how ever many dimensions) and individual 
      subscripts  cannot  exceed 65535.  For example, DIM A(65535)  and  DIM 
      B(255,255)  each  create an array occupying &50000 (327680)  bytes  of 
      memory.  If there is insufficient space for the array (or the  maximum 
      subscript/number  of  dimensions is exceeded) the  "DIM  space"  error 
      results.

   f. When  run, BIGBASIC by default grabs all but 64K of the machine's  low 
      memory.   The 64K is left so that "external" commands can be run  from 
      BIGBASIC  (e.g. *COPY to copy a file).  The amount of  memory  grabbed 
      can  be  controlled  by an optional switch in the  command  line,  for 
      example:

      C>BIGBASIC /128

      which  tries to grab 128 Kbytes for the data area (i.e. additional  to 
      that  needed  for the interpreter's code).  If successful,  this  will 
      result  in  HIMEM  being set to &20000.   If  insufficient  memory  is 
      available, all of the machine's memory will be taken (leaving  nothing 
      for external commands).  The following command:

      C>BIGBASIC /999

      will result in the maximum possible amount of memory being grabbed for 
      BASIC's use, since there will never be 999 Kbytes free under MS-DOS.

   g. BIGBASIC does not prevent the user setting HIMEM to a value above  its 
      initial  (and thus highest legitimate) value.  However, if he does  so 
      the system will most probably "crash".

   h. The  EVAL function is more restricted in its use than  with  BBCBASIC.  
      In  particular,  EVAL  will not operate correctly if  it  attempts  to 
      activate  (via a user-defined function) any of the  statements  INPUT, 
      READ  or  CALL.   For example, the following  program  will  not  work 
      correctly:

          100 PRINT EVAL("FN1*3")
          110 END
          120 ;
          130 DEF FN1
          140 LOCAL A
          150 INPUT "Enter a number",A
          160 = A

   i. HIMEM  cannot  be changed whilst BASIC's stack is in  use,  i.e.  when 
      inside  a loop, subroutine, function or procedure.  Any attempt to  do 
      so will result in the "Mistake" error.

   j. The  format of data structures within BASIC's heap is  different  from 
      that  of  BBCBASIC.   A program which peeks this  area  (hopefully  no 
      programs  poke it!) will not work correctly without  alteration.   The 
      main  difference is that all items are at paragraph-aligned  addresses 
      (integer multiples of 16 bytes) and all 16-bit pointers to heap  items 
      are the segment value (offset assumed zero).

   k. You  can  *LOAD  or *SAVE a file only up to  &FFFF  (65535)  bytes  in 
      length.   If you try to *LOAD a file longer than this, only the  first 
      65535  bytes of the file will be loaded.  If you try to *SAVE  a  file 
      longer  than 65535 bytes, the length will be evaluated MOD 65536.   In 
      neither case will any error message be produced.

   ASSEMBLER:

   There are differences in the use of the assembler and the interfacing  of 
   assembly  language routines with BASIC (i.e. the CALL statement  and  the 
   USR function).  The main ones are as follows:

   a. Since   the  assembler  necessarily  works  with  64K  segments   (the 
      processor's  instruction pointer is only 16 bits), BASIC's data  space 
      is  considered  for  this purpose as  consisting  of  consecutive  64K 
      regions (&00000 to &0FFFF, &10000 to &1FFFF etc.).

   b. When  a  CALL  or USR is done, the least significant  16-bits  of  the 
      address  become  the  program  counter (IP  register)  and  the  most-
      significant  16-bits are converted into a segment value selecting  the 
      appropriate 64K region.

   c. The  assembler  uses P% as the program counter, as  usual,  where  the 
      least  significant  16-bits  are  assumed  to  be  the  value  in  the 
      processor's  instruction  pointer.  If, when assembling,  the  program 
      counter attempts to cross the boundary between two 64K segments  (i.e. 
      the  least significant word of P% is incremented from &FFFF to  &0000) 
      the "Wrap" error (code 98) results.

   d. Addresses  &0FFxx  are  still used to access the  emulated  BBC  Micro 
      Operating  System  calls,  in particular "read  character  at  cursor" 
      (&FFF4)  and "read character dot pattern" (&FFF1).   Unlike  BBCBASIC, 
      these addresses are entirely possible as true assembly language  entry 
      points  and must therefore be avoided when using the assembler.   This 
      problem may be circumvented by using CALL with at least one  parameter
      (in  addition  to the address) which will enter an  assembly  language 
      routine even if its address is in the range &0FF00 to &0FFFF.

   e. The  parameter block built by CALL is structured differently, since  a 
      16-bit  pointer is inadequate to locate a variable  within  BIGBASIC's 
      extended   addressing  space.   The  first  byte  is  the  number   of 
      parameters,  as  before, and each parameter item consists of  5  bytes 
      (not 3 as with BBCBASIC) as follows:

          Byte 0:    The variable "type", exactly as with BBCBASIC.
          Bytes 1,2: The offset value of the variable or string descriptor.
          Bytes 3,4: The segment value of the variable or string descriptor.

      The contents of the (4-byte) string descriptor differ from BBCBASIC in 
      that  the  16-bit  pointer (bytes 2 & 3 of  the  descriptor)  are  the 
      segment  address  of  the string, which always  lies  on  a  paragraph 
      boundary (i.e. offset = 0000).

      To  give  a specific example: locate a string variable  given  as  the 
      second  parameter of a CALL (e.g. CALL  code,junk,string$),  returning 
      es:bx as the string's address and cl as its length:

          mov  bx,ds:[bp+7]   ;get string descriptor offset (note ds:)
          mov  es,ds:[bp+9]   ;get string descriptor segment (note ds:)
          mov  cl,es:[bx+0]   ;get string length
          mov  es,es:[bx+2]   ;get string segment
          mov  bx,0           ;get string offset

      This may be compared with the equivalent routine for BBCBASIC:

          mov  bx,[bp+5]      ;get string descriptor offset
          mov  cl,[bx+0]      ;get string length
          mov  bx,[bx+2]      ;get string offset

   f. The segment registers are set up by CALL and USR as follows:

          CS:  The code segment of the assembler routine.   If in the bottom 
               64K of BASIC's data space this will be the same as DS;  if in 
               the next 64K region it will be DS+&1000, and so on.

          DS:  BASIC's primary data segment (corresponding to the bottom 64K 
               of  the  data  space).   BASIC's private  workspace  is  from 
               DS:0000 to DS:03FF.   PAGE,  TOP and LOMEM are always in this 
               segment, as is CALL's parameter block.

          ES:  The segment value of the first item in CALL's parameter  list 
               (if  any).   This simplifies the task of writing an  assembly 
               language  routine which is compatible with both BBCBASIC  and 
               BIGBASIC,  so long as CALL has only one parameter (other than 
               a string variable).

          SS:  BASIC's  stack  segment  (i.e.  the  64K  segment  containing 
               HIMEM).   The  assembly language routine can safely use a few 
               tens of bytes of stack below SS:SP.

   g. The  SI  register is set to &FFFF on entry to  the  assembly  language 
      routine.   This allows the routine to test whether it was called  from 
      BIGBASIC  or BBCBASIC, since BBCBASIC always sets SI to a value  other 
      than  &FFFF  on  entry.  Using this, it would  be  possible  to  write 
      assembly language library routines which would run with both  BBCBASIC 
      and BIGBASIC.

   h. When  an  assembly  language  program  uses  absolutely-addressed  RAM 
      locations  for temporary storage, these are best defined using DB,  DW 
      or  DD  within the assembler code itself.  This will  result  in  them 
      being  in the "code segment" and their contents can then  be  accessed 
      using a CS: segment override.  For example:

          mov  cs:[savesp],sp      ;Save stack pointer temporarily
               ......              ;Some code
          mov  sp,cs:[savesp]      ;Restore the stack pointer
               ......              ;Some more code
         .savesp DW 0              ;Define storage location

      The  alternative  of  reserving  the  storage  space  outside  of  the 
      assembler  (using  DIM),  which is acceptable for  the  "small  model" 
      BBCBASIC,  creates the problem of determining which segment it is  in.  
      If  the  storage location's address is in the bottom  64K  (less  than 
      &10000)  then  it  will  be  in  DS:,  but  this  is  an   undesirable 
      restriction.


9. BBCRUN AND BIGRUN

   BBCRUN  and  BIGRUN  are "run-only" versions  of  BBCBASIC  and  BIGBASIC 
   respectively.   They differ from the full interpreters in  the  following 
   ways:

   a. They  have  no  command ("immediate") mode in which  programs  can  be 
      LOADed, SAVEd, LISTed, EDITed etc.  When a BASIC program is terminated 
      with  END or STOP, or simply "falls off the end", the  interpreter  is 
      exited and control is returned to the calling program.  Similarly,  if 
      an  untrapped  (or  untrappable) error occurs, the  error  message  is 
      printed and control is returned to the calling program (e.g. DOS).

   b. They are designed so that the interpreter and the user's BASIC program 
      can be combined into a single .EXE file, which when run directly  from 
      the  DOS  prompt  (for example) is indistinguishable  from  any  other 
      stand-alone  program.  However, the CHAIN statement is implemented  so 
      programs  consisting  of  multiple  modules  or  overlays  are   still 
      possible.   The  combined .EXE file may be up to about  96  Kbytes  in 
      length (approx. 32K for the run-only interpreter and 64K for the BASIC 
      program).

   c. The  following  commands do not exist, and if encountered in  a  BASIC 
      program cause a "Syntax error": AUTO, DELETE, EDIT, LIST, LISTO, LOAD, 
      NEW, OLD, RENUMBER, SAVE and *EDIT.

   The programs BBCRUN and BIGRUN build a composite .EXE file containing the 
   run-only interpreter and the BBCBASIC program, and give it the same  name 
   as  the BASIC program but with the extension .EXE rather than .BBC.   The 
   original .BBC file is not affected.

   The  BBCBASIC program is not checked to see whether it contains  anything 
   which  is  incompatible  with the run-only version, such as  one  of  the 
   commands listed above.  It is up to the user to make these checks.

   BBCRUN and BIGRUN can be run either in an interactive mode, in which  the 
   user  is prompted for the name of the BBCBASIC program etc., or  directly 
   from the DOS prompt by means of command-line parameters (see later).  The 
   latter is useful when run from a batch file.

   The  interactive  mode is initiated by simply typing BBCRUN  (or  BIGRUN) 
   followed  by  RETURN.   In this mode you are asked whether  you  want  to 
   CRUNCH or UNLIST the program: CRUNCHing the program makes it as difficult 
   as  possible  for  someone to examine your code;  it  also  shortens  the 
   program  and  speeds  it  up somewhat,  although  not  all  programs  can 
   successfully  be CRUNCHed. If you cannot (or do not want to)  CRUNCH  the 
   program  it  may still be useful to UNLIST it (assuming  it  doesn't  use 
   calculated line numbers), since this removes the line numbers from  error 
   messages.

   If  you  reply  "Yes" to either question the standard  CRUNCH  or  UNLIST 
   utility   is  invoked  via  COMMAND.COM;  if  CRUNCH.COM  or   UNLIST.COM 
   (respectively) isn't found in the path an error will be reported.  CRUNCH 
   and UNLIST will, as usual, rename the original (listable) program as .BAK 
   but  BBCRUN  and BIGRUN automatically rename the .BAK file back  to  .BBC 
   before  exiting.   If  your  PATH  string  contains  a  non-existent   or 
   inaccessible directory, BBCRUN and BIGRUN will report an error.

   You  have  no control over the value of PAGE at which the  BASIC  program 
   will  reside,  this  is  always &900 (the  default  value  for  the  full 
   interpreters).   This  value allows you to program all  the  user-defined 
   characters  (128  to  255).  Since this means that the  final  .EXE  file 
   incorporates  the region normally containing the user-defined  characters 
   (&500  to &8FF) you are given the option of pre-defining these  when  the 
   .EXE  file  is built.  You are requested to specify the name  of  a  file 
   containing a binary image of the character font data.  If you do not want 
   to pre-define this data, simply press RETURN.

   The  easiest way to create a suitable character font file is to  write  a 
   short  BASIC program to define the characters (using VDU 23...) and  then 
   save  the memory image with *SAVE USERFONT 500 +400.  BBCRUN simply  puts 
   this  file  in the appropriate place in the final .EXE  file,  below  the 
   BASIC program (for testing with the full interpreters you can *LOAD  this 
   file  to  address  500  by hand).  In order for  this  font  data  to  be 
   recognised,  at least one character must be defined conventionally  using 
   VDU 23; if this is not done the data in the file will be ignored.

   In case the final program wants to take parameters from the command  line 
   this is made available to BASIC as a "fixed string" (with leading  spaces 
   stripped)  at address &100.  To access this, the first line of the  BASIC 
   program should copy it into a conventional string variable, as follows:

     10 C$ = $&100

   This  is necessary because location &100 is the "string accumulator"  and 
   is  used  by  BASIC  as a scratchpad during  the  processing  of  several 
   statements.  Since this line will not be meaningful if executed under the 
   full  interpreter  (BBCBASIC  or BIGBASIC) it should  be  replaced  while 
   testing by a line of the form:

     10 INPUT C$

   When  the program has been thoroughly tested the line can be  changed  as 
   per the first example, prior to executing BBCRUN or BIGRUN.

   The  string at &100 will contain the entire command tail except  for  any 
   re-direction  or pipe commands and the /nnn parameter (to  determine  the 
   amount of RAM used) if present.

   The  alternative  way of executing BBCRUN or BIGRUN,  using  command-line 
   parameters, takes the following form:

          BBCRUN progfile [fontfile] [/U] [/C]

   where "progfile" is the name of the BBC BASIC program, "fontfile" is  the 
   (optional)  name of a file containing the user-defined font data and  the 
   switches "/U" or "/C" invoke the UNLIST or CRUNCH utilities respectively.  
   In  this mode BBCRUN does not prompt the user for input unless  the  file 
   progfile.EXE  already  exists.   In this case it will  still  prompt  for 
   confirmation that this file should be deleted.  If run from a batch file, 
   this  can  be eliminated by testing for, and if necessary  deleting,  the 
   .EXE file before activating BBCRUN.


10. ENHANCEMENTS OVER 6502 VERSION

   a. "Implied  integer  variables" are used, i.e.  it is not  necessary  to 
      declare a variable as integer type (with %) for advantage to be  taken 
      of fast integer arithmetic.  For example, FOR...NEXT loops execute  at 
      integer  speed  whether  or not the control variable  is  an  "integer 
      variable", so long as it has an integer value.

   b. END,  or  "dropping  off"  the end of the  program  text,  causes  all 
      currently open files to be closed.  Untrapped errors also close files. 
      STOP leaves files open.

   c. READ # can be used as an alternative to INPUT #.

   d. RUN "filename" can be used as an alternative to CHAIN "filename". 

   e. Commands  (e.g. LIST) can be included in programs but exit to  command 
      level on completion (and don't close files).

   f. CALL can "create" variables; i.e.  variables included in its parameter 
      list need not have been defined before the CALL statement is used.

   g. The  GET  function  is extended so that  GET(n)  returns  the  (8-bit) 
      contents of 80x86 port n, using 16-bit addressing.

   h. A  new statement PUT has been added to output to an 80x86 8-bit  port; 
      the  syntax  is  PUT port,value.  The token value is &CE;  it  has  no 
      unique  errors of its own.  The full 16-bit 80x86 port  addressing  is 
      available.

   i. The compound relational operators (<=,>=,<>) are also accepted in  the 
      reverse order (=<,=>,><).

   j. A  byte  variable (e.g. ?X) may be used as the control variable  of  a 
      FOR...NEXT loop and only one byte of memory will be affected.

   k. AUTO,  DELETE,  LIST and RENUMBER will accept hyphen (-)  as  well  as 
      comma as the line-number delimiter.

   l. "Bad program" does NEW automatically.

   m. Line numbers up to 65535 are permitted.

   n. RENUMBER allows the increment value to be greater than 255.

   o. If  an  invalid  character is encountered in  an  expression,  "Syntax 
      error" is issued rather than "No such variable".

   p. OLD  correctly  restores both most significant and  least  significant 
      bytes of the first line number.

   q. A "LINE space" error is issued if the Lexical Analyser tries to expand 
      a line above 255 characters.

   r. Function and procedure names may terminate in $ or %, e.g. FNLEFT3$ is 
      a valid function name.

   s. An area of memory reserved by DIM is initialised to zeroes.

   t. The  default prompt from an INPUT statement is "? " not "?" (i.e.  the 
      80x86 version prints a space after the query).

   u. REPORT does not output a new-line preceding the error message, so  the 
      message can be positioned anywhere on the screen.

   v. STR$  defaults  to formatting with 9 significant figures  (6502  BASIC 
      defaults  to 10 significant figures).  For example,  STR$(9/10)  gives 
      "0.9" with the 80x86 version and "0.8999999999" with the 6502 version.


11. OTHER DIFFERENCES BETWEEN THE VERSIONS

   a. The  internal  format of programs is slightly  different.   The  first 
      three bytes of each program line (length, line number LSB, line number 
      MSB)  are in reverse order compared to the 6502 version. There  is  no 
      initial &0D byte: the length-byte of the first program line is  stored 
      at PAGE.  The program is terminated by a line of length zero and "line 
      number" &FFFF.  Spaces between the line number and the first character 
      of  the  line are NOT permitted (in DEF and DATA statements)  and  are 
      stripped automatically on entry.

   b. Arithmetic  operations and functions do NOT use identical  algorithms; 
      in particular the transcendental functions are evaluated using  power-
      series  expansions  rather than  continued-fraction  expansions.   The 
      accuracy  of  the results is comparable (approximately  9  significant 
      figures).

   c. Three  or more digit exponents (e.g. 1E123) are  treated  differently; 
      the 80x86 versions evaluate the full exponent and give "Too big" or  a 
      zero result depending on the exponent sign.  The 6502 version  accepts 
      only the first two  digits (i.e.  1E123 is treated as 1E12 followed by 
      3).

   d. If the number of significant figures called for by @% is greater  than 
      10,  and  E-format or F-format is selected, the  80x86  versions  will 
      print trailing zeros whereas the 6502 version treats all  out-of-range 
      values of @% as 10.

   e. The  numeric  range of floating-point numbers is  different.   In  the 
      80x86 versions it is approximately 5.9E-39 to 3.4E38.

   f. If  an attempt is made to search for the occurrence of a  null  string 
      within  a string, INSTR returns 0 in the 80x86 versions and 1  in  the 
      6502 version.

   g. COUNT  in the 80x86 versions counts all characters with  ASCII  values 
      greater than 13.  COUNT is set to zero by carriage-return (ASCII  13). 
      Characters  with ASCII values less than 13 (e.g. line-feed, ASCII  10) 
      have no effect on COUNT.

   h. "New line" in the 80x86 versions is carriage-return, line-feed  rather 
      than line-feed, carriage return.

   i. Line number zero cannot be entered.

   j. The  format of data files is quite different.  Strings are  stored  as 
      the characters of the string followed by carriage return.  Numbers are 
      stored as five bytes of binary.

   k. A  single  stack  (the processor's hardware stack)  is  used  for  all 
      nesting  and  looping structures and for storage of  local  variables. 
      There are no "Too many FORs", "Too many GOSUBs" or "Too many  REPEATs" 
      errors;  all give "No room" (untrappable) when the free space is  used 
      up.  Because of the single stack you cannot jump out of (for  example) 
      a  FOR...NEXT  loop  and then encounter (say)  RETURN.  Similarly  you 
      cannot  use  a subroutine or FOR...NEXT loop to  save  variables  with 
      LOCAL.

   l. The  80x86 versions will tolerate omission of the statement  separator 
      (:) in multi-statement lines when this does not lead to ambiguity.

   m. The  assembler is for the 80x86 and uses Intel mnemonics  and  syntax; 
      comments  are introduced by ";".  There is no "Byte" error, but  there 
      are  new "Multiple label" and "Size needed" errors.  There must  be  a 
      delimiter  (e.g. a space) between the op-code and the operand(s).  DB, 
      DW  and  DD  are equivalent to EQUB/EQUS, EQUW and EQUD  in  the  6502 
      version.

   n. CALL  and  USR  work slightly differently  because  of  the  different 
      processor.  For  example, A%, B%, C%, D% and F% are  copied  into  the 
      processor's  registers.  The order of items in CALL's parameter  table 
      is different.

   o. Determination  of  ERL is done differently and  occasionally  gives  a 
      different  result, particularly in function and procedure calls.  E.g. 
      if  an error occurs in a procedure call the 6502 version may give  the 
      "error  line" as the line containing the definition whereas the  80x86 
      versions  always gives the line containing the call.  This is  usually 
      more helpful.

   p. There is no "$ range" error.

   q. LOCAL, READ and VDU cannot accept a null list of arguments.

   r. Line  numbers are "executed" more frequently than in the 6502  version 
      and this can be evident when in TRACE mode.

   s. Integer  variables  do  not increment or  decrement  in  a  "circular" 
      fashion; you get "Too big" if you try to increment above &7FFFFFFF  or 
      decrement below &80000000.

   t. If a "Mistake" error occurs, the variable is created.  For example, if 
      OLD is mis-spelled then the program in memory may be corrupted.

   u. If  line 65535 does not exist, the statement GOTO 65535 is  equivalent 
      to END.

   v. The random number generator is initialised by RUN, therefore RND  will 
      return zero until RUN (or CHAIN) is first issued.

   w. LISTO defaults to 7.

   x. In AUTO, line numbers are preceded by the usual command prompt.

   y. STOP  is not a fatal error; in particular it does not  affect  REPORT, 
      ERL or ERR.

   z. An empty assembler statement (e.g. "[" on its own) does not result  in 
      the program counter being printed.

  aa. A  calculated  line number expression after GOTO,  GOSUB,  RESTORE  or 
      TRACE must be enclosed in parentheses.

  ab. READ  accepts  any non-space character as a DATA delimiter  (not  just 
      comma)  and  may  give odd results if the DATA  statement  is  wrongly 
      formed.

  ac. "@"  is  a  valid character within a  variable  name.   Therefore  the 
      statement  "PRINT  ABC@%" will print the value of the  variable  ABC@% 
      rather than the value of ABC followed by the value of @%.

  ad. The  string  space  allocation algorithm is different  from  the  6502 
      version.

  ae. MOD and DIV never issue the "Division by zero" error.

  af. The INPUT statement cannot be invoked from an immediate command  (even 
      if within a procedure or subroutine).

  ag. If  two  functions or procedures are defined with the same  name,  the 
      80x86 versions will use the definition nearest the end of the program.

  ah. The  ON...GOSUB...ELSE  construct executes any statements  after  ELSE 
      only  if  the  control  variable is out of  range.  The  6502  version 
      unconditionally executes any subsequent statements on the same line.

  ai. Trailing spaces are not automatically stripped from input lines.

  aj. RENUMBER may be confused by comments or literal strings containing the 
      character &8D.

  ak. VDU does not accept the trailing "|" delimiter.
