GET_GMC

GET is a relocatable 289-byte machine code subroutine, embedded in line 1’s REM statement, that provides controlled keyboard input for ZX81/TS1000 BASIC programs. It is invoked via USR GET, returns the length of the typed response, and stores the actual characters in a pre-defined string variable G$. The routine reads an allowable character set from the REM line immediately following the RAND USR GET call, supporting ranges (e.g., 0-9, A-F) and comma-separated lists. It features a flashing cursor, DELETE key support, an elapsed-time counter accessible via PEEK 16516–16518, and a configurable “key already pressed on entry” behaviour patchable at GET+129.

---

Program Analysis

Program Structure

The program divides cleanly into three layers: the machine code payload in line 1’s REM, a short BASIC runtime support block (lines 2–190), and a lengthy self-documenting demonstration that runs from line 1000 onward. Line 90 immediately branches to the demo, so lines 100–190 act as a reusable subroutine called repeatedly with GOSUB 100.

1. Line 1 – REM holding 289 bytes of Z80 machine code (the GET routine itself).
2. Line 2 – REM title/authorship label.
3. Lines 3–4 – Variable initialisation: GET=16520 (entry point), A$ (prompt string).
4. Line 90 – Unconditional branch to demo start at 1000.
5. Lines 100–190 – “Press CONT or STOP” input subroutine, itself using USR GET.
6. Lines 1000–2120 – Sequential demo/documentation pages, each terminated by GOSUB 100.
7. Lines 9997–9999 – End-of-program housekeeping: STOP, SAVE, RUN loop.

Machine Code Payload (Line 1 REM)

The 289-byte Z80 routine stored from address 16520 (decimal) is fully relocatable; its entry point is defined by LET GET=16520, which must be adjusted if the routine is placed elsewhere. Key behaviours reconstructable from the hex dump include:

• Reads the ZX81 system variable at address 0x4010 (E_LINE area) to locate the REM line immediately following the calling BASIC line, which specifies allowable characters as ranges (A-F) or comma-separated lists (2,7,C,R).
• Maintains a 24-bit elapsed-tick counter written to addresses 16516–16518 (PEEK 16516 + 256*PEEK 16517 + 65536*PEEK 16518), allowing response-time measurement.
• Uses a flashing cursor character whose ASCII code is held at GET+113 (default 0 = space), patchable at runtime with POKE GET+113,CODE "S" etc.
• Entry-time key-press suppression logic is controlled by a single byte at GET+129: value 40 (normal, debounced) or 24 (accept key already held on entry).
• The routine returns the length of the typed response in the ZX81 calculator stack/HL register pair, which BASIC reads as the result of USR GET; the response itself is written directly into the pre-allocated string G$.
• DELETE key handling and automatic exit when G$ is filled are implemented entirely in machine code.

BASIC Invocation Pattern

The canonical calling sequence demonstrated in the program is:

1. Allocate response buffer: LET G$=" " (length sets maximum input length).
2. Position cursor: PRINT AT row,col;
3. Call routine and capture length: LET N$=G$( TO USR GET)
4. Immediately follow that line with a REM specifying valid characters: e.g., REM Q or REM 0-9.
5. Test N$ for empty (ENTER pressed with no input) or specific values.

The slice G$( TO USR GET) is an elegant single-expression idiom: USR GET both executes the machine code and returns a number used immediately as the string slice upper bound, discarding trailing padding spaces.

The CONT/STOP Subroutine (Lines 100–190)

Lines 100–190 use GET recursively (the subroutine calls USR GET while itself being called from within the demo). It sets G$=" " (four spaces), calls USR GET constrained to REM C,N,O,P,S,T at line 140 (the six distinct characters in CONT and STOP), then pattern-matches the returned N$ against "STOP" and "CONT". An empty response (ENTER alone) loops back. A valid "CONT" clears the screen and returns; "STOP" halts execution.

Response-Time Counter Demo

Lines 1580–1670 demonstrate the timer feature. The user is asked to press Q; after the call returns, the counter bytes are read and converted to seconds using the empirical constant 446.1667 counts per second (noted as approximately 26,770 counts per minute). The author explicitly acknowledges this constant varies between machines and must be calibrated per unit.

Relocation and Memory Placement Notes

The demo text describes three valid placement strategies for the routine:

• Inside a line 1 REM (as demonstrated here), with POKE 16419,2 to shift the BASIC display start past line 1 so LIST 2 shows the program without the binary garbage.
• Above RAMTOP (in the space reserved by lowering RAMTOP before loading).
• Between the BASIC program area and the display file.

The value GET=16520 corresponds to the byte immediately after the five-byte line header of line 1 (line number 2 bytes + length 2 bytes + REM token 1 byte = 5 bytes; line 1 starts at 16514 on a standard 16K machine, so the payload begins at 16519 or 16520 depending on the exact header count), consistent with standard ZX81 memory layout where BASIC starts at address 16509.

Notable Techniques

• Self-documenting demo loop: The entire program is both documentation and live demonstration, using GET to page through its own manual.
• Parameterised character filter via REM: Reading the following REM line at runtime to determine valid input is an unusually flexible design for a machine code routine of this era.
• Single-expression capture: LET N$=G$( TO USR GET) avoids a separate variable assignment for the length.
• Patch-in-place customisation: Cursor character and entry-debounce behaviour are exposed as documented POKE offsets rather than requiring re-assembly.

Bugs and Anomalies

• Line 1130 concatenates without a newline after “G$.” and continues on line 1140 mid-sentence — a cosmetic flow artifact of the 32-column display wrapping, not a logic error.
• Line 1790 contains the spelling “RECIEVED” (should be “RECEIVED”) — a typo in the documentation string only.
• The SAVE line (9998) saves the program as "GET"; the program counter in line 9999 uses RUN to restart, meaning a loaded copy will auto-demo from the top.