Lesson 2

\       Lesson 2 - Using F-PC
\       The Forth Course
\       by Richard E. Haskell
\          Dept. of Computer Science and Engineering
\          Oakland University, Rochester, MI 48309

comment:



                                Lesson 2

                               USING F-PC


                2.1  USING SED TO EDIT FILES            2-2

                2.2  LOADING AND RUNNING YOUR PROGRAMS  2-3

                2.3  DEBUGGING YOUR PROGRAMS            2-4

                     EXERCISES                          2-6



































2.1  USING SED TO EDIT FILES

        The full-screen editor SED is used to edit your programs and
        store them in permanent disk files.  For example, to write the
        program for solving Exercise 1.1 in Lesson 1 enter F-PC
        and in response to the ok prompt type

        sed hw1
        This will create a new sequential file called HW1.SEQ.
        All F-PC source files have the extension SEQ that is automatically
        appended to your filename if you do not specify it.

        The first line of your program should begin with a backslash \
        and followed by the name of your program or file.  This first
        line will be printed at the top of each page when you print out a
        listing of the program.  You do this by typing FPRINT HW1.

        On the second line of the file type a backslash \ and a Tab.
        Then press Alt-O P.  This will paste the date and time.

        Now type in the complete program as follows:
comment;

\       Homework #1
\        07/02/89 08:25:20.35

\       Exercise 1.1 -- Lesson 1
\       Find area, circumference and center of rectangle

: sides         ( t l b r -- r-l b-t )
                ROT                     \ t b r l
                -                       \ t b r-l
                -ROT                    \ r-l t b
                SWAP - ;                \ r-l b-t

: area          ( t l b r -- area )
                sides * ;

: circum        ( t l b r -- circum )
                sides + 2* ;

: center        ( t l b r -- xc yc )
                ROT                     \ t b r l
                +                       \ t b r+l
                2/                      \ t b xc
                -ROT                    \ xc t b
                + 2/ ;                  \ xc yc






comment:
        Note that an intermediate word SIDES was defined that leaves
        the values (right-left) and (bottom-top) on the stack.  The
        word SIDES is then used in the definitions of both AREA and
        CIRCUM.  F-PC is case insensitive which means that you can use
        upper or lower case interchangeably.  We will normally follow
        the convention of defining our own words in lower case and use
        upper case for F-PC words that we use in our definitions.  This
        makes it easy to recognize in a definition which words are F-PC
        words and which ones are words that we have previously defined.

        Note also that in the definitions of SIDES and CENTER we have
        shown the stack picture as comments on the right side of each
        line.  You will find this to be very useful when considerable
        stack manipulation is going on.

        The SED editor has a full range of editing capabilities that are
        described in CHAPTER 4 of the F-PC's USER'S MANUAL.  This manual
        is on disk in the F-PC package and you can type out Chapter 4 by
        typing

        type chapter4.txt

        Once you have finished entering the program you leave SED by
        pressing ESC followed by <Enter>.  At this point you can edit
        another file by just typing its name.  If you don't want to edit
        another file at this point press ESC.  You are now in F-PC with the
        ok prompt.  You should generally be able to load and run your
        program at this point.  However, the SED editor has not released
        the memory that it used in editing your program and if you have
        a large program that allocates lots of memory you may have trouble
        loading it at this point.  I have therefore adopted the practice
        of leaving F-PC at this point by typing BYE and then entering it
        again by typing F from DOS.  At this point you can load any size
        file without problems.

