TOOLKIT

Toolkit is a BASIC program manager for the TS2068 that provides four machine code-driven utilities: RENUMBER (with GOTO/GOSUB chain updating), REMKILL (bulk deletion of REM statements), LIST VARIABLES, and COMPACTION (converting numeric literals to VAL “n” form to save 3 bytes each). The machine code, 1350 bytes loaded at address 64048, was originally written for the ZX Spectrum by John Charlesworth and published in Your Computer magazine (Vol. 4, No. 4), then adapted for the TS2068 by Jack Dohany. A two-part tape save routine handles the BASIC portion (saved with an auto-run LINE parameter) and the machine code block separately. The COMPACTION function uses the VAL “n” number-storage trick, and the documentation explicitly warns that RENUMBER must be run before COMPACTION, and that computed or evaluated line numbers (such as GO TO VAL “1000”) are not handled by the renumberer.

---

Program Analysis

Program Structure

The program divides into three logical regions. Lines 10–160 form the documentation browser, a paginated help system navigated by a lower-screen menu. Lines 800–940 contain the shared subroutine for the page-navigation prompt. Lines 9980–9999 are the Toolkit Menu and machine code handler, kept in the high line-number range so they survive a DELETE 1,1000 when a user wants to merge their own BASIC program with the toolkit.

Line range	Role
10–20	REM credits and main documentation menu display
50–68	Documentation main menu: backup, read docs, go to toolkit, stop
90	Backup routine (from documentation menu)
100–160	Six-page documentation browser
800	Spare STOP (unused in normal flow)
900–940	Page-navigation subroutine (Copy / Menu / Last / Next)
9980–9996	Toolkit menu: INPUT selection, dispatch to machine code
9998–9999	Boot loader: sets RAMTOP, loads machine code block, jumps to line 1

Machine Code Interface

All four functional utilities are implemented as machine code routines residing at fixed addresses starting at 64048. The BASIC handler passes parameters via POKEs into system variables before calling RANDOMIZE USR.

• RENUMBER — entry point USR 64048. New first line stored at addresses 23299–23300, step at 23301–23302, split across two bytes using INT (n/256) for the high byte and n - 256 * PEEK for the low byte.
• REMKILL — entry point USR 64841. No parameters needed.
• LIST VARIABLES — unusual use of PRINT USR 65184 rather than RANDOMIZE USR, suggesting this routine returns a printable value (likely 0) as a side effect after outputting to the screen.
• COMPACTION — entry point USR 65017. Converts numeric literals to VAL "n" form, saving 3 bytes per number.

The machine code block is 1350 bytes long. At load time (line 9998), CLEAR 64048 sets RAMTOP to protect this area before the block is loaded with LOAD ""CODE.

Two-Part Tape Save

Both the documentation menu (line 90) and the toolkit menu (line 9994) implement a two-part tape save. The BASIC program is saved with a LINE 9998 auto-run parameter (pointing to the boot loader), followed by a BEEP gap, then the machine code saved as a CODE block at 64048 for 1350 bytes. A VERIFY pass with empty filenames is used to confirm both parts. Lines 90 and 9994 are nearly identical save routines; line 90 names the BASIC file "TOOLKIT" while line 9994 names it "TK", suggesting the shorter name was adopted for tape efficiency or label convenience.

Page Navigation Subroutine (line 900)

The subroutine at line 900 is the documentation engine’s navigation layer. It displays a one-line menu in the lower screen (PRINT #1) offering Copy, Menu, Last page, or else next page. It then busy-waits with a polling loop at line 910 that waits until INKEY$ changes from its initial (empty) captured state, avoiding the stale-keypress problem. Line 925 normalizes lowercase to uppercase with CHR$ (CODE k$-32), enabling case-insensitive input.

Documentation Flow and Page Navigation

Each page ends with a GO SUB 900 call. On return, the caller checks K$: if "M" it runs from the start (RUN), if "L" it jumps back one page explicitly. The “next page” action falls through to the next line naturally. This gives a simple but effective forward/backward pager without a page-number array.

• Lines 108–109: Menu or back to page 1 (line 100)
• Lines 118–119: Menu or back to page 1 (line 100)
• Lines 128–129: Menu or back to page 2 (line 110)
• Lines 138–139: Menu or back to page 3 (line 120)
• Lines 148–149: Menu or back to page 4 (line 130)
• Line 152: Last page — always returns to menu on any key (no “Last” option)

Lines 158–160 appear after line 152 and are unreachable in normal flow, representing a dead code fragment likely left over from an earlier page-layout revision.

Toolkit Menu Input Method

Rather than using INKEY$, the toolkit menu at line 9980 uses INPUT FFF to read the function number as a numeric variable. This means the user must press Enter after typing their choice. Each option is dispatched by a sequential chain of IF FFF=n THEN ... checks on lines 9982–9995, with a fallthrough GO TO 9980 at line 9996 for invalid input. The variable name FFF (all-caps triple letter) is unusual but valid BASIC.

Notable Techniques

• High-byte/low-byte POKE pattern for 16-bit values: POKE addr, INT (n/256) and POKE addr-1, n - 256*PEEK addr — a standard approach for passing 16-bit integers via system memory.
• Case normalization via CHR$ (CODE k$-32) at line 925, only applied when k$ > "Z" (i.e., when the character is lowercase ASCII).
• PRINT USR for LIST VARIABLES (line 9990) rather than RANDOMIZE USR; this is intentional since the routine presumably prints its own output and returns 0, and using PRINT avoids leaving a floating-point result in the calculator stack.
• CLEAR before LOAD CODE at line 9998 to protect the machine code area from BASIC’s memory manager.

Bugs and Anomalies

• Line 900 uses lowercase k$ while most of the documentation browser checks uppercase K$. In Sinclair BASIC these are distinct variables. Line 108 checks k$="M" (lowercase) which matches the subroutine’s assignment, but lines 118, 128, 138, 148 check K$="M" (uppercase), meaning the Menu option silently fails on pages 2–5 (only “Last page” or “next page” will work). This is a likely transcription bug introduced during adaptation.
• Lines 158–160 are dead code unreachable from the normal documentation flow after line 152’s unconditional GO SUB 900: RUN.
• Line 9982 sets defaults TTT=100 and SSS=10 with IF FFF=1 THEN INPUT ... on the same line, meaning the defaults are assigned even when FFF<>1, though this is harmless since the branch to 9988 skips the renumber logic.