
                                  SST  1.15
                                  ---------

                  Stevens Software Tools (Turbo)  'C' library
                  -------------------------------------------

    


                                   CONTENTS


    1.      Introduction . . . . . . . . . . . . . . . . . . . . . . . . .
      1.1        Copyright . . . . . . . . . . . . . . . . . . . . . . . .
      1.1.1           Legal notice . . . . . . . . . . . . . . . . . . . .
      1.2        Technical support . . . . . . . . . . . . . . . . . . . .
      1.3        Distribution  . . . . . . . . . . . . . . . . . . . . . .
        1.3.1         P.D.N . . . . . . . . . .  . . . . . . . . . . . . .
        1.3.2         H.P.N . . . . . . . . . .  . . . . . . . . . . . . .
        1.3.3         NON COMMERCIAL use . . . . . . . . . . . . . . . . .
        1.3.4         COMMERCIAL use . . . . . . . . . . . . . . . . . . .
      1.4        Acknowledgements  . . . . . . . . . . . . . . . . . . . .


    2.      Features . . . . . . . . . . . . . . . . . . . . . . . . . . .
      2.1        Low level functions . . . . . . . . . . . . . . . . . . .
      2.2        Window System . . . . . . . . . . . . . . . . . . . . . .
      2.3        Data Entry System . . . . . . . . . . . . . . . . . . . .
      2.4        Editor  . . . . . . . . . . . . . . . . . . . . . . . . .

    3.      Using SST  . . . . . . . . . . . . . . . . . . . . . . . . . .
      3.1        Using the library functions . . . . . . . . . . . . . . .
        3.1.1         Compiling and Linking  . . . . . . . . . . . . . . .
        3.1.1         Using the MAKEFILE . . . . . . . . . . . . . . . . .

    4.      Low level functions  . . . . . . . . . . . . . . . . . . . . .
      4.1        Video functions . . . . . . . . . . . . . . . . . . . . .
      4.2        Keyboard functions  . . . . . . . . . . . . . . . . . . .
      4.3        Mouse functions . . . . . . . . . . . . . . . . . . . . .
      4.4        String functions  . . . . . . . . . . . . . . . . . . . .
      4.5        Miscellaneous functions . . . . . . . . . . . . . . . . .
      4.6        Fossil functions  . . . . . . . . . . . . . . . . . . . .

    5.      High level functions . . . . . . . . . . . . . . . . . . . . .
      5.1        Window functions  . . . . . . . . . . . . . . . . . . . .
      5.2        Menu functions  . . . . . . . . . . . . . . . . . . . . .
      5.3        Data entry functions  . . . . . . . . . . . . . . . . . .
      5.4        Editor functions  . . . . . . . . . . . . . . . . . . . .
      5.5        Help system functions . . . . . . . . . . . . . . . . . .
      5.6        Selection system functions  . . . . . . . . . . . . . . .




    1.  Introduction:
    -----------------


        This SST toolkit is provided to extend your C compilers standard
        run time library. It contains a substantial number of functions
        which provide a variety of capabilities.

        The toolkit may be used FREE of charge (i.e. dont send any money
        to me) for NON-COMMERCIAL use.  The fee for COMMERCIAL use has not
        been established yet but you may contact me regarding this for
        more information.

        The only compiler support for the moment is Turbo C, Turbo C++ and
        Borland C++ (however no C++ extensions have been used here).


        The toolkit has the following features.


        o       Low Level video support.
        o       Low Level keyboard support.
        o       Low level mouse support.
        o       Low level string manipulation
        o       Low level fossil interface

        o       High level windows system.
        o       High level pull down menus.
        o       High level formatted data entry.
        o       High level help interface.
        o       High level editor interface.
        o       High level pick and select interface.


        I would expect several small bugs to be floating around, so if you
        find any then please let me know, or better still try to fix them
        and tell me what to do.


        Thank you to Borland International for your fine range of
        Compiler products.




    1.1  Copyright:
    ---------------

        Documentation - (C)  Copyright  1991,1992  by Steven Lutrov.

        Source code   - (C)  Copyright  1991,1992  by Steven Lutrov.


        No patent liability is assumed with respect to the use of the
        information contained herein.

        You may develop any program you want by using the SST library.

        You may sell or give away your programs you develop using the
        toolkit including executable programs and their object modules.

        You may modify this code code to your hearts content for your
        own use.

        You may not publish this source code as your own work even if you
        have modified it.





    1.1.1  Legal notice:
    --------------------

        In no event shall Steven Lutrov or be liable to you or anyone else
        for any damages or costs, including, but not limited to, any lost
        profits, lost savings, lost income, lost information, loss of life,
        loss of spouses life, or any other incidental or consequential damages
        arising out of  the use or inability to use the SST library.





    1.2  Technical support:
    ----------------------


        Since I run a BBS system I am prepared to setup an Echomail
        support conference and any messages can be posted here where
        I or other users will try and answer any qeuries etc..

        Should you have any improvements additions or corrections to the
        source code, then by all means post them to me, they are extremely
        welcome here.

        Your name ( if you have no objections) will then added to the
        acknowledgements section.


        o       Land mail               Steven Lutrov
                                        P.O. Box 466
                                        Essendon 3040, VIC
                                        Australia

        o       Electronic mail         The Software Parlour BBS
                                        phone  - 61-3-338-3794
                                        bauds  - V42bis,V32,V22bis,V22,V21

                                        Crash Mail - 24 hours

                                        Email  - 3:635/544@fidonet
                                                 3:635/534@fidonet
                                                 58:4100/34@intlnet
                                                 58:4100/40@intlnet


     1.3.  Distribution:
     -------------------


     You are encouraged to  copy the toolkit files and  share  it  freely
     with others.  You have the luxury of trying out the complete programs
     at your own pace and in the comfort of  your  own home  or workplace.



     1.3.1.  P.D.N:
     --------------


     The  PDN  ( Programmers Distribution Network ) is   dedicated   to
     supporting programmers all  over the  world  and has  many notable
     programmers involved. The PDN distributes  source code, utilities,
     libraries .., shareware, public domain and freeware etc.


     This toolkit is also officially released to the PDN and shall meet
     all the requirements required by the PDN.


     More information may be obtained from the following..


     PDN International Coordinator    - Erik Vanriper
                                        1:260/230@fido.org



     1.3.2.  H.P.N:
     --------------


     The  HPN (Hax & Programming Network) is dedicated to supporting
     programmers all over Australia with  many notable programmers
     involved. The HPN distributes  source code, utilities, libraries ..,
     shareware, public domain and freeware etc.


     This toolkit is also officially released to the HPN and shall meet
     all the requirements required by the HPN.

     More information may be obtained abou HPN from the following..
     You may also File request the file with a mailer using the
     magic word "HPNINFO" form 3:635/544@fidonet or 58:4100/40@intlnet.

     OPN Coordinator                     - Steven Lutrov
                                           3:635/534@fidonet
                                           3:635/544@fidonet




    1.3.3  NON-COMMERCIAL use:
    --------------------------

        You may use the SST toolkit in a NON-COMMERCIAL enviroment free
        of charge.

        Just for the sake of keeping track as to how many people might be
        using this toolkit, I would appreciate if you send me a postcard
        or leave a message on the BBS (if you are local).




    1.3.4  COMMERCIAL use:
    ----------------------


        To use the SST toolkit in a COMMERCIAL enviroment, a commercial
        license must be obtained, otherwise it would be a breach of
        the copyright laws.

        For pricing information you will need to contact the author ,
        see section 1.2 .



    1.4  Acknowledgements:
    ----------------------


        Steven Lutrov      - 91-08-12
        ---------------------------
              Iinitial release.


        Richard Deguara    - 92-04-27
        -----------------------------
              Code modification to allow windows with no borders.




    2.1  Low level functions
    ------------------------

    The system was initially built with low level functions. All the
    high level functions use the low level functions, such as reading
    and writing to the screen. Initially the low level routines used
    an assembler module to get full benefit from speed, but after
    running a Profiler on the code the speed of the assembler code
    was actually about 10% slower. I was naturally shocked being a
    former assembler programmer.

    The low level video functions actually perform direct screen
    writes and reads and rid the toolkit of any assembler code and
    any tracking of video retrace registers. This is highly
    questionable, non-portable and risky and very hacker-mentality
    like, but I like it.





    2.2   Windows System:
    --------------------

    The window library is set of text mode functions that display
    smart windows that track the order of precedence. In other words
    windows pop up on top of other ones, and can hide or dissappear
    and make the window under it visible etc.
    All the Data Entry, Editor, Menus, Help system use the the common
    window library of functions.  All the windows created preserve
    what they cover and hence restore the image beneath when the
    window is closed. Each window can have borders titles footers
    and selectable attributes.

    An important feature is that the windows do not have to be visible
    in order to write to them. The title or border or any other
    characteristic of a window may be altered while the window is
    visible or invisible.



    2.3 Data Entry System:
    ----------------------

    The data entry system uses the window library to implement general
    purpose data entry. Here is how it works: You establsh a window
    with the Westablish() function and build an array of data entry
    field definitions. You write some prompting info to the window and
    call the Fdataentry() function. The data entry function takes over
    and collects the users key entries into a predefined buffer. There
    are validation functions which can be used to check for correct
    entry both prior to and after the entry is completed as well as
    specifiying that the data entry must be of a certain type.
    The types available include ASCII, Integer, Hexadecimal, Currency
    etc etc. Each entry may also be converted to lower, upper or proper
    case. A help function may be assigned to each field, the function
    may be activated only once when you are on the field, always when
    you are on the field, or only when you hit the help key on the
    field.

    The fields use dynamically allocated linked lists for good memory
    management.



    2.3   Editor:
    -------------



        Editing keystrokes.
        -------------------


        RETURN       - inserts carrage return.
        ESC          - exits the editor.
        TAB          - moves to the next tab stop.
        SHIFT_TAB    - moves to the previous tab stop.

        UP           - moves up one line.
        PGUP         - moves up one page.
        CTRL_PGUP    - moves to the top of the 1st page.

        DOWN         - moves down one line.
        PGDN         - moves down one page.
        CTRL_PGDN    - moves to the bottom of the last page.

        LEFT         - moves left on character.
        CTRL_LEFT    - moves to the previous word.

        RIGHT        - move forward on character.
        CTRL_RIGHT   - moves to the next word.

        HOME         - moves to the first column.
        CTRL_HOME    - moves to the first column and row on
                       the first page.

        END          - moves to the end of the last page.
        CTRL_END     - moves to the last column and row on
                       to the last page.

        INS          - toggles inserting mode.
        DEL          - deletes the predecessing character.

        CTRL_Y       - deletes the current line.
        CTRL_D       - deletes the predecessing word.

        F2           - Exits the editor.
        F3           - erases the edit buffer.
        F4           - reformats the current block.
        ALT_F7       - copies the current block.
        F7           - marks the block begining.
        F8           - marks the block end.
        ALT_F8       - move_block the current block;
        F9           - deletes the current block.
        F10          - unmark blocks.





    3.1  Using the library functions:
    ---------------------------------

        Every function that is usable in the SST library has a
        corresponding prototype in one of the associated header files.
        As most of the high level functions are all windows based the
        prototypes would usually be found in "sstwin.h".



    3.1.1  Compiling and Linking:
    -----------------------------

        The basic command line compiler and linker commands to build
        your files are as follows, provided you compiler paths are
        all set up appropriately.


        Using Turbo C++ or Turbo C
        --------------------------

                  tcc demo.c ssts.lib

        Using Borland  C++
        ------------------

                  bcc demo.c ssts.lib


        I choose to use the IDE, so in here you will need to create a
        project file for your application and include the SST library
        in you project as well as you application file, then press
        the Make key to make your application.




    3.1.2  Using the Makefile:
    --------------------------

        In the distribution archive there is a MAKEFILE provided. You
        can build all the source code and the library as well as all
        the demo programs by using the makefile.


        On the commmand line simply enter "MAKE". The make utility is
        provided with your compiler and will automatically try to find
        and use a file called MAKEFILE unless another one is specified
        as a parameter to MAKE.

        You should first check out the file MAKEFILE as you may need to
        make changes here to match the path to your compiler. You can
        also set a different memory model.

        The default memory model is SMALL.




    4.  Low level functions:
    ------------------------

        The low level functions are mainly for video, keyboard and mouse
        functions.

        The high level functions make extensive use out of the lower
        level functions




    4.1  Video functions:
    ---------------------



    ------------------------------------------------------------------------
    NAME          ... vbeep

    DESCRIPTION   ... Make a mscbeep noise, what else !

    PROTOTYPE     ... void mscbeep            (int mode);

    ARGUMENTS     ... mode         - TRUE   - Will make an error beep.
                                     FASLE  - Will make a pleasent beep;

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... vblinkbit

    DESCRIPTION   ... Enables or disables the blink bit in the video
                      register, this is only available on EGA and VGA
                      systems.

    PROTOTYPE     ... void vblinkbit(int f);

    ARGUMENTS     ... f            - TRUE  blinking is enabled.
                                     FALSE  intensity is enabled.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... vclearrline

    DESCRIPTION   ... Clears the an entire line on the screen with an
                      attribute.

    PROTOTYPE     ... void vclearrline (unsigned char l, unsigned char a);

    ARGUMENTS     ... l            - The line to clear.
                      a            - The attribute to clear the screen with.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vcls

    DESCRIPTION   ... Clears the entire screen with an attribte by scrolling.

    PROTOTYPE     ... void vcls (unsigned char a);

    ARGUMENTS     ... a            - The attribute to clear the screen with.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... vfill

    DESCRIPTION   ... Fills a rectangular area of the screen with a given
                      char and attribute.

    PROTOTYPE     ... void vfill(int x, int y, int yy, int xx, int c, int a);

    ARGUMENTS     ... x            - Starting column.
                      y            - Starting row.
                      yy           - Number of rows.
                      xx           - Number of columns.
                      c            - Char used for filling
                      a            - Attribute used for filling.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vget

    DESCRIPTION   ... Gets a character and attribute form the screen at the
                      given coordinates.

    PROTOTYPE     ... int vget(int x, int y);

    ARGUMENTS     ... x            - Starting column.
                      y            - Starting row.

    RETURNS       ... 16 bit word (integer) holding the char and attribute.
                      The high order 8 bits hold the attribute and the low
                      order 8 bits hold the char.


    ------------------------------------------------------------------------
    NAME          ... vgeta

    DESCRIPTION   ... Gets an attribute form the screen at the given
                      coordinates.

    PROTOTYPE     ... int vgeta(int x, int y);

    ARGUMENTS     ... x            - Starting column.
                      y            - Starting row.

    RETURNS       ... 16 bit word (integer) holding the attribute.



    ------------------------------------------------------------------------
    NAME          ... vgetac

    DESCRIPTION   ... Gets an attribute form the screen at the current
                      cursor coordinates.

    PROTOTYPE     ... int vgetac(void);

    ARGUMENTS     ... void

    RETURNS       ... 16 bit word (integer) holding the attribute.




    ------------------------------------------------------------------------
    NAME          ... vgetch

    DESCRIPTION   ... Gets a char form the screen at the given coordinates.

    PROTOTYPE     ... int vgetch(int x, int y);

    ARGUMENTS     ... x            - Starting column.
                      y            - Starting row.

    RETURNS       ... 16 bit word (integer) holding the char.



    ------------------------------------------------------------------------
    NAME          ... vgetchc

    DESCRIPTION   ... Gets a char form the screen at the current
                      cursor coordinates.

    PROTOTYPE     ... int vgetchc(void);

    ARGUMENTS     ... void

    RETURNS       ... 16 bit word (integer) holding the char.




    ------------------------------------------------------------------------
    NAME          ... vgetcur

    DESCRIPTION   ... Returns the current cursor positions. Make sure you
                      pass the address to the arguments.

    PROTOTYPE     ... void vgetcur(int *x, int *y);

    ARGUMENTS     ... x            - The column.
                      y            - The row.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vhidecur

    DESCRIPTION   ... Hides the cursor making it invisible to the screen.

    PROTOTYPE     ... void vhidecur(void);

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... visega

    DESCRIPTION   ... Test if an EGA adaptor is installed.

    PROTOTYPE     ... int visega(void);

    ARGUMENTS     ... void

    RETURNS       ... TRUE         - EGA adaptor present.
                      FALSE        - EGA adaptor NOT present.


    ------------------------------------------------------------------------
    NAME          ... visvga

    DESCRIPTION   ... Test if an VGA adaptor is installed.

    PROTOTYPE     ... int visvga(void);

    ARGUMENTS     ... void

    RETURNS       ... TRUE        - VGA adaptor present.
                      FALSE       - VGA adaptor NOT present.



    ------------------------------------------------------------------------
    NAME          ... vnormalcur

    DESCRIPTION   ... Makes the cursor appear in its normal state, as it
                      would from boot-up state.

    PROTOTYPE     ... void vnormalcur(void);

    ARGUMENTS     ... void

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... vpopcur

    DESCRIPTION   ... Pops the last saved cursor configuration and position
                      from the cursor save stack.

    PROTOTYPE     ... void vpopcur(void);

    ARGUMENTS     ... void

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vpopscreen

    DESCRIPTION   ... Pops the last saved screen from the screen save stack.

    PROTOTYPE     ... void vpopscreen(void);

    ARGUMENTS     ... void

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vpushcur

    DESCRIPTION   ... Saves the current cursor configuration and position
                      to the cursor save stack.

    PROTOTYPE     ... void vpushcur(void);

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... vpushscreen

    DESCRIPTION   ... Pushes (saves) an entire screen to the screen save
                      stack. The stack is allocated in the far heap , The
                      Turbo C enviroment (Turbo C editor & debugger) under
                      normal conditions does not leave you much memory
                      here, so you will have to change the options to make
                      more of the far heap available.

    PROTOTYPE     ... int vpopscreen(void);

    ARGUMENTS     ... void

    RETURNS       ... 0          - No errors.
                      -1         - Maximum screen saves exceeded.
                      -2         - Out of memory, (far heap).



    ------------------------------------------------------------------------
    NAME          ... vputch

    DESCRIPTION   ... Writes a char directly to the video memory with
                      a specified attribute.

    PROTOTYPE     ... void vputch(int x, int y, unsigned char a,
                                  register unsigned char c);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.
                      a            - The attribute to write in.
                      c            - The char to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vputf

    DESCRIPTION   ... Writes a string directly to the video memory with
                      a specified attribute, using a variable argument
                      convention.

    PROTOTYPE     ... void vputf(int x, int y, unsigned char a,
                                 char *fmt, ...);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.
                      a            - The attribute to write in.
                      fmt          - The formated string to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vputfc

    DESCRIPTION   ... Writes a centered string directly to the video memory
                      with  a specified attribute, using a variable argument
                      convention.

    PROTOTYPE     ... void vputfc(int y, unsigned char a, char *fmt, ...);

    ARGUMENTS     ... y            - The starting row.
                      a            - The attribute to write in.
                      s            - The formatted string to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vputs

    DESCRIPTION   ... Writes a string directly to the video memory with
                      a specified attribute.

    PROTOTYPE     ... void vputs(int x, int y, unsigned char a,
                                 register char *cp);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.
                      a            - The attribute to write in.
                      cp           - The string to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vputsc

    DESCRIPTION   ... Writes a centered string directly to the video memory
                      with  a specified attribute.

    PROTOTYPE     ... void vputsc(int y, unsigned char a, char *s);

    ARGUMENTS     ... y            - The starting row.
                      a            - The attribute to write in.
                      s            - The string to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vset25

    DESCRIPTION   ... Sets the video adaptor to display 25 lines per screen.

    PROTOTYPE     ... void vset25(void);

    ARGUMENTS     ... void

    RETURNS       ... void

    ------------------------------------------------------------------------
    NAME          ... vset43

    DESCRIPTION   ... Sets the video adaptor to display 43 lines per screen.
                      This is only possible on EGA and VGA systems.

    PROTOTYPE     ... void vset43(void);

    ARGUMENTS     ... void

    RETURNS       ... void

    ------------------------------------------------------------------------
    NAME          ... vset50

    DESCRIPTION   ... Sets the video adaptor to display 50 lines per screen.
                      This is only possible on EGA and VGA systems.

    PROTOTYPE     ... void vset50(void);

    ARGUMENTS     ... void

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vsetcur

    DESCRIPTION   ... Positions the cursor at the specified coordinates.

    PROTOTYPE     ... void vsetcur(int x, int y);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... vsetcurtype

    DESCRIPTION   ... Sets the cursor for a particular appearance. Refer to
                      the IBM manual on Interrupt 0x10 for charactersitics.

    PROTOTYPE     ... void vsetcurtype(unsigned t);

    ARGUMENTS     ... t            - The cursor type.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... vshowcur

    DESCRIPTION   ... Unhides the cursor, this is usually called some time
                      after the vhidecur function to make the cursor
                      visible again.

    PROTOTYPE     ... void vshowcur(void);

    ARGUMENTS     ... void

    RETURNS       ... void






    4.2  Keyboard functions:
    ------------------------



    ------------------------------------------------------------------------
    NAME          ... kgetch

    DESCRIPTION   ... Gets a character from the keyboard and hooks to a
                      help function if the help key is pressed. The global
                      variable help_key is set to F1 by default, but may
                      be overwritten by re-assignment.
                      This function discards any extended keystrokes,
                      returning only when a non-extended keystroke is
                      available, see kgetche() for extended keystrokes.

    PROTOTYPE     ... unsigned int kgetch(void);

    ARGUMENTS     ... void

    RETURNS       ... The character received.
                      HIGH order 8 bits = scan code.
                      LO   order 8 bits = ASCII char.
                      see <sstkey.h> for key definitions.



    ------------------------------------------------------------------------
    NAME          ... kgetche

    DESCRIPTION   ... Gets a character from the keyboard and hooks to a
                      help function if the help key is pressed. The global
                      variable help_key is set to F1 by default, but may
                      be overwritten by re-assignment.
                      This function supports extended keystrokes (F11 & F12
                      etc).

    PROTOTYPE     ... unsigned int kgetche(void);

    ARGUMENTS     ... void

    RETURNS       ... The character received.
                      HIGH order 8 bits = scan code.
                      LO   order 8 bits = ASCII char.
                      see <sstkey.h> for key definitions.


    ------------------------------------------------------------------------
    NAME          ... kkeyhit

    DESCRIPTION   ... Tests if a key has been pressed. This function
                      supports extended keystrokes.

    PROTOTYPE     ... int kkeyhit(void);

    ARGUMENTS     ... void

    RETURNS       ... TRUE        - Key has been hit.
                      FALSE       - No key has been hit.



    ------------------------------------------------------------------------
    NAME          ... kstate

    DESCRIPTION   ... Test the state of all the special keys by using a bios
                      call. The function returns a 16 bit word holding the
                      state of the keys. The following constants may be used
                      in determining if a key is pressed by ANDing the
                      returned result.

                             K_RIGHTSHIFTDOWN     - right shift key is down.
                             K_LEFTSHIFTDOWN      - left shift key is down.
                             K_CTRLSHIFTDOWN      - ctrl shift keys are down.
                             K_ALTSHIFTDOWN       - alt shift keys are down.
                             K_SCROLLLOCKON       - scroll-lock key is on.
                             K_NUMLOCKON          - num-lock key is on.
                             K_CAPSLOCKON         - caps-lock key is on.
                             K_INSON              - insert key is on.
                             K_CTRLNUMLOCKON      - ctrl num-lock keys are on.
                             K_SCROLLLOCKDOWN     - scroll-lock key is down.
                             K_NUMLOCKDOWN        - num-lock key is down.
                             K_CAPSLOCKDOWN       - caps-lock key is down.
                             K_INSDOWN            - insert key is down.


    PROTOTYPE     ... int far *kstate(void);

    ARGUMENTS     ... void

    RETURNS       ... Far pointer to an integer (16 bit word) of the key
                      states.





    4.3  Mouse functions:
    ---------------------



    ------------------------------------------------------------------------
    NAME          ... msdleftpressed

    DESCRIPTION   ... Tests if the left mouse button has been pressed twice.
                      This is used in selecting items where the mouse needs
                      to be clicked twice within a certain time period. The
                      time period is preset and is optimised to give the
                      same performance as the IDE.

    PROTOTYPE     ... int msdleftpressed(void);

    ARGUMENTS     ... void

    RETURNS       ... !0           - The left button has been pressed
                                     twice.
                      0            - The left button has not been pressed
                                     twice.



    ------------------------------------------------------------------------
    NAME          ... msdrightpressed

    DESCRIPTION   ... Tests if the right mouse button has been pressed twice.
                      This is used in selecting items where the mouse needs
                      to be clicked twice within a certain time period. The
                      time period is preset and is optimised to give the
                      same performance as the IDE.

    PROTOTYPE     ... int msdrightpressed(void);

    ARGUMENTS     ... void

    RETURNS       ... TRUE         - The right button has been pressed
                                     twice.
                      FALSE        - The right button has not been pressed
                                     twice.


    ------------------------------------------------------------------------
    NAME          ... msgetch

    DESCRIPTION   ... Suspends execution until a mouse button is pressed.

    PROTOTYPE     ... #define msgetch()  while(mspressed());

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... msgetpos

    DESCRIPTION   ... Gets the mouse coordinates.

    PROTOTYPE     ... void msgetpos(int *x, int *y);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... mshide

    DESCRIPTION   ... Hides the mouse cursor making it invisible.

    PROTOTYPE     ... void mshide(void);

    ARGUMENTS     ... void

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... msinstalled

    DESCRIPTION   ... Tests to see if the mouse driver is installed.

    PROTOTYPE     ... int msinstalled(void);

    ARGUMENTS     ... void

    RETURNS       ... TRUE         - Mouse is installed.
                      FALSE        - Mouse is not installed.


    ------------------------------------------------------------------------
    NAME          ... msleftpressed

    DESCRIPTION   ... Tests if the left mouse button has been pressed.

    PROTOTYPE     ... #define msleftpressed()  (mspressed()&1)

    ARGUMENTS     ... void

    RETURNS       ... TRUE         - The left button has been pressed.
                      FALSE        - The left button has not been pressed.



    ------------------------------------------------------------------------
    NAME          ... mspressed

    DESCRIPTION   ... Tests if the mouse buttons are pressed.

    PROTOTYPE     ... int mspressed(void);

    ARGUMENTS     ... void

    RETURNS       ... TRUE         -  The mouse buttons are pressed.
                      FALSE        -  The mouse buttons are not pressed.



    ------------------------------------------------------------------------
    NAME          ... msreleased

    DESCRIPTION   ... Tests if a mouse button has been released.

    PROTOTYPE     ... int msreleased(void);

    ARGUMENTS     ... void

    RETURNS       ... TRUE         - The mouse button has been released.
                      FALSE        - The mouse button has not been
                                     released.


    ------------------------------------------------------------------------
    NAME          ... msreset

    DESCRIPTION   ... Resets the mouse.

    PROTOTYPE     ... void msreset(void);

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... msrightpressed

    DESCRIPTION   ... Tests if the right mouse button has been pressed.

    PROTOTYPE     ... #define msrightpressed()   (mspressed()&2)

    ARGUMENTS     ... void

    RETURNS       ... TRUE         - The right button has been pressed.
                      FALSE        - The right button has not been pressed.




    ------------------------------------------------------------------------
    NAME          ... mssetpos

    DESCRIPTION   ... Positions the mouse cursor at a specific location.

    PROTOTYPE     ... void mssetpos(int x, int y);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... mssettravel

    DESCRIPTION   ... Sets the mouse travel limits.

    PROTOTYPE     ... void mssettravel(int minx, int maxx,
                                           int miny, int maxy);

    ARGUMENTS     ... minx         - Minimum starting column.
                      maxx         - Maximum ending column.
                      miny         - Minimum starting row.
                      maxy         - Maximum ending row.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... msshow

    DESCRIPTION   ... Enables the mouse cursor, making it visible.

    PROTOTYPE     ... void msshow(void)

    ARGUMENTS     ... void

    RETURNS       ... void






    4.4  String functions:
    ----------------------



    ------------------------------------------------------------------------
    NAME         ... strchangechar

    DESCRIPTION  ... Finds all letters in a string matching one character
                     and replaces them with another, observing case when
                     replacing.

    PROTOTYPE    ... int  strchangechar(char *s, int a, int b);

    ARGUMENTS    ... s             - String to search.
                     a             - Char to search for.
                     b             - Char to replace with.

    RETURNS      ... The number of matches found.


    ------------------------------------------------------------------------
    NAME         ... strchangestr

    DESCRIPTION  ... Changes all occurrences of one string to another,
                     obsering case when replacing.

    PROTOTYPE    ... char *strchangestr(char *s, char *a, char *b);

    ARGUMENTS    ... s             -  String to search.
                     a             -  String to search for.
                     b             -  String to replace found strings.

    RETURNS      ... The address of the modified string, or NULL if no
                     matches were found.



    ------------------------------------------------------------------------
    NAME         ... strchecksum

    DESCRIPTION  ... Calculates the checksum of a string. The checksum is
                     calculated by adding up the ASCII values of each
                     character in the string.

    PROTOTYPE    ... unsigned long strchecksum(char *s);

    ARGUMENTS    ... s             -  String to checksum.

    RETURNS      ... The checksum of the input string.



    ------------------------------------------------------------------------
    NAME         ... strcode

    DESCRIPTION  ... Encodes/decodes a string. Call this function to encode
                     a string, then call again using the same key to decode
                     it.  When reading or writing from a disk file, be sure
                     to open the file in binary mode.


    PROTOTYPE    ... char *strcode(char *s, char *k);

    ARGUMENTS    ... s             -  String to encode/decode.
                     k             -  Key string.

    RETURNS      ... The address of the input string



    ------------------------------------------------------------------------
    NAME         ... strcountchar

    DESCRIPTION  ... Counts occurrences of a character in a string,
                     observing case of letters.

    PROTOTYPE    ... int  strcountchar(char *s, int c);

    ARGUMENTS    ... s             -  String to search.
                     c             -  Char to search for.

    RETURNS      ... The number of occurrences of the character in the
                     string.



    ------------------------------------------------------------------------
    NAME         ... strcountstr

    DESCRIPTION  ... Counts occurrences of one string within another,
                     observing case of letters.

    PROTOTYPE    ... int  strcountstr(char *a, char *s);

    ARGUMENTS    ... a             -  String to search for.
                     s             -  String to search.

    RETURNS      ... The number of times that string a occurs in
                     string s.


    ------------------------------------------------------------------------
    NAME         ... strcvt

    DESCRIPTION  ... Performs one or a number of conversions on a string,
                     according to the options provided. You can pass the
                     following pre-defined constants as the option
                     parameter and may OR them to perform multiple
                     operations.


    PROTOTYPE    ... char *strcvt(char *d, char *s, int option, int ml);

    ARGUMENTS    ... d             -  Destination string.
                     s             -  Source string.
                     option        -  Option required.
                                      NOBLANKS        - remove blanks
                                      NONONALPHA      - remove non
                                                        alphabetic chars
                                      NONONNUMERIC    - remove non numeric
                                                        chars
                                      NOLEADBLANKS    - remove leading
                                                        blanks
                                      NOTRAILBLANKS   - remove trailing
                                                        blanks
                                      NOALPHA         - remove alphabetic
                                                        chars
                                      NONUMERIC       - remove numeric chars
                                      NOPUNCT         - remove punctuation
                                      TOSINGLE        - convert multiple
                                                        blanks to single
                                      TOUPPER         - convert lower case
                                                        chars to upper
                                      TOLOWER         - convert upper case
                                                        chars to lower
                                      TOPROPER        - capitalize all words
                                      TOUNPROPER      - un - capitalize all
                                                        words
                                      TONOCR          - remove all CR's

                     ml            -  Maximum length of string.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.



    ------------------------------------------------------------------------
    NAME         ... strdelete

    DESCRIPTION  ... Deletes a substring from within a string, observing
                     case when deleting.

    RETURNS      ... char *strdelete(char *a, char *s);

    ARGUMENTS    ... a             -  Substring to delete.
                     s             -  String to delete from.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.




    ------------------------------------------------------------------------
    NAME         ... strdeleteall

    DESCRIPTION  ... Deletes all occurrences of a substring from within a
                     string, observing case of letters.

    PROTOTYPE    ... char *strdeleteall(char *a, char *s);

    ARGUMENTS    ... a             -  Substring to delete.
                     s             -  String to delete from.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.




    ------------------------------------------------------------------------
    NAME         ... strichangestr

    DESCRIPTION  ... Changes all occurrences of one string to another,
                     ignoreing case when replacing.

    PROTOTYPE    ... char *strichangestr(char *s, char *a, char *b);

    ARGUMENTS    ... s             -  String to search.
                     a             -  String to search for.
                     b             -  String to replace found strings.

    RETURNS      ... The address of the modified string, or NULL if no
                     matches were found.



    ------------------------------------------------------------------------
    NAME         ... strichecksum

    DESCRIPTION  ... Calculates the checksum of a string. The checksum is
                     calculated by adding up the ASCII values of each
                     character in the string, all lower-case letters will
                     be translated as upper-case.

    PROTOTYPE    ... unsigned long strichecksum(char *s);

    ARGUMENTS    ... s             -  String to checksum.

    RETURNS      ... The checksum of the input string.



    ------------------------------------------------------------------------
    NAME         ... stricountchar

    DESCRIPTION  ... Counts occurrences of a character in a string,
                     ignoring case of letters.

    PROTOTYPE    ... int  stricountchar(char *s, int c);

    ARGUMENTS    ... s             -  String to search.
                     c             -  Char to search for.

    RETURNS      ... The number of occurrences of the character in the
                     string.


    ------------------------------------------------------------------------
    NAME         ... stricountstr

    DESCRIPTION  ... Counts occurrences of one string within another,
                     ignoring case of letters.

    PROTOTYPE    ... int  stricountstr(char *a, char *s);

    ARGUMENTS    ... a             -  String to search for.
                     s             -  String to search.

    RETURNS      ... The number of times that string a occurs in
                     string s.


    ------------------------------------------------------------------------
    NAME         ... stridelete

    DESCRIPTION  ... Deletes a substring from within a string, ingoring
                     case when deleting.

    RETURNS      ... char *stridelete(char *a, char *s);

    ARGUMENTS    ... a             -  Substring to delete.
                     s             -  String to delete from.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.



    ------------------------------------------------------------------------
    NAME         ... strideleteall

    DESCRIPTION  ... Deletes all occurrences of a substring from within a
                     string, ignoring case of letters.

    PROTOTYPE    ... char *strideleteall(char *a, char *s);

    ARGUMENTS    ... a             -  Substring to delete.
                     s             -  String to delete from.

    RETURNS      ... Address of the modified string, or NULL if substring
                     not found.



    ------------------------------------------------------------------------
    NAME         ... striinc

    DESCRIPTION  ... Determines if and where one string is included within
                     another, ignoring case of letters.

    PROTOTYPE    ... char *striinc(char *a, char *s);

    ARGUMENTS    ... a             -  String to search for.
                     s             -  String to search.

    RETURNS      ... A pointer to the location in 's' that contains 'a',
                     or NULL if not found.


    ------------------------------------------------------------------------
    NAME         ... strinc

    DESCRIPTION  ... Determines if and where one string is included within
                     another, obseriving case of letters.

    PROTOTYPE    ... char *strinc(char *a, char *s);

    ARGUMENTS    ... a             -  String to search for.
                     s             -  String to search.

    RETURNS      ... A pointer to the location in 's' that contains 'a',
                     or NULL if not found.



    ------------------------------------------------------------------------
    NAME         ... strinsert

    DESCRIPTION  ... Inserts one string into another.

    PROTOTYPE    ... char *strinsert(char *a, char *s, int p);

    ARGUMENTS    ... a             -  String to insert.
                     s             -  String to receive insertion.
                     p             -  Starting position.

    RETURNS      ... The address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strisblank

    DESCRIPTION  ... Determines if a given string is blank (whitespace).

    PROTOTYPE    ... int  strisblank(char *s);

    ARGUMENTS    ... s             -  String to check.

    RETURNS      ... TRUE if string is blank, FALSE otherwise




    ------------------------------------------------------------------------
    NAME         ... strisrep

    DESCRIPTION  ... Searches for, and replaces one string within another,
                     ignoring case of letters.

    PROTOTYPE    ... char *strisrep(char *s, char *a, char *b);

    ARGUMENTS    ... s             -  String to search.
                     a             -  String to search for.
                     b             -  String to replace with.

    RETURNS      ... The address of the modified string, or NULL if the
                     search string wasn't found.


    ------------------------------------------------------------------------
    NAME         ... strleft

    DESCRIPTION  ... Create a new string from left or right by taking a
                     specified portion of a string from its left and
                     creates a new string.

    PROTOTYPE    ... char *strleft(char *s, int n);

    ARGUMENTS    ... s             -  String used for input.
                     n             -  Number of chars to copy.

    RETURNS      ... Address of the newly created string or a NULL if a
                     memory allocation error occurred.


    ------------------------------------------------------------------------
    NAME         ... strljust

    DESCRIPTION  ... Left justifies a string.

    PROTOTYPE    ... char *strljust(char *s);

    ARGUMENTS    ... s             -  String to justify.

    RETURNS      ... Address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strmiddle

    DESCRIPTION  ... Create a new string from part of an input string by
                     taking a section from input string starting at given
                     position and taking the given amount of characters
                     creating a new string.

    PROTOTYPE    ... char *strmiddle(char *s, int p, int n);

    ARGUMENTS    ... s             -  String used for input.
                     p             -  Position to start copying.
                     n             -  Number of chars to copy.

    RETURNS      ... Address of the newly created string or a NULL if a
                     memory allocation error occurred.



    ------------------------------------------------------------------------
    NAME         ... strresize

    DESCRIPTION  ... Adjusts the length of a string, either by truncation or
                     padding with spaces.

    PROTOTYPE    ... char *strresize(char *s, int n);

    ARGUMENTS    ... s             -  String use for input.
                     n             -  New length.

    RETURNS      ... Address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strright

    DESCRIPTION  ... Create a new string from left or right by takeing a
                     specified portion of a string from its right and
                     creates a new string.

    PROTOTYPE    ... char *strright(char *s, int n);

    ARGUMENTS    ... s             -  String used for input.
                     n             -  Number of chars to copy.

    RETURNS      ... Address of the newly created string or a NULL if a
                     memory allocation error occurred.


    ------------------------------------------------------------------------
    NAME         ... strrjust

    DESCRIPTION  ... Right justifies a string.

    PROTOTYPE    ... char *strrjust(char *s);

    ARGUMENTS    ... s             -  String to justify.

    RETURNS      ... Address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strrotleft

    DESCRIPTION  ... Rotates a string specified number of characters left.
                     The rotated characters wrap around to the opposite
                     side of the string.

    PROTOTYPE    ... char *strrotleft(char *s, int n);

    ARGUMENTS    ... s             -  String to rotate.
                     n             -  Count to rotate.

    RETURNS      ... Address of the modified string


    ------------------------------------------------------------------------
    NAME         ... strrotright

    DESCRIPTION  ... Rotates a string specified number of characters right.
                     The rotated characters wrap around to the opposite
                     side of the string.

    PROTOTYPE    ... char *strrotright(char *s, int n);

    ARGUMENTS    ... s             -  String to rotate
                     n             -  Count to rotate

    RETURNS      ... Address of the modified string.



    ------------------------------------------------------------------------
    NAME         ... strshiftleft

    DESCRIPTION  ... Shifts a string a specified number of characters left
                     Characters that shift past the beginning of the string
                     "drop off" and spaces are added to the right of the
                     string.

    PROTOTYPE    ... char *strshiftleft(char *s, int n);

    ARGUMENTS    ... s             -  String to shift.
                     n             -  Char count to shift.

    RETURNS      ... Address of the Modified string


    ------------------------------------------------------------------------
    NAME         ... strshiftright

    DESCRIPTION  ... Shifts a string a specified number of characters right
                     Characters that shift past the end of the string
                     "drop off" and spaces are added to the left of the
                     string.

    PROTOTYPE    ... char *strshiftright(char *s, int n);

    ARGUMENTS    ... s             -  String to shift.
                     n             -  Char count to shift.

    RETURNS      ... Address of the Modified string



    ------------------------------------------------------------------------
    NAME         ... strsrep

    DESCRIPTION  ... Searches for, and replaces one string within another,
                     observing case of letters.

    PROTOTYPE    ... char *strsrep(char *s, char *a, char *b);

    ARGUMENTS    ... s             -  String to search.
                     a             -  String to search for.
                     b             -  String to replace with.

    RETURNS      ... The address of the modified string, or NULL if the
                     search string wasn't found.




    ------------------------------------------------------------------------
    NAME         ... struplow

    DESCRIPTION  ... Converts a string to mixed upper & lowercase characters.
                     Characters are forced to upper or lowercase depending
                     upon the previous character in the string.

    PROTOTYPE    ... char *struplow(char *s);

    ARGUMENTS    ... s             -  String to convert

    RETURNS      ... Address of the modified string






    4.5  Miscellaneous functions:
    -----------------------------







    4.6  FOSSIL functions:
    ----------------------




    -------------------------------------------------------------------------
    NAME          ... finit

    DESCRIPTION   ... Function 0x00.   Initialise a port.

    PROTOTYPE     ... unsigned int finit(unsigned int p, unsigned int b);

    PARAMETERS    ... p            - Port number.
                      b            - The desired port parameters (see
                                     below)

                      Setting the Parameters
                      ----------------------
                      The 16 bit word is used to set the port's Data Width,
                      Stop Bits, Parity and Baud Rate.  (The number is the
                      the sum of all the  appropriate binary bits indicated
                      below.). Note that only the lower order of the word
                      is used.

                         Bits 0 and 1 set the data word width:
                              00 = 5 bits wide
                              01 = 6 bits wide
                              10 = 7 bits wide
                              11 = 8 bits wide

                         Bit 2 sets the number of stop bits:
                              00 = 1 stop bit
                              01 = 2 stop bits

                         Bits 3 and 4 set the port's parity:
                              00 = no parity
                              01 = odd parity
                              10 = even parity

                         Bits 5, 6, and 7 set the port's baud rate:
                              000 = 19200 baud    100 = 1200 baud
                              001 = 38400 baud    101 = 2400 baud
                              010 = 300   baud    110 = 4800 baud
                              011 = 600   baud    111 = 9600 baud


                    Graphically, the byte looks like this:

                    bits 7 6 5   4 3   2   1 0
                         | | |   | |   |   | |
                         | | |   | |   |    - ----  Data Word Width
                         | | |   | |    ----------  Stop Bits
                         | | |    - --------------  Parity
                          - - --------------------  Baud Rate


    RETURNS       ... unsigned     - Bit 0-7   - Modem status.
                                     Bit 7     - Will be set if there is
                                                 an error.
                                     Bit 8-15  - Port and line status.

                                     See also fstatus() function.


    -------------------------------------------------------------------------
    NAME          ... fputch

    DESCRIPTION   ... Function 0x01.   Outputs a single char to the port
                      It places the character into the FOSSIL's transmit
                      queue.  If there is no room in the transmit buffer,
                      this call will wait until there is.  It is
                      recommended that this call should either be avoided
                      (use fpoke instead) or be used when room in the
                      buffer is  guaranteed, since there is a risk of this
                      call "hanging" the machine waiting for the buffer to
                      make room, and there is no check for a 'stuck'
                      transmitter.  Use fstatus to determine if there is
                      room.


    PROTOTYPE     ... unsigned int fputch(unsigned int p, char c);

    PARAMETERS    ... p            - Port number.
                      c            - The char to be sent.

    RETURNS       ... unsigned     - Bit 6-0 - port status.
                                     Bit 7   - set on error.

                                     See fstatus() for more info.


    -------------------------------------------------------------------------
    NAME          ... fgetch

    DESCRIPTION   ... Function 0x02.   Reads a single char from the port.
                      If there is a character available in the receive
                      buffer, it returns with the next character. It will
                      wait until a character is received if none are
                      available.

    PROTOTYPE     ... unsigned int fgetch(unsigned int p);

    PARAMETERS    ... p            - Port number.

    RETURNS       ... unsigned     - The char received.



    -------------------------------------------------------------------------
    NAME          ... fstatus

    DESCRIPTION   ... Function 0x03.   Gets the port status. The function
                      returns with the line and modem status. The must be
                      initialised (see finit).  For the meanings of the bit
                      flags refer to the Rev 5 FOSSIL spec.

    PROTOTYPE     ... unsigned int fstatus(unsigned int p);

    PARAMETERS    ... p            - Port number.

    RETURNS       ... unsigned     - A 16 bit word holding the status of the
                                     port, refer to the table below.

                                     Bit 7  - data carrier detect.
                                     Bit 8  - input data is
                                              available in buffer.
                                     Bit 13 - room is available in
                                              output buffer.
                                     Bit 14 - output buffer is empty.




    -------------------------------------------------------------------------
    NAME          ... ffinit

    DESCRIPTION   ... Function 0x04.  Initialise a port for FOSSIL
                      (bufferred and interrupt  driven) processing.  If
                      'fb' is used (it points to a byte location), the value
                      at that memory location will be incremented once every
                      time a ^C is entered at the local keyboard. If the 'f'
                      parameter is left as zero, it will be ignored, else it
                      should be the memory address of a structure to return
                      the FOSSIL driver's revision number and maximum
                      function call number (useful for testing a minimum
                      standard - the maximum  function number of a FOSSIL
                      revision 5 compatible driver is 0x1B. This function
                      returns a value 0x1954 if a FOSSIL driver is installed.

    PROTOTYPE     ... unsigned int ffinit(unsigned int p, unsigned int *f,
                                          char far *fb);

    PARAMETERS    ... p            - Port number.
                      f            - Byte flag for
                      fb           - Byte to be set upon ^C.


    RETURNS       ... unsigned     - F_SIGNATURE (0x1954) if sucessfull.


    -------------------------------------------------------------------------
    NAME          ... ffdeinit

    DESCRIPTION   ... Function 0x05.   Deinitialises the fossil driver.
                      This should be called to deinitialise the communcations
                      port and disable interrupt processing on the port.
                      This would turn off hardware communications interrupts
                      and route all communcations calls to the usual BIOS.

    PROTOTYPE     ... void ffdeinit(unsigned int p);

    PARAMETERS    ... p            - Port number.

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... fdtr

    DESCRIPTION   ... Function 0x06.  Raises or lowers the DTR line of the
                      modem. Dropping DTR for a short period (say > .5 sec)
                      will normally force a modem to hang up.

    PROTOTYPE     ... void fdtr(unsigned int p, unsigned int d);

    PARAMETERS    ... p            - Port number.
                      d            -

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... ftickparms

    DESCRIPTION   ... Function 0x07.   Get the timer tick parameters.
                      This is used to determine the parameters of the timer
                      tick on any given machine.

    PROTOTYPE     ... unsigned int ftickparms(unsigned int *ms);

    PARAMETERS    ... ms           - An integer pointer that get set to the
                                     approximate number of milliseconds
                                     per tick.

    RETURNS       ... unsigned     - Ticks per second on interrupt number
                                     in the AL register.



    -------------------------------------------------------------------------
    NAME          ... fflushout

    DESCRIPTION   ... Function 0x08.   Flush the output buffer and wait
                      until the entire output is empty. On return, the
                      transmit buffer is guaranteed to be empty.

    PROTOTYPE     ... void fflushout(unsigned int p);

    PARAMETERS    ... p            - Port number.

    RETURNS       ... void


    -------------------------------------------------------------------------
    NAME          ... fpurgeout

    DESCRIPTION   ... Function 0x09.   Purge the output buffer and throw
                      away all pending output.

    PROTOTYPE     ... void fpurgeout(unsigned int p);

    PARAMETERS    ... p            - Port number.

    RETURNS       ... void


    -------------------------------------------------------------------------
    NAME          ... fpurgein

    DESCRIPTION   ... Function 0x0A.   Purge the input buffer and throw
                      away all pending input.

    PROTOTYPE     ... void fpurgein(unsigned int p);

    PARAMETERS    ... p            - Port number.

    RETURNS       ... void


    -------------------------------------------------------------------------
    NAME          ... fpoke

    DESCRIPTION   ... Function 0x0B.   Send a char to a port without wait.
                      This call does not wait if there is no room available.

    PROTOTYPE     ... unsigned int fpoke(unsigned int p, char c);

    PARAMETERS    ... p            - Port number.
                      c            - The char to send.

    RETURNS       ... unsigned     - 0x00  - Char not accepted.
                                     0x01  - Char accepted.


    -------------------------------------------------------------------------
    NAME          ... fpeek

    DESCRIPTION   ... Function 0x0C.   Non-destructively reads a char from
                      the port. This does not take the received character out
                      of the buffer, and will be returned again by executing
                      fgetch.


    PROTOTYPE     ... unsigned int fpeek(unsigned int p);

    PARAMETERS    ... p            - Port number.

    RETURNS       ... unsigned     - The available char.
                                     F_NULL - If no char available.



    -------------------------------------------------------------------------
    NAME          ... fkbdpeek

    DESCRIPTION   ... Function 0x0D.   Non-destructively reads a char from
                      the keyboard without wait. This call does not flush
                      the key, which will be available again by calling
                      fkbdgetch.

    PROTOTYPE     ... unsigned int fkbdpeek(void);

    PARAMETERS    ... void

    RETURNS       ... unsigned     - A standard IBM scan code interpretation
                                     of the char read.

                                     F_NULL - If no char available.



    -------------------------------------------------------------------------
    NAME          ... fkbdgetch

    DESCRIPTION   ... Function 0x0E.   Get a character from the keyboard.
                      If one is not available, it waits until a key has been
                      hit.

    PROTOTYPE     ... unsigned int fkbdgetch(void);

    PARAMETERS    ... void

    RETURNS       ... unsigned     - A standard IBM scan code interpretation
                                     of the char read.

                                     F_NULL  - If no char available.


    -------------------------------------------------------------------------
    NAME          ... fflow

    DESCRIPTION   ... Function 0x0F.   Enable or disbale flow control,
                      allowing you to switch off and on XON/XOFF (or ^S/^Q)
                      and CTS/RTS handshaking.  If running a high speed modem
                      with the FOSSIL driver 'locked' at a particular baud
                      rate, you may find that CTS/RTS handshaking cannot be
                      controlled since this is automatically provided in
                      these circumstances. An additional flag (see FOSSIL
                      spec) allows finer control over the FOSSIL's
                      transmitter.

    PROTOTYPE     ... void fflow(unsigned int p, unsigned char m);

    PARAMETERS    ... p            - Port number.
                      m            - Bit mask describing flow control.

                                     0     - XON/XOFF on transmitt (watch
                                             for XOFF while sending).
                                     1     - CTS/RTS
                                     3     - XON/XOFF on receive (send XOFF
                                             when buffer is near full).
                                     4-7   - All 1.

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... fcontrol

    DESCRIPTION   ... Function 0x10.   Enable or Disable extended ^C or ^K
                      checking (from remote).  If enabled, the FOSSIL
                      automatically makes ^C and ^K 'transparent' from the
                      remote (as are flow control XON and XOFFs), but
                      instead sets the flag returned by this call.


    PROTOTYPE     ... unsigned int fcontrol(unsigned int p, unsigned char m);

    PARAMETERS    ... p            - Port number.
                      m            - Bit mask for control.
                                     0x00  - Enable/disable ^C && ^K
                                             checking.
                                     0x01  - Enable/disable the transmitter.

    RETURNS       ... unsigned     - ???????????????????



    -------------------------------------------------------------------------
    NAME          ... fgotoxy

    DESCRIPTION   ... Function 0x11.   Sets the cursor at a specific
                      location.

    PROTOTYPE     ... void fgotoxy(unsigned int x, unsigned int y);

    PARAMETERS    ... x            - Starting column.
                      y            - Starting row.

    RETURNS       ... void




    -------------------------------------------------------------------------
    NAME          ... fwherexy

    DESCRIPTION   ... Function 0x12.   Gets the current cursor location.

    PROTOTYPE     ... unsigned int fwherexy(unsigned int *x,
                                            unsigned int *y);

    PARAMETERS    ... x            - Starting column.
                      y            - Starting row.

    RETURNS       ... unsigned     - ??????????????????????????




    -------------------------------------------------------------------------
    NAME          ... fdispansi

    DESCRIPTION   ... Function 0x13.   Writes a single char via ANSI to the
                      console.

    PROTOTYPE     ... void fdispansi(char c);

    PARAMETERS    ... c            - The char to write.

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... fwatchdog

    DESCRIPTION   ... Function 0x14.  Enable/Disable watchdog carrier
                      processing.

    PROTOTYPE     ... void fwatchdog(unsigned int p, int f);

    PARAMETERS    ... p            - Port number.
                      f            - Processing mode
                                     0x00  - Disable
                                     0x01  - Enable
    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... fdispbios

    DESCRIPTION   ... Function 0x15.  Write a char to the console using
                      existing BIOS support routines.

    PROTOTYPE     ... void fdispbios(char c);

    PARAMETERS    ... c            - The char to write.

    RETURNS       ... void




    -------------------------------------------------------------------------
    NAME          ... ftickchain

    DESCRIPTION   ... Function 0x16. Inserts/deletes a specified function
                      to/from a the timer tick chain.

    PROTOTYPE     ... unsigned int ftickchain(int a, void (far *func)());

    PARAMETERS    ... a            - Insert/Delete mode.
                                           0x00   - Delete.
                                           0x01   - Add.
                      func         - Address of function to insert/delete.

    RETURNS       ... unsigned     - 0x00   - Successful.
                                     0x01   - Unsuccessful.



    -------------------------------------------------------------------------
    NAME          ... freboot

    DESCRIPTION   ... Function 0x17. Reboots the system.

    PROTOTYPE     ... void freboot(unsigned int w);

    PARAMETERS    ... w            - Mode for bootstrap.
                                     0x00  - Cold boot.
                                     0x01  - Warm boot.

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... fgetblk

    DESCRIPTION   ... Function 0x18. Reads a block of data from the port.
                      This call attempts to receive 'z' number of bytes from
                      port 'p' to the address 'buf'; it returns the number of
                      bytes actually received, which can be zero (if not is
                      available). Using this method is much faster than
                      individual calls to fgetch and is preferred in high
                      speed communications or intense activity (such as
                      during file transfers).

    PROTOTYPE     ... unsigned int fgetblk(unsigned int p, void far *buf,
                                           unsigned int z);

    PARAMETERS    ... p            - Port number.
                      buf          - Buffer for received chars.
                      z            - Maximum number of chars to transfer
                                     to buffer.

    RETURNS       ... unsigned     - The number of chars transferred.



    -------------------------------------------------------------------------
    NAME          ... fputblk

    DESCRIPTION   ... Function 0x19. Writes a block of data to the port.
                      Since the FOSSIL's transmit buffer may not have
                      sufficient room, transmission of the complete block is
                      never guaranteed.  This call has significantly less
                      overhead than calling fputch a number of times, and
                      should be used in preference at least in high speed
                      situations or at peariods of intense activity (such
                      as file transfers).

    PROTOTYPE     ... unsigned int fputblk (unsigned int p, void far *buf,
                                            unsigned int z);

    PARAMETERS    ... p            - Port number.
                      buf          - Buffer to be transfered.
                      z            - Maximum number of chars to transfer
                                     from buffer.

    RETURNS       ... unsigned     - The number of chars transferred.



    -------------------------------------------------------------------------
    NAME          ... fbreak

    DESCRIPTION   ... Function 0x1A. Begin/End sending a break signal.
                      This function sets  (transmits) or resets the break
                      signal line in the modems signal.  This signal is
                      often used for special processing or override
                      signalling between local and remote systems.

    PROTOTYPE     ... void fbreak(unsigned int p, unsigned int f);

    PARAMETERS    ... p            - Port number.
                      f            - Mode of break signal.
                                     0x00  - Stop sending break.
                                     0x01  - Begin sending break.

    RETURNS       ... void


    -------------------------------------------------------------------------
    NAME          ... finfo

    DESCRIPTION   ... Function 0x1B. Gets information about the fossil
                      driver.

    PROTOTYPE     ... unsigned int finfo(unsigned int p, void far *buf,
                                         unsigned int z);

    PARAMETERS    ... p            - Port number.
                      buf          - The user buffer to which the
                                     information will be transferred to.
                                     See table below for buffer format.

                           Format of driver info
                           ---------------------

                           Offs    Size   Description
                           ----    ----   -----------------------
                           0x00    WORD   size of structure in bytes.
                           0x02    BYTE   FOSSIL spec conformance.
                           0x03    BYTE   revision of driver
                           0x04    DWORD  pointer to ID string.
                           0x08    WORD   size of input buffer.
                           0x0A    WORD   bytes left in input buffer.
                           0x0C    WORD   size of output buffer.
                           0x0E    WORD   bytes left in output buffer.
                           0x10    BYTE   width of screen.
                           0x11    BYTE   length of screen.
                           0x12    BYTE   computer to modem baud rate.

                      z            - Size of user buffer.

    RETURNS       ... unsigned     - The number of chars transferred.


    -------------------------------------------------------------------------
    NAME          ... faddapp


    PROTOTYPE     ... unsigned int faddapp(unsigned int p, unsigned int *c,
                                           void (far *func)());

    PARAMETERS    ... p            - Port number.
                      c            -
                      func         -

    RETURNS       ... unsigned     -


    -------------------------------------------------------------------------
    NAME          ... fdelapp

    DESCRIPTION   ... Function 0x1D. Removes a multiplex appendage to the
                      FOSSIL, this should be used in conjunction with the
                      faddapp function.

    PROTOTYPE     ... unsigned int fdelapp(unsigned int p, unsigned int *c,
                                           void (far *func)());

    PARAMETERS    ... p            - Port number.
                      c            -
                      func         -

    RETURNS       ... unsigned     -






    5.  High level functions:
    -------------------------

        The high level functions are mainly window functions and internally
        use the low level functions functions.




    5.1  Window functions:
    ----------------------


    ------------------------------------------------------------------------
    NAME          ... Wclear

    DESCRIPTION   ... Clears the contents of a window.

    PROTOTYPE     ... void Wclear(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void





    ------------------------------------------------------------------------
    NAME          ... Wcursor

    DESCRIPTION   ... Sets a windows cursor

    PROTOTYPE     ... void Wcursor(WINDOW *wnd, int x, int y)

    ARGUMENTS     ... wnd          - Window handle.
                      x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Wdeleteall

    DESCRIPTION   ... Closes all the windows by recursively calling the
                      Wdelete function. Use this with caution as it will
                      every window you have open.

    PROTOTYPE     ... void Wdeletall(void)

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Wdelete

    DESCRIPTION   ... Deletes a window and frees all the memory that it
                      initially allocated.

    PROTOTYPE     ... void Wdelete(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void




    -------------------------------------------------------------------------
    NAME          ... Westablish

    DESCRIPTION   ... Creats a new window.

    PROTOTYPE     ... WINDOW *Westablish (x int, y int, h int, w int)

    PARAMETERS    ... x            - The starting column of the window.
                      y            - The starting row of the box.
                      h            - The height of the window.
                      w            - The width of the window.

    RETURNS       ... A pointer to the new created window. It will return
                      NULL if memory allocation fails.




    ------------------------------------------------------------------------
    NAME          ... Wforefront

    DESCRIPTION   ... This will re position the window so that it is in
                      front of all the other windows.

    PROTOTYPE     ... #define Wforefront(wnd)

    ARGUMENTS     ... wnd          - The window handle.



    ------------------------------------------------------------------------
    NAME          ... Wgetsel

    DESCRIPTION   ... Allows the user to make a window selection.

    PROTOTYPE     ... int Wgetsel(WINDOW *wnd, int s, char *keys)

    ARGUMENTS     ... wnd          - Window handle.
                      s            - Selection.
                      keys         - A pointer to a string whoose charcaters
                                     are valid keystrokes

    RETURNS       ... The key pressed.




    ------------------------------------------------------------------------
    NAME          ... Whide

    DESCRIPTION   ... Hides a window, this only makes it invisible so it
                      can be restored.

    PROTOTYPE     ... void Whide(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wmove

    DESCRIPTION   ... Moves a window and its contents.

    PROTOTYPE     ... #define Wmove(wnd,x,y)

    ARGUMENTS     ... wnd          - Window handle.
                      x            - The starting column.
                      y            - The starting row.



    ------------------------------------------------------------------------
    NAME          ... Wprintf

    DESCRIPTION   ... Writes a formatted variable argument to a window,
                      as with the printf function.

    PROTOTYPE     ... void Wprintf(WINDOW *wnd, char *ln, ...)

    ARGUMENTS     ... wnd          - Window handle.
                      ln           - The formatted line to write.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wprompt

    DESCRIPTION   ... Display a window prompt.

    PROTOTYPE     ... void Wprompt(WINDOW *wnd, int x, int y, char *s)

    ARGUMENTS     ... wnd          - Window handle.
                      x            - The starting column.
                      y            - The starting row.
                      s            - The prompt string.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Wputch

    DESCRIPTION   ... Outputs a character to a window, using the WIN_FACE
                      attributes.

    PROTOTYPE     ... void Wputch(WINDOW *wnd, int c)

    ARGUMENTS     ... wnd          - Window handle.
                      c            - The character to write.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Wputchat

    DESCRIPTION   ... Outputs a character and attribute to a window.

    PROTOTYPE     ... void Wputchar(WINDOW *wnd, int c, int bg, int fg,
                                    int i)

    ARGUMENTS     ... wnd          - Window handle.
                      c            - The character to write.
                      bg           - Background colour.
                      fg           - Foreground colour.
                      i            - Intensity (BRIGHT || DIM).

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Wrear

    DESCRIPTION   ... This will reposition a window so that it is the
                      very last window on the screen.

    PROTOTYPE     ... #define Wrear(wnd)

    ARGUMENTS     ... wnd          - Window handle.




    ------------------------------------------------------------------------
    NAME          ... Wresetvideo

    DESCRIPTION   ... Normalises the video attributes for a given window.
                      This would set the attributes to the default state.

    PROTOTYPE     ... #define Wresetvideo(wnd)

    ARGUMENTS     ... wnd          - Window handle.



    ------------------------------------------------------------------------
    NAME          ... Wrevvideo

    DESCRIPTION   ... Reverses the video attributes for a given window.

    PROTOTYPE     ... #define Wrevvideo(wnd)

    ARGUMENTS     ... wnd          - Window handle.



    ------------------------------------------------------------------------
    NAME          ... Wrmove

    DESCRIPTION   ... Moves a window and its contents, this is different to
                      the Wmove macro in that it will move a window and
                      remember which other windows are behind or in front of
                      it. It will move behind if it is not the active window.

    PROTOTYPE     ... #define Wrmove(wnd,x,y)

    ARGUMENTS     ... wnd          - Window handle.
                      x            - The starting column.
                      y            - The starting row.




    -------------------------------------------------------------------------
    NAME          ... Wsetborder

    DESCRIPTION   ... Sets a windows border to particular format.

    PROTOTYPE     ... void Wsetborder(WINDOW *wnd, int btype)

    ARGUMENTS     ... wnd          - Window handle.
                      btype        - Sets the border styles,

                                     BRD_SPACE      - spaces                                       /* single line */
                                     BRD_SINGLE     - single line
                                     BRD_DOUBLE     - double line
                                     BRD_DOUBLESIDE - double sides & sngl top
                                     BRD_DOUBLETOP  - double top & sngl sides
                                     BRD_SINGLESIDE - ditto
                                     BRD_SINGLETOP  - ditto
                                     BRD_NOBORDER   - no borders

    RETURNS       ... void




    -------------------------------------------------------------------------
    NAME          ... Wsetcolour

    DESCRIPTION   ... Sets up the colors for a given window. If the video
                      adaptor is monochrome then the function uses its
                      default attributes (BLACK and WHITE) and returns.
                      You may also use the predifined constant BLINK to
                      add blinking attribute to any of the colours.
                      Eg   RED+BLINK.

    PROTOTYPE     ... void Wsetcolour (WINDOW *wnd, int area,
                                       int bg, int fg, int inten);

    PARAMETERS    ... wnd          - Pointer to the slected window.
                      area         - The area to repaint.

                                     WIN_BORDER  - border or frame
                                     WIN_TITLE   - title area
                                     WIN_ACCENT  - accent, highlight bar
                                     WIN_FACE    - window face
                                     WIN_FLDFACE - window field face
                                     WIN_ALL     - all above components

                      bg           - Back ground attribute.
                      fg           - Fore ground attribute.
                      inten        - Intensity.
                                     BRIGHT      - high intensity
                                     DIM         - low intensity

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wsetintensity

    DESCRIPTION   ... Sets the intensity of a given window.

    PROTOTYPE     ... void Wsetintensity(WINDOW *wnd, int inten)

    ARGUMENTS     ... wnd          - Window handle.
                      inten        - The intensity to set to.
                                     BRIGHT      - high intensity
                                     DIM         - low intensity

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wsettitle

    DESCRIPTION   ... Sets the title of a window.

    PROTOTYPE     ... void Wsettitle(WINDOW *wnd, char *title, int just)

    ARGUMENTS     ... wnd          - Window handle.
                      title        - Pointer to the string containing the
                                     title.
                      just         - The justification of the title.
                                     JUST_C     - centre justify
                                     JUST_L     - left justify
                                     JUST_R     - right justify

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Wshow

    DESCRIPTION   ... Displays a window. The window must have already been
                      established using Westablish.

    PROTOTYPE     ... void Wshow(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void








    5.2  Menu functions:
    --------------------



    -------------------------------------------------------------------------
    NAME          ... Minit

    DESCRIPTION   ... This function sets all the configuration variables in
                      a pulldown menu to the default state. The colours are
                      all set to monochrome (BLACK and WHITE) , the title
                      string is NULL and the border is BRD_SINGLE. The
                      functions  Msetborder(), Msettitle() and Msetcolour()
                      can be  called to change the style.

    PROTOTYPE     ... void Minit (void);

    PARAMETERS    ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Mselect

    DESCRIPTION   ... Opens and executes a pull-down type menu.
                      See the SSTWIN.H file for structure components.

    PROTOTYPE     ... void Mselect(MENU *mn, int h)

    ARGUMENTS     ... mn           - Pointer to the menu structure.
                      h            - If menu should hide prior to calling
                                     selected function.
                                     TRUE   - Hide
                                     FALSE  - Leave as is
    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Msetborder

    DESCRIPTION   ... Sets up the border style for the current pull-down
                      menu.

    PROTOTYPE     ... void Msetborder (int btype);

    PARAMETERS    ... btype        - The border style.
                                     BRD_SPACE      - spaces                                       /* single line */
                                     BRD_SINGLE     - single line
                                     BRD_DOUBLE     - double line
                                     BRD_DOUBLESIDE - double sides & sngl top
                                     BRD_DOUBLETOP  - double top & sngl sides
                                     BRD_SINGLESIDE - ditto
                                     BRD_SINGLETOP  - ditto
                                     BRD_NOBORDER   - no borders

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Msetcolour

    DESCRIPTION   ... Sets up the colors for the current pull-down menu.
                      If the adaptor is monochrome then the function uses
                      its default attributes (BLACK and WHITE) and ignore
                      the parameters you have passed.

    PROTOTYPE     ... void Msetcolour (int area, int bg, int fg,
                                       int inten);

                      area         - The area to repaint.

                                     WIN_BORDER  - border or frame
                                     WIN_TITLE   - title area
                                     WIN_ACCENT  - accent, highlight bar
                                     WIN_FACE    - window face
                                     WIN_FLDFACE - window field face
                                     WIN_ALL     - all above components

                      bg           - Back ground attribute.
                      fg           - Fore ground attribute.
                      inten        - Intensity.
                                     BRIGHT      - high intensity
                                     DIM         - low intensity

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Msetfullwidth

    DESCRIPTION   ... Forces the pull-down menu to use the entire width of
                      the screen, or a calculated minimum width.

    PROTOTYPE     ... void Msetfullwidth(int f);

    PARAMETERS    ... f            -  FALSE   - Use calculated screen width
                                      TRUE    - Use full screen width.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Msettitle

    DESCRIPTION   ... Sets the title for the current pull-down menu.

    PROTOTYPE     ... void Msettitle (char *title, int just);

    ARGUMENTS     ... title        - Pointer to the string containing the
                                     title.
                      just         - The justification of the title.
                                     JUST_C     - centre justify
                                     JUST_L     - left justify
                                     JUST_R     - right justify

    RETURNS       ... void






    5.3  Data entry functions:
    --------------------------



    ------------------------------------------------------------------------
    NAME          ... Fcleartemplate

    DESCRIPTION   ... Clears a template to all blanks, see also
                      Fnulltemplate.

    PROTOTYPE     ... void Fcleartemplate(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Fdataentry

    DESCRIPTION   ... Process data entry for a screen template.

    PROTOTYPE     ... int Fdataentry(WINDOW *wnd, int p)

    ARGUMENTS     ... wnd          - Window handle.
                      p            - TRUE  - process all keystrokes. Ret
                                             PgUp, PgDown, Home , End etc.
                                     FASLE - preserve PgUp, PgDown, Home,
                                             End for internal use.

    RETURNS       ... The last keyboard keystroke.


    ------------------------------------------------------------------------
    NAME          ... Fdataview

    DESCRIPTION   ... Displays the data entry for a screen template.
                      This will not allow any editing and the cursor is
                      invisible inside this function.

    PROTOTYPE     ... int Fdataview(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... The last keyboard keystroke.


    ------------------------------------------------------------------------
    NAME          ... Fendfunc

    DESCRIPTION   ... This is a powerfull feature in field editing. This
                      function will allow you to specify a new function
                      that will determine which keys are valid for exiting
                      field edit sessions. The function must be set prior
                      to the Fdataentry function. For a sample take a look
                      at the default_endstroke function in sstfield.c .

    PROTOTYPE     ... void  Fendfunc(int (*func) (int));

    ARGUMENTS     ... func         - Pointer to the new function to be
                                     used. If NULL it will use the
                                     default function.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Ferrorfunc

    DESCRIPTION   ... This is a powerfull feature in field editing. During
                      each keypress inside a field, the char entered is
                      checked for validation. If the key pressed is invalid
                      then the function specified is called. There are
                      certain rules that should be followed. During each
                      invalid key pressed a string of the error
                      interpreation is passed to the function. For each
                      corrective action and valid keystroke a NULL is
                      passed to the function. Upon initialisation a built
                      in function is used that pops a small window to alert
                      the user, and the windows disappears during the
                      corrective action.


    PROTOTYPE     ... void  Ferrorfunc(int (*func) (char *s));

    ARGUMENTS     ... func         - Pointer to the new function to be
                                     used. If NULL it will use the
                                     default function.
                      s            - The string interpreation for the
                                     error created.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Festablish

    DESCRIPTION   ... Establishes a field in a window template. This
                      function is used in making a window a field template.
                      You need to pass it parameters for its location,
                      the field mask, the edit buffer, and the field types
                      etc.  The display mask is a string enclosed in double
                      quotes and is used in defining an input field for the
                      particular data element. The underscore character
                      represents character positions in the mask.
                      Punctuation characters may be inserted anywhere in the
                      mask string. The number of underscore characters must
                      be atleast the length of the data element, but may be
                      more.

    PROTOTYPE     ... FIELD *Festablish(WINDOW *wnd, int cl, int rw,
                                        char *msk, char *bf, int ty,
                                        int fcnv)

    ARGUMENTS     ... wnd          - Window handle.
                      cl           - The starting column of the field.
                      rw           - The starting row of the field.
                      msk          - The field input mask string. eg

                                     "__/__/__"       - sample date mask.
                                     "(___)____-__"   - sample phone with
                                                        area code mask.
                                     "$___.__"        - sample currency mask.

                      bf           - The buffer that is updated upon
                                     editing.
                      ty           - The field type,
                                     FLD_ALNUM    - alpha & numeric &
                                                    space
                                     FLD_ALPHA    - alpha & space
                                     FLD_DIGIT    - digit only
                                     FLD_ASCII    - ascii char only
                                     FLD_PRINT    - printable character
                                     FLD_XDIGIT   - hexadecimal char
                                     FLD_DATE     - date fromat char
                                     FLD_INT      - integer
                                     FLD_CURR     - currency format

                      fcnv         - The field conversion flags.

                                     FLD_LJUST    - left justify field
                                     FLD_RJUST    - right justify field
                                     FLD_TOUPPER  - convert to upper case
                                     FLD_TOLOWER  - convert to lower case
                                     FLD_TOPROPER - convert to Proper case
                                     FLD_ZFILL    - zero fill blanks


    RETURNS       ... Pointer to the new created field. The function may
                      also return NULL if no memory could be allocated to
                      the field.



    ------------------------------------------------------------------------
    NAME          ... Finittemplate

    DESCRIPTION   ... Initialises all the variables needed to create an
                      entry template. The window must have already been
                      established to call this function. This function
                      also frees any memory used by the fields, so may
                      be called after the editing session prior to
                      deleting the window.

    PROTOTYPE     ... void Finittemplate(WINDOW *wnd);

    ARGUMENTS     ... wnd          - Window handle;

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Fnulltemplate

    DESCRIPTION   ... Clears a template to all NULL chars, see also
                      Fcleartemplate.

    PROTOTYPE     ... void Fnulltemplate(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void



    ------------------------------------------------------------------------
    NAME          ... Fprevalidate

    DESCRIPTION   ... Assigns a validation function to a particular field.
                      The function would be called upon each keypress while
                      still editing a field. This is usefull in converting
                      or translating each key that is pressed.

    PROTOTYPE     ... #define Fprevalidate(f,v) f->fvalid=v

    ARGUMENTS     ... f            - Pointer to the field structure.
                  ... v            - Pointer to the function to be used for
                                     validation.



    ------------------------------------------------------------------------
    NAME          ... Fprotect

    DESCRIPTION   ... Protects a field by not allowing the user to edit
                      it. It is still displayed etc, but is skipped.

    PROTOTYPE     ... #define Fprotect(f,s)  f->fprot=s

    ARGUMENTS     ... f            - Pointer to the field.
                      s            - TRUE  - Protect.
                                     FALSE - Unprotect.




    ------------------------------------------------------------------------
    NAME          ... Fpostvalidate

    DESCRIPTION   ... Assigns a validation function to a particular field.
                      The function would be called when the editing of the
                      field is completed.

    PROTOTYPE     ... #define Fpostvalidate(f,v) f->fvalid=v

    ARGUMENTS     ... f            - Pointer to the field structure.
                  ... v            - Pointer to the function to be used for
                                     validation.



    ------------------------------------------------------------------------
    NAME          ... Fhelpfunc

    DESCRIPTION   ... Assigns a new help function to the specified field.
                      A help function may be diplayed for the particular
                      field upon pressing the help key (usually F1) or
                      instantly as soon as the field is selected,
                      see the argument "w" for more details.


    PROTOTYPE     ... void Fhelpfunc(FIELD *f, void (*h)(char *), int w);

    ARGUMENTS     ... f            - Pointer to the field.
                      h            - Pointer to the help function.
                      w            - Field help type.
                                     HELP_KEYED   - when help key pressed
                                     HELP_INITIAL - when initially on field
                                     HELP_ALWAYS  - when always on field
                                     HELP_DONE    - set as completed help



    ------------------------------------------------------------------------
    NAME          ... Fsethelpwin

    DESCRIPTION   ... Set a field's help window.

    PROTOTYPE     ... void Fsethelpwin(FIELD *fld, char *hwin, int x, int y)

    ARGUMENTS     ... fld          - Pointer to the field structure.
                      hwin         - Help tag string.
                      x            - The starting column.
                      y            - The starting row.

    RETURNS       ... void




    ------------------------------------------------------------------------
    NAME          ... Ftally

    DESCRIPTION   ... Displays all the fields in a window.

    PROTOTYPE     ... void Ftally(WINDOW *wnd)

    ARGUMENTS     ... wnd          - Window handle.

    RETURNS       ... void








    5.4  Editor functions:
    ----------------------


    ------------------------------------------------------------------------
    NAME          ... Eopen

    DESCRIPTION   ... Opens a text editing window. The window must first be
                      created using the Westablish function, and its
                      characteristics may be set eg (title and colours).
                      The window is to be displayed using the Wshow
                      function then you can call the Eopen function.
                      See sec 2.4 for the editing commands.

    PROTOTYPE     ... void Eopen(WINDOW *wnd, char *bf, int bsize)

    ARGUMENTS     ... wnd          - Window handle.
                      bf           - Pointer to the text buffer.
                      bsize        - The size of the text buffer.

    RETURNS       ... void





    5.5  Help system functions:
    ---------------------------



    ------------------------------------------------------------------------
    NAME          ... Hload

    DESCRIPTION   ... Loads a help definition file. If the help file is
                      unable to be opened for some reason the function
                      returns.

    PROTOTYPE     ... void Hload(char *hn)

    ARGUMENTS     ... hn           - The name of the help file including
                                     full path.

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Hset

    DESCRIPTION   ... Sets a particular help screen to be current and
                      active.

    PROTOTYPE     ... void Hset(char *s, int x, int y)

    ARGUMENTS     ... s            - The help title tag.
                      x            - Starting column of the help screen.
                      y            - Starting row of the help screen.

    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Hsetborder

    DESCRIPTION   ... Sets a help windows border to a particular format.

    PROTOTYPE     ... void Hsetborder(int btype)

    ARGUMENTS     ... btype        - Sets the border styles
                                     BRD_SPACE      - spaces                                       /* single line */
                                     BRD_SINGLE     - single line
                                     BRD_DOUBLE     - double line
                                     BRD_DOUBLESIDE - double sides & sngl top
                                     BRD_DOUBLETOP  - double top & sngl sides
                                     BRD_SINGLESIDE - ditto
                                     BRD_SINGLETOP  - ditto
                                     BRD_NOBORDER   - no borders

    RETURNS       ... void





    -------------------------------------------------------------------------
    NAME          ... Hsetcolour

    DESCRIPTION   ... Sets up the colors for a help window.

    PROTOTYPE     ... void Hsetcolour (int area, int bg, int fg, int inten);

    PARAMETERS    ... area         - The area to repaint.

                                     WIN_BORDER  - border or frame
                                     WIN_TITLE   - title area
                                     WIN_ACCENT  - accent, highlight bar
                                     WIN_FACE    - window face
                                     WIN_FLDFACE - window field face
                                     WIN_ALL     - all above components

                      bg           - Back ground attribute.
                      fg           - Fore ground attribute.
                      inten        - Intensity.
                                     BRIGHT      - high intensity
                                     DIM         - low intensity
    RETURNS       ... void



    -------------------------------------------------------------------------
    NAME          ... Msetspace

    DESCRIPTION   ... Sets the spacing between items on the menu. This is
                      usefull in streching out the menu to fit into a screen
                      when there isnt enough items etc. The spacing area
                      parameter is bitwise so you may pass
                      SPC_LEFT | SPC_RIGHT etc.

    PROTOTYPE     ... void Msetspace(int sp, int a)

    PARAMETERS    ... sp           - The number of space chars to use for
                                     spacing.
                      a            - The portion of the menu that will be
                                     used for spacing.

                                     SPC_BETWEEN  - spacing between items
                                     SPC_LEFT     - left most end of menu
                                     SPC_RIGHT    - right most end of menu

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Hsettitle

    DESCRIPTION   ... Sets the title of a help window.

    PROTOTYPE     ... void Hsettitle(char *t, int j)

    ARGUMENTS     ... t            - Pointer to the string containing the
                                     title.
                      j            - The justification of the title.
                                     JUST_C     - centre justify
                                     JUST_L     - left justify
                                     JUST_R     - right justify

    RETURNS       ... void





    5.6  Selection system functions:
    --------------------------------



    ------------------------------------------------------------------------
    NAME          ... Sdelete

    DESCRIPTION   ... This function frees all the memory used by the linked
                      list in the selection system. Call this when the
                      selection has been made.

    PROTOTYPE     ... void Sdelete(void)

    ARGUMENTS     ... void

    RETURNS       ... void


    ------------------------------------------------------------------------
    NAME          ... Sforeach

    DESCRIPTION   ... Calls a specific function for each of the tagged
                      selection list elements.

    PROTOTYPE     ... void Sforeach(void (*func) (char *s));

    ARGUMENTS     ... func         - Pointer to the function to be called.

    RETURNS       ... void




    -------------------------------------------------------------------------
    NAME          ... Sinsert

    DESCRIPTION   ... Inserts a string into the selection record. This is
                      used in establishing a linked list fro the selection
                      system.

    PROTOTYPE     ... SelREC *Sinsert(char *s);

    ARGUMENTS     ... s            - Pointer to string to be inserted.

    RETURNS       ... Pointer to the selection record.




    -------------------------------------------------------------------------
    NAME          ... Sselonestr

    DESCRIPTION   ... Opens the selection system and prompts the user for
                      a selection of one item only, ie no tagging.

    PROTOTYPE     ... char *Sselonestr(int x, int y, int t);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.
                      t            - The number of rows to show in the
                                     window.

    RETURNS       ... Pointer to the selection item in the record or NULL
                      if ESC was pressed.



    -------------------------------------------------------------------------
    NAME          ... Sselstr

    DESCRIPTION   ... Opens the selection system and prompts the user for
                      a selection of multiple items, ie tagging by using
                      the space key.

    PROTOTYPE     ... int Sselstr(int x, int y, int t);

    ARGUMENTS     ... x            - The starting column.
                      y            - The starting row.
                      t            - The number of rows to show in the
                                     window.

    RETURNS       ... The last key pressed.
                      The function Sforeach should be called in extracting
                      the selected items.




