
-------------------------------------------------------------------------------

        Z X 8 1   C O R A L   B A S I C   I N T E R P R E T E R

                              version 7.0
                 copyright by Carlo Delhez, 1987 - 1993

          English manual first started 27th of September 1992
                   manual version 0.10 as of 93-12-07

-------------------------------------------------------------------------------

ZX81 Coral Basic Interpreter was first marketed by Terminal Software, Baarle
Nassau, Netherlands. The original Dutch manual is ISBN 90-6883-041-4, first
printed November 1987.

-------------------------------------------------------------------------------


INTRODUCTION

CBI is an acronym for Coral Basic Interpreter. It combines the efficiency
of a new and fast Pseudo Screen Editor with the ease of a powerful extension
of the ZX81 BASIC.

CBI provides you with a new Full Entry Editor which can be used in Line
Mode or Pseudo-Screen Mode. All the disadvantages of the (rather slow) regular
ZX81 editor have vanished, e.g. as a result of the Auto Repeat on all keys,
yet all its useful features, such as Direct Syntax Check and Pull Down Edit,
are still available! Moreover, the Full Entry Editor is completely
space-insensitive, so any computer freak can easily use a ZX81 now without
actually having to know which keys to press to obtain the various keywords.

Additionally, the ZX81 BASIC has been extended with 43 new commands and
many `old' commands have been revised for faster or better operation.
The new possibilities include:

(1) Several useful programming aids, such as automatic line numbering,
    deletion of large blocks of program lines by a single command,
    data protection against NEW, CLEAR and RUN, program renumbering,
    tracing and deceleration of program execution, etc.

(2) The possibility to use Pascal- and C-like structures, making commands
    like GOTO and GOSUB completely superfluous: Procedures with two-way
    data transport (any number of strings or numerical variables may
    be used for data exchange), conditional loop structures (DO, LOOP,
    EXIT, WHILE, UNTIL), expanded IF statement that allows for conditional
    execution of a block of program lines and also offers an ELSE condition.
    And ofcourse, all these structures may be nested at will!

(3) Efficient data manipulations by way of commands like DATA, READ and
    RESTORE; easy stack manipulations via POP, PUSH, DUP, CLR STACK.

(4) Useful applications for machine code programmers such as DPOKE, DPEEK
    and CALL, and also the unique possibility to expand the ZX81 BASIC
    even further with your own machinecode routines which may read the
    required parameters directly from BASIC.

(5) Faster and improved graphical capabilities.

Even though CBI offers so many advanced features, the actual code is only
some 5k in length and is stored above RAMtop (by default). CBI is suited
to be used with all existing ZX81 BASIC and machine code programs.
Programs written in CBI can also be used on a `normal' ZX81, provided
that you don't use the new commands in your program.


STARTING CBI

By default, the code of CBI is stored above RAMtop. Before loading the
program, you must reserve space for the code. Type the following commands
to achieve this:

                POKE 16388,8
                POKE 16389,107
                NEW

Now you can load the program:

                LOAD "CBI"

After loading, press any key to clear the ZX81. CBI can now be activated
by a call to address 27400:

                RAND USR 27400

If all goes well, the normal message 0/0 should appear (yet one line higher
than usual) and just below it a black block: the cursor. CBI is now ready
to be used.

