                              Z88 BASIC Patch

The version of BBC BASIC resident in the Cambridge Computer Z88 is deficient 
in  a  few respects,  especially in the lack of any  editing  facilities  or 
support for graphics operations.   The purpose of the BASIC Patch program is 
to provide some of these capabilities.

The  patch program is installed with a simple CHAIN command,  and thereafter 
remains resident until the machine is reset or BASIC is KILLed.  It occupies 
two  kilobytes of memory,  and results in the value of PAGE being raised  to 
&2B00;  when  the graphics operations are used a further 2K is used for  the 
display buffer.

The patch will work only on an expanded machine (at least 128 Kbytes of  RAM 
installed in slot 1).   If this is not the case,  or if the available memory 
has been deliberately reduced by changing HIMEM,  the message "No RAM"  will 
be displayed when the program is CHAINed.

The new features provided by the patch program are as follows:

*EDIT line number

     This command allows you to edit a specified program line.   It  results 
     in  the  line  being displayed (after a short delay)  with  the  cursor 
     positioned at the end,  and you can then edit the line using any of the 
     usual line-editing features, as follows:

          left           Move cursor left one character
          right          Move cursor right one character
          SHIFT left     Move cursor left one word
          SHIFT right    Move cursor right one word
          <> left        Move cursor to start of line
          <> right       Move cursor to end of line
          DEL            Backspace and delete
          SHIFT DEL      Delete character under cursor
          <> DEL         Delete entire line
          <> D           Delete from cursor to end of line
          <> G           Delete character under cursor
          <> S           Swap case
          <> T           Delete up to next space
          <> U           Insert space at cursor position
          <> V           Toggle between insert and overtype

     To enter the edited line into the program press ENTER;  to abandon  the 
     edit and leave the line unchanged press ESC.

     You  can  also use *EDIT to concatenate two or more program  lines,  by 
     specifying the first line and last line separated by commas (e.g. *EDIT 
     10,30).  In this case you will have to edit out the line numbers of the 
     second and subsequent lines (and delete the old lines afterwards).

     *EDIT may be abbreviated to *E. (the dot is required).


MODE n

     The  MODE statement allows selection of the normal text-only mode (MODE 
     0)  or  a text-and-graphics mode (MODE 1).   In MODE 1 the  display  is 
     split into two parts:  a text-window on the left and a  graphics-window 
     on the right.  The text window consists of 8 rows of 50 characters, and 
     the  graphics window is 64 pixels high by 256 pixels wide;  you  cannot 
     (normally) mix text and graphics in the same window.

     Points in the graphics window are addressed as x,y coordinates from 0,0 
     (the bottom-left corner) to 255,63 (the top-right corner), although the 
     origin can be moved using the PLOT -1 statement (q.v.).

     Although MODE 1 sets up the window positions and sizes as described, it 
     is  possible  to  change these using the VDU  statement.   However  the 
     method of doing this is outside the scope of this document.   It is not 
     advisable to cause the text and graphics windows to  overlap,  although 
     this may occasionally be useful.

     MODE  clears  the display (both text and graphics windows),  moves  the 
     text  cursor  to  0,0 (the top left of the  text  window),  resets  the 
     graphics  origin and moves the graphics cursor to 0,0 (the bottom  left 
     of the graphics window).

     In  MODE  0  (the  normal  94-column  text  mode)  the  other  graphics 
     statements have no effect.


CLG

     This clears the graphics window (only); it does not affect the position 
     of  the graphics cursor.   Note that CLS can be used to clear the  text 
     window and leave the graphics window unchanged.


DRAW x,y

     Draws  a  straight line (in black) between the current position of  the 
     graphics cursor and the specified coordinates,  then moves the graphics 
     cursor to the specified position.

     This statement is identical to PLOT 5.


MOVE x,y

     Moves  the graphics cursor to the specified coordinates,  but does  not 
     affect what is displayed.

     This statement is identical to PLOT 4.


