(from Your Spectrum 7, Sep.1984)



BASIC AT A STRETCH



Tired of using the same old commands? Well, saddle up your Interface 1

unit and let Gavin Smyth demonstrate the practice at adding up to 26

new commands to your Spectrum.





Sinclair Basic, for all its slowness, is fairly comprehensive. But as

with all things, the more you have, the more you want and a few extra

commands might certainly come in useful. How about, for instance, an

absolute draw. With Interface 1 attached, it's possible to add as many

extra commands as you like.



First, let's look at the extended interpreter and the individual

routines in detail.





NEW INTERPRETATIONS



When a line of Basic is entered, the original ROM checks its syntax;

if it fails to recognise the command, it passes control over to the

Interface 1 ROM. This scans the line checking for new words such as

'FORMAT'. If this test also fails, the processor jumps to the error

handling routine (at ERR6) via the vectored address at 23735. You can

alter this address and have further tests implemented to provide extra

commands.



This is what the extended interpreter does. It checks for the presence

of an asterisk at the beginning of a statement followed by a letter;

with this simple test, however, only 26 new commands can be invented.

If it finds no asterisk or letter it gives the usual syntax error. If

all is correct, it jumps to the actual routine via the table of

vectors. Note that unimplemented commands point to the error handler.

The individual command routines check the rest of the syntax and

contain the runtime routine.



For the interpreter to function properly, there must be at least one

space between the new command word and any following arguments. The

command word must start with an asterisk and a letter, followed by any

(or no) characters at all.





ABSOLUTE DRAW



The first new command is:



*DRAW x,y



Which draws to the point (x,y). It's much simpler to use than relative

co-ordinates (especially in graphs). Thus:



PLOT 100,100: DRAW 20,30



is equivalent to:



PLOT 100,100: *DRAW 120,130



First, the routine calls SPACE to get to the end of the first word (in

this case, *DRAW). Then it checks for the presence of two numeric

arguments separated by a comma; if there's something wrong it jumps to

the error handler. In syntax time - that is, when the line is first

entered into a program - the routine ends here; in runtime the rest is

executed. This part simply calculates the size of the relative

co-ordinates and calls the Basic ROM's DRAW subroutine.



When this subroutine is being executed, the Interface 1 ROM is paged

in. This allows routines in the Interface l's ROM, such as STEND, to

be simply CALLed; routines in the main ROM, such as FNDINT1, have to

be called via RST 10h followed by the starting address (this is true

for all the new command routines).





PRINTING PIXELS



The next routine allows a user-defined graphic character to be placed

anywhere on-screen. The reason for restricting it to UDGs is that it's

unlikely that anyone would want to print a lot of text like this

(since the routine handles only one character at a time) and, if

required, the UDGs may be re-defined as letters.



The syntax for the command is:



*PRINT x,y,c



Where (x,y) are the pixel co-ordinates of the top left corner of the

character (x lies between zero and 255, y between zero and 175) and c

is the number of the UDG (UDG A is zero, UDG B is one ... UDG U is

20). For example:



FOR x=0 TO 247: *PRINT x,100,0: NEXT x



The above will glide the first UDG (initially a capital 'A') across

the screen. This time the extended syntax checker looks for three

numbers separated by commas.



In the runtime routine, the data for the UDG is found and shifted

across to give the correct information for the screen memory; the

listing contains the code and full comments. The routine ends with the

attribute bytes being set to the permanent colours.





PIXEL SCROLL



The scroll command allows pixel scrolling of the entire screen. The

actual command is:



*SCROLL n



Where n is a numeric expression controlling the direction of the

scrolling (n must lie between zero and 255, but only the mod four

value is used):



n=0 (or 4,8,...) scrolls right one pixel

n=1 (or 5,9,...) scrolls up

n=2 scrolls left

n=3 scrolls down



For example, to scroll one whole character down, you could use:



FOR f=1 TO 8: *SCROLL 3: NEXT f



This moves the screen by eight pixel lines. The syntax checker this

time looks for only one numeric argument. Only the lower two bits are

used (giving a range of zero to three) and the routine jumps to each

