# Using Merlin Pro

The installed software is **Merlin Pro 2.33 for ProDOS** from the requested Internet Archive item. The notes below describe the commands discussed during setup. Display switching and returning to the menu were exercised; source saving and the example program have not yet been confirmed on the physical Apple.

## Editor and display commands

| Task | Action |
| --- | --- |
| Enter editor from main menu | Press **E** |
| Use 40-column text in editor | Press and release **Esc**, then press **Control-Q** |
| Return to 80-column text | At the editor command prompt, type `VIDEO 3` and Return |
| Return to main menu | At the editor command prompt, type `Q` and Return |
| Leave source-entry or line-edit mode first | Press **Control-C**, then issue the desired editor command |
| Add source lines | Use `A` at the editor command prompt |
| Assemble source | Use `ASM` at the editor command prompt |

The earlier `PR#3` experiment was performed in Applesoft BASIC. Inside Merlin, use its own display controls; its `PR#` command is for printer selection. [Manual, page 35](https://archive.org/download/MerlinProMacroAssembler/Merlin%20Pro%20Manual.pdf)

## Save and reload source

You can save onto the same floppy that contains Merlin. A separate blank floppy is not required for a small first program.

1. Exit source-entry mode if necessary with Control-C.
2. Type `Q` and Return at the editor command prompt.
3. At the main menu, press **S** for Save Source.
4. Supply a new name such as `/MERLIN/HELLO` and press Return. Merlin adds `.S` automatically.
5. Wait for disk activity to finish and check for errors.

If Merlin offers the last filename with a flashing question mark, **Y** accepts that name; another key lets you supply a different name. Be careful not to replace a file you want to preserve.

To reload, boot Merlin, press **L** for Load Source, and supply the same name without `.S`. A successful load enters the editor. The ProDOS version stores source as TXT files, even though some general sections of the manual describe the DOS version's binary source format.

Use **O**, the letter O, for Save Object Code after assembly when you also want a runnable machine-code file. Saving object code does not replace saving editable source. [Manual, pages 16–18 and ProDOS notes](https://archive.org/download/MerlinProMacroAssembler/Merlin%20Pro%20Manual.pdf)

The original `/MERLIN` disk has **21 free 512-byte blocks**, or 10,752 bytes before any subsequent saves and allocation overhead. This is about 10 KB, suitable for a small source file. It is not a current measurement of the physical floppy. A separate ProDOS work disk is the next step when more room is needed. [Disk A catalog](https://archive.org/download/MerlinProMacroAssembler/Merlin-proProdos2.33-aCatalog.txt)

Merlin's **D** command in this ProDOS version opens disk commands; it is not the DOS 3.3 version's drive-toggle command. Commands include `ONLINE` to inspect available volumes and `PREFIX pathname` to change the current path. A work disk in the other drive can be addressed by its ProDOS volume name once it exists.

## Assembly language support

Merlin accepts standard 6502 mnemonics including `LDA`, `STA`, `TAX`, `LDX`, `JSR`, `RTS`, and `BNE`. It supports labels, constants, expressions, normal 6502 addressing modes, data definitions, macros, conditional assembly, included source files, listings, symbol tables, and linking. Sourceror is the accompanying disassembler.

The manual also describes support for newer processors. The CPU in this Apple has not been identified, so use original 6502 instructions until its capabilities are established. Assembler acceptance does not prove CPU compatibility.

The example from the conversation is saved as [example.S](../src/example.S):

```asm
        ORG $0800

START   LDA #$2A     ; Put hexadecimal 2A into A
        TAX          ; Copy A into X
        STA RESULT   ; Store A in memory at RESULT
        RTS          ; Return to caller

RESULT  DFB $00       ; Define one byte, initially zero
```

`ORG` sets the assembly origin. `DFB` emits a byte. Labels begin at the left edge; an instruction without a label needs leading whitespace. The `#` in `LDA #$2A` means an immediate value, while `STA RESULT` addresses memory. Merlin computes the address of `RESULT`.

This is a syntax example, not a completed load-and-run tutorial. It has not been assembled or executed during this session. `RTS` assumes the program was invoked with a suitable return address on the stack; do not treat a raw jump into it as equivalent to a subroutine call.

## Disk B

The `/APPLESOFT` volume on disk B contains `SOURCEROR.FP`, `APPLESOFT.S`, four `WHATSIT` support files, ProDOS, BASIC.SYSTEM, and STARTUP. Its purpose is to produce an annotated assembly-language disassembly of the Applesoft ROM. It is optional for writing your own assembly programs.

The manual notes that running `SOURCEROR.FP` deletes itself and some temporary work files, so use a replaceable copy if experimenting with that utility. Disk B has not been transferred to a physical floppy in this session. [Disk B catalog](https://archive.org/download/MerlinProMacroAssembler/Merlin-proProdos2.33-bCatalog.txt), [manual, pages 124–125](https://archive.org/download/MerlinProMacroAssembler/Merlin%20Pro%20Manual.pdf)