2.2  LOADING AND RUNNING YOUR PROGRAMS

        To load the program you typed in the file HW1.SEQ just type

        fload hw1

        If you didn't make the file HW1.SEQ you can accomplish the same
        thing by just loading this lesson by typing

        fload lesson2

        This is because everything is a comment except the definitions of
        the words SIDES, AREA, CIRCUM and CENTER.

        The process of loading either of these files causes all of the
        colon definitions to be added to the dictionary.  It is just as
        if you typed in all of the colon definitions when in the
        interpretive mode of F-PC.  Except that all the colon definitions
        are now saved on disk and you can go in and edit them at any time.

        If you test the program by using the values given in Exercise 1.1
        you will obtain the following results:

        31 16 94 69 area . 3339
        31 16 94 69 circum . 232
        31 16 94 69 center . . 62 42

        10 27 215 230 area . -23921
        10 27 215 230 circum . 816
        10 27 215 230 center . . 112 128

        The second value of area equal to -23921 makes no sense.  What
        has happened is that the area is greater that 32767 and thus
        the 16-bit signed value has gone into the negative region because
        bit 15, the sign bit, is set to 1.  We can print out the real
        value for the area by using the Forth word U. (U-dot) rather than
        . (dot).  The word U. prints out the unsigned 16-bit integer value
        on top of the stack.  This will produce the following result.

        10 27 215 230 area u. 41615


2.3  DEBUGGING YOUR PROGRAMS

        F-PC has several useful words to help you debug your programs.
        The word SEE will let you decompile a word.  For example, after
        FLOADing the file HW1 (or LESSON2) type

        see area
        see sides
        see circum
        see center

        Note that each colon definition is shown.  This is done by looking
        up each word in the dictionary and then looking up the name of each
        word in its definition.

        The word VIEW allows you to find the file in which a given word is
        defined and to display the actual definition as written in the file.
        Type

        view sides

        You can use the word VIEW to find the definition of any F-PC word.

        The F-PC word DEBUG is a powerful debugging tool that allows you
        to single step through the definition of a word while watching
        what is being stored on the stack.

        After FLOADing LESSON2 type

        debug area


        The next time the word AREA is executed, it will pause at each word
        in its definition and display the stack contents.  Pressing any key
        (other than Q, C, N, U, X or F) will continue the single stepping.
        For example, if you type

        10 27 215 230 area

        the definition of AREA will be displayed on the top of the screen
        and the following will be displayed on the bottom of the screen as
        you press the space bar three times.

        10 27 215 230 AREA  [4]    10     27      215     230
        12648  0 :   SIDES      ?>  [2]    203  205
        12648  2     *          ?>  [1]  41615
        12648  4     UNNEST     ?>  ok

        After each name in the definition is executed by pressing the
        space bar, the number of items on the stack is shown in the
        brackets [ ] and the values of the top four items on the stack
        are displayed.  Note in this case that when the two values 203
        and 205 were multiplied to produce 41615 the reason for the
        displayed value of -23921 when we tested the program becomes clear.
        In fact, after single stepping through the above definition of AREA
        the value 41615 will be left on the stack.  If you then type . (DOT)
        the value -23921 will be displayed.  This, of course, is just the
        signed value of the 16-bit integer 41615.

        Type UNBUG to cancel debug so that future executions of AREA will
        not be debugged.  While single stepping,

                pressing Q will quit DEBUG and execute UNBUG;

                pressing C will continue execution to the end of the
                definition or until <Enter> is pressed;

                pressing F will return temporarily to Forth
                (press <Enter> to return to single stepping of the
                debugged word);

                pressing X will toggle the source listing on and off;

                pressing N will nest into the word to be executed;

                pressing U will unnest back to the calling word.

        As an example of nesting, type DEBUG AREA and then type

        10 27 215 230 AREA

        Then press N.  This will nest into the definition of SIDES.
        Single step through this definition and watch how it returns
        to the definition of AREA.



EXERCISE 2.1

        Make a file called HW2.SEQ and write the following colon definition
        in this file:

        : stacktest     ( a b -- ? )
                        DUP *
                        SWAP DUP
                        * + ;

        Add a stack picture to the right of each line in this definition.
        FLOAD the file and use DEBUG to single step through the word when
        you type

        4 5 stacktest

        What value in terms of a and b is left on the stack?

comment;