Bas2Txt

Bas2Txt is a machine code utility that converts a BASIC program stored in memory into a plain ASCII text file. The BASIC loader (lines 10–170) encodes a Z80 machine code routine as a long hexadecimal string, which is decoded byte-by-byte via POKE into RAM starting at address 64900. Two entry points exist: USR 64909 relocates the BASIC area, and USR 65042 performs the actual translation, writing the program out as a SAVE-compatible text file. The hex-decode loop at line 9030 converts each pair of ASCII hex digits into a byte using a compact expression that handles both digit (0–9) and uppercase letter (A–F) characters without branching on IF. Comments in the REM statements (lines 9050–9054) document the multi-step workflow: load the code, run it, then load the resulting ASCII file back.

---

Program Structure

The program is organized into three logical sections:

1. Lines 10–170: Build a long hex-encoded machine code string in A$ through concatenation across multiple lines.
2. Lines 1010–9040: Decode the hex string and POKE each byte into RAM starting at address 64900.
3. Lines 9050–9054: REM statements documenting the two-phase usage workflow.

Hex String Construction

The machine code is split across lines 10–170 as uppercase hex pairs stored in A$. Each line appends additional hex data using LET A$=A$+"...". This approach sidesteps any single-line length limit and allows the full binary payload to be embedded in BASIC source. The total encoded data spans roughly 175+ bytes of Z80 code.

Hex Decode Loop (Line 9030)

The decode loop at lines 1020–9040 iterates over A$ two characters at a time. The core POKE expression is:

(CODE A$(I)-(48 AND CODE A$(I)<58)-(55 AND CODE A$(I)>64))*16 + CODE A$(I+1)-(48 AND CODE A$(I+1)<58)-(55 AND CODE A$(I+1)>64)

This converts a hex digit character to its numeric value branchlessly:

• For digits '0'–'9' (ASCII 48–57): subtracts 48, yielding 0–9.
• For letters 'A'–'F' (ASCII 65–70): subtracts 55, yielding 10–15.
• The high nibble is multiplied by 16 before adding the low nibble.

The AND keyword is used here as a conditional mask (its Sinclair BASIC boolean behavior returning 0 or the left operand), not as a bitwise operator — a characteristic idiom for branchless conditional arithmetic.

Memory Layout and Entry Points

Address	Purpose
64900	Start of machine code block (CLEAR target)
64909	First entry point: relocates the BASIC area in memory
65042	Second entry point: translates BASIC to ASCII text

The CLEAR 64899 at line 1 sets the top of BASIC RAM just below the code block, protecting the poked bytes from being overwritten by BASIC’s variable storage.

Machine Code Functionality

The embedded Z80 routine implements the actual BASIC-to-text conversion. Readable ASCII strings are embedded directly in the hex data; decoding the payload reveals messages such as "BASIC has been moved.", "PRESS ANY KEY TO CLEAR MEMORY.", and the save prompt 'To save BASIC as text file: SAVE "name" CODE 28416,'. The routine uses ROM calls (indicated by addresses such as CD B6 FF, CD C9 FF, etc.) to perform output and interact with the BASIC system.

Workflow and Usage

The REM statements (lines 9050–9054) document a multi-step process:

1. Run the BASIC loader to poke the machine code into RAM.
2. Execute PRINT USR 64909 to relocate BASIC.
3. Load the target BASIC program into the now-relocated area.
4. Execute PRINT USR 65042 to translate and save the program as a text file.
5. The saved file can be loaded back and will be in ASCII format.

Notable Techniques

• The branchless hex-digit decode in line 9030 avoids IF statements, keeping the loop tight and efficient.
• Splitting the hex string across multiple LET A$=A$+"..." lines works around line-length constraints while keeping the loader self-contained.
• The CLEAR statement in line 1 is integral to the program’s function, not merely a safety measure — it reserves high RAM for the machine code before any variables are allocated.
• Line numbering is non-uniform (10–170 for data, 1010 and 9030–9040 for the decode loop), suggesting the program was edited over time with new sections inserted.
• The note in line 9054 warns that line 1’s CLEAR address may need to be adjusted to 768 depending on the system configuration, indicating the tool was designed with some portability in mind.