XBASIC : User Guide Introduction ------------ XBASIC is an extension to the BASIC language on your Spectrum, giving you more than 20 new commands to greatly simplify writing BASIC programs, XBASIC is designed to be very simple to use. There is no list of RANDOMIZE USR addresses to remember, as all the commands have their own new keyword, prefixed by '*' to distinguish them from normal commands. The new keywords can be used either as direct commands or put into programs, and variably or complex expressions can be used instead of numbers as parameters. Single-key entry of the new keywords can be used if you wish (see user defined keys). Features of XBASIC include: * Full line re-number, including GOTO's/GOSUBS, in any step size. * Automatic line numbering. * Block line delete. * Upto 10 user-defined keys. * Repeat... UNTIL loops. * Selective on-screen colour change. * Irregular shape fill. * Comprehensive error/break trapping, with reserved variables ERR and ERL * String search. * 6 new error-reports. Loading ------- To load XBASIC simply enter LOAD"". The program loads in 2 parts, and when it is ready a message will be displayed, along with a coloured border. When you press a key the loader program deletes itself; and you will be left with the normal 'Sinclair Research 1982' copyright message, as well as a flashing coloured square in the bottom right-hand corner of the screen - this shows that XBASIC is operational (it can be turned off if you find it annoying). You are now ready to type in a program using XBASIC commands. Getting Started --------------- After loading, type in the line * COLOUR 7, 1 and 'enter'. The keyword, COLOUR should be spelled out as 6 separate letters, although it does not matter whether upper or lower case is used. The screen and border should now be blue with white letters. This command is equivalent to PAPER 1: INK7: BORDER1: CLS Variables could be used instead of constants. To show this, type in this short program: 10 RANDOMIZE USR 53000 20 INPUT "INK",I,"PAPER", P 30 * COLOUR I. P 40 PRINT"NEW COLOURS": GOTO 20 Line 10 is necessary in all programs using XBASIC -if it is not included, any XBASIC command in the program will give a NONSENSE IN BASIC error-report. To delete the program, do not use NEW, or XBASIC will be turned off. Instead, use the XBASIC command *NEW (typed as 4 separate characters). If you do type NEW, then XBASIC can be re-started with RANDOMIZE USR 53000 - this is a second use for this command (it must also be used as the first line of a new program). If a program stops with an error, or because you press BREAK, then CONTINUE will not work as it usually does. Instead, press 'C' (the key with CONTINUE on it) with SYMBOL SHIFT - you will find this gives the line RANDOMIZE USR 53000: CONTINUE. This will allow a program to continue after an error. The key '?' has been redefined so that it gives this line in K-mode - see the section on user-defined keys for the method of doing this. If an XBASIC command is entered incorrectly, trying to run it will give the new error-report: * 1 ERROR IN XBASIC There are also 5 other new reports - these will be mentioned in the appropriate sections. Also see this section on error-trapping. NOTE that there is no syntax-check on entry - any errors will only be deleted when the program is run. Automatic Line Numbering ------------------------ To produce automatic line-numbers, type in *AUTO 10, 10. This will give the report 0 OK, 0:1. As soon as you press a key, you will find that the first line-number - in this case 10 - has been printed at the bottom of the screen. When you press 'enter', to add the first line to the program, the next line-number, 20, will appear immediately. Automatic numbers will continue to appear in this way until you press BREAK, or the line-number exceeds 9999. In both cases you will hear a short beep. The first number in the command gives the line-number to start at, and the second number the amount to add on for each subsequent line. You can miss out the second number, in which case the computer will assume you mean a step of 10. The comma must, however, be included. Line Re-numbering ----------------- There are three possible forms for this command: *RENUM means re-number starting at line 10, with a step of 10 *RENUM 25, means re-number starting at line 25, with step of 10 *RENUM100,5 means re-number starting at line 100 with step of 5 All the line-numbers of your program will be changed. In addition, the numbers in GOTO and GOSUB commands will also be changed even if the line-numbers referred to do not exist. If a GOTO or GOSUB refers to a line after the end of the program, it will be changed to 9999. If there are any calculated GOTO/GOSUBs, for example GOTO (A*10) + 250, these will not be altered. However, the keyword will be left flashing, so you notice that it has to be changed eventually. If you have a large program. using *RENUM may give you an error message OUT OF MEMORY. This is because the command needs to store the old and new numbers of every line to refer to when changing GOTOs and GOSUBS. The amount of memory free must be at least four times the number of lines in the program (in bytes). If re-numbering would produce any lines with numbers greater than 9999. nothing will be changed and the report INTEGER OUT OF RANGE will be produced. Block Line Delete ----------------- If your program contains a block of lines you wish to delete. you can use the *DELETE command. You must specify the first line to delete, and you can specify the last line - if you don't, it will be assumed that you mean delete up the end of the program. *DELETE 50,100 means delete from lines 50 to 100 *DELETE 30, means delete from line 30 to the end of the program. User-Defined Keys ----------------- You can re-define up to 10 keys to produce any sequence of characters (up to 10 long). User-defined keys only work in the K-mode. so you re-define any of the red symbols on the keys (used with SYMBOL SHIFT) and still use the symbol normally in L-mode. Other keys can be defined, but they will not be so useful. The '?' key is already re-defined. but you can change this if you wish. Some examples are now given of useful definitions for keys. (a) To re-define SYMBOL SHIFT/N (Comma) to produce the XBASIC keyword * NEW, type: *KEY, : *NEW SYMBOL SHIFT/N Typing SYMBOL SHIFT/N in K-mode will then produce *NEW in L-mode it will still produce a comma (,) (b) To re-define '>' (on RANDOMIZE key) to give RANDOMIZE USR 53000, type: *KEY : RANDOMIZE USR 53000 (c) To re-define '£' (On X key) to do INK 0 : PAPER 7 : CLS followed by ENTER, type: *KEY£ : INK 0 : PAPER7: CLS _ ^ UNDERLINE CHARACTER MEANS 'ENTER' Pressing '£' in K-mode will then instantly reset the colours to their initial values, without pressing ENTER. (d) To 'un-define' the '£' key, type: *KEY£ (with no colon) There are two new error-reports associated with user-defined keys - these are *5 DEFINITIONS TOO LONG and *4 TOO MANY DEFINED KEYS Do not re-define the "*" key, or you will be unable to enter any XBASIC commands. *BREAK: CONTINUE is useful in preventing accidental break-in to basic program. String Search ------------- To find the line in your program containing PRINT "NAME", type in : *FIND: PRINT "NAME" If the string is found, then as an automatic listing will be produced with the cursor at the appropriate line (so you can edit it immediately). Note that the search is from the current line to the end of the program, so to search the whole program you should enter LIST before the * FIND command. If the string is not found, the error report: * 6 STRING NOT FOUND until produced The colon in the * FIND command is optional. Its purpose is to put the computer into K-mode if you require this to enter a keyword. If you are not searching for a keyword, the colon can be omitted. REPEAT .... UNTIL Loops ----------------------- This is an alternative loop structure to IF ... THEN GOTO ... or FOR ... NEXT. It is found in many versions of BASIC, but not the Spectrum. The format is:- 100 *REPEAT 110 } 120 } 130 } STATEMENTS TO BE REPEATED 140 } 150 } 160 *UNTIL Condition The *REPEAT statement causes the statements between it and the *UNTIL command to be repeated until the condition is true. The condition is the same as one found in an IF ... THEN statement. For example, this program prints the square-roots of numbers typed in until a 0 is entered, 10 RANDOMIZE USR 53000 20 PRINT "REPEAT-UNTIL DEMONSTRATION" 30 *REPEAT 40 INPUT N 50 PRINT N, SQR N 60 *UNTIL N=0 REPEAT - UNTIL loops allow better program structure than GOTO statements. There are 2 error-messages associated with repeat/until loops: * UNTIL without REPEAT * Too many REPEATS and Note that REPEAT/UNTIL loops can be nested to a level of ten deep. After this, error *3 will be produced. (Try the program above, using *AUTO to enter the lines) Note that RUN does NOT clear the REPEAT stack as it does the GOSUB stack - this means that if you have a program with an error that keeps stopping while inside a loop, you may get *3 after several runs. The command *RESET can be used to reset the REPEAT stack in these situations. Error - Trapping ---------------- With XBASIC, your programs need never stop with errors such as VARIABLES NOT FOUND or INVALID ARGUMENT when someone types in some wrong input - All errors can be "trapped" and a jump made to a special part of the program when an error occurs. Two "reserved variables", ERR and ERL, give you the number of the error that occurred, and the number of the line in which it happened. The command used is *ERROR, and it can take three forms: *ERROR:GOTO 1000 means go to the line 1000 if an error occurs. *ERROR:CONTINUE means carry on with the next statement if an error occurs. *ERROR:STOP means that off error-trapping, and stop with a report if an error occurs. Try this program: (Use *AUTO for the line-numbers) 10 RANDOMIZE USR 53000 20 *ERROR : GOTO 100 30 INPUT A 40 PRINT A 50 GOTO 30 100 PRINT "ERROR:";ERR,"AT LlNE:",ERL 110 GOTO ERL + 1 When you type in numbers (line 30), they will be printed out in line 40. Now try typing in a instead of a number - this would normally stop the program with error 2:Variable not found. However, instead, line 100 prints out the message ERROR:2 AT LINE 30 and the program carries on from line 40 again. Some errors are not trapped, and will give the normal report: These are errors 0 OK 9 STOP statement D BREAK - CONT repeats H STOP in INPUT L BREAK into program This means that only reports which would give true errors are trapped, and the program will still stop normally when a STOP or BREAK occurs. In some cases, you may wish to trap reports D, H and L as well, in order to stop people breaking into your program. In this case, there is another XBASIC statement you can use, *BREAK. Like *ERROR, this has 3 forms: *BREAK: GOTO 500 *BREAK: CONTINUE and *BREAK: STOP *BREAK does exactly the same as *ERROR, only the 3 extra reports are trapped as well. *BREAK:STOP means exactly the same as *ERROR:STOP - both turn off error and break-trapping completely. To turn off BREAK trapping but keep ERROR trapping simply use the appropriate *ERROR: command. To demonstrate break-trapping, try this program: 10 RANDOMIZE USR 53000 20 * BREAK: CONTINUE 30 INPUT A 40 IF A=999 THEN STOP 50 GOTO 30 If you type in STOP at line 30, the program will carry on instead of stopping with report H. Because of line 40, you can stop the program by typing in 999. Note that when your program stops, error or break trapping will not be turned off, and will still be operational if you then run another program. If you have been using error-trapping, enter *ERROR:STOP before starting on a new program. As mentioned earlier, the variable ERR gives the number of any error that occurs. For errors with a letter, the value in ERR will be the corresponding number - e.g. error A will give ERR=10, error B will give 11, etc. The six new errors. *1 to *6, give values of ERR from 101 to 106. XBASIC also offers a machine-code break feature, in case your machine-code routines crash and get stuck in an infinite loop. To use this, you must simultaneously press all the five keys from B to SPACE. This is disabled when break-trapping is used. IMPORTANT: Before doing something else, enter *BREAK:STOP - or you may end up having to pull the plug out and start again! Graphics Commands ----------------- XBASIC offers three new graphics commands, two of which give features not otherwise possible in BASIC. The *COLOUR command has already been mentioned - it is followed by values for ink and paper, and changes ink, paper and border colour simultaneously. A related command is *CCOL (Change Colour). It allows you to change colours of objects already on the screen without clearing the display. To demonstrate its use, type in these lines. *COLOUR 0,7 PRINT INK 2; "RED" PRINT INK 4; "GREEN" Now type in *CCOL 2,1 The top line on the screen, which was red will now be blue. The command means "change anything In red ink to blue ink instead". Now type *CCOL 4,6# The hash (#) symbol means that the second number refers to paper, not ink - so the lettering in green ink (4) is changed to yellow paper (6). Type *CCOL 6#,5# - and yellow paper is changed to cyan. Type *CCOL 5#,3 - and the area with cyan paper is now magenta ink. Finally, type *CCOL 8, 0 All ink should now be black. The'8' means "change everything on the screen" If you try this program: 10 RANDOMIZE USR 53000 20 PRINT INK 0; "¦" [Solid black square character] 30 FOR C =0 to 7 40 *CCOL 8, C 50 PAUSE 2 60 NEXT C: GOTO 30 You will produce an effect similar to the XBASIC indicator square. The final graphics command is * FILL. It allows you to fill in an irregularly-shaped area, bounded by a continuous line. Try this program; 10 RANDOMIZE USR 53000 20 CIRCLE 100,80,50 30 CIRCLE 100,80,30 40 *FILL 100,120 The result should be a filled-in 'doughnut' shape. You can also "unfill" an area already inked-in, by using INVERSE 1 before the *FILL command. An area to be "un-filled" must be surrounded by a "paper" boundary. Note that *FILL wraps around the edges of the screen, so if it goes off the bottom it will continue from the top, etc. When filling an area, you must make sure that it is COMPLETELY surrounded - a gap of one pixel is enough for the fill to 'leak' out. *FILL takes account of the current INK and PAPER colours, as well as INVERSE, so for this reason you may find it slightly slower than some similar programs. Miscellaneous Commands ---------------------- *PUT is a 2-byte version of POKE. For instance, to move the character-set to address 56000, you would type in: *PUT 23606, 56000 (Don't do this unless there's a character set there!) As usual, variables or expressions can be used instead of constants. *GET is the opposite to *PUT, although it is a command, not a function. To find the present address of the user-defined graphics, you could type: * GET 23675 *GET A is equivalent to PRINT PEEK A + 256 * PEEK (A+1) *STORE is used to store a complete copy of the present T.V. picture somewhere in memory. A convenient place is above XBASIC, at address 57000. To do this, type: *STORE 57000 You can recall the picture at any time by entering: *RECALL If a number is given after *RECALL, for example *RECALL 32000, the picture will be recalled from that address. If no address is given. then the picture will be taken from whenever the last *STORE command said. *STAT gives you the length of the present BASIC program. the length of the variables area. the amount of free memory and the current value of RAMTOP. *PIP followed by a number from 0 - 255 controls the keyboard click. *PIP L is the same as POKE 23609. L *INDIC 0 turns off the XBASIC coloured indicator square *INDIC 1 turns it on again. *OFF turns off XBASIC (it can be re-started with RANDOMIZEUSR 53000). You should use *OFF before loading any code on to off XBASIC, or the machine will crash. Saving XBASIC Programs ---------------------- When you save a program that uses XBASIC, you must also save XBASIC itself. To do this. use the following line: SAVE "NAME" LINE 10: SAVE "XBASIC" CODE 52991, 3050 The program must then start with the following lines: 10 CLEAR 52990: LOAD "" CODE 20 RANDOMIZE USR 53000 Note that XBASIC occupies the area from 52991 to 56050. The area above this can be used to store spare screens, machine-code routines, other utility programs as assemblers etc. Appendix A : List of XBASIC Commands ------------------------------------ (Parameters in square brackets are optional) *AUTO start, [step] *BREAK: CONTINUE *BREAK: GOTO line number *BREAK: STOP *CCOL present colour [#], new colour [#] *COLOUR ink, paper *DELETE start, [end] *ERROR: CONTINUE *FILL x,y *FIND [:] string *GET address *INDIC 0 or 1 *KEY character [: up to ten characters] [_] *OFF *NEW *PUT address,number *PIP number *RECALL [address] *REPEAT *RESET *RENUM [start,] [step] *STORE address *STAT *UNTIL condition