If you’ve examined some of your programs for any of the Sinclair computers containing machine code, you’ve probably seen machine code routines called in a variety of ways. The most common calls are:
RANDOMIZE USR n or
LET A = USR n
where “n” represents the address where the machine code is located. How do you know which way to call a USR routine? The purpose of this article is to explain why USR routines are called in the ways they are, and to suggest some alternate ways of calling USR routines.
THE BASICS
As you probably know, the heart of the Sinclair computers (QL’s excepted) is the Z80 microprocessor. When using BASIC in our programs, we are communicating with the Z80 in and indirect way. Our commands are “interpreted” by the ROM into instructions that are meaningful to the Z80 microprocessor. The extra step of interpreting the BASIC program takes time and means that BASIC programs run slower. Sinclair computers allow us to execute programs that are directly executable by the Z80 microprocessor by use of the USR function. The USR function removes us from the safety of BASIC, since you can easily cause the computer to crash. Don’t worry, you can’t hurt the computer, but you can easily lose a program painstakingly entered into the computer. You are working without a net when you run machine code programs. The results are breathtaking when the program works, but until your programs are fully debugged, you are only a step away from disaster. For this reason, SAVE your machine code programs before running them.
When invoking the USR function, we are telling the computer to execute a machine code program at a specific address. Inside the Z80 microprocessor, there are three “register pairs” that can hold any integer between 0 and 65535. These register pairs are called the HL, DE, and BC registers (There are other registers, but they are more difficult to use). When we write machine code programs, we manipulate the contents of these registers, and the contents of RAM to some useful purpose.
WHAT HAPPENS ON RETURNING TO BASIC FROM A USR ROUTINE?
In most cases, after finishing a USR routine, we return to BASIC. On returning to BASIC, THE CONTENTS OF THE BC REGISTER PAIR ARE INTERPRETED AS A NUMBER. This fact allows us to pass information from our machine language routines back to BASIC.
Let’s write a program that does nothing but load the BC register pair with the number 50 decimal, and return to BASIC. (This will work on any Sinclair computer).
ENTER:
POKE 30000,1
POKE 30001,50
POKE 30002,0
POKE 30003,201
To the Z80 microprocessor, this program means, load the BC register with 50, then return. In Z80 mnemonics this is abbreviated as:
LD BC, 32 (that's 50 in hexadecimal)
RET
Now let’s prove that the contents of the BC register are interpreted as a number on return to BASIC.
ENTER:
PRINT USR 30000
The computer will print 50.
Try entering:
LET A = USR 30000
PRINT A
The computer prints 50, but this time the contents of the BC register have been assigned to the variable A.
A common USR call is:
RANDOMIZE USR n
The effect of this call is to put the contents of the BC register in the system variable SEED. SEED is used to provide a number for random numbers. To see the results of RANDOMIZE USR 30000 enter:
(TS1000, TS1500, or ZX81 version)
PRINT PEEK 16384 + PEEK 16435 * 256
(TS2068, or SPECTRUM version)
PRINT PEEK 23670 + PEEK 23671 * 256
Again, the computer prints 50, the number that has been stored in SEED. (You can find the system variables by looking in the appendix of your manual)
You should be careful when using the RANDOMIZE USR n command. If you are using random numbers somewhere in your program as in a game, the RANDOMIZE USR n command may keep putting the same number in SEED time and time again. This will mean that you will keep getting the same random numbers again and again. After using RANDOMIZE USR n, you should have another line that says RANDOMIZE or RANDOMIZE 0. This will cause the number of frames shown since you turned your computer on to be deposited in SEED. This number should be fairly random.
In the preceding examples we have seen three common ways of calling routines. Now let’s examine a couple of more advanced methods.
ADVANCED USR CALL TECHNIQUES
Since we have seen that the BC register pair is interpreted as a number on return to BASIC, it is possible to use USR calls in any way that a numeric argument is valid. For example, you could have a line that said:
IF USR n = 10 THEN GOTO 1000
and it would be perfectly legal. You could execute multiple USR routines with a statement such as:
LET A = (USR n or USR m or USR p)
and all three routines would be executed.
I enjoy storing DATA in strings. String storage of data has the advantage of being compact, and the SINCLAIR computers handle strings especially well. My favourite USR call is:
LET A$ = CHR$ USR n
It has the advantage of setting the system variable DEST to contain the address of A$(1). This means that you can store data in strings and easily find the location of that string for your machine code routine. (DEST will also point to numeric variables, but they are quite a bit more difficult to use) The one thing that you have to remember when using DEST is that you must restore A$(1) to some legal character code between 0 and 255. This is easily done by ending your routine with:
LD HL, (DEST)
LD C, (HL)
LD B, 0
RET
This loads the BC register with the character that is pointed to by DEST. It is much like saying:
LET A$(1) = A$(1)
One final tip on calling USR routines. If you need to set a value to a USR routine from BASIC you can always POKE it to some unused location in memory, but here is a bit more elegant way. Pass the number to memory with the RANDOMIZE function. Suppose you want to set the number 3 to the routine. Just enter RANDOMIZE 3 and the number 3 will be put in SEED. Then call your USR routine and have it read SEED. It’s simple, and will even put two-byte numbers in SEED. The one number it won’t work for is zero.
Once you have learned that the BC register is the key to returning to BASIC, you will find that your machine code routines will be more imaginative.
From the Sept 1985 issue of RAMTOP, Cleveland Ohio. Retyped by G. Chambers
PRINT FREE for the Spectrum
How many times have you wished there was an easy way to get the equivalent to the 2068 PRINT FRRE routine when in the Spectrum mode. But there is a relatively easy procedure. Just enter the following as a direct command:
PRINT 65535 - USR 7960
This will give the bytes of free Spectrum memory.