## Symbols

When a programmer writes an assembly language program instead of directly referring to a memory address over and over again they use a symbolic name instead. For example, instead of always directly hard-coding $C000 everywhere to read the keyboard they would instead write:

                           ORG $300
                           KEYBOARD EQU $C000
    300:AD 00 C0 .1        LDA KEYBOARD
    303:10 FB              BPL .1
    305:8D 00 04           STA $0400
    306:60                 RTS

Let's try this out in the debugger. Make sure AppleWin is running. Press F2 (to reboot), then Ctrl-F2 (to break), and F7 (to enter the debugger.) If you don't want to type in the following hex code, you can select it, copy it (Ctrl-C), and paste it into the Debugger console (Ctrl-V).

    300:AD 00 C0 10 FB 8D 00 04 60
    300L

Press F7 to exit the debugger, then type:

    HOME:CALL 768

Press Enter. The emulated computer will wait for your to press a key and then echo it in the top left.

When debugging assembly programs since you typically don't have the source file availabe you can tell the debugger how to interpret a memory address as a variable name or symbol. A symbol is the symbolic name and the address assigned to it.

AppleWin supports loading of the assemblers ACME, and Merlin's symbol tables -- a collection of symbols, one per line, organized and collectively called a symbol table. The semi-colon is a comment-till-end-of-line. The file format per line is: ADDRESS SYMBOL

e.g.

    ; IO Map
    C000 KEYBOARD

There are 9 symbol tables to help organize "modules"; each symbol table individually can be turned off/on independently.

     MAIN    APPLE2E.SYM
     BASIC   A2_BASIC.SYM
     ASM     A2_ASM.SYM
     User1   A2_USER1.SYM
     User2   A2_USER2.SYM
     Src1    A2_SRC1.SYM
     Src2    A2_SRC2.SYM
     DOS33   A2_DOS33.SYM
     PRODOS  A2_PRODOS.SYM

On startup the debugger reads 3 symbol tables by default: Main, Basic, User1.

Looking up symbols is easy. If you can't remember an address of a symbol, or the reversse -- can't remember the symbol for an address -- you can use the following symbol commands: (#### referes to either a hex address or a symbolic name)

Command | Effect
SYM | Display the number of symbols in the Main, User, and Source symbol tables.
SYM #### | Look-up the Symbol or Address, and display which Symbol Table it is in.
SYMUSER LOAD | Reloads the User Symbol Table: A2_USER1.SYM
SYMUSER CLEAR | Clears the User Symbol Table from RAM.
SYMMAIN #### | Look-up only in the Main symbol table.
SYMUSER #### | Look-up only in the User symbol table.
SYMSRC #### | Look-up only in the Source symbol table.
SYM name = #### | Add (or update) a symbol in the User table with the new Address.
SYM ! name | Remove a symbol from the User table.
MEB symbol ## | Set memory (at the symbol Address) to the 8-Bit (byte) Value.
MEW symbol #### | Set memory (at the symbol Address) to the 16-Bit (word) Value.
E16 symbol #### | Alias for EW.

Examples:

Input | Effect
SYM | Displays number of symbols in the Main, User, and Source tables.
SYMMAIN CLEAR | Clears the main symbol table!!
SYMMAIN LOAD APPLE2E.SYM | Reloads the main symbol table.
SYM FA62 | Look up the Address $FA62 (RESET).
SYM HOME | Look up the Symbol Home ($FC58).
SYM LIFE = 300 | Define a new user symbol, called “Life” at Address $0300.
MEB LIFE 64 | Set 8-Bit variable (@ $0300)“Life” to 100 (decimal).
MEW LIFE 3E8 | Set 16-Bit variable (@ $0300)“Life” to $3E8 = 1000 (decimal).