Merge 1

With File 1, support for mail merging letters.

This program implements a mail-merge system that loads a letter template and a data file from tape, then merges field values from the data file into the letter before printing or displaying the result. The letter template uses special byte markers (131 for field delimiters, 143 for end-of-letter, 144 for a special character, 94 for field references) stored in memory starting at address 38000, while the merged file is assembled at address 32500. A 14-byte machine code routine is POKEd into address 60000 and executed via RANDOMIZE USR to perform fast block memory copies using the Z80’s LDIR instruction (opcode 237, 176), with source and destination addresses patched at runtime by reading the system variables for the RANDOMIZE seed. The program detects whether a printer is attached by reading port 251 (the keyboard/printer port) and supports paginated output with configurable lines-per-page.

---

Program Analysis

Program Structure

The program is organized into several functional blocks:

• Lines 10–11: Initialization — POKEs a 14-byte machine code routine into address 60000 and jumps to the main menu at line 1000.
• Lines 20–23: Subroutine for printing a slice of b$ and tracking line/page counters (x1, x4).
• Line 30: Machine code launcher — patches source and destination addresses into the routine at 60000 and executes it via RANDOMIZE USR 60000.
• Lines 70–72: Input validation subroutine — pads z$ to exactly 10 characters and prompts for confirmation.
• Lines 1000–1130: Setup phase — loads the letter template and the data file from tape, measures their lengths, and detects printer presence.
• Lines 1140–1240: Field-scanning loop — scans the letter at 38000 for field delimiter bytes (131), builds an array b() of field start addresses, then walks the template at 61000 to assemble the merged output at 32500.
• Lines 2000–2050: Field substitution — when a caret (ASCII 94) is encountered in the template, reads a numeric field index, looks up the corresponding data in b(), and copies it into the output buffer.
• Lines 3000–3450: Output/rendering engine — reads the assembled output from 32500 and prints it word-wrapped, handling special control bytes for page breaks (139) and form feeds (134), with optional printer copy via COPY.
• Line 5000: End-of-list prompt — offers another copy pass.
• Line 6000: SAVE line to preserve the program.

Machine Code Routine

Line 10 POKEs 14 bytes into address 60000. The DATA at line 11 decodes as follows:

Offset	Byte(s)	Z80 Mnemonic	Notes
0	01 00 00	LD BC, 0	BC = byte count (patched at runtime, offsets 1–2)
3	21 00 00	LD HL, 0	HL = source address (patched at offsets 4–5)
6	54	LD D, H
7	5D	LD E, L	DE = HL (destination = source initially, then patched)
8	21 00 00	LD HL, 0	HL = destination address (patched at offsets 9–10)
11	ED B0	LDIR	Block copy BC bytes from HL to DE
13	C9	RET

The routine is a standard Z80 LDIR block copy. The patching mechanism in line 30 is indirect: RANDOMIZE v stores v in the system variable at addresses 23670–23671 (the last RANDOMIZE value), and the program reads those bytes back with PEEK q / PEEK r to write the low and high bytes of each 16-bit address into the machine code. This avoids any direct address arithmetic in BASIC.

Memory Map

Address	Purpose
32500	Output buffer — merged, ready-to-print letter
37997	Number of fields (byte) in data file header
37998–37999	Length of loaded CODE block (low/high byte)
38000	Letter template loaded from tape
60000–60013	Machine code LDIR routine
61000	Data file loaded from tape
23670–23671	System variable: last RANDOMIZE seed (used for address patching)

Key BASIC Idioms and Techniques

• RANDOMIZE for address passing: Using RANDOMIZE to store a value in a known system variable location and immediately PEEKing it back is an efficient way to split a 16-bit integer into low/high bytes without using INT or MOD arithmetic.
• Word-wrap in lines 3060–3110: The renderer scans forward up to 32 characters, tracks the last space position, and breaks there, implementing a rudimentary word-wrap without string slicing beyond what the BASIC b$(TO y-x) in line 20 provides.
• Field array b(): Rather than storing field content, b() stores the memory addresses of each field’s start within the data file at 38000, enabling direct PEEK-based copying in line 2030 without intermediate string allocation.
• Printer detection (line 1040): Reads port 251 (IN 251) to test keyboard row bits — value 58 indicates the printer is present/selected, value 126 the normal keyboard state. The expression using (1 AND ...) and (0 AND ...) produces a boolean 0/1 result for p.
• Pad-to-10 loop (lines 70–71): Trims silently if too long, then pads with spaces in a tight self-referencing GO TO loop until z$ is exactly 10 characters, matching the tape filename length requirement.

Special Control Bytes in Templates

• 131 — Field delimiter in the data record; marks boundaries between fields.
• 139 — Paragraph/section break marker in the letter template (triggers top-of-column spacing).
• 143 — End-of-letter sentinel; written at the tail of the loaded CODE block (line 1030) and tested in line 1140 to detect end of records.
• 144 — Special character in the output stream (tested at line 3030); causes the renderer to fall through to the word-wrap block rather than treating it as a line-break control.
• 134 — Form-feed / page-eject marker (line 3300); triggers a full COPY and advances the record pointer.
• 94 (caret ^) — Field substitution marker in the template; introduces a numeric field index to be looked up in b().

Bugs and Anomalies

• Line 3110: The line ends with LET x=x-1: followed by a bare colon — this trailing colon is a no-op but syntactically harmless.
• Line 3220: Entirely commented out with REM, yet the code before it (lines 3210–3219) still performs partial spacing logic; the intent of the REM’d double-line spacing is unclear and may represent an unfinished edit.
• Line 1040: The second term (0 AND IN 251=126) always evaluates to 0 regardless of the port reading, so p can only ever be 0 or 1 based solely on the first term. The second term appears to be a leftover from a more complex detection attempt.
• Line 70: If LEN z$ > 10, b$ is set to " " (a space), but the condition check at line 1010 tests b$<>"c", so an over-length name silently re-prompts — this is functional but the logic is indirect.