3.  Beginners guide to Using MERLIN

Notes and demonstrations for the beginning programmer

3.1  Introduction

The purpose of this section  is   not  to  provide  instruction  in
assembly language programming. Rather, it is to introduce MERLIN to
programmers new to assembly language programming  in  general,  and
MERLIN in particular.

This section does not attempt to present demonstrations of each and
every  command  option.  Instead,  the  objective is to clarify and
present examples of  the  more  common  operations,  sufficient  to
provide  a  basis  for further independent study on the part of the
programmer.

a note of clarification:

Throughout the MERLIN manual, various uses are made  of  the  terms
"mode" and "module."

In this section, module  refers  to  a  distinct  computer  program
component of the MERLIN system. The four modules are:

  1.  Executive

  2.  Editor

  3.  Assembler

  4.  Symbol Table Generator

Each of the above modules is grouped under one of the  two  CONTROL
MODES:

  1.  The Executive, abbreviated EXEC  and  indicated  by  the  "%"
      prompt.

         W Executive Module

  2.  The Editor, indicated by the ":" prompt (which is very  teeny
      tiny in the 80 column mode of your Apple).

         W Editor Module

         W Assembler Module

         W Symbol Table Module

In MERLIN, the term  mode  is  used  in  a  recursive  sense.   For
example,  when you are in the EXEC mode and type "E", you enter the
Editor Control Mode (":" prompt). If you  then  type  "A[dd]",  you
enter  the  "ADD"  mode.   Some time later, you will enter a "NULL"
line which will move you back into the Editor Control Mode.
















The above, after a  few  moments  reflection,  is  both  clear  and
sensible.   However,  there  is  one mode movement that can lead to
confusion if the words are not read clearly.  That movement is when
you  move  from  the  Editor Control Mode (often referred to as the
EDITOR) to the "EDIT" mode.  The separator  tabs  for  this  manual
don't help this confusion factor much when they refer to the Editor
Control Mode as "EDITOR". Sorry about that. However, pay attention,
you have been warned.

3.2  Input

Programmers familiar with some assembly and higher level  languages
will  recall  the  necessity  of formatting the input, i.e. labels,
opcodes, operands, and comments must be entered (typed) in specific
fields or they will not be recognized by the assembler program.

In MERLIN, the TABS operator (command)  provides  a  semi-automatic
formatting feature.

When entering a program, remember that during assembly  each  space
in  the source causes a tab to the next tab field. Two spaces where
you meant one will (hopefully) not cause an  assembler  error  when
you  later type "ASM".  If due to mischance, the error on input did
cause an assembly error, you will be witness to the playing of  the
SDS death song.

The real harm of extra spaces is the amount of disk storage wasted.
If  you  are  prone  to typing extra spaces, investigate the Change
command in the EDITOR.  It  allows  matching  for  two  spaces  and
replacement by one.


4.  Sample Program

