
Forth-help              F-PC Forth Command Help
                         

                           F-PC word catgories

       Applications          Boolean-words         Branch/Loop

       Color-words           Compile-Directives    Display-words

       DOS-Commands          Double-Number         Field-words

       File-words            Internals             Keyboard-words

       LineEdit-words        Logical-words         Math-words

       Memory-words          Menu-words            Number-Conversion

       String-words          Time/Date-words       Window-words



Applications         F-PC Application generation words
                      

       FSAVE           Save the current memory image to a file.

       TURNKEY         Save reduced size memory image to a file
                        without heads.

       BOOT            A deferred word that you can fill with your
                        own boot time routine.

       DEFAULT         A deferred word that handles the DOS command
                        line entered at the beginning of execution.

       INITSTUFF       A deferred word initialization CHAIN of routines
                        to perform in sequence at cold start time.



  (F9 will browse the source for a word, and Alt-H will browse its Help)

Boolean-words          Boolean Operators in F-PC
                        


                <              >              0<             0>

                <=             >=             U<             U>

                U<=            U>=            <>










  (F9 will browse the source for a word, and Alt-H will browse its Help)

Branch/Loop       Conditional Branch and Loop Control
                   


                IF     ...     ELSE   ...     THEN

                BEGIN  ...     UNTIL

                BEGIN  ...     WHILE  ...     REPEAT

                DO     ...     LEAVE  ...     LOOP

                DO     ...     ?LEAVE ...     +LOOP

                FOR    ...     NEXT

                UNDO


  (F9 will browse the source for a word, and Alt-H will browse its Help)

Color-words            Color Control in F-PC
                        


                RED            GREEN          BLUE

                YELLOW         MAGENTA        CYAN

                BROWN          WHITE          BLACK

                LTGRAY         DKGRAY         LTBLUE

                LTGREEN        LTRED          LTMAGENTA

                >FG            >BG            >COLOR

                >LCD           >MONO


  (F9 will browse the source for a word, and Alt-H will browse its Help)

