Hexas, Basic*Olay

Hexas is a symbolic hex assembler written in BASIC that reads machine code expressed as hexadecimal bytes embedded within REM statements and assembles it to a target address. It supports forward-reference resolution, relative jump range checking, and two-pass label/symbol table management using parallel DIM arrays for names, addresses, and relocation records. A companion relocator module generates position-independent code by patching absolute addresses at load time, making the output relocatable to any memory location. The Basic*Olay loader uses a machine code routine in REM line 1 to install an overlay system, reporting entry points for COPY and OVERLAY functions along with the next available address.

---

Program Analysis

Program Structure

The listing comprises two distinct programs. The first is Hexas, a symbolic hex assembler; the second is Basic*Olay, a loader/installer for an overlay system. In Hexas, lines 1–12 form a REM expander that grows a REM statement to hold machine code output. Lines 6670–6995 are the scanner/parser that walks through REM-embedded source. Lines 7000–7450 handle token reading and symbol definition. Lines 7460–7690 parse label and equate directives. Lines 7700–7915 perform the second-pass back-patch (relocation resolution). Lines 7970–8205 print the symbol table and completion report. Lines 8995–9090 constitute the relocator data setup routine, reached by continuing after a STOP.

Machine Code in REM Statements

Both programs store executable Z80 machine code in REM line 1. In Hexas, line 1 contains the REM expander routine invoked at line 8 via RAND USR 16514. In Basic*Olay, line 1 holds the overlay manager, invoked at line 45 via RAND USR 16686. The REM bytes are accessed directly by POKEing or PEEKing absolute addresses, a standard technique for embedding machine code without a separate binary file.

REM Expander (Lines 1–12)

Before assembly can begin, Hexas must create a sufficiently large REM statement to hold the assembled output. Lines 4–11 prompt for the required byte count N, patch the REM length field at addresses 16444–16445, call the machine code expander, then fill the new REM body with 22 (the byte for the NEWLINE token) as a placeholder. This is a well-known idiom for allocating workspace inside the BASIC program itself.

Assembler Pass Structure

The assembler is effectively a two-pass design implemented in a single scan with deferred back-patching:

1. Pass 1 (scan): Starting at BASIC address A=16508, the scanner (GOSUB 6930) seeks parenthesised hex blocks. Inside each block, hex digit pairs are assembled immediately into memory at address Z. Labels (prefixed +) are recorded in N$(NS)/N(NS). References (prefixed $ or £) are deferred into R$(NR)/R(NR).
2. Pass 2 (back-patch): At line 7700, every entry in the reference table is matched against the name table. Relative references get range-checked (±128 bytes) and POKEd as signed offsets. Absolute references ($/£) are stored little-endian by the routine at line 7920.

Symbol and Reference Tables

Array	Dimensions	Purpose
N$(LL,8)	48 × 8 chars	Symbol names (definitions)
N(LL)	48 elements	Symbol addresses
R$(LL+LL,9)	96 × 9 chars	Reference names with type prefix
R(LL+LL)	96 elements	Reference target addresses

The first character of each R$ entry encodes the reference type: + for relative, $ or £ for absolute (two-byte little-endian). The name portion starts at character 2, allowing a single string to carry both metadata and the label name.

Key BASIC Idioms

• LET I=1, LET O=0, LET T=28, LET TT=256, LET NL=118 — constants stored in variables to save repeated literal parsing overhead and improve inner-loop speed.
• T=28 is the BASIC token code for 0; hex digits 0–9 and A–F are detected by testing X >= T and X <= 43 (token 43 = F), exploiting the ZX81 token table layout where digits are consecutive.
• NL=118 is the NEWLINE token (0x76), used to detect end-of-line while scanning REM body bytes.
• Hex nibble conversion uses 16*(X-T)+Y-T, a compact formula relying on the same token-offset trick.
• IF X<0 THEN LET X=X+TT at line 7880 converts a negative signed byte offset to its unsigned 8-bit equivalent for POKEing.

Relocator Setup (Lines 8995–9090)

After the main assembly, the user types CONT to fall through to the relocator setup. This routine iterates the reference table a second time, collecting only absolute ($-prefixed) reference addresses into a data table appended after the assembled code. It then patches three fields inside the relocator stub: the count of relocatable words, the base address of the assembled block, and the code length — all computed from the assembled address ranges. The result is a self-contained relocatable binary with an embedded relocation map.

Basic*Olay Loader

The second program installs the overlay manager stored in its REM line 1. Lines 35–40 write the user-supplied load address E into a two-byte pointer at 16507–16508 (little-endian), then call RAND USR 16686 to execute the installer. Line 70 computes the next available address as E+172 (0xAC bytes), consistent with the 01 AC 00 operand visible in the REM hex dump which loads BC with the copy length.

Notable Techniques

• Source code is embedded directly in BASIC REM lines as parenthesised hex strings — no separate editor or file format is needed.
• The scanner navigates raw BASIC line storage by PEEKing absolute addresses and advancing A byte-by-byte, bypassing the BASIC interpreter’s own line-access mechanisms for speed.
• Line number recovery for error messages uses TT*PEEK AA + PEEK (AA+I), decoding the two-byte big-endian line number stored at the start of each BASIC line in memory.
• Error bytes are marked in-place with POKE A, Y+128 (setting bit 7), providing a visual inverse-video marker in the REM source for post-mortem debugging.
• The GOTO 7490 inside the label-parsing loop at line 7560 uses a bare LET W=M / loop-back pattern rather than a WHILE construct, a common ZX81 BASIC workaround for the absence of structured loops.

Potential Issues

• Line 7560 reads GOTO 7490 but the loop body starts at 7500; line 7490 only resets LET W=M, so the first iteration after a non-= character does redundantly re-execute that assignment — functionally harmless but slightly unexpected.
• The REM expander fills new bytes with 22 (NEWLINE token), but the assembled output subsequently overwrites these; if N is underestimated the assembler will silently overwrite subsequent BASIC lines without warning.
• The symbol table is capped at 48 definitions and 96 references (LL=48); exceeding these limits will cause a subscript error with no graceful message.