NOTE 1 : In some cases the ZX81 may switch from CBI to its `normal'
         operating system (i.e. the K-cursor reappears). This happens for
         example after the NEW command. In such cases, CBI can be restarted
         by typing the command  RAND USR 27400  again. If this doesn't bring
         you back to the CBI cursor, type  POKE 16393,0  first, and then
         try again. If this still doesn't work, reset the ZX81 and reload
         CBI.

NOTE 2 : If you wish to restart CBI without leaving it, the command
         POKE 16393,0  must be typed. This will refresh all the system
         variables held by CBI.

NOTE 3 : As CBI is quite an extensive and advanced piece of software, it
         may still contain bugs. If you have problems with CBI or discover
         bugs, please contact me at the address at the bottom of this
         document.


USING THE NEW EDITOR

Directly after having started CBI, the cursor appears in the
bottom-lefthand corner of the screen (the black block). The cursor
indicates where the text that you're typing will appear. Contrary to the
conventional ZX81 editor, the CBI editor is a so-called 'Full Entry
Editor' which means that all commands need to be typed in full, letter
by letter. Pressing (for example) the key 'P' will simply show the
letter 'P' and NOT the keyword 'PRINT'. For obtaining the keyword
'PRINT', you'll have to hit the keys 'P', 'R', 'I', 'N' and 'T'. They
may seem cumbersome, but you'll get used to it soon enough and discover
that it's more natural to use such an editor!

This 'full entry' is the main difference with respect to the 'old' ZX81
editor. Additionally, you'll discover that the CBI editor always responds
quickly and accurately to the keys you press - independent of the length
of the current edit line. The RubOut and Cursor Left/Right keys are still
the same, so these won't cause any problems.

Also new is the auto-repeat facility on all keys. Keeping a key pressed
down for more than, say, 1/3rd of a second will cause quick repetition
of this key for as long as you keep it pressed down. This seems
particularly useful for the cursorkeys and RubOut, but could be used for
other purposes as well.

The CBI editor is space-insensitive, so space between commands and
parameters may be omitted at all times. If you do add spaces, CBI will
ignore these. Spaces at improper positions will also be ignored.
The following three lines will all have the same effect:

        PRINT AT 5,0;"SPAC";CHR$ 42
        PRINTAT5,0;"SPAC";CHR$42
        P RIN TAT5  ,0; "SPAC" ; CH R$4 2

If the line has a linenumber, CBI will make sure that the command appears
with proper lay-out in the listing. For example:

        10IFINKEY$<>CHR$118THENGOTO10
becomes
        10 IF INKEY$<>CHR$ 118 THEN GOTO 10

Text between quotes will be left unchanged by CBI. Also, the number of
spaces inbetween a linenumber and the command should be set manually by
the user for proper program indentation (yet another feature of CBI!):

        - no space           : CBI will add one
        - one or more spaces : CBI will keep them

One of the advantages of the ZX81 editor is the direct syntax check.
This feature has been improved with CBI. If a line contains a syntax
error, CBI will reprint the line with proper spacing AND put the cursor
at (or close to) the place where the syntax error occured. This makes
correcting of the error extremely easy!

If you actually entered the above line, you will have noticed that you
didn't get a program listing after having pressed NewLine. By default,
CBI is in 'NOSTALGIC' mode: CBI then resembles the original ZX81 a lot,
but there are some differences. Not getting a listing is one of them.
Nostalgic-mode (N-mode) is characterized by the following features:

        1) Edit-line and Input always in line 23
        2) Errormessages always in line 22
        3) CLS after each direct command
        4) Error 5 if printing goes beyond line 21

As you may notice, N-mode is very well suited to run existing ZX81
programs. After LOADing a program from tape, CBI will detect if this
program was written with CBI and, if this is not the case, switch to
N-mode automatically, thus making sure that the programs still runs OK.

N-mode was not designed for writing programs: CBI-mode is much better
suited for that purpose, providing a Pseudo Screen Editor. You can enter
CBI-mode by typing

        NOSTALGIC OFF

The cursor will now appear in the top-lefthand corner of the screen. In
CBI-mode the entire screen can be used for EDIT, LIST and PRINT. Hitting
NewLine several times will move the cursor downward. Typing the command

        PRINT "HULLO GLOBE"

will print the text immediately below the command and the cursor will
appear yet one line lower. The message '0/0' will not be shown after
each command. But typing the command

        PRINT ZX81

WILL show the error message '2/0' and the cursor just below it. In case
you forgot what error 2 means, type

        ERR MSGS ON
        PRINT ZX81

and this time, the error will be explained in plain English.
When the cursor reaches the bottom screen line, the screen will automatically
be scrolled upward. CBI-mode is characterized by the following features:

        1) Full screen available for editor and Input
        2) Errormessages at current print position
        3) CLS only on explicit command
        4) Automatically upward scrolling screen

All the usual ZX81 symbols (including the graphics) can be accessed via
the CBI editor. For graphics, press the Graphics key (Shift-9) once; the
cursor won't change, but CBI will now interpret subsequent keypresses as
graphics symbols (e.g. inverse letters). Pressing the Graphics key once
more will bring you back to the usual character mode.
There is an important application for the graphics symbols within the CBI
editor: any unquoted text which is typed in inverse video will be ignored
by the full entry decoder yet be reversed to normal video. As an example:

        LET TANGENT=Y/X

could normally not be typed with the CBI editor as the keyword 'TAN' is
recognized by the keyword decoder, thus reporting a syntax error:

        LET TAN GENT=Y/X

However, if you type the word 'TANGENT' in inverse video, there's no such
problem! Also consider the following example:

        PRINT VAL "COSPI"

This will give error report 2. Now type the line again, but with the two
quotes in inverse video: this makes the string delimiters 'invisible' for
the keyword decoder, hence the keywords 'COS' and 'PI' are recognized!
It is essential to invert BOTH quotes: an odd number of quotes will cause
a syntax error.

Since CBI does not show the program listing after adding a new line to
the program, the cursor-up/down keys are no longer useful for moving the
programline-cursor. The cursor-up key is not used by CBI, the cursor-down
key has a new functionality: it leaps out of the current editline without
executing it! Since there is no program cursor anymore, Edit (Shift-1) can
also not be used. Instead, the more flexible EDIT command is now available.
Any line of the program can be accessed immediately by typing

        EDIT linenumber

You can then change the line at will and enter by NewLine, or leave it
without any change via the cursor-down key (Shift-6).

It may take a while before you are fully used to the new editor, but I'm
sure that you will then enjoy using it and outgrow the 'old' ZX81 editor.


THE 'OLD' COMMANDS

Some of the familiar ('old') ZX81 commands have been improved or changed
in Coral Basic. These changes are discussed below.

------  CLS  ------------------------------------------------------------------

Still works in the same way, but is now significantly faster.

------  FAST  -----------------------------------------------------------------

The CBI editor always uses SLOW mode as to prevent annoying screen flashes.
Typing the command FAST seems to have no effect at all. However, CBI remembers
that this command was given and will switch to FAST mode as soon as a command
or program is executed.

------  GOSUB  ----------------------------------------------------------------

This command is still available for reasons of compatibility. However, the
ample possibilities of structured programming offered by CBI (e.g. procedures
and loops) make this command more or less superfluous. Try to avoid it in
newly written software!

------  GOTO  -----------------------------------------------------------------

See GOSUB - the same applies.

------  INPUT  ----------------------------------------------------------------

The syntax of this command has been changed. The usual forms `INPUT A' and
`INPUT X$' are still available, but there now also is a possibility to
include a quoted text between the INPUT command and the variable. Examples:

        INPUT "HOW MANY: ";NUMBER
        INPUT "NAME? ";N$

The quoted text will be printed at the current PRINT position and the usual
INPUT cursor appears directly after it (CBI mode), or in the bottom screen
line (N mode). Try the following program in CBI-mode as well as in N-mode:

        10 INPUT ">";X          { simple calculator! }
        20 PRINT X
        30 GOTO 10

------  LIST  -----------------------------------------------------------------

There is a difference between LIST in N-mode and in CBI-mode. In N-mode, the
the program is listed from the specified linenumber onwards until the top
22 lines of the screen are full. In CBI-mode, the program gets listed in
subsequent blocks of 23 lines each. After every block, you have to press a
key. Press SPACE (Break) to abort the LIST command, or any other key to
continue with the next block. After Break, CBI returns to edit mode or
executes the next programline in case the LIST command was part of a Basic
program. Keeping the Break key pressed down, will eventually produce error D.

------  LLIST / LPRINT  -------------------------------------------------------

After having aborted a LLIST or LPRINT command via the Break key, it is
advised to issue an LPRINT command before proceeding. This empties the
printerbuffer and reinitializes the system variables concerned.

------  LOAD  -----------------------------------------------------------------

See SAVE - the same applies.

------  NEW  ------------------------------------------------------------------

This command not only clears the RAM memory below RAMtop, but also temporarily
deactivates CBI. Restart CBI via RAND USR 27400.

------  PLOT  -----------------------------------------------------------------

Much faster than the old PLOT routine.

------  PRINT  ----------------------------------------------------------------

In N-mode, the PRINT command works exactly the same as in ZX81 Basic.
For CBI-mode, it must be noted that PRINTing does NOT result in automatic
upward screen scrolling if the screen gets filled within a single PRINT
command. Try the following programs in CBI-mode and note the difference:

        10 PRINT "12";          and     10 PRINT "123";
        20 GOTO 10                      20 GOTO 10

------  REM  ------------------------------------------------------------------

All the text after a REM is ignored by the full-entry decoder.
There is a small 'bug' in the CBI code that adds a space between the REM and
the following text each time you edit and reenter the line. So, remove one
space each time you edit a REM line to compensate for this bug.

------  SAVE  -----------------------------------------------------------------

Apart from the conventional ZX81 system variables, the Basic program and the
Basic variables, also some specific CBI system variables get saved. For
details about CBI system variables being saved, read the relevant section.
After loading, these system variables are restored properly.

------  SCROLL  ---------------------------------------------------------------

Much faster and does not distort the display file. At all times, avoid using
the conventional ZX81 SCROLL routine in combination with CBI.

------  SLOW  -----------------------------------------------------------------

See FAST - the same applies.

------  UNPLOT  ---------------------------------------------------------------

Much faster than the old UNPLOT routine.

-------------------------------------------------------------------------------


THE NEW COMMANDS

In the following section, all new commands offered by CBI are summed up
alphabetically with required syntax, brief explanation of usage and - where
needed - one or more examples.

The required syntax is written down with special symbols. These are:

- bln           : boolean value (zero for false or non-zero for true);
                  a boolean value is used by conditional commands like IF.
                  example:  X<Y AND Y>100
- data_list     : a list containing any number of numerical expression and/or
                  string expressions, with successive entries separated by
                  commas (','). String expressions need to be preceeded by
                  a period ('.') as well.
                  example:  81,.("ZX"+STR$ 81),92,."CBI"
- name          : consists out of alphanumerical symbols; the first symbol
                  must be a letter (not a number).
                  example:  PROFIT89NET
- sw            : switch word; can be ON or OFF.
- swv           : switch value; can be 1 (for ON) or 0 (for OFF).
- var           : name of a numerical variable that need not be declared yet.
                  example: OLDX
                       or: A(10,3)
- $var          : name of a string variable that need not be declared yet.
                  example: R$
                       or: X$(3)
- x y z         : numerical expressions.
                  example: 127
                       or: 3*R/(2*Q*B(1)+1)
                       or: COS(PI*H/6)
- [...|...]     : represents a choice between two possible items.
                  example: [ UNTIL | WHILE ]
- {...}         : optional part of the sytax; may - but need not - be omitted.
- {x}           : numerical expression or nothing; when no numerical expression
                  is typed by the user, the value x=0 will be assumed.


------  AUTO x STEP y  --------------------------------------------------------

Each time the cursor appears on the screen, a line number will be printed
automatically. The line number starts with value x and is incremented in
steps y. The auto-function ends when an empty line is entered (i.e. by
pressing NewLine immediately after the line number) or when the line
number exceeds 9999. AUTO also works with numerical INPUT statements (may
be used to show a default value which may be altered by the user).

Example:        AUTO 50 STEP 10         generates 50,60,70,...
                AUTO 92 STEP 9999       generates 92 only


------  BREAK sw  -------------------------------------------------------------

Enables the user to enable/disable the break key function. When the edit
mode is entered (e.g. after an error message), break is automatically enabled
again. When the break key is disabled, a program can also not be halted by
typing STOP for an INPUT value.

Example:        10 BREAK OFF
                20 DO UNTIL INKEY$="S"
                30 LOOP

This program can only be stopped by pressing "S". Note that the break key
always remains enabled during LOAD and SAVE.


------  CALL x  ---------------------------------------------------------------

Calls the machine code program at address x. CALL replaces RAND USR and
similar commands.

Example:        CALL 2602       wipes the screen (ROM routine for CLS).


------  CHAR x  ---------------------------------------------------------------

Equivalent to PRINT CHR$ x; but takes care of automatic scrolling when the
screen gets filled in CBI-mode and is suited for all characters (including
the new CBI keywords).

Example:        10 FOR K=0 TO 255
                20  CHAR K
                30 NEXT K               prints the entire character set.


------  CLR STACK  ------------------------------------------------------------

Clears the entire stack. CLR STACK should be used after having interrupted a
subroutine or a procedure by Break and you don't want to resume its execution.
This prevents unwanted `stack growth'.

