X Basic

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