The first step is to "boot" MERLIN by any of the  numerous  methods
available   (power   cycling,  PR#6,  CNTRL-OPEN-APPLE-RESET,  BRUN
MERLIN).  In any case, you should end up in the Executive mode with
the   "%"  prompt.   If  unsuccessful  in  this, consult your Apple
Manual, etc.  Assuming success, perform the following steps:

  1.  Type a single capital 'E', this will place you in the  Editor
      Control  Mode  (which  will  be called [the] Editor from this
      point forward) with the ":" prompt.

  2.  Type a single "A" and press RETURN. This will put you in  the
      ADD  mode.  There will be a "1", for line one, to the left of
      the curser.

  3.  Enter a "*" (asterisk). An asterisk as a first character of a
      line tells the assembler that this is a comment (REMark) line
      and anything after the asterisk is to be ignored.  To confirm
      this,  continue by typing "DEMO PROGRAM 1" and hit the RETURN
      key.  (I don't really mean that you should "hit"  the  return
      key,  rather  I  mean  that  you should gently press it as an
      indication to your Apple that you are finished with a line of
      input.  In fact, I'm already suffering ennui about mentioning
      it at all. How about I just say <R> when  its  time  for  our
      friend  the  RETURN key? Good. By the way, I will continue to
      ask you to "hit" certain keys. Just take my word for it, they
      deserve it).

  4.  You will now see that the cursor has dropped  down  one  line
      and there is a "2" just to the left.

  5.  Hit the space bar and type "OBJ", space once more, then  $300
      <R>.   Note  that the use of OBJ is discouraged in most cases
      because it is neither required nor desirable.

      "Why!" You cry; are you using OBJ? "Because  we  are  getting
      tricky so this demo doesn't get out of hand with details that
      are better left to much later." So there!

  6.  Spaces are becoming more of a problem than the RETURN key. If
      it's alright with you, I'll use <sp> from here on.

      Type:<sp>ORG<sp>$300<R>

  7.  Type:BELL<sp>EQU<sp>$F8DD<R>  Note that "BELL" is a label and
      is typed with no leading spaces.

  8.  Type:START<sp>JSR<sp>BELL<sp>;RING THE BELL<R>       Note the
      semicolon.  It marks the start of the comment (REMark) field.
      You do not HAVE to use the semicolon. However, convention and
      good  taste  dictate  that  you  should.  In  addition, using
      editors on program text files is often made  much  easier  by
      having  a unique character delimit the start of the [comment]
      field.

  9.  Type:END<sp>RTS<R>

 10.  The program has been completely entered, but  the  system  is
      still  in  the  ADD mode. To exit ADD,Type:<R> or CNTRL-X<R>.
      The ":"  prompt  will  reappear,  indicating  that  you  have
      returned to the EDITOR.

 11.  The screen should now look like this:

      1 *DEMO PROGRAM 1

      2       OBJ     $300

      3       ORG     $300

      4 BELL  EQU     $F8DD

      5 START JSR     BELL    ;RING THE BELL

      6 END   RTS

      Note that each string of  characters  has  been  moved  to  a
      specific  field.   There  are four such fields, not including
      the line numbers which are on the left.  The fields and their
      uses are:

        1.  Label field; BELL,  START,  and  END  are  examples  of
            labels.   Line  1,  which is totally comments, does NOT
            have ANY fields since it is ignored by the assembler.

        2.  Opcode field. JSR and RTS are opcodes, an opcode  is  a
            mnemonic  (aid)  that stands for a predefined operation
            of the 6502 micro processor.  When the assembler "sees"
            an  opcode,  it will generate one or more bytes of data
            in the program. These bytes  will  cause  the  6502  to
            perform the operation described for the stated mnemonic
            in standard programming manuals.

            On the  other  hand,  OBJ,  ORG,  and  EQU  are  called
            pseudo-op's.  A  pseudo  op  is  an  instruction to the
            assembler rather than  the  processor  being  assembled
            for.   A pseudo op may or may not result in bytes being
            placed into the program.  None of the pseudo op's  used
            in  this demo program resulted in the direct generation
            of  code. However, they  did  convey  information  that
            will be used in the code generation process.

            In the pure sense of a pseudo op, no executable code is
            ever  a  direct  result of a pseudo op.  This is not to
            say you could not specify an entire program  using  the
            "HEX"  pseudo  op; rather one could say "that is a dumb
            way to do it."

            In summary, a line of  code  consists  of  one  of  the
            following:

            LABEL<sp>OPCODE<sp>OPERAND<sp>;COMMENT

            LABEL<sp>OPCODE<sp>OPERAND

            LABEL<sp>OPCODE<sp>;COMMENT

            LABEL<sp>OPCODE

            <sp>OPCODE<sp>OPERAND<sp>;COMMENT

            <sp>OPCODE<sp>OPERAND

            <sp>OPCODE<sp>;COMMENT

            <sp>OPCODE

            <sp>;COMMENT

            *COMMENT


4.1  Verification

In the example shown here, the program is short and thus  is  still
on  the  screen  at  the  completion  of  the Add mode.  For longer
programs you will use various  tools  provided  by  the  EDITOR  to
verify  that the entered code is what was intended.  We will sample
some of these tools now.

Type:L[ist]<R> a copy of the program will be listed on the screen.

Type:I5<R> This will cause you to go into the insert mode. You will
          be  inserting  IN  FRONT of the present line 5. Note that
          the line number to the left of  the  cursor  is  5.  This
          means  that  the  first line you type will become the new
          line 5. The old line 5 and all subsequent lines will have
          one  added  to  their  line  numbers. Lines above will be
          unchanged. While the foregoing  may  seem  basic,  it  is
          essential that you have a firm grasp of these concepts in
          order  to  interact  with  the  EDITOR  in   a   mutually
          beneficial fashion.