Example:        10 GOSUB 30
                20 STOP
                30 CLR STACK
                40 RETURN

You'll get error 7/40 because CLR STACK deleted the return line number.


------  CURSOR x  -------------------------------------------------------------

Lets CHR$(x) act as a cursor in the CBI line editor. Use only single-position
characters (no keywords) and also no control codes (like NewLine).

Example:        CURSOR 131              gives 'half' a cursor.


------  DATA data_list  -------------------------------------------------------

Provides the data for a READ statement. It is necessary to issue a RESTORE
command at least once in the program in order that the data-pointer has a
proper value.

Example:        10 RESTORE
                20 READ N$
                30 READ NUMBER
                40 PRINT N$;NUMBER
                50 DATA ."ZX",81


------  DEF PROC name  --------------------------------------------------------

Starts the definition of a procedure named 'name'. This definition must be
ended by an END PROC statement. The procedure may be called by the command

        name{:data_list}

and in case the data_list is added, the data-pointer will be set to point to
it, so that the parameters in the list may be read by READ commands.
When a DEF PROC is encountered during execution of a program, its entire
definition block will be skipped (i.e. not executed). Procedure definitions
may be nested, but this is not advised. DEF PROC should not be used as a
direct command.

Example:        10 DEF PROC ENIGMA
                20  READ X$
                30  FOR K=1 TO LEN X$
                40   LET X$=X$(2*K-1)+X$
                50  NEXT K
                60 END PROC .X$( TO LEN X$/2)
                65
                70 ENIGMA:."DESREVER"
                80 READ E$
                90 PRINT E$