PLOT n,x,y

     A multi-purpose plotting statement,  whose effect is controlled by  the 
     first parameter n:

          n              action

          -1        Move the graphics origin to x,y.

          0         Move the graphics cursor relative to the last point.

          1         Draw a line, in "black", relative to the last point.

          2         Draw a line, in "inverse", relative to the last point.

          3         Draw a line, in "white", relative to the last point.

          4         Move the graphics cursor to the absolute position x,y.

          5         Draw a line, in "black", to the absolute position x,y.

          6         Draw a line, in "inverse", to the absolute position x,y.

          7         Draw a line, in "white", to the absolute position x,y.

          8-15      As 0-7,  but plot the last point on the line twice (i.e. 
                    in the "inverting" modes omit the last point).

          16-31     As 0-15, but draw the line dotted.

          32-63     As  0-31,  but  plot the first point on the  line  twice 
                    (i.e. in the "inverting" modes omit the first point).

          64-71     As 0-7, but plot a single point at x,y.

          72-79     Draw a horizontal line left and right from the point x,y 
                    until the first "lit" pixel is encountered,  or the edge 
                    of the window.  This can be used to fill shapes.

          80-87     Plot  and fill a triangle defined by the two  previously 
                    visited points and the point x,y.

          88-95     Draw  a  horizontal line to the right of the  point  x,y 
                    until  the  first "unlit" pixel is encountered,  or  the 
                    edge of the window. This can be used to "undraw" things.

          96-103    Plot  and  fill a rectangle whose opposite  corners  are 
                    defined by the last visited point and the point x,y.

     
POINT(x,y)

     This function returns the state of the pixel at the specified location, 
     as  0  (unlit)  or  1 (lit).   If the specified point  is  outside  the 
     graphics  window  (taking  into account the position  of  the  graphics 
     origin), or if MODE 0 is selected, the value -1 is returned.

The graphics statements COLOUR and GCOL are not implemented.
Installation of the BASIC Patch has a number of "side effects" of which  you 
should be aware:

1.  Changing  HIMEM will have the effect of disabling the patch.   If  HIMEM 
    has  been  changed it must be set back to &C000 before  re-CHAINing  the 
    patch program (or alternatively KILL and re-start BASIC from the INDEX).  
    Changing  HIMEM is not recommended in any case,  since setting it to  an 
    unsuitable value will "crash" the machine (even without the patch).

2.  The "Silly",  "RENUMBER space" and "LINE space" errors will not  appear; 
    instead the "No room" message will be produced in each case.

3.  You  are  advised to select MODE 0 before entering Pipedream,  since  it 
    seems to get confused by the presence of the graphics window.

4.  Since  Cambridge  Computer provided no "legal" method  of  installing  a 
    patch  such  as  this (indeed,  for a long time I thought  it  would  be 
    impossible!),  a rather "dirty" method has had to be adopted.   This has 
    some unfortunate, but unavoidable, consequences:

    (a) The  RUN  and CHAIN commands may occasionally fail to work  properly 
        (on  average fewer than 1 in 1000 times).   If this happens no  harm 
        will be done; simply issue the command again.

    (b) If  you  reply to the INPUT statement with a very long string  (more 
        than 252 characters) the machine will crash, so you must avoid doing 
        so.

5.  Using  graphics  statements  in an ON ERROR routine may  give  anomalous 
    results.  For example:

          10 ON ERROR MODE 0 : REPORT : END
          20 MODE 1
          30 REPEAT
          40   DRAW RND(256)-1,RND(64)-1
          50 UNTIL FALSE

    The above program can be exited only by pressing ESCape.   The intention 
    is that this will cause the display to clear and the message "Escape" to 
    be  displayed.   In  practice,  the message actually displayed  will  be 
    "Sorry,  not implemented" since,  although the Patch is active, the MODE 
    statement still affects REPORT, ERR and ERL.


The  patch  has  been tested only with EPROM Operating System  version  2.2, 
although  it should also work with ROM version 3.0.   Since it of  necessity 
depends  on  certain  specific features of the  Operating  System  remaining 
unchanged,  I  cannot guarantee that it will operate correctly (or  at  all) 
with other versions.  (Note: to discover the version of your machine when in 
BASIC, press HELP then the left-arrow key).


Richard Russell, 27th March 1988.

STOP  PRESS  Version  2.1  includes a  graphics  dump  for  Epson-compatible 
printers.  The statement CALL 11011 will dump the graphics window.

Email: richard@rtrussell.co.uk              Web: http://www.rtrussell.co.uk/
