------------------------------------------------------------------------------- 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: X100 - 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 ***>