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



