Toolkit

This program is the documentation and menu handler for “TOOLKIT,” a BASIC utility suite for the TS2068 (adapted from a Spectrum original by John Charlesworth, published in Your Computer Vol. 4, No. 4). The toolkit provides four machine code routines: a BASIC line renumberer, a REM statement killer, a variable lister, and a BASIC compactor that converts numeric literals to VAL “n” form to save 3 bytes per number. The machine code block is 1350 bytes long, loaded at address 64048, with entry points at 64048 (renumber), 64841 (REMKILL), 65017 (compaction), and 65184 (list variables). The renumber routine reads its new-first-line and step values from system memory via POKE to addresses 23299–23302 before calling USR 64048. A two-part tape SAVE routine stores the BASIC and machine code separately, and the loader at line 9998 uses CLEAR to set RAMTOP before loading the code block.

---

Program Analysis

Program Structure

The program is divided into two major functional blocks: a documentation browser (lines 9936–9987) and the main toolkit menu/dispatcher (lines 9988–9999). The documentation block itself is organized as a multi-page reader with a shared subroutine-like jump target at line 9980 that handles page-turn navigation. The toolkit menu at line 9988 uses a numeric INPUT into variable FFF to select functions, followed by a cascade of IF statements dispatching to the appropriate machine code entry point.

Documentation Browser (Lines 9936–9985)

Lines 9936–9945 display the top-level documentation menu and handle key input for four choices: backup, read documentation, go to toolkit menu, or stop. The documentation itself spans six pages (lines 9947–9976), each page ending with a LET RET=VAL "NNNN": GO TO VAL "9980" pattern that stores a return address in the variable RET before jumping to the shared page-navigation handler.

The handler at line 9980 prints a status bar to channel #1 (the lower screen) offering COPY, MENU, or ENTER=NEXT PAGE options. Lines 9981–9985 poll INKEY$ in a tight loop, branching on Enter (CHR$ 13) to clear screen and jump to RET, on M/m to RUN (restarting the program), or on C/c to invoke COPY.

Toolkit Menu and Dispatcher (Lines 9988–9997)

Line 9988 presents the six-option main menu and takes a numeric INPUT into FFF. Option 1 (RENUMBER) falls through to line 9989, which prompts for the new first line number (TTT, default 100) and step (SSS, default 10). Line 9990 validates the parameters before proceeding.

Options 2 through 5 are handled by individual IF lines (9992–9995), each calling a specific machine code entry point via RANDOMIZE USR or PRINT USR.

Machine Code Entry Points

Option	Function	Entry Point	Call Method
1	Renumber	64048	RANDOMIZE USR
2	REMKILL	64841	RANDOMIZE USR
3	List Variables	65184	PRINT USR
4	Compaction	65017	RANDOMIZE USR

The use of PRINT USR for the variable lister (line 9993) rather than RANDOMIZE USR is intentional: the machine code routine returns a value to be printed, or the call is simply used for its side effect with the return value discarded to screen. Note that line 9993 issues a STOP after the call, consistent with the documentation’s instruction to use COPY to capture variable output.

Renumber Parameter Passing via POKE

Line 9991 communicates the new first line and step to the machine code by POKEing values into addresses 23299–23302. The high and low bytes of each 16-bit value are computed manually:

• POKE 23300, INT(TTT/256) — high byte of new first line
• POKE 23299, TTT - 256*PEEK 23300 — low byte of new first line
• POKE 23302, INT(SSS/256) — high byte of step
• POKE 23301, SSS - 256*PEEK 23302 — low byte of step

This avoids using the INT/MOD combination or bitwise operations, instead reading back the already-POKEd high byte to compute the low byte remainder.

SAVE/LOAD Mechanism (Lines 9946, 9995, 9998–9999)

The program performs a two-part tape operation: first saving the BASIC with LINE 9998 as the auto-start line, then saving the 1350-byte machine code block starting at address 64048. Line 9998 is the bootstrap loader that issues CLEAR 64048 to set RAMTOP, prints a status message, and then loads the code block. Line 9999 jumps to line 9931, which is not present in this listing — it presumably exists in the full loaded program as an entry point into the toolkit.

The backup option at line 9946 saves under the name “TOOLKIT” whereas the in-menu save at line 9995 uses “TK” and “TKB” — a minor inconsistency between the two save paths.

Key BASIC Idioms and Techniques

• VAL “n” everywhere: Nearly all numeric literals are written as VAL "n", which is the compaction format that TOOLKIT’s own compaction function produces. This entire handler section is already in compacted form, demonstrating the tool’s output.
• Tight INKEY$ polling: Lines like IF INKEY$="" THEN GO TO VAL "9939" form a busy-wait loop for key detection, a standard idiom.
• Lower-screen status bar: PRINT #VAL "1"; AT VAL "0", VAL "0"; ... writes to the two-line lower screen area (stream 1), keeping menu prompts separate from the main display area.
• GO TO non-existent line 9931: Used deliberately as a jump to a line that exists only after the full toolkit is loaded; harmless during documentation browsing since this path is only reached after a SAVE/LOAD cycle.

Anomalies and Notes

• Line 9952, 9958, 9964, 9970, 9975, 9978, 9979, 9986, and 9987 are empty lines serving only as visual separators in the listing.
• Line 9988 contains an INPUT FFF followed immediately by IF FFF<>VAL "1" THEN GO TO VAL "9992", meaning option 1 falls through inline to line 9989 rather than branching — a slightly unusual but valid flow.
• The documentation explicitly warns that GO TO VAL "1000"-style computed line numbers will not be renumbered by the toolkit — an honest self-referential limitation, since this entire program uses that very pattern.
• Line 9962 notes that a “NONSENSE IN BASIC” error after toolkit operations is not abnormal, suggesting the machine code may leave the BASIC pointer in an inconsistent state.