------  DELETE x TO y  --------------------------------------------------------

Removes all the lines with number x through y from the program. Neither line x
nor line y need actually exist. DELETE may only be used as a direct command.

Example:        DELETE 0 TO 9999        deletes entire program


------  DO { [UNTIL|WHILE] bln }  ---------------------------------------------

The DO command indicates the beginning of a (conditional) loop structure,
which has to be ended by a matching LOOP command. The three possible
structures are:

        DO           ... LOOP   : unconditional (infinite) loop
        DO UNTIL bln ... LOOP   : repeat until bln=true (1)
        DO WHILE bln ... LOOP   : repeat while bln=true (1)

It is possible to leap out of each of these three structures by way of an
EXIT command within the loop. The DO...LOOP structures may be nested at will.

Example:        10 INPUT X
                20 LET Y=X
                30 DO UNTIL Y*Y=X
                40  LET Y0=Y
                50  LET Y=(Y+X/Y)/2
                60  IF Y0=Y THEN EXIT
                70  PRINT "SQR(";X;")=";Y
                80 LOOP


------  DPEEK var,x  ----------------------------------------------------------

Double peek (word value), equivalent to the more cumbersome command:

        LET var=PEEK x+256*PEEK (x+1)

Example:        DPEEK DF,16396          lets DF point to the display file


