TUTORIAL

In this chapter, we'll go step-by-step through the process of writing a
small program with the S-C Macro Assembler.

Put the S-C Macro Assembler disk in drive 1, and boot the disk.  Select
from the menus the main memory, 40-column version of the assembler. 
When the assembler finishes loading, you will see its title and a ":"
prompt with a cursor.

Then type in the following short program:

1000 TONE   LDA $C030
1010 LOOP   DEY
1020        BNE LOOP
1030        JMP TONE

Now type "LIST" to see the program as the computer has it.  The display
should look like this:

:LIST
 1000 TONE   LDA $C030
 1010 LOOP   DEY
 1020        BNE LOOP
 1030        JMP TONE
:


Description of the Source Program:

The listing above is called a source program.  It is the text form of an
assembly language program.  Later we will go through the steps necessary
to convert it to executable form, but for now let's observe what the
source form looks like.

The first column contains line numbers.  These are numbers from 0 to
65535.  Assembler line numbers work just like BASIC line numbers for
editing, inserting and deleting lines, but have nothing to do with the
flow of control (no GOTO linenumber.)

The second column contains labels.  These are used instead of line
numbers for controlling the program flow.  They also can act like BASIC
variables.  In our example, the labels are TONE and LOOP.

The third column contains opcodes (OPeration codes).  These are either
standard 6502 instructions, SWEET-16 instructions, macro calls, or
special "directives" to the S-C Macro Assembler.  In our example, all
the opcodes are 6502 instructions (LDA, DEY, BNE, and JMP).

The fourth column contains operands.  The opcode tells the computer what
to do; the operand tells what to do it to.  The operand can be a number,
a label, or an arithmetic expression.  Sometimes the opcode does not use
an operand, as in the DEY above.  Others use a more complicated format. 
The operand on the first line above, "$C030", is a hexadecimal number. 
The operands on the BNE and JMP lines are labels.


Saving a Source Program on Disk:

To save the program to a disk, type "SAVE NOISY".  This is a standard
DOS SAVE command, just like you would use in BASIC.  Note that S-C Macro
Assembler source files are type "I" files.  DOS thinks they are Integer
BASIC programs, but they will not run as they are.  (DOS is fooled, but
Integer BASIC would not be fooled at all.)  NOTE:  You do NOT need to
have Integer BASIC in your machine to use the S-C Macro Assembler.

To clear memory for a new program type "NEW".  To reload the program
from disk type "LOAD NOISY".


Assembling a Source Program:

A program must be assembled into binary form before it can be executed. 
The command to assemble a program is "ASM".  Try it now....

Our program is now assembled into memory starting at address $0800.  The
display should look like this:

:ASM

 0800- AD 30 C0 1000 TONE   LDA $C030
 0803- 88       1010 LOOP   DEY
 0804- D0 FD    1020        BNE LOOP
 0806- 4C 00 08 1030        JMP TONE

 SYMBOL TABLE

 0803- LOOP
 0800- TONE
:

Notice that two more columns have been added to the left of those we saw
when we typed "LIST".  The first new column contains the memory
addresses (in hexadecimal) into which the program assembled.  The second
column has one, two, or three hex numbers (two digits each) which are
the contents of the memory locations.

The Symbol Table is a list of all the labels and the values assigned to
them, in alphabetical order.

The program is now in memory in two forms.  The source program is there,
right beneath DOS.  The executable form, called the "object" program, is
in memory from $0800 through $0808.


Executing the Object Program:

To run the program, type "MGO TONE".  Do you hear the tone coming from
your Apple speaker?  It is being produced by continually toggling the
position of the speaker coil by addressing $C030, at about 800 toggles
per second.  This makes a tone of about 400 Hertz.

As soon as you get tired of it, hit the RESET key to stop the noise. 
Note that you can run a program from the assembler by MGO-ing to a
label, and that the RESET key reenters the assembler.  (Unless you have
a very old Apple II with the original monitor ROM; if you have one of
those, you will get the "*" prompt:  type 3D0G to reenter the
assembler.)


Now we have walked through the entry, assembly, and execution of a very
small program.  The same steps would work for a large program, but there
are many other features built-in to the S-C Macro Assembler which can
make programming in assembly language even easier than programming in
BASIC.


Modifying a Source Program:

To get the flavor of some more of the features of the S-C Macro
Assembler, let's modify the TONE program a little.

It would be nice if the TONE program would stop gracefully without
hitting the RESET key.  I like to set it up to quit when any key is
pressed on the keyboard.  I do it like this:

1030       LDA $C000     LOOK AT KEYBOARD
1040       BPL TONE      NO KEY PRESSED YET
1050       STA $C010     CLEAR KEYBOARD STROBE
1060       RTS           RETURN

Note that a new column has been added: the comments column.  The operand
column ends with a blank; any useful comments to help you understand
next week what you did today can be written after that blank.

If you type in those four lines, and then type the LIST command, you
will see that they are now part of your source program.  Line 1030 has
been replaced, since you typed a new line 1030.

Now type ASM, to create the new version of your program in executable
(object) form.  And execute it, by typing MGO TONE.  This time you can
stop the tone by pressing any key.


Easier Entry of Source Programs:

Now let's try an easier way to enter source lines.  First save the
latest version of your TONE program on a disk by typing SAVE NOISY
again.  Then type "NEW" to erase the source program from memory.  (It is
still on the disk.)

Now hold down the CTRL key ("CTRL" means "control"), and type the letter
I.  We call that typing "control-I".  Look at the screen.  You will see
that the Apple printed "1000 ", and the cursor is blinking after that. 
Type control-I again, and you will see the cursor move over about 7
character positions.

Whenever you type control-I at the beginning of a line, the S-C Macro
Assembler will automatically generate the next line number for you. 
Usually this will be ten higher than the last line number you entered or
deleted.  (The increment is settable to whatever interval you like.)

Whenever you type control-I inside a line (beyond the beginning), the
cursor will move to the next tab stop.  Play with this a while, and you
will find that the tab stops line up nicely with the source program
format.

Why don't you try typing in the TONE program again, with a few more
comments for good measure?  This time use control-I for the line numbers
and tabbing.  Start by typing NEW, so we know that there are no stray
line numbers left from some previous work.  I am going to help you,
showing control-I with the symbol "^I".  Now type:

:^ITONE^ILDA $C030^ITOGGLE THE APPLE'S SPEAKER
:^ILOOP^IDEY^I^IDELAY FOR ABOUT 1250 MICROSECONDS
:^I^IBNE LOOP
:^I^ILDA $C000^ILOOK AT KEYBOARD
:^I^IBPL TONE^INO KEY PRESSED YET
:^I^ISTA $C010^ICLEAR KEYBOARD STROBE
:^I^IRTS^I^IRETURN
:LIST

Type ASM again, and MGO TONE.  The program should work just like it did
the first time.  Stop it by pressing any key.

With this brief introduction, you should now be ready to dive into the
following chapters.  As you study each new command or feature,
experiment with it until you really understand what is happening.  Look
up some of the books mentioned in the Reference Bibliography for help in
understanding the 6502 language.  If you need some personal help, call
us at (214) 324-2050.