separate scrolling routine. The left and right scrolls are fairly

simple - they just shift each line of 32 bytes by one bit. The up and

down scrolls are complicated by the layout of the screen memory, but

all they do is move each line into the one above or below, clearing

the final one.



The colour attributes are not affected at all, since they have only

character block and not pixel resolution.





SIMPLE SOUNDS



The final routine is a simple sound effects generator - useful for

games if nothing else. The command syntax is:



*ZAP n



Where n, between zero and two [sic], specifies the type of sound:



n=0 gives an explosion noise

n=1 gives a falling tone

n=2 gives a rising tone



For example:



FOR f=1 TO 100: *ZAP INT(RND*3): NEXT f



The above will give several seconds of 'exciting' sounds (well, more

exciting than BEEP!). The computer again looks for a single argument

and checks its value; if it's out of range, it gives an error,

otherwise it jumps to the specific routine. The rising and falling

tones are produced by short beeps of changing frequencies, while the

explosion is produced by sending 'random' data from the ROM to the

speaker port.





A COMMANDING LEAD



You can check from the assembler listing several important points

about adding new commands:



1. First, the syntax is checked - using EXPT1NM for numeric

expressions and CP "," to check for separating commas. This section

ends with CALL STEND.



2. Next comes the runtime routine and, since the values of the

arguments are on the calculator stack, these can be pulled off into

the A register with FNDINT1.



3. The runtime code ends with a jump to END1.



4. Any subroutine in the Basic ROM must be called via RST 10h. Note

that all registers are preserved while the ROMs are paged.



5. Before the code will run, the vector at 23735 must point to the

beginning, with a jump back to ERR6 at the end to trap genuine syntax

errors.



The code may be entered using either an assembler or the Basic program

provided which will relocate the 559 bytes of machine code anywhere in

memory; it should run on a 16K Spectrum, so long as Interface 1 is

connected.



To use it, set lines 10 and 20 to the desired starting address (for

example, 31000 in a 16K machine and 64700 in a 48K model). Next SAVE

the program in case there is a mistake (which is usually fatal in

machine code). Now, RUN the program and after a few minutes a message

will appear on the screen; the code has been located in memory but

will have no effect since the vector at 23735 has not been altered. To

use the extra commands enter the line in the message - as a single

line rather than two separate POKEs, otherwise the machine may crash.



If NEW is entered the vector is reset; however, the code is still in

memory, so repeat the two POKEs to allow the commands to be used.

We've seen a simple interpreter that will allow up to 26 new commands,

but with only four examples; there are 22 more possible words, so get

working!





ASSEMBLER NOTES



The assembler used was the Artic version which, in fact, is slightly

non-standard. The main differences between it and a standard assembler

are:



EQU is replaced by the '=' sign.



All numbers are in hexadecimal unless preceded by '+' or '-', in which

case they are in decimal.



DEFB, DEFW, and so on do not exist; the number or label is simply

placed in the source text where the DEFB would occur, and EX AF,AF' is

entered as EX AF.







This is the machine code disassembly of a series of extended Basic

routines which expand Sinclair Basic by up to 26 new commands, of the

form '*name'; ie. commencing with an asterisk, followed by a letter

(upper or lower case) or word and any necessary parameters. (Note that

this program only works with Interface 1 attached, and the system

variable vector at 23735 and 23736 should be set to point to START.)



The table of vectors to the specific routines.



This routine provides the command to carry out absolute drawing. It is

used in the form *DRAW x,y (or *d x,y), where x and y are the

co-ordinates of the point to be drawn to.



You can print a UDG anywhere on the screen using the routine below.

You access this ability using the command *PRINT x,y,c (or *p x,y,c),

where (x,y) is the pixel co-ordinate of the top left of the character

and c is the number of the UDG (A is '0', B is '1', and so on).



This part of the program provides a pixel scroll in any of four

directions; the command is used in the form *SCROLL n (or *s n), where

n specifies the direction.



This last routine provides better sound effects. The command is used

in the form *ZAP n (or *z n), where n specifies whether you require an

explosion, a falling tone or a rising tone.