Your Spectrum
Issue 6, August 1984 - Toolkits
Home Contents KwikPik
A toolkit is a utility program that will take a lot of the sweat and worry out of writing and debugging your own programs; often too, it will give commands and routines the computer manufacturer should have installed in the ROM in the first place! These are likely to include: Renumber, Delete, Free Memory, Find, List Variables and Alter. You may find one or two are missing, but in that case, there'll probably be instead some other useful goodies tucked away in that binary brainbox. And, as you'll see from the table included in this article, some toolkits have a larger range of commands than others. But, much like computers in general, put a number of them side-by-side and you'll be able to say that each should ideally have something that one of the others has got. That's life, I guess!
So, what are these routines for? Well, say for instance that you've written a long program without keeping an absolute record of the variable names you have used (tsk, tsk). In that case, FIND DX (for instance) will jump to the rescue and list out the lines where you used the variable DX. No can find? Great ... in that case you can use it as your next variable.
Have you ever kept rigidly to a line spacing of 10 - 10, 20, 30, 40 ... - only to find that you need to insert some lines between lines 110 and 120? Well, no problem if there are just a few of them - 111,112, 113, etc. But what if you need to insert a routine of 20 or so lines? Yes, of course you can change the line numbers, but at this stage it's all too easy to overwrite an existing line and ... whoops, another chunk of debugging to deal with. RENUMBER is the simple and safe (usually!) way out.
Then again, perhaps you have a big program and you want to know how much memory you've got left. You can remember reading in that book you bought last Saturday about some POKEs and PEEKs that will tell you but, now where was that page? In fact, it's much easier to just type FREE (or some such) and see the answer immediately. All these are often used applications of the ubiquitous toolkit.
If you're in the market for a toolkit (or I've just convinced you that you should be!), you probably won't be surprised to find out that there are a number of toolkits for the Spectrum, and two of the five reviewed here are readily available over the counter in two of the larger chain stores. The other three can be ordered through the post if you're unable to find them in good shops.
The table at the end lists the routines available from each toolkit and provides a quick comparison of what each offers. But this is by no means the whole story, for ease of use is an important factor too. One toolkit from a year or so back required something like 'RANDOMIZE USR 63338 a,b,c,d' to be typed in each time you wanted a specific routine; certainly it provided the goods, but it was also a case of getting the instructions out every time you wanted to use it! Then there's the matter of
Essential for software development, toolkits are often billed as the programmer's 'tools of the trade'. Peter Freebrey takes five such packages on the bench and examines whether they fulfill their promise.
'friendliness' of operation ... is it possible to irrevocably change (or ruin) your program by just a simple mis-key? Sometimes to get the set of routines you want, you have to accept a compromise. I'll be dealing with each toolkit individually, pointing out not only its better points but the rough edges as well. Do you want ease of use? Do you use a lot of user-defined graphics? Do you write long, long programs?
As usual, the final decision has to be tempered by the specific needs of the prospective user. So, research your requirements and check 'em all out.
LINE RANGEstartfullstart

Master Toolkit
This product also uses an interrupt mode and in so doing introduces two new routines to the expected toolkit range: CLOCK and ALARM. Although I doubt that these will shake the programming world, we all know how easily time flies when deep into the latest keyboard creation. The line-up of routines in Master Tool Kit (MTK) is fairly extensive and easy to use. It has programs for either 16K or 48K machines, one each side of the cassette. LOADing is carried out with LOAD "", and to invoke the toolkit press Symbol Shift and Space at the same time. This will clear the screen, and now the routines may be called by pressing a single key followed by Enter. MTK will remain active until you key 'B' (return to Basic). The only criticism I have of the system is that the 'R' key is used for
(surprise, surprise...) RENUMBER; 'R' is also Spectrum's RUN key and should you forget - in a moment of weakness - that you've not returned to Basic, 'R' will RENUMBER your program completely starting at line 10! This is because MTK routines are called in the form:

R range,start,increment

But if no additional information is added to the prime call letter, then default values are assumed; in this case: 'range' - the entire program; 'start' - 0; and 'increment' - 10. Having default values assumed is useful on the one hand, but on the other there's then no option to escape. This option of range is a nice feature of MTK and obviously vital for a good RENUMBER; it's also very useful in specifying a range of lines in which to FIND or SUBSTITUTE.
MTK has a neat feature where Space and the 'K' key pressed together change the cursor to its K mode and where the next key pressed generates its associated keyword - so saving the common need to key in THEN ... KEYWORD followed by delete THEN! RENUMBER will only work within a sequential block of lines and to change the order of blocks, you'll have to use MOVE. This brings us to the only apparent bug in MTK. On MOVEing a block of lines, you may want to alter the GO TOs, GO SUBs and so on, that
refer to this block. They will still have the old numbers and the obvious ploy is to use the facility provided - SUBSTITUTE. But be warned, although the routine will appear to work, in this case it does not. It will provide a string, and not a substitute number! Your program won't recognise these pseudo- numbers, so use FIND and LIST instead and then make the necessary changes individually.
In addition to the more usually found REMKILL, to save on memory space, MTK also offers the option of PACK which will 'pack' multiple statements into single lines. Going yet one stage further you also have COMPRESS which will replace explicit numeric constants in a form that the computer recognises but which, in certain instances, can save a considerable amount of memory space.
Not only does MTK have a versatile range of toolkit routines, it also provides the facility of programmable function keys. Ten keys ('0'-'9') may be user- defined either to simply print the specified function (keywords, variables, text, etc) or to print and ENTER - altogether a very desirable feature. DISPLAY VARIABLES is a complete LIST including all elements of arrays (all variables except for FOR ... NEXT loops are displayed in lower case, even if you've programmed them in capitals). MTK does not have auto- line number or a display of user- defined graphics.
TT-S Gamma
This tape from Timedata not only has a toolkit (called Gamma) that's much like the foregoing, but also four other utility programs - high resolution screen drawing, user-defined graphics creator, a tape header analyser, and a machine code memory test program. With this, you certainly get your money's worth!
The toolkit program comes first and you load it by keying LOAD "".This auto-RUNs and immediately sets two general safeguards - NEW is inhibited so you can no longer accidentally erase your program and it's impossible to overwrite an existing program line. Thus you have an excellent line editor;
type in the line you wish to EDIT, press any keyword key and the line is displayed at the bottom of the screen. If required, it may be deleted by either DELETE or by typing in the line number and keying Enter.
Once you've invoked the toolkit by hitting the '0' key with the Symbol Shift key pressed, routines are all single key entries. AUTO line number and DELETE need no comment. FREE not only displays the free memory available, program and variable space but also the current values of the system variables; it also shows the current user- defined graphics characters. HELP displays the toolkit routines and their associated keys; FIND will hunt out occurrences of a specified string starting its search from a specified line number (defaulting to line 0 if no start is given).
Only the line numbers are displayed - no program lines are LISTed. RENUMBER will only work within a sequential block of lines (renumbering all GO TOs, GO SUBs, etc). MOVE is superior to other versions in that it also renumbers all references to the new block of lines (providing they're not in the form of GO TO 330+R). In fact MOVE is so good one wonders why
Gamma has got both RENUMBER and MOVE! Both commands are 'intelligent' in that they'll close up the specified line increment, even where you've not allowed sufficient space! It's also possible to have lines going up to line 16000 (normal maximum is 9999). The first two digits of these extended lines are replaced by a non-numeric character and they can't be edited (although they can be RENUMBERed or MOVEd). References to these lines elsewhere will have to be changed for the program to function correctly - for instance, GO TO < 350 becomes 12350.
The keyword, VARIABLES, LISTs variables but arrays are only shown by their dimensions. F/N is put against variables used in FOR ... NEXT loops together with the line number of the FOR statement. TRACE is an interesting variant in that not only can you select the delay (from single-step up to about five seconds) but in addition to displaying the current line number, it'll also show the current values of specified variables.
All the TT-S programs will run on either 16K or 48K Spectrums, with or without Interface 1 and Microdrives. Routines are even provided that enable you to copy these programs on to a Microdrive wafer.

This toolkit has been on the market for a long time (in computer program terms) and it's one I've used extensively over the last two years. These days, coming with additional options, ZXED is still easy to use and reasonably foolproof. On LOADing, it automatically relocates in memory to suit either 16K or 48K Speccy. It has a short Basic call routine starting at line 9900 and the toolkit functions are invoked by GO TO 9900. I have the following two lines at the beginning of my programs:

1 GO TO 100
2 GO TO 9900

Where line 100 is the true start of my program. Once called, the display will
show a flashing 'T' cursor in the bottom left corner of the screen - all toolkit routines are now obtained by a single key operation. H - HELP will display the routines and their call letters.
ZXED is very 'user friendly' ... call R - RENUMBER and you will be asked 'from line' ... followed by 'to line' ... 'new base' ... and finally 'increment'; there's no need to refer to the manual here! You don't even have to give actual line numbers, providing of course that the portion you wish to RENUMBER falls within the line numbers you have specified. There are a few points to watch out for: 1.) when you MERGE your program with the previously LOADed toolkit, you must not have any lines in the range 9900 to 9916 - ZXED's Basic call routine; 2.) if you wish to APPEND - to add further commands or text to an existing line(s) - you must remember to start with a colon; and 3.) SEQUENCE (Auto line number) will not differentiate between an unused line number and one already assigned.
RENUMBER will only renumber sequentially within a specified block of lines; in other words, if you have blocks of lines starting at 100, 500 and 1000 you can RENUMBER the block at line 100 anywhere up to the start of the next block (anywhere between one and
500). If your new block of lines overwrites existing lines (at say line 500) then ZXED will not implement your command and will print an appropriate error message.
On completion of a successful RENUMBER, all GO TOs, GO SUBs, RESTOREs, LISTs, LLISTs, RUNs, SAVEs and line references are renumbered with the exception of computed GO TOs, GO SUBs, etc, (for example GO TO 330+R) but ZXED will LIST these for your inspection. If you do wish to move an entire block of lines to elsewhere within the program, then MOVE will do this. But you must make a note of all references to line numbers calling into this block from elsewhere in the program and alter them individually. To help you do this you can use FIND. ZXED's FIND is probably one of the best I've come across and on calling it, you are asked to enter the search string (keywords, variables or text). Having done so, all lines with this search string will be LISTed to the screen.
ZXED also gives the option of a reduced package of routines (on the other side of the tape) which take up less memory; here the options are reduced to BYTES (Free Memory), DELETE RENUMBER and SEQUENCE. This facility can be useful if you have a long program which needs some tidying up!
Super Toolkit
This is quite a newcomer to the market and uses an interrupt mode of operation. In theory, therefore, a routine using this mode can be inserted and performed between the computer's regular cycle of operations. Of course, the computer has to display a screen picture, and it also has to work out the computations that you've set within your program; it can't do these simultaneously and so it carries out the various manoeuvres in strict cyclic order. Interrupting this order and performing another operation can be highly beneficial in certain circumstances, although with this toolkit I'm not so sure.
Nectarine goes to some pains to tell the user not to use Super Toolkit with Interface 1 connected (ie. Microdrives) or with a machine code program using interrupts; despite that, a new version will be available soon on Microdrive
cartridge. The introduction in the instruction manual says "all in all these features (the toolkit routines) add up to make Super Toolkit the most useful, powerful and user friendly suite of utility programs available to Spectrum Basic programmers". I'll let you make up your own minds on that one ... just don't write in if you disagree with it.
The tape provides versions for both the 16K and 48K Spectrums, plus there's a demonstration program. That's sensibly placed after the two toolkit programs, obviating the need to grind through it each time you want to LOAD your toolkit. If you've keyed in LOAD "" (for the demo), don't get worried if your Spectrum appears inert - it's merely ignoring the first two machine code programs on the tape.
To LOAD Super Toolkit (48K version) type 'CLEAR 62838: LOAD "48" CODE' and having got a successful LOAD, enter 'RANDOMIZE USR 62839' to activate the routines. You can then LOAD or enter your program. To call the commands, simply press Enter and the relevant key (for example, Enter and the 'M' for the MEMORY MAP). If you have RUN your program, first enter PRINT, REM or CLS to enable the toolkit.
The routines themselves are somewhat limited in operation: RENUMBER will only renumber the complete program; you can choose the 'start line' and 'step' but not a finish line! The manual says "it looks neater and is easier to debug if the lines are all
numbered in equal steps". I suppose it does look neat but I prefer to keep my programs structured (loosely) in blocks - for instance, all initialisation, DIMs, etc, starting from line 100; important GO SUBs from line 500; the main program starting from line 1000; and DATA from line 8000. Then I always know where to look for specific routines, whereas here one use of Enter and the 'R' key and I'd be lost.
Super Toolkit does not renumber computed lines (GO TO 330+R, etc) which is fair enough as neither do any of the others. But it does not tell you if or where any such lines may be. BLOCK DELETE functions correctly but is a trifle slow. There's no FIND but there is REPLACE KEYWORD, which only works on keywords (PRINT, REM, LIST, and so on). You're asked for the CODE of the old keyword and the CODE for the new - and this you will have to look up in your Spectrum manual (pages 183-188). Although this works well, the routine seems a little limited. The only use for it that comes to mind is that suggested in the instructions - PRINT to LPRINT!
There appears to be a bug in the LIST VARIABLES routine; although it produced a screen display, the keyboard always locked-up after its use. That means the power supply has to be switched off and back on again, to regain control (with the subsequent reLOADing of both the toolkit and the program). The VARIABLE LIST indicates an array with two brackets but doesn't give the dimensions.

ZX Toolkit
This package, though not so well publicised as ZXED, has been available for nearly as long and has been upgraded slightly to include a SEARCH and LIST routine and limited Microdrive information (by calling MEMORY MAP). Two versions are provided (on either side of the tape), one each for 16K
and 48K machines. Operation is slightly more fiddly than with ZXED. For instance, to call the RENUMBER routine, you have to key in RANDOMIZE FN r (start line, finish line, new start line, step) including the brackets and commas. All GO TOs, GO SUBs and so on are renumbered (with the exception of computed line numbers) and these must be altered (if necessary) individually. To help the programmer these are displayed 'flashing' within the LISTing. If you wish to RENUMBER outside a sequential block then, as in ZXED, you have to use MOVE. However, with this toolkit, while the lines are MOVEd to a new position in the program LISTing, their original line numbers are retained. This enables you to use RENUMBER on these lines (to put them in their right sequence), which will then alter all the relevant calls to this block anywhere in the program - clever stuff!
On all calls that involve displaying a
result (SEARCH and LIST, MEMORY MAP, VARIABLES DUMP, and so on) you must specify the output device. Sadly, SEARCH and LIST only displays line numbers of the occurrence and does not LIST the full lines. MEMORY MAP gives a fair bit of information, including the size of the program and bytes free, and displays the user-defined characters. The TRACE routine displays the current line number of a RUNning program at the top right of the screen and the speed of program operation is selectable from normal down to very slow. The VARIABLES DUMP is useful but fails to list individual elements of arrays, giving only the lengths of string variables.
Unusually, Star Dreams has also included a HEX DUMP starting at a specified memory location. Those with a little time to spare who are interested in what goes on inside the Spectrum will find this facility provides good reading.
Home Contents KwikPik