Compile-Directives         Compiler Controls
                            


                COMMENT:       (              \

                }              \\             /*

                #IF            #ELSE          #THEN










  (F9 will browse the source for a word, and Alt-H will browse its Help)

Display-words      Display Output and Control Words
                    

        >ATTRIB1       >ATTRIB2       >ATTRIB3       >ATTRIB4

        >ATTRIB5       >ATTRIB6       >ATTRIB7       >ATTRIB8

        >BOLD          >BOLDBLNK      >BOLDUP        >LCD

        >MONO          >NORM          >REV           >REVBLNK

        >UL            AT             CLS            CR

        DARK           EEOL           EMIT           FEMIT

        IBM--LINE      IBM-AT         IBM-AT?        IBM-DARK

        PAGE           SPACE          SPACES         TYPE

  (F9 will browse the source for a word, and Alt-H will browse its Help)

DOS-Commands                DOS Commands
                             


                CD             CHDIR          CLS

                COPY           DEL            DIR

                REN            RENAME         SYS

                `              $SYS           "SYSCOMMAND








  (F9 will browse the source for a word, and Alt-H will browse its Help)

Double-Number          Double Number Operators
                        


                *D             2!             2>R

                2@             2DROP          2DUP

                2R>            D+             D-

                D.             D.R            D0=

                D2/            D<             D=

                D>             DMAX           DMIN

                DU<            UD.            UD.R


  (F9 will browse the source for a word, and Alt-H will browse its Help)

Field-words            F-PC Field Conversion Words
                        

        Moves From      CFA     >BODY    BODY      Moves To

                        CFA     >LINK    LINE

                        CFA     >NAME    NAME

                        BODY    BODY>    CFA

                        LINK    L>NAME   NAME

                        LINK    LINK>    CFA

                        NAME    N>LINK   LINK

                        NAME    NAME>    CFA

  (F9 will browse the source for a word, and Alt-H will browse its Help)

File-words             File Control Words
                        

  F-PC uses HANDLES to interface with DOS files. A handle to DOS is a 16 bit
number in the range 0 to 20. The first handles 0 to 4 are taken for DOS's
standard devices. F-PC uses a structure in CODE space that holds the number
DOS calls a handle, as well as the name of the file associated with the
handle.  F-PC calls this entire STRUCTURE a HANDLE.  You can create handles
which hold the above mentioned items, with the word HANDLE.  A handle that
contains a name can be opened, closed, deleted renamed etc.  A handle once
created returns address, and all file words know how to step into a handle
to get or set the information they need.

  More information is available on the following items:


        Handle-Structure       File-Wordset       Lineread-Example


  Also see the Users Manual Chapter 5 for additional information.

Handle-Structure       F-PC handle structure
                        


        The HANDLE memory data structure is as shown here.


          1byte    65 bytes      2 bytes    2 bytes
        Ŀ
         count   Filename....0  attrib    handle > -1 
        
          addr     addr+1          addr+66    addr+68
                                            
                    >NAM           >ATTRIB   >HNDLE
           
            Address of the array returned by a word defined with HANDLE.

   A >HNDLE value of less than 0 indicates no file is open on this handle.



Lineread-Example       An Example of File Usage
                        

A sequential line read word LINEREAD is provided, which reads one line at a
time from the file whose handle is in SEQHANDLE, returning an address of a
count string which also includes the CRLF characters at the end of the
line.  You will have to strip them off if you don't want them. The LINEREAD
word is used as follows:

: sample        ( | <filename> --- )
        open                    \ open a file
        0.0 seek                \ reset file pointer buffer
        begin
                lineread        \ read a line, returns an address of counted $
                dup c@          \ check for length,
        0 <> while              \ while buffer contains something
                cr count 2- type\ type line just read without the CRLF chars.
        repeat  drop            \ repeat till file empty.
        close ;                 \ close the file.


File-Wordset           The File Control Wordset
                        

 $FILE          $FLOAD         $HOPEN         .FILE          .FPATH

 >LINE          CHARREAD       CLOSE          CLOSEALL       CURPOINTER

 FILE           FILE>TIB       FL             FLOAD          FPATH

 FPATH+         HCLOSE         HCLOSE         HCREATE        HDELETE

 HIDELINES      HNDLS          HOPEN          HRENAME        IBLEN

 IBRESET        LINEREAD       LOAD           MOVEPOINTER    OBLEN

 OK             OPEN           SEEK           SEQDOWN        SEQHANDLE

 SEQHANDLE+     SEQUP          SETTIB         SHOWLINES      HANDLE

  (F9 will browse the source for a word, and Alt-H will browse its Help)

Internals              F-PC Internal Structure
                        
   F-PC is a DTC (Direct Thread Code) 16 bit Forth. Both stacks are 16 bits.
 F-PC obtains its large addressing space through the use of segment pointers
 to COLON definitions which are located outside of Forth's normal 64k CODE
 area. F-PC's symbols or headers are also kept in an external 64k segment
 area, leaving all of the 64k CODE area for CODE and DATA. Additional space
 savings have been obtained by placing all ." strings in LIST space with the
 COLON definitions.  The primary limiting factor in F-PC with respect to
 space utilization seems to be symbol space, which is limited to around
 5000 symbols max. To a large extent even this limit can be overcome through
 the use of a built in BEHEAD mechanism. VERY LARGE applications can be
 coded in F-PC.  F-TC does have the usual 8086 type problem of dealing with
 large linear data areas across 64k segment boundries, but again there are
 the usual solutions to this problem involving the use of either segment and
 offset double pointers, or of placing data elements on segment boundries.

Internals for   CODE-DEFs   COLON-DEFs  VARIABLEs   CONTANTs

                HEADERs     VALUEs      DEFERREDs    CREATE-DOESs

HEADERs               F-PC Internal Structure  (Headers)
                        
                        The Header of the word HEX

             Ŀ
     >VIEW   view    16 bit-offset into file where word was defined.
             Ĵ
     >LINK   link    Offset of next lower definition's LINK field.
             Ĵ
     >NAME    cnt    Usual count type with smudge and immediate bits.
             Ĵ
                H     First letter of the HEX definition.
             Ĵ
                E   
             Ĵ
             1 X     Most significant bit of last char set to 1.
             Ĵ
             CFA PTR  Offset of CFA in CODE space.
             
                        ("Y" operators are used to manipulate HEAD space.)

COLON-DEFs            F-PC Internal Structure  (COLON)
                        
                The CODE Field of the COLON definition HEX


                CFA
           +0Ŀ
      BODY>   $E9    The infamous CFA (Code Field Address).
           +1Ĵ
              NEST    Relative offset to NEST for COLON definition.
           +3Ĵ
      >BODY  LIST    BODY starts at CFA + 3, and contains the RELATIVE
                SEGMENT of where the the list is located in LIST
                        space.

                        ("X" & Long operators are used to manipulate
                        LIST space.)

       The next screen shows the LIST space for the COLON definition HEX.


                        F-PC Internal Structure  (COLON)
                        
                 The LIST space of the COLON definition HEX

         +0Ŀ
             (LIT)   The formula below returns this the LIST address.
         +2Ĵ
              $10     ' HEX >BODY @ XSEG @ + ( --- A1 )
         +4Ĵ
             BASE  
         +6Ĵ
              !      The remaining 6 bytes of the 16 byte segment are
         +8Ĵ  null filled.
            UNNEST 
           

  a1 returned by the above calculation is in LIST space, and you could use
LDUMP to examine it, but XDUMP will perform the calculation for you if
used as follows:
                        ' HEX >BODY @ 10  XDUMP

CODE-DEFs             F-PC Internal Structure  (CODE)
                        
                The CODE Field of the CODE definition 2+

                CFA
           +0Ŀ
              $E9             POP AX
             Ŀ
              $05 $0200       ADD AX, # $0002
                   Ŀ
              $50             PUSH AX         The last four instructions
             Ĵ            Ŀ     makeup the 1PUSH macro
              $26             ES:           
             Ĵ                          
              $AD             LODSW       The last three instructions
             Ŀ                       makeup the NEXT macro
              $FFE0           JMP AX        
                        

        As you can see the CFA of a CODE definition contains CODE.

VARIABLEs             F-PC Internal Structure  (VARIABLEs)
                        
                  The CODE Field of the VARIABLE DPL


                CFA
           +0Ŀ
      BODY>   $E8    CALL instruction.
           +1Ĵ
              NEXT    Relative offset to NEXT code routine.
           +3Ĵ
      >BODY  VALUE   The BODY of a VARIABLE contains the actual
               variables value.


  The code for a variable simply CALLs NEXT which pushes the address of the
BODY of the variable on the data stack and continues execution.




CONSTANTs             F-PC Internal Structure  (CONSTANTs)
                        
                  The CODE Field of the CONSTANT MAGENTA


                CFA
           +0Ŀ
      BODY>   $E8    CALL instruction.
           +1Ĵ
              DOCON   Relative offset to DOCONSTANT code routine.
           +3Ĵ
      >BODY  VALUE   The BODY of a CONSTANT contains the actual
               constant's value.


  The code for a constant CALLs DOCONSTANT which pushes the contents of the
BODY of the constant on the data stack and continues execution.




VALUEs                F-PC Internal Structure  (VALUEs)
                        
                  The CODE Field of the VALUE ROWS


                CFA
           +0Ŀ
      BODY>   $E8    CALL instruction.
           +1Ĵ
              DOVAL   Relative offset to DOVALUE code routine.
           +3Ĵ
      >BODY  VALUE   The BODY of a VALUE contains the actual
               VALUE's value.


  The code for a constant CALLs DOVALUE which pushes the contents of the
BODY of the value on the data stack and continues execution.




DEFERREDs              F-PC Internal Structure  (DEFERREDs)
                        
                  The CODE Field of the DEFERed word CR


                CFA
           +0Ŀ
      BODY>   $E8    CALL instruction
           +1Ĵ
              DODEF   Relative offset to DODEFER code routine.
           +3Ĵ
      >BODY  VALUE   The BODY of a DEFERRED word contains the CFA of
               the word CR is deferred to (CRLF in this case).


  The code for a deferred word CALLs DODEFER which executes the contents of
the BODY of the deferred word.




CREATE-DOESs          F-PC Internal Structure  (CREATE-DOESs)
                        


  The structure of CREATE DOES> words in F-PC is fairly complex, so we will
look at a simple but specific example of how such a word is compiled into
the various segments used by F-PC. The example we will use is for a
defining word that creates words that type a single graphics character to
the display:

        : GREMIT <name> ( N1 --- )
                        CREATE C, DOES> 1 TYPE ;

        $02 GREMIT HAPPY        \ $02 is the hex value for "" A happy face.


  On the next screen we will see how these words get compiled into memory.


                Press PgDn to see the compiled structure.

                        F-PC Internal Structure  (CREATE-DOESs cont.)
                        

        List segment of GREMIT                   Child's List segment
      Ŀ
 LIST  CREATE  C,  (;CODE)  GREMIT-DOES ptr  (LIT)  1  TYPE  UNNEST 
      
                 Ŀ             Ŀ
        <Ĵ XSEG @ +               XSEG @ + 
                    V           
                      ^                       ^
      Ŀ
 CODE  JMP NEST  LIST ptr  CALL  DODOES  DOES-LIST ptr    ...
      
                               ^        CODE and BODY for the word GREMIT
                 
      Ŀ
 CODE  CALL  GREMIT-DOES  $02       CODE and BODY of the word HAPPY
      
                                        Press PgDn for more description

                        F-PC Internal Structure  (CREATE-DOESs cont.)
                        

  As you can see in the previous screen, building the definition GREMIT
(shown top and middle) compiles information into both the LIST and CODE
areas. The child word HAPPY (at the bottom) compiles a small amount
information into the CODE area.  This is a particularly efficient way to
create classes of words that differ only in their data. In this case HAPPY
uses only five bytes of CODE memory.

  The child of a CREATE-DOES word in effect calls a headerless COLON
definition that is built as part of the defining word.

  When compiling GREMIT, a pointer to GREMIT-DOES is compiled into LIST
space for later use when compiling the child words. The child word is then
linked to call the DOES portion of the parent word.

  When the parent word is executing through its LIST, parent execution
actually stops after (;CODE) is executed.  The remainder of the parent
definition is only executed by the child words.

Keyboard-words              Keyboard Words
                             

  F-PC provides flexible and powerful access to the keyboard.  You can read
all keys on the keyboard that will return keycodes, and even differentiate
between keys that return the same keycodes but different scancodes. It is
also possible to look ahead one keystroke to see what key has been pressed
but has not been read yet.

                KEY            KEY?           KEYFILTERing

                (KEY)          (KEY?)         Looking-Ahead

                BIOSKEY        BIOSKEY?       ?KEYPAUSE

                SCANCODES





KEYFILTERing          Key Filtering: What's it for?
                       

  A deferred word KEYFILTER is provided for the purpose of allowing
applications to process all keys returned from the keyboard prior to those
keys being passed to the rest of the Forth system.


Looking-Ahead
SCANCODES       Looking at the next key without getting it
                 

  A VALUE BIOSKEYVAL is provided which holds the keycode and scancode of
the most recent call to BIOSKEY? . Since the key is not actually read
from the keyboard buffer, this provides a mechanism for looking ahead one
keystroke. This can be useful when writing a key interpreter for an
application.

                             Scan Codes
                             

  Scancodes are values assigned to keys according to their position on the
keyboard rather than by their ASCII table position. Immediately after a key
is accepted using KEY you can look at the value in BIOSKEYVAL . The upper
byte of this word will contain the Scan code for the key just read.  This
allows you to see the keypad + - * and number keys as different from the
same keys in the main body of the keyboard.  See the IBM documentation for
a table of scan codes.


LineEdit-words           Using the Line Editor
                          

  F-PC provides a very nice general purpose line editor for use in your
programs. The word to invoke it is LINEEDITOR . Its usage is as follows:

                20 8 MYBUF 22 LINEEDITOR ( --- f1 )

  In the above example, the edit will start at column 20 of row 8. The edit
will be performed on the counted string in MYBUF, and the maximum length the
edit will be allowed to be will be 22 characters.  The line editor is
terminated by either the Enter key or the ESC key. If the ESC key was
pressed then a FALSE boolean flag is returned, otherwise a TRUE flag is
returned.  A mouse can be used to position the cursor within the edit line.

  If the edit is completed with Enter, then the edit string is placed back
into MYBUF. If the edit is terminated with ESC then MYBUF will contain the
original string unmodified by any edit operations performed during
lineedit.


Logical-words             Logical Operators
                            

  F-PC provides the usual logical operators. These operators are BIT logical.

                     AND    OR     NOT    XOR

Math-words                  Math Operators
                             
  F-PC provides several single and double precision math operators, as well
as several shift operators. Most of these are written in assembly language
to provide high performance. An additional set of math operators is
provided in an add-on file supporting floating point math. Both software and
hardware floating point math are supported: see the files SFLOAT.SEQ and
HFLOAT.SEQ for further information on floating point math.

        +      -      *      /      MOD    /MOD   */MOD

        */     NEGATE ABS    UM*    U*D    *D     M/MOD

        MU/MOD UM/MOD 1+     2+     1-     2-     S>D

        2*     8*     2/     U2/    U8/    U16/   ?NEGATE

        D+     D-     DABS   D2*    D2/

        DNEGATE        ?DNEGATE

Memory-words                Memory Operators
                             

  A full complement of memory operators is provided in F-PC to access
normal CODE segment memory, as well as external areas of the PC outside the
64k boundry.  Additional support is provided for EXPANDED memory: see the
file EXPANDED.SEQ.

        @      !      C@     C!     MOVE   CMOVE  CMOVE>

        @L     !L     C@L    C!L    CMOVEL CMOVEL>

        HERE   ?CS:   ?ES:   COMPARE SSEG  YSEG  YCSET

        YHERE  YS:    Y@     Y!     YC@    YC!    Y,

        XHERE  X,     XC,    XDP    XDPSEG SCAN   SKIP

        PARSE