------  DPOKE x,y  ------------------------------------------------------------

Double poke (word value), equivalent to the more cumbersome set of commands:

        POKE x,y-256*INT (y/256)
        POKE x+1,INT (y/256)

Example:        DPOKE 32734,DF+1

has the effect of HOME (also see example at DPEEK for definition of DF).
A number that has been stored by DPOKE can be read by DPEEK and vice versa.


------  DRAW TO x,y  ----------------------------------------------------------

Draws the best possible line from the last plot position to position (x,y).
Note that a line drawn from (a,b) to (c,d) is not exactly the same as a line
drawn from (c,d) to (a,b). For wiping a line drawn by DRAW, UNDRAW must be
applied in the same direction.

Example:        PLOT 0,0
                DRAW TO 63,43           draws a line across the screen


------  DUP var  --------------------------------------------------------------

Copies the value of the top element of the stack into variable var. The stack
itself remains unaltered.

Example:        10 DEF PROC WHERE
                20  DUP RT
                30  PRINT "CALLED FROM ";RT
                40 END PROC
                80 WHERE


------  EDIT x  ---------------------------------------------------------------

Moves line x (or the first line with a number higher than x) into the editor.
May only be used as a direct command.


------  ELSE  -----------------------------------------------------------------

To be used in combination with WHEN - see there.


------  END PROC {data_list}  -------------------------------------------------

Indicates the end of a procedure definition. When the procedure is executed
and the data_list after the END PROC is present, the data pointer will be
set to point to this data_list, so READ commands can be used to read the
data. For an example of a procedure with two-way data exchange see DEF PROC.


------  END WHEN  -------------------------------------------------------------

Indicates the end of a WHEN structure - see WHEN for more details.


------  ERR MSGS sw  ----------------------------------------------------------

When ERRor MeSsaGeS are on, all error messages will be briefly explained in
plain English. Unknown error messages will be commented as 'ERROR?'.

Example:        ERR MSGS ON             enable error messages
                PLOT 100,100            ... B/0 INTEGER OUT OF RANGE


------  ERROR x  --------------------------------------------------------------

When CHR$(x) is a printable, non-control, single-position character, an error
message with this character will be forced. Note that ERROR 28 has no effect.

Example:        ERROR 63                ... Z/0


------  EXIT  -----------------------------------------------------------------

Has two different applications:

 (1)  as direct command: quit CBI (not a very sensible decision!);
 (2)  in a program: jumps out of the current LOOP structure.

For an example of case (2), see the DO command.


------  HOME  -----------------------------------------------------------------

A fast and economic alternative for PRINT AT 0,0;


------  INDENT  ---------------------------------------------------------------

Gives your program a proper, professionally looking lay-out. Use INDENT to
improve the legibility and surveyability of your program; the structure of
your program is much clearer after using this command. When INDENT comes
across a structural error in your program, it will stop its task.
Note that INDENT may only be used as a direct command and sometimes results
in undefined (and unimportant) error messages.


------  LINE var,x  -----------------------------------------------------------

Puts into variable var the address where Basic line x or the first line with
a number larger than x starts. The actual command of that line is then located
at address var+4 (e.g. PRINT).

Example:        LINE FIRST,0            always FIRST=16509, start of basic area


------  LOOP  -----------------------------------------------------------------

Indicates the end of a DO...LOOP structure - see DO for an example.


------  NOSTALGIC sw  ---------------------------------------------------------

Switches between the two possible edit modes:

 (1)  NOSTALGIC ON      : N-mode (nostalgic mode)
 (2)  NOSTALGIC OFF     : CBI-mode (Coral Basic mode, screen editor)

For a more detailed description of N-mode and CBI-mode, please refer to the
section "Using the new Editor".


------  ON/OFF  ---------------------------------------------------------------

These two reserved CBI keywords can only be used in combination with other
CBI commands, viz. those that need 'sw' as parameter.

Example:        NOSTALGIC ON
                BREAK OFF


------  POP var  --------------------------------------------------------------

Takes the top element off the stack and stores its value in variable 'var'.

Example:        1000 DEF PROC ALTER
                1010  POP CRA
                1020  POP LRA
                1030  IF LRA>=1E4 THEN LET LRA=1E4
                1040  PUSH LRA
                1050  PUSH CRA
                1060 END PROC

This procedure needs to be called just before the end of another procedure
as to make sure that the latter does not cause error B when it was called
by way of a direct command.


------  PROTECT sw  -----------------------------------------------------------

Can be used to disable the commands CLEAR, RUN and NEW in order to protect
programs and variables against against accidental loss.

Example:        PROTECT ON
                LET AMOUNT=99.95
                CLEAR


