Hex Code Memory Loader

This program is a hexadecimal machine-code editor and assembler aid for entering Z80 opcodes directly into reserved RAM above RAMTOP. It reads RAMTOP from system variables at addresses 16388–16389, then lets the user type hex byte pairs interactively, displaying them in a grid of 10 columns with a moveable cursor. Commands dispatched via a lookup array F(20) support operations including GO (execute via USR), LOAD (POKE bytes into RAM), SAVE, DELETE, cursor movement (positive and negative), relative jump calculation with asterisk-placeholder adjustment, a DOWNLOAD routine that prepends a self-contained tape-loader header sequence, and a full screen PRINT redisplay. The relative-jump subroutine at line 1300 correctly handles the two’s-complement wrapping for backward branches and accounts for placeholder asterisks in the hex string that represent not-yet-resolved bytes. RAMTOP is manipulated at line 9060 by poking address 16389 to reserve blocks of 256 bytes, after which the program re-saves and restarts itself.

---

Program Analysis

Program Structure

The program is divided into clearly delineated functional blocks, each occupying a line-number range and labelled with inverse-video REM comments:

Line range	Purpose
10–50	Memory reservation check / entry gate
60–141	Initialisation: read RAMTOP, build command dispatch table F()
200–360	Main input loop: strip spaces, classify input, dispatch or append hex
400–470	Cursor print / erase subroutines
500–520	Command dispatcher
600–660	Append hex bytes to display grid
700–750	GO – execute code at RAMTOP via USR
800–890	LOAD – POKE hex string into RAM
900–970	Move cursor forward
1000–1070	Move cursor backward
1100–1195	Redisplay entire hex buffer
1300–1390	Relative-jump calculation
1400–1460	SAVE program
1600–1640	DELETE bytes at cursor
2000–2090	Asterisk-placeholder adjustment for relative jumps
3000–3130	DOWNLOAD – prepend tape-loader stub and POKE all bytes
9000–9110	Reserve memory by poking RAMTOP, re-save and restart

Command Dispatch Mechanism

Commands are single characters whose ASCII codes (minus 43) index into the array F(20), populated at lines 131–141. The dispatcher at line 510 is simply:

GOSUB F(CODE I$(1)-43)

The trigger condition at line 300 is CODE I$(1)>=44 — i.e. any character with ASCII code above 43 (comma) that is not a hex digit handled earlier. The mapping is:

Character	ASCII	Index (ASCII−43)	GOSUB target	Function
,	44	1	700	GO (execute)
3	51	6 (but 3=hex digit, unreachable)	800	LOAD
.	46	3	—	(unassigned)
+	43	—	—	(below threshold)
F(6)=800	Triggered by ASCII 43+6=49 = ‘1’ — potential conflict with hex digit ‘1’

In practice the hex digits 0–9 and A–F have ASCII codes 48–70. The check at line 300 (CODE I$(1)>=44) means single-character hex digits like ‘,’ (44) would be misrouted. The program sidesteps most conflicts because hex input is always exactly two characters, making LEN I$>1 true and causing the two-character hex path to be taken. However the dispatch table assignments at lines 132–141 use indices 6–18, corresponding to ASCII codes 49–61, which overlap with hex digit characters — this is a latent ambiguity for single-character commands that happen to be hex digits.

RAMTOP and Memory Reservation

The ZX81/TS1000 system variable RAMTOP is a 16-bit little-endian value stored at addresses 16388–16389. Line 60 reads it as:

LET RT=PEEK 16388+256*PEEK 16389

When memory has not yet been reserved, the program branches to line 9000, which pokes address 16389 with 128-NB (where NB is the number of 256-byte blocks). This effectively lowers RAMTOP by NB×256 bytes, carving out space above BASIC for machine code. The program then re-saves itself and calls RUN to restart cleanly with the new RAMTOP in effect.

Hex Buffer and Display

All entered bytes are kept in the string H$ as pairs of ASCII hex characters. Placeholder ** pairs are inserted at the current cursor position CI and later replaced during POKE operations. The display grid at lines 610–650 and 1160–1190 prints pairs separated by spaces in rows of 10, with a line break (two extra spaces) after every 10th byte, creating a 10-column layout. The cursor position is displayed as an inverse > character, computed by:

PRINT AT 2+INT(CI/10), 3*(CI-10*INT(CI/10)); "%>"

This maps CI to a row/column on screen without needing a 2D array.

LOAD Subroutine and POKE Loop

The LOAD routine (lines 800–890) prepends a short Z80 stub to H$:

"3E1EED47FD210040C9"

This is: LD A,1EH / LD I,A / LD IX,4000H / RET — a standard setup sequence. The POKE loop at lines 830–890 steps through H$ two characters at a time, skipping * placeholders, and converts each hex pair to a byte value using the formula:

16*(CODE H$(I)-28) + CODE H$(I+1)-28

This relies on the ZX81 character set where ‘0’ = code 28, ‘A’ = code 38, so CODE digit - 28 gives the numeric value 0–15 for hex digits 0–9 and A–F.

Relative Jump Calculation

The subroutine at lines 1300–1390 calculates the signed byte displacement for a Z80 relative jump (e.g. JR, DJNZ). The user supplies a target cursor index JCI; the displacement is JS = JCI - CI - 1. Before computing, subroutine 2000 counts * placeholder characters between the current position and the target and adjusts JS accordingly, since placeholders occupy space in H$ but not in the final machine code. If the displacement exceeds the range −128 to +127, an error message is displayed. For negative displacements, two’s-complement wrapping is applied: JS = JS + 256. The byte is then encoded back into two hex-digit characters using the same code-offset arithmetic.

DOWNLOAD Routine

Lines 3000–3130 implement a self-contained tape-loader download. It prepends a longer Z80 loader stub to H$:

"00002A04404E23462B118240C5011D0009C1EDB03E1EED47FD210040C9"

This stub reads the byte count from the first two bytes at RAMTOP (little-endian), then performs a block load (LDIR) before the standard setup sequence. The total byte count (hex buffer length minus asterisks, plus 9 bytes for the stub) is computed at lines 3020–3050 and POKEd as a 16-bit little-endian value at RAMTOP and RAMTOP+1.

Notable Techniques

• Space-stripping loop (lines 220–260) walks I$ index-by-index and removes all spaces using string slicing, avoiding any built-in trim function.
• The F() dispatch array avoids a long chain of IF/GOTO statements for command routing.
• Cursor display uses integer division (INT(CI/10)) rather than a modulo operator, since ZX81 BASIC has no MOD.
• Hex-to-byte conversion exploits the contiguous ZX81 character codes for digits and letters, requiring no lookup table.
• The ** placeholder convention allows multi-byte instructions to be entered incrementally, with operand bytes filled in later.

Bugs and Anomalies

• Line 3060 contains a typo: "LENGHT" instead of "LENGTH".
• The delay loop at lines 9040–9050 (FOR T=1 TO 20: NEXT T) is extremely short and unlikely to provide a meaningful pause on any hardware speed.
• The command dispatch index calculation (CODE I$(1)-43) overlaps with ASCII codes for hex digit characters when commands are single characters, creating a potential ambiguity for single-character inputs that are also valid hex digits (e.g. ‘1’, ‘2’, ‘3’).
• The SAVE at line 9100 saves to filename "1024%5" (where %5 is an inverse ‘5’), which encodes an auto-run flag in a non-standard way relative to the BASIC line-number convention.
• Line 1044’s cursor-move-negative code does not call GOSUB 1100 to refresh the display after moving, whereas the positive-move routine at line 960 does call GOSUB 400 — both do call 400, so display is consistent; this is not a bug.