Type:*<R>   Note that you are still in the insert mode.  This  will
          be true until we tell you how to exit in a moment.

Type:*<R>

Type:<sp>TYA<R>

Type:<R>  This is one of the methods of exiting the Insert (or Add)
          mode.   There  are two others (I don't know why there are
          two, there just are), CTRL-X and CTRL-C. (^X and ^C  from
          now on. Aren't I the laziest devil?)

          Looking ahead. If you wish to exit the EDIT mode prior to
          the   line[s]   specified  (perhaps  you  have  typed  an
          intemperate phrase), use ^X or ^C.  I would  use  one  or
          the  other  in all cases so panic doesn't set in when you
          have destroyed a line the moment  you  hit  <R>  and  you
          can't remember the "secret" code to exit with no change.

In order to verify what transpired, Type:L<R>  This will  list  the
source code:

1 *DEMO PROGRAM 1

2       OBJ     $300

3       ORG     $300

4 BELL  EQU     $F8DD

5 *

6 *

7       TYA

8 START JSR     BELL    ;RING THE BELL

9 END   RTS

The three new lines (5, 6,  and  7)  have  been  Inserted  and  the
subsequent original source lines have been renumbered.

We are now going to Delete some of the source lines:

Type:D5<R>   (If you are a masochist,  Delete5  or  Delete  5  work
              equally well).  Note that nothing new (except the ":"
              prompt ) appears on the screen.

Type:L<R>   and list the source. Note that one of the asterisks  is
              gone  and  the  following  lines  all  have  new line
              numbers.

Type:D5,6<R>   This is our friend the Delete operating on  a  range
              of  lines.  List the source once more and notice that
              we are back to the original source.

The automatic  renumbering  feature  makes  it  CRUCIAL  that  when
deleting  lines,  you  start with the highest line numbers and work
backwards to the lowest. In addition, listing the  portions  to  be
deleted  just  prior  to  issuing  the delete command can save much
heartbreak.

The Add,  Insert,  and  Edit  commands  have  several  sub-commands
comprised of ^[CHAR]. To demonstrate, using our BELL routine:

Type:E6<R> This will put you in the Edit mode for line 6 ONLY.

6 END RTS will appear on the screen and the cursor is over the  "E"
          in "END".

TYPE:^D   The "E" disappears!  Type:^D^D and "END" is eaten up. The
          cursor is positioned to the left of the opcode (RTS).

Type:<R>  and you will exit the Edit mode.

Type:L<R> Too list the source. In line 6 the RTS opcode is all that
          remains.

Type:E6<R> We are going to re-edit line 6.

TYPE:^I   You are in the Character Insert Mode.  Do  not  move  the
          cursor  with  the arrow keys or space bar unless you wish
          to exit the insert mode.

Type:END<R> This puts back the label and exits the Edit mode.

Type:L<R> List the program once  more  and  note  that  line  6  is
          restored (did you really think it wouldn't be?).


In the examples we have shown so far, typing <R> causes us to  exit
the Edit mode.

Type:E3,6<R> (try it and ride along) the  cursor  will  be  on  the
          space in column 1 and the line number will be "3".  Using
          the arrow keys, step out to the right of the "$300" and

Type<sp>;comment<R> You will see that you are  now  presented  with
          line 4.

Type:<R>  Now we are at line 5.

Type:<R>  Guess what? Line 6. One more time

Type:<R>  You are out of the Edit mode because  you  exhausted  the
          "range" of lines specified on the "E" command.

Type:L<R> Note that the source is the same except for that  comment
          you added on line 3.

4.2  Assembly

The next step in using MERLIN is to assemble the source  code  into
object code.

Assuming you are in the EDITOR (":" prompt), Type:ASM<R>.

On your screen you will see the following:


UPDATE SOURCE (Y/N)?

Type:N

You will then see:



                        1       *DEMO PROGRAM  1
                        2               OBJ     $300
                        3               ORG     $300
                        4       BELL    EQU     $FBDD
0300:   20 DD FB        5       START   JSR     BELL    ;RING THE BELL
0303:   60              6       END     RTS


End assembly


4 bytes


Errors  0


SYMBOL TABLE - ALPHABETICAL ORDER


        BELL    =$F8DD          ?       END     =$0303


?       START   =$0300


SYMBOL TABLE - NUMERICAL ORDER


?       START   =$0300          ?       END     =$0303


        BELL    =$FBDD

If instead of completing the above listing, the  system  plays  the
"SDS Death Song" and displays an error message:

  1.  Note the line number referenced in the message.

  2.   Type:<R> until the "...BYTES' message appears.

  3.   Refer back to  the  subsection  on  INPUT  and  compare  the
      listing with ???.
       Look especially for elements in incorrect fields.

  4.   Assuming you found the error, you can fix it using the  EDIT
      techniques  learned  earlier,  or  if the source is in such a
      state you don't feel comfortable attempting that large a  job
      right  now;  you  can type "NEW", which erases all input, and
      start fresh.

If (when) all went (goes) well, to  the  right  of  the  column  of
numbers down the middle of the screen is the familiar, source code.

To the left of the numbers, beginning on line 5,  is  a  series  of
numeric  and  alphabetic  characters.  This is the object code; the
opcodes  and  operands  assembled   to   their   machine   language
hexadecimal equivalents.

Left to right, the  first  group  of  characters  is  the  routines
starting  address  in  memory (see the definition of OBJ and ORG in
the section entitled " PSEUDO Opcodes -  Directives").   After  the
colon is the number "20". This is the one byte hexadecimal code for
the opcode JSR.

Note that the label "START" is  not  assembled  into  object  code;
neither  are the comments, or pseudo op's such as ORG and OBJ. Such
elements are only for the convenience and utility of the programmer
and  the  use  of  the assembler program. They are of no use to the
computer and therefore,  are  not  translated  into  the  machine's
language.

The next two bytes (each pair of characters is one byte), on line 5
bear  a curious resemblance to the last group of characters on line
4; have a look.  In line 4 of the source code we told the assembler
that  the  label "BELL" EQUated with address $FBDD. In line 5, when
the assembler encountered "BELL" as the operand, it substituted the
specified  address (number). The sequence of the high and low bytes
was reversed, a 6502 convention.

4.3  Saving and Running a Program

The final step in using MERLIN is running the program. Before that,
it would be a good idea to save the source code.  Keep in mind that
the source code can be saved at any time. However,  the  saving  of
object  code  can  take  place  ONLY  after  a successful assembly.
Perform the following steps:

  1.  Return  to  the  EDITOR  control  mode  (if  necessary)   and
      Type:Q<R>.

  2.  You will then Quit the EDITOR and  return  to  the  EXECUTIVE
      (EXEC) mode. If the MERLIN system disc is still in the drive,
      remove it and insert an initialized work disc.

  3.  Type:S<R>    (This is the EXEC Save source command) EXEC will
      ask  you  for  a file name. Type:DEMO1<R>    When the file is
      saved, the "%" prompt will return.

  4.  Type:C (Catalog) and look at the output. The source code  has
      been  saved  as a binary file with the file name of "DEMO1.S"
      The .S suffix is a  MERLIN  file  labeling  convention  which
      indicates  the  file  is  a source code file.  This suffix is
      automatically appended to the name by the "S" command.

  5.  <R> to return to the EXEC mode.

  6.  Type:O  (Object code save). The object code  is  saved  under
      the  same  name  as  earlier  specified  for the source file.
      However, there is no danger of overwriting  the  source  file
      because  no  suffix is appended to the object code name. This
      is an Apple convention and I don't want to  hear  that  whine
      about "Why didn't you append a ".O" to the file name?"

  7.  While writing either file to disk,MERLIN  also  displays  the
      address  parameter,  and  calculates  and displays the length
      parameter.  If you would like to have the address and  length
      information visible for future reference, you can use the DOS
      RENAME facility to do so.  Remember, the source MUST  end  in
      ".S" if MERLIN is to read it in at some future time.

  8.  Type:E    (this returns you to the editor mode.)

  9.  Type:MON<R>   and the monitor prompt of "*" appears.

 10.  Type:300G<R>    a beep is heard! YOUR  demonstration  program
      was  responsible  for it! It works! call up Steve W. at Apple
      and apply for a job. You are a full fledged assembly language
      programmer.

 11.  A final mundane job. Type:^Y<R> and you will return to  EXEC,
      which is the subject of our next section.