------  PUSH x  ---------------------------------------------------------------

Stores the number x on top of the stack - see example at POP.


------  READ [var|$var]  ------------------------------------------------------

The READ command is an important tool for data exchange between various parts
of a program. The three different ways in which the READ command can be used
are summed up below. In general, READ takes a data item from the data list
that is specified by the current value of the data pointer. In case no
data item can be found, error G results.

 (1)  Combined with DATA and RESTORE;
      This is the most obvious usage - see DATA for an example.
 (2)  Combined with PROCedures;
      Both while calling a procedure and while returning from it, data
      can be passed - see DEF PROC and END PROC.
 (3)  By way of direct reading and/or setting of the data pointer (address
      32732). The following program is an example of this method:

                10 RAND PI
                20 RESTORE
                30 DATA 0
                40 DPOKE 32732,16514
                50 READ X
                60 PRINT X


------  RESEQ x:y,z  ----------------------------------------------------------

Resequences the program from line x onwards by renumbering this one to line y
and proceeding with steps z. The RESEQ command does not change linenumbers
after GOTO and GOSUB statements; taking into account the numerous possibilities
for structured programming offered by CBI, this seems no restriction.

Example:        RESEQ 0:100,10          renumbers program as 100,110,120,...


------  RESTORE {x}  ----------------------------------------------------------

Positions the data pointer on the first data element found in or after line x.
Note that RESTORE without number looks for the first data element in the
program. See DATA for an example.


------  TRACE swv;{x}  --------------------------------------------------------

In case swv=1 a program will be traced during running: before executing
subsequent lines of Basic, the line number will be displayed in the top
righthand corner and a small pause (in length proportional to x) will be
held. On a normal ZX81, use x=2750 for 1 second.

Example:        TRACE 1;2000            waits approx. 0.72 second


------  UNDRAW TO x,y  --------------------------------------------------------

Works just like DRAW, but uses UNPLOT instead of PLOT.


------  UNTIL/WHILE  ----------------------------------------------------------

These reserved CBI keywords can only be used in combination with a DO...LOOP
structure. See DO for an example.


------  USER x  ---------------------------------------------------------------

Probably the most interesting command for machine code programmers. The USER
command has the effect that subsequent '*' commands are redirected to the
user-definable machine code routine at address x. This allows the user to
easily expand the Basic with self-written routines. For a more detailed
explanation, please refer to the section "Brief Explanation of the USER
Command". Note that the '*' command cannot be used after the THEN in an IF
statement. Apply a WHEN construction instead.

------  WHEN bln DO  ----------------------------------------------------------

This command is an extension of the IF command and allows for conditional
execution of program blocks (instead of just a single command). The stucture
of a WHEN block within a program is as follows:

        WHEN bln DO
         )
         > program lines to be executed when bln=true
         )
        ELSE
         )
         > program lines to be executed when bln=false
         )
        END WHEN

The ELSE with subsequent program lines is optional.
WHEN...END WHEN structures may be nested at will.

Example:        100 INPUT L$
                110 LET V$="AEIOU*"
                120 FOR N=1 TO 6
                130  WHEN L$=V$(N) AND T<6 DO
                140   PRINT L$;" IS A VOWEL"
                150   LET N=6
                160  ELSE
                170   WHEN N=6 DO
                180    PRINT L$;" IS A CONSONANT"
                190   END WHEN
                200  END WHEN
                210 NEXT N

Also note that the '*' command (see USER) cannot be used after the THEN in
an IF statement. Apply a WHEN construction instead.


SYSTEM VARIABLES

In order that an Operating System can function properly, a list of internal
variables is needed: the so-called system variables. By way of these system
variables, the computer knows the status of the system at any time, and
conversely, the system status can easily be altered by POKEing the system
variables. Basically, CBI makes use of the usual ZX81 system variables
(as described in Chapter 28 of the "ZX81 Basic Programming" manual).
However, CBI needs some additional system variables and these are described
below. The addresses are valid for the original version of CBI, and may
be shifted in case of relocated versions.

address  bytes  flag    name            description
-------  -----  ----    ----------      --------------------------------------
16393      1     S      OS_type         Contains an odd number (most likely 1)
                                        when CBI is active; CBI cannot be
                                        started if OS_type is already odd
16417      1            CBI_fl1         Various system flags
16508      1     S      CBI_fl2         Varioys system flags
32730      2     S      UD_SR           Address defined by USER command
32732      2     S      Dat_Pnt         Data pointer; points to item to be
                                        read or item just read
