BBC MICRO · AGENT HANDBOOKALPHA · USE AT YOUR OWN RISK

BBC BASIC and memory

Match the actual language

The BBC Micro's usual BASIC II and the Master's BASIC IV are not ARM/RISC OS BASIC V/VI, BBC BASIC for Windows or SDL BASIC. Do not borrow a keyword merely because an online page says “BBC BASIC”. Check the edition and target.

• INSTALL, LIBRARY and OVERLAY procedure libraries are BASIC V additions; do not generate INSTALL "GFXLIB" for a stock BASIC II/IV target.
• The BBC BASIC inline assembler and BeebAsm are different source dialects. Use the project's existing build syntax. Target NMOS 6502 unless the selected machine/source explicitly permits 65C12 instructions.
• Keep integer/real, string, indirection and PROC/FN semantics native.
• Check line ordering and duplicate numbers when merging numbered listings. DIM a% n reserves n+1 bytes; integer arrays require more than one byte per element. Count actual tokenized program bytes, not source-file characters.

Loading is not typing

LOAD reads a saved tokenized BASIC program; CHAIN loads and runs it. *EXEC feeds text to the command interpreter as typed input: numbered lines enter a program; they are not automatically a running program.

In this project's BeebAsm disc recipes, use PUTBASIC for numbered BASIC programs and PUTTEXT for a textual !BOOT command file. Inspect and reuse an existing known-good disc recipe rather than inventing a tokenizer/loader. The EGFX basic-program.py selects reachable helpers and writes compact text; PUTBASIC is the subsequent tokenization step. They are different operations.

Account for memory ownership

• PAGE is the start of the BASIC program. Do not assume it is always &1900: filing system and machine configuration matter.
• TOP is the end of the program. Variables/arrays/strings and allocation grow above the program; BASIC's software stack needs space below HIMEM. LOMEM controls the start of the variable area.
• HIMEM sets BASIC's upper memory boundary. Lowering it does not relocate program bytes already above it, move a library, or create more memory.
• A MODE change changes screen requirements and can affect BASIC's available memory. Establish the mode and reserve workspace before allocating buffers or entering PROCs. Do not move the stack limit while PROC frames already exist.
• Sideways ROM storage, sideways RAM, main RAM, Master shadow RAM and parasite RAM are separate resources. Host addresses are not parasite pointers. Use the documented MOS/Tube transport.

EGFX BASIC host contract

The EGFX BASIC guide requires MODE 1 then top-level HIMEM=&2400, before any PROC call or allocation; it checks TOP<=&2200. These constraints come from the EGFX profile: check the paired source/API revision.

For the DFS example with PAGE=&1900:

Keep the original library guards. A 3–4 KiB tokenized program starting at &1900 does not fit this program budget. First measure reachable-helper compaction and heap/stack headroom. A larger application needs an explicitly designed, tested layout, supported overlay strategy or selected Tube profile; do not remove guards, invent BASIC V library loading, silently switch target, or change the ROM to hide an application layout error.

Sources and further reading

• Acorn BBC Microcomputer User Guide, chapter 40 (HIMEM, LOMEM, TOP, PAGE), keyword reference and assembler chapters: archived original guide.
• Acorn Master Series Reference Manual, Part 1 (MOS/filesystems) and Part 2 (BASIC IV/assembler): remastered original-manual archive.
• BASIC version history, for the BASIC V additions.
• Paired EGFX source: docs/basic.md (memory/interpreter contract), docs/architecture.md (ownership), src/gfx-basic.bas (guards/helpers), tools/basic-program.py and src/disc.6502 (build recipe).

These are original summaries and links to the sources.