
TOOL
by John Wilson
from Sinclair Answers #1, Autumn 1984


[NOTE: The 48K version of this routine does not work, as a chunk of code ]
[was missed out of the listing and a correction was never printed. The   ]
[functions of the 16K version seem to work OK.                           ]
[Also, there were several inconsistencies in the article with the figures]
[quoted for RAMTOP, so I've used the lowest figure in all cases, in case ]
[space below the load point is being used for workspace, although it's   ]
[probable that RAMTOP just needs to be set one byte below the load point ]
[(thus CLEAR 31899 for 16K and CLEAR 63999 for 48K). There were a        ]
[number of other printing errors in the article which I've just corrected]
[without bothering to point them out. For a program which was supposed   ]
[to provide a "sure-fire" error checking facility, it was one of the most]
[sloppily printed articles I've ever seen. Whoever prepared it should    ]
[have been given a damn good thrashing. I'm surprised that the programmer]
[didn't write in to complain.                                        JimG]


BANISH THE KEYBOARD BLUES
Want a sure-fire way of keying in listings? Cut back the hassle of errors
with our checksum program.

[Hah! It might, if they'd bothered to print the listing correctly, or    ]
[at least bothered to print a correction in a later issue.           JimG]


The common typing error - so easy to make, so hard to detect - is the
bane of any micro user who wants to try a program listing taken from a
magazine; but no more. [Hah! again. JimG]

Sinclair Answers has developed a unique system which will help ensure
that typing in Spectrum programs we publish is error free, and an
auto-line number and renumber facility. It checks that each line you
have typed in is identical to the listing.

The system is based on an error checking method common in
communications called the checksum. Though not absolutely fool proof,
we are convinced the system is a major contribution to code safety.

Checksumming works in a number of ways, all based on mathematical
manipulations on the value of the data being checked. This is possible
because all data, be it a set of program commands or data that the
program will work with, is stored in memory in the form of numbers. At
machine level this is binary numbers, though for human convenience
these are usually turned into decimal or hexadecimal numbers.

One method of checksumming is to add up all the values of the data
together. For example, if we had the data 12, 18, 14, 15, 16, 5, 55,
45 we would count through and get the result 180. But this method has
its shortcomings. What if we typed in 12, 18, 14, 15, 16, 15, 45, 45?
We still get the checksum answer 180, yet we have a different set of
data which could generate a dramatically different set of results.
Also consider the order of the data. There's no easy way of producing
a checking method for that!

To limit this cancelling effect on the checksum it is wise to produce
a checksum for smaller chunks of data, say groups of 100 bytes.
However, this only reduces the problem, it doesn't make it disappear.
So when using checksums, beware that through some rare fluke you may
have typed in different data with exactly the same checksum. And don't
always rely on the code being typed in correctly because the checksum
is right; save your code before executing.

There are other ways of doing a checksum, though adding the data is
the most popular way. You could multiply the values, divide them -
perform any mathematical function you like.

We have used the exclusive OR method. The logic of the exclusive OR
(EOR for short) may be hard to grasp if you haven't encountered fairly
advanced maths or logic. It works like this:

Take p and q to be sentences, or mathematical propositions. p EOR q
will only be true if one of them is true and and the other false. For
example, p could be replaced with "the sun is shining", and q with "it
is dark". These can't both be true or false at the same time. In
binary terms, 1 EOR 0 and 0 EOR 1 produces the result 1, and both 1
EOR 1 and 0 EOR 0 yields 0.

Our checksum program starts off with the first byte in the data being
EORed with 0 (so, if the first byte is 10101010, the result is the
same). Then the next byte is checked, but this time not against zero
but against the new value, in our case 10101010. Say the second byte
is 10110110, then the result is worked out as follows:

        10101010
    EOR 10110110
        --------
        00011100

00011100 is then EORed with the third byte, and so on until the chunk
of data is checked. The result is a byte that should match the
checksum value we will have printed in the magazine.

Our checksum program is written in machine code, and includes the auto
line number and renumber facility - essential utilities for the
serious programmer. The auto line number inserts an incrementing line
number automatically at the beginning of each line ready for you to
type in the program statements. The renumber allows you make all the
line numbers in the program (including those embedded in GOTO and
GOSUB) increment by a set amount (for example, by tens). Both
utilities can be used with any program.

There are two listings, one for the 16K and the other for the 48K
Spectrum. A word of warning. This program works on interrupts and may
crash if another peripheral (such as a Kempston joystick) is on the
back of the Spectrum.

Type in the Basic loader (Fig.1) for both the 16K and 48K Spectrums,
remembering to save a copy to tape. After typing in the Basic loader
type CLEAR 31888 for the 16K, or CLEAR 63988 on the 48K. Run the
program and input the hex data Fig.3 for the 16K and Fig.2 for the
48K. The listing is printed out into blocks for easier reading. The
first number on each line is the address where the data should be
inputted. The hex number in the angle brackets is the checksum for
that given line.

The Basic loader will give a checksum on every line of input,
indicated by a flashing two byte hex number, so you will he able to
check against the hex listings. If you have made a mistake type in
'$$' when asked for data, and the monitor will ask you for the start
address you wish to edit.

Enter the data in hex, copying the appropriate hex listings given for
your machine (depending on whether it's 16K or 48K). Please check each
block of data with the checksum given. Once you have finished, exit
from the Basic program by typing '##' when prompted for hex input.

Before running the program SAVE the machine- code first. To SAVE on
16K machines type: SAVE "TOOL" CODE 31900,931. On the 48k model type:
SAVE "TOOL48" CODE 64000,1028. Now you're ready to run. Type: CLEAR
31888 (CLEAR 63988 for 48K). Then type: LOAD "" CODE 31900 (48K
machines: LOAD "" CODE 64000). Your program is now ready and waiting.

To start the renumbering routine on the 16K model, type: RANDOMIZE USR
31900, or for 48K: RANDOMIZE USR 64000. This defaults to renumber with
starting line 10 and increasing in steps of 10. But if you wish to
change this, select the appropriate POKE from the list below,
replacing the variables (like LOW STEP-NUMBER) with the appropriate
decimal number. The 'LOW' and 'HIGH' are there because the step size
and start number (both currently set at 10) are stored in two bytes,
LOW and HIGH.

In the unlikely event that you want a number in either case over 255
(which in binary is the highest value of a byte - 11111111), then you
will have to use the HIGH byte, otherwise ignore it. Note that the
program will not renumber properly if the numbers are greater than
10,000, 50 alter the steps accordingly.

16K models:                     48K models:
POKE 31901, low step-number     POKE 64001, low step-number
POKE 31902, high step-number    POKE 64002, high step-number
POKE 31907, low start-number    POKE 6400710w start-number
POKE 31908, high start-number   POKE 64008, high start-number

To start the auto line number on the 16K models, type: RANDOMIZE USR
32333, or for 48K: RANDOMIZE USR 64429. Then type the start line.
After each ENTER the program will automatically produce the next line
number.

After each line entered you will see on the right-hand side of the
screen a number in angle brackets. This is the all important checksum.
You check this against the number printed in the same fashion in the
listing in the magazine. If the numbers match, you can be fairly
certain that you haven't made any typing errors. If the numbers don't
match, check carefully through the line, trying to spot those obscure
but often damaging little errors. But remember, even the smallest
change will alter the value of the checksum, even if it won't alter
the running of the program (for example, if you re-worded or shortened
a REM statement).

In order to stop entering the program, just press ENTER straight after
the line number. If you wish to turn the auto line function off at any
time, type: RANDOMIZE USR 32330 for 16K models, or for 48K: RANDOMIZE
USR 64426.

Note that when entering the program the first line will not be listed
to the screen. To produce a full listing to the screen with checksums,
type: RANDOMIZE USR 32768 for 16K models, or for 48K: RANDOMIZE USR
64789. To produce a checksum listing to the printer type: RANDOMIZE
USR 32775 on 16K models, or for 48K: RANDOMIZE USR 64796. A summary of
the POKEs and USR calls are given in Fig.4.

By John Wilson, a computer programmer.


FUNCTION:       16K ADDRESSES:          48K ADDRESSES:

Starting up:    CLEAR 31888             CLEAR 63988
Loading         LOAD "" CODE 31900      LOAD "" CODE 64000
(Note that you can use the program name between the inverted commas in
the LOAD statement.)

Renumber:
Enable          RANDOMIZE USR 31900     RANDOMIZE USR 64000
Change step     POKE 31901,low step     POKE 64001,low step
                POKE 31902,high step    POKE 64002,high step
Change start    POKE 31907,low start    POKE 64007,low start
                POKE 31908,high start   POKE 64008,high start

Auto line and checksum:
Enable          RANDOMIZE USR 32333     RANDOMIZE USR 64429
Disable         RANDOMIZE USR 32330     RANDOMIZE USR 64426
Change step     POKE 32433,low step     POKE 64529,low step
                POKE 32434,high step    POKE 64530,high step

Listing program plus checksum:
To screen       RANDOMIZE USR 32768     RANDOMIZE USR 64789
To printer      RANDOMIZE USR 32775     RANDOMIZE USR 64796