32734      2     S      Cur_Pos         Position of cursor on the screen
32736      1            Temp            Used for temporary data storage
32737      1            Scr_Cnt         Counts number of scrolls in LIST
32738      1            Sto_33          Stores CBI_fl1 during SAVE/LOAD
32739      2            Pause           Contains pause for TRACE
32741      2            Cur_Err         Position of error in editline
32743      2            Cur_Inp         Saves cursor position during INPUT
32745      2            Line_St         Start address of editline
32747      2            Line_End        End address of editline
32749      2            Last_Key        Code of last key pressed
32751      2            Time            Autorepeat timer
32753      2            Strt            Linenumber for AUTO
32755      2            Step            Increment for AUTO
32757      8            Room            Used for floating point arithmetic
32765      1            Cur_Ch          Cursor character
32766      2            NU              not used

An 'S' in the flag column indicates that these system variables are Saved
to tape. Note that the names of the system variables (like Line_St) are not
recognized by Basic. It is advised not to change the system variables unless
you know what you're doing.

CBI_fl1 and CBI_fl2 contain 16 status bits. These are discussed below:

    CBI_fl1, address 16417, not saved

        bit     function if value is 1
        ----    ---------------------------------------
        0       TRACE active
        1       print spaces in front of linenumber
        2       ERR MSGS active
        3       a listing is being printed
        4       AUTO active
        5       keyrepeat is being used
        6       print space after present keyword
        7       NOSTALGIC active

    CBI_fl2, address 16508, gets saved

        bit     function if value is 1
        ----    ---------------------------------------
        0       value of Dat_Pnt is not valid
        1       Do not print CR/LF at the end of a line
        2       Cursor is in the middle of a keyword
        3       Dat_Pnt points to a proper data-item
        4       Break key is disabled
        5       CBI is in edit-mode
        6       set to 1 directly after SAVE and LOAD
        7       CBI is in FAST mode


Again: these bits should only be changed with great care. In fact, many of
the bits are not at all useful for the user and the others can easily be
changed via the usual CBI commands like NOSTALGIC and TRACE.


CHARACTERSET

In the CBI editor, commands need to be typed in full (letter by letter), but
nevertheless, CBI still converts the keywords to single character codes for
faster execution of programs. As an example, the keyword "CALL" gets converted
to CHR$(67). You can see this by typing the command CHAR 67.

Below is a list of all the CBI-specific keywords. Note that these cannot be
used with the CHR$ function. Use the CHAR command instead.

         67     CALL                     89     INDENT
         68     ERR MSGS                 90     RESEQ
         69     DPOKE                    91     OFF
         70     ERROR                    92     CURSOR
         71     CHAR                     93     DATA
         72     (space)                  94     RESTORE
         73     TRACE                    95     READ
         74     DRAW                     96     NOSTALGIC
         75     UNDRAW                   97     USER
         76     PROTECT                  98     *
         77     EDIT                     99     ON
         78     AUTO                    100     HOME
         79     DEF PROC                101     BREAK
         80     END PROC                102     DPEEK
         81     (proc)                  103     LINE
         82     DELETE                  104     POP
         83     DO                      105     PUSH
         84     LOOP                    106     CLR STACK
         85     EXIT                    107     DUP
         86     UNTIL                   108     ELSE
         87     WHILE                   109     END WHEN
         88     WHEN

Character 72 is used as programline indentation; character 81 is placed
in front of the name of a procedure call (but invisible).
All the above codes are only valid while CBI is active. Once outside CBI,
the ZX81 will show all the CBI-specific characters as question marks (?).


BRIEF EXPLANATION OF THE 'USER' COMMAND

In order to be able to extend the ZX81 Basic with self-written machine code
routines via the '*' command, the command USER must first be applied to set
the address of the routine that interprets and executes the user MC routines.
This address will be denoted 'I_S' (Interpreter_Start).

In the following, all instructions are Z80 mnemonics rather than Basic
commands, and all numbers are hexadecimal rather than decimal.

When the '*' command is encountered, two calls to I_S will be made:

        (1) first time during syntax check;
        (2) second time when the command is to be executed.

These two calls can be distinguished from each other by

        CALL 0DA6.

This routine only changes the Zero-flag, viz.:

         Z : call during syntax check;
        NZ : call during program execution.

In most cases, the syntax check most be done on BOTH occasions, especially
when numerical expressions are present in the command: these will be fully
checked during syntax check, and will be actually evaluated during execution.
So, the general shape of the command interpreter will be:

        I_S     { Syntax Check }        ; check syntax, evaluate parameters
                CALL DA6                ; test sytax flag
                RET Z                   ; return if not executing
                { Execution }           ; otherwise execute command(s)
                RET                     ; end.

In case I_S needs to serve more than one command, the syntax check must
select the required command so that the proper routine can be called during
execution. Below some hints for making the syntax check easier:

(1) A useful feature of direct syntax check is that the line can be sent back
    to the editor as often as needed and be corrected by the user until the
    syntax is completely right. There is a very easy way to send the editline
    back to the editor:

                RST 08
                DEFB 0B

    Usually, this would lead to error C, but during syntax check this causes
    the line to reenter the editor as to be corrected by the user. The cursor
    appears in the line on the position that is pointed to by CH_ADD (4016).
    Note that RST 08 can always be used from any subroutine level, i.e. the
    stack needs NOT to be cleared by POP's and RET's first. Moreover, RST 08
    does not return to the place where is was called; instead, the execution
    is automatically restarted at address I_S as soon as the user presses
    NewLine (after having made the required correction(s)).

(2) When the routine at I_S is entered, CH_ADD contains the address of the
    first character after the '*'. This address and the character on it
    can easily be fetched by the command RST 18, returning HL = (4016) and
    A = (HL). All subsequent characters can be determined by RST 20.
    This instruction automatically increments the value of CH_ADD before
    fetching the new characters. Note that both RST 18 and RST 20 skip
    spaces!

(3) If you wish to include one or more numerical expressions in the syntax,
    these can easily be checked and evaluated by a single CALL:

         CALL 0D92

        - During syntax check, the part of the edit line that starts at
          address CH_ADD is tested for presence of a numerical expression.
          All explicit numbers in the expression are expanded with the
          usual 6-byte arithmetic coding (no need to bother about that).
          In case the numerical expression contains some kind of error, the
          line is automatically sent back to the editor (the CALL obviously
          does not return in that case).

        - During execution, the expression gets evaluated and the value is
          put on the arithmetic stack. The value can be unstacked by a
          call to address 0EA7; this returns the value in registerpair BC.
          Obviously, this rounds the value to an integer in the range
          0 through FFFF (if this is not possible, error B will be forced).

    In both the above cases, after the call, CH_ADD points to the first
    character in the edit line that could impossibly be part of the numerical
    expression (e.g. a separator ',' or ':', or NewLine) and A contains the
    code of that character.

NOTE: loading a program destoys the value set by USER and therefore
      you'll have to type it again. This is particularly inconvenient if
      you wish USER to point to a file-loading routine (for example QZ,
      disk driver or RAMdisk driver). To cure this problem, enter the
      following three POKEs:

      POKE CBI+1058,0
      POKE CBI+1059,0
      POKE CBI+1060,0

      where CBI is the start-address of the CBI code (27400 by default).

The '*' command offers great opportunities for machine code programmers as
there are numerous applications. The program 'CBI-DEMO' contains some examples
of the possibilities offered by this command. Line 0 of this program contains
a machinecode program of some 1270 bytes. If you wish to make use of the '*'
command, it may be worthwhile to study this machinecode program, for example
by way of a DisAssembler. The address I_S is at 16516. After having typed
'USER 16516', you get access to 13 new commands that are being used in the
various procedure definitions in CBI-DEMO. The new commands are:

*BYTE:x                 a subsequent 'READ $var' must be used to obtain the
                        binary representation of PEEK(x) in $var
*CDUMP:x                full-screen characterdump of a block of 528 bytes
                        at address x onwards
*CLOCK:"hh:mm:ss"       starts real-time clock (24h based) at given time and
                        continuously displays it in the top righthand corner
                        of the screen; interrupt-based, so does not work on
                        ZX81 emulators; the clock stops running after any
                        command that touches FAST or SLOW mode; the clock
                        can also be stoped by the command *CLOCK:
*COMPL:x,y              change value of bit x of the byte at address y
*GAME                   nice and simple game
*HEXDUMP:x              full-screen hexdump of a block of 176 bytes at address
                        x onwards
*IND.ZERO               removes programline indentation from program
*INVERT:x,y,p,q         inverts a screenblock; top print coordinate is (x,y);
                        q is the depth of the block, p is the width
*PROCS                  shows all the procedure currently defined
*RES:x,y                clear bit x of the byte at address x
*SCRLIN$:x              a subsequent 'READ $var' must be used to obtain the
                        contents of screenline x in $var (32 characters long)
*SET:x,y                set bit x of the byte at address x
*SHOW                   shows a list of the new '*' commands available

Note that the symbols p,q,x,y represent arbitrary numerical expressions!


USING CBI WITH EXISTING SOFTWARE

In principle, CBI can be used with all existing ZX81 BASIC programs and their
complementary machine code routines. There are some obvious exceptions:

(1) If the program needs more than 11k of free RAM;
(2) If machine code programs or data need to be placed in the upper part of
    the 16k RAM memory block;
(3) If the program reduces the Display File, e.g. by calling the ZX81
    SCROLL routine directly;
(4) If the program changes the value of addresses 16417 or 16508.

The best way to find out if a program can be used together with CBI, is
simply to try it yourself. In many cases, a small alteration of an
incompatible program can fix the problems!

Some of the above problems are related to the fact that CBI is located in the
upper 7k of the 16k RAM. These problems can easily be solved by relocating
the CBI code. This can be done with the program 'CBI-REL'.


-------------------------------------------------------------------------------

For all questions or suggestions regarding CBI, please write to

        Carlo Delhez,
        Emmastraat 3,
        4651 BV Steenbergen,
        Netherlands.

-------------------------------------------------------------------------------


<*** End of File ***>
