

                                  TPFAST  4.0
                                  -----------


                         'FAST Turbo Pascal library'

                CopyRight (c) 1989,1990,1991    Steven Lutrov

    


                                   CONTENTS


    1.      Introduction . . . . . . . . . . . . . . . . . . . . . . . . .
      1.1        Copyright . . . . . . . . . . . . . . . . . . . . . . . .
      1.2        Technical support . . . . . . . . . . . . . . . . . . . .
      1.3        Distribution  . . . . . . . . . . . . . . . . . . . . . .
        1.3.1    P.D.N . . . . . . . . . . . . . . . . . . . . . . . . . .
      1.4        Registration  . . . . . . . . . . . . . . . . . . . . . .

    2.      Function Descriptions  . . . . . . . . . . . . . . . . . . . .
      2.1        Distribution Files  . . . . . . . . . . . . . . . . . . .

    3.      Quick reference  . . . . . . . . . . . . . . . . . . . . . . .
      3.1        Bit wise  . . . . . . . . . . . . . . . . . . . . . . . .
      3.2        Files . . . . . . . . . . . . . . . . . . . . . . . . . .
      3.3        Keyboard  . . . . . . . . . . . . . . . . . . . . . . . .
      3.4        Video . . . . . . . . . . . . . . . . . . . . . . . . . .
      3.5        Text graphics . . . . . . . . . . . . . . . . . . . . . .
      3.6        Strings . . . . . . . . . . . . . . . . . . . . . . . . .

    4.      Detail Reference . . . . . . . . . . . . . . . . . . . . . . .
      4.1        Bit wise  . . . . . . . . . . . . . . . . . . . . . . . .
      4.2        Files . . . . . . . . . . . . . . . . . . . . . . . . . .
      4.3        Keyboard  . . . . . . . . . . . . . . . . . . . . . . . .
      4.4        Video . . . . . . . . . . . . . . . . . . . . . . . . . .
      4.5        Text graphics . . . . . . . . . . . . . . . . . . . . . .
      4.6        Strings . . . . . . . . . . . . . . . . . . . . . . . . .







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


     If you are a serious  Pascal programmer  then then you are bound one
     day to say to your self " i'm  in  the need for  some speed ! ". ( i
     hope  the  makers   of   "Top Gun"  dont  mind me   saying   that) .

     The best way to do  this is  by  programming  in assembler.  Even  C
     programmers find they   need to  use assembler  code  to enhance its
     performance. I have written several routines that will help speed up
     execution time remarkably. The profiler gave me results of  upto 80%
     improvement  in  speed, for this reason i delibretaly have functions
     that are similar or identical in operation to the standard run time.

     This toolkit will not give  you fancy  pull-down menus and exploding
     windows etc, it was never intended to be that.   They  are low level
     functions only, and may be used for building other functions that do
     have fancy things ...... ( This is what I use it for ..)


     The toolkit itself has  over 100 very  usefull and  highly optimised
     low level functions.


     The following is a list of all the assembler module files are  brief
     description of the functions.



               TPFBIT.ASM     - mathematical bit manipulation
               TPFFILE.ASM    - file manipulation routines
               TPFSCRN.ASM    - graphics and crt routines
               TPFKBD.ASM     - keyboard handling routines
               TPFVIDEO.ASM   - screen handling routines
               TPFSTR.ASM     - string manipulation routines





     All of these were tested  with is Borlands  Turbo Pascal 6.0  but i
     cannot give a warranty of any kind, either expressed  or implied. I
     only  guarantee  that this toolkit  will occupy  diskspace.  Please
     read the CopyRight section for more information.


     This  toolkit  is released  under the shareware  concept and is NOT
     public domain,  freeware or  cripple ware,  please read section 1.3
     for more information.







     1.1.  CopyRight:
     ----------------

     In no event shall Steven Lutrov 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 this library.





     1.2.  Technical Support:
     ------------------------

     Technical support is best achieved if you have a modem and understand
     the  BBS  scene.   You can dial up  The Software Parlour BBS where an
     echo-mail area will be set up and messages can be posted, I or others
     may be able to help etc etc.
     You may also write to me at the address provided.

     I will also guarnatee that the latest version of this library will be
     posted on The Software Parlour BBS.




          BBS phone     -     +61-3-301-1877
          Baud rates    -     V42bis,V32,V22bis,V22,V21

          BBS address   -     3:635/534@fido.org
                              58:4100/34@intlnet


          Postal Addresso -   Steven Lutrov.
                              PO BOX 466
                              Essendon, VIC 3040
                              Australia




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


     You are encouraged to  copy the toolkits 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.


     After you have used the  toolkit for a  reasonable  evaluation period
     you  should  either  discontinue  use  of  the  program or purchase a
     licensed copy from the author.  Your support is important and greatly
     appreciated.   with it, shareware  authors are  encouraged to  design
     and  distribute new   products.   without it, a  great deal  of  high
     quality, low cost software will cease to be available.



     in the  case of distribution  via any  telecommunications  link,  the
     following must be done:

     *      z-modem  or  some other  error  checking protocol must be used
     *      all  files (including documentation files) must be transferred
            in a library or archive format.  this means the files have all
            been combined into one file.




     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 PDN.


     More information may be obtained from the following..


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





     1.4.  Registration:
     -------------------

     Why pay at all?


        1 ..  You receive full Assembly and Pascal source code, and may
              modify it to suit you own needs.

        2 ..  Automatic subscription  to The Software Parlour BBS
              (Home of TPFAST , and other programmers goodies).

        3 ..  Free upgrade offers

        6 ..  Your input and ideas help shape future upgrades with
              acknowledgment  of your  contributions placed in the
              source code.

        7 ..  A sense of pride and ownership in having honestly
              participated   in   the   shareware    revolution

        8 ..  You help to keep software prices down by supporting a
              distribution method which doesn't depend on expensive
              advertising campaigns.


     So please take it serously, and enjoy the fun  of  legally  sharing
     good software with your friends and associates.

     Should you wish to register the toolkit , please print out the file
     "register.txt" and fill in the relavent details.



     2. Descriptions:
     ----------------

          The following sections will give a brief description of the
          functions available.



     Bit wise
     ---------

          These functions do bitwise  conversions such as  rotating  bits
          left or right in given bytes or words.

          Other math related functions include converting bytes and words
          to Hexadecimal strings.



     Files:
     ------


          These functions provide support for  file manipulation such  as
          creating,  opening,  reading,  writing  and erasing files. Each
          file that is created can have  any  attribute including  hidden
          , system, read-only and sub-directory attributes. All the  file
          fuctions are referenced by a unique (integer) handle.      This
          handle is allocated by DOS. You can open files for "reading" or
          "writing" or "reading and writing", and you can also change the
          logical read/write position of a file.

          Additional functions are provided  that enable  you to to  read
          and write to a specific disk sector, and enable and disable the
          DOS verification flag.




     Keyboard
     --------

          These  functions will    just  about  cover  all  the low level
          keyboard functions that you would ever need.
          You can test if the  ALT,CTRL,INS  are down, test  if  the LEFT
          SHIFT and RIGHT SHIFT or BOTH SHIFTS are down. Test if CAPSLOCK
          ,SCROLLLOCK, NUMLOCK etc are set, or you can set them your self.

          You can make any key a push-on and release-off switch,    get a
          scan code of any keypress, clear the keyboard buffer etc etc.



     Video
     -----

          These functions perform  all the low level video that you would
          ever need. All the  functions  write directly  to the VIDEO RAM
          for optimum performance, and even support the old CGA  monitors
          that have snow problems.

          There is a global variable in  the TPFAST.PAS unit file  in the
          initialisation section that nedds to  be set for TRUE  if   you
          have one of these old beasties, otherwise it should be left  as
          FALSE.

          There is  also  support  provided  for  multiple  Video  Pages,
          scrolling, cursor  movement,  screen  saving,  partial   screen
          saving, changing the attributes on sections or  all the screen.

          Strings can be formatted , justified ,  centered  and   trimmed
          before they are sent to the screen.  Strings  can be  displayed
          vertcally.

          Strings can be  written  to  any  video  page  in     slectable
          attributes at any position, in reverse or intense text.

          You may view or set the attributes of any char or string on the
          screen.

          The blink bit may be  toggled to give you a  Yellow  backgroung
          with a black foreground etc etc   ( something you dont see that
          often ).



     Text Graphics
     -------------

          These functions  will  do  low  level  text  screen    handling
          including  saving, copying and restoring screen contents  to  a
          buffer,  drawing  boxes,  filling  an  entire  screen  with   a
          character.

          Moves a whole or part of  a  screen image in any direction, and
          scroll the contents of a whole or  part  of  a screen vertcally
          and horizontally.



     Strings
     -------

          These functions perform very fast string manipulation, some are
          identical  only  in  functionality to those provided by the run
          time    library,   they  differ  significantly  in    execution
          performance.


          Functions include, changing and deleting characters,  comparing
          strings,  returning  portions  of  strings,  case   conversions,
          padding  strings,  searching  and  replacing  strings, creating
          strings and counting words in a string.




     2.1 Distribution Files:
     -----------------------

          The following files should be include in the distribution
          archive.



         REGISTER.TXT    - product registration form
         TPFAST.TXT      - documentation
         READ.ME         - release and special information file
         TPFAST.PAS      - tpfast unit file

         TPFBIT.ASM      - math functions, assembler source
         TPFFILE.ASM     - file functions, assembler source
         TPFKBD.ASM      - keyboard functions, assembler source
         TPFSCRN.ASM     - screen functions, assembler source
         TPFSTR.ASM      - string functions, assmbler source
         TPFVIDEO.ASM    - video functions, assembler source

         TPFBIT.OBJ      - math functions, assembler object code
         TPFFILE.OBJ     - file functions, assembler object code
         TPFKBD.OBJ      - keyboard functions, assembler object code
         TPFSCRN.OBJ     - screen functions, assembler object code
         TPFSTR.OBJ      - string functions, assmbler source
         TPFVIDEO.OBJ    - video functions, assembler object code



         T_BIT.PAS       - example on bit functions
         T_FILE.PAS      - example on file functions
         T_KBD.PAS       - example on keyboard functions
         T_SCRN.PAS      - example on screen functions
         T_STR           - example on string functions





     3.  Quick Reference:
     -------------------


     3.1  Bitwise:
     -------------


     bytetohex         ...    Converts a byte to hex.
     rotatebyteleft    ...    Rotate the bits of a byte left.
     rotatebyteright   ...    Rotate the bits of a byte right.
     rotatewordleft    ...    Rotate the bits of a word left.
     rotatewordright   ...    Rotate the bits of a word right.
     wordtohex         ...    Convert a word variable to hex.





     3.2  Files:
     -----------


     fclose            ...    Closes a file
     fcreate           ...    Create a file with specified attributes.
     ferase            ...    Erases a specified file
     fopen             ...    Opens a file with specified access.
     fread             ...    Reads a file to a buffer
     fseek             ...    Change logical read/write position in
                              a file
     fwrite            ...    Writes to a file
     getverify         ...    Returns the dos verification flag
     readsector        ...    Reads from  a specified disk sector
     setverify         ...    Change the the dos verification flag
     writesector       ...    Writes to a specified disk sector.





     3.3  Keyboard:
     --------------



     altkeydown        ...    Report if <alt> key is pressed
     capslockdown      ...    Report if <caps lock> key is pressed
     capslockon        ...    Report if <caps lock> key is currently on
     clearbuffer       ...    Clears the keyboard buffer.
     clearcapslock     ...    Clears the <caps lock> key.
     clearins          ...    Clears the <ins> key.
     clearnumlock      ...    Clears the <num lock> key.
     clearscrolllock   ...    Clears the <scroll lock> key.
     ctrlkeydown       ...    Report if <ctrl> key is pressed
     ekeypressed       ...    Test if enhanced key is pressed.
     freshchar         ...    Clears the keyboard buffer and returns the
                              next keystroke.
     getekey           ...    Get enhanced keystroke.
     getkey            ...    Get keystroke.
     inskeydown        ...    Report if <ins> key is pressed
     inskeyon          ...    Report if <ins> key is currently on
     keypause          ...    Makes any key a push-on and release-off
                              switch.
     lastkey           ...    return the last keyboard code from the
                              buffer
     leftshiftdown     ...    Report if <left shift> key is pressed
     nextkey           ...    Extracts next keystroke from buffer without
                              removing it.
     numlockdown       ...    Report if <num lock> key is pressed
     numlockon         ...    report if <num lock> key is currently on
     rightshiftdown    ...    report if <right shift> key is pressed
     scrolllockdown    ...    Report if <scroll lock> key is pressed
     scrolllockon      ...    Report if <scroll lock> key currently on
     setcapslock       ...    Set the <caps lock> key.
     setins            ...    Set the <ins> key.
     setnumlock        ...    Set the <num lock> key.
     setscrolllock     ...    Set the <scroll lock> key.



     3.4  Video:
     -----------



     blinkoff          ...    Sets text attribute to not blink.
     blinkon           ...    Set text attribute to blink.
     clearpage         ...    Clears a previously saved page from memory.
     colourx           ...    Change the attribute of a column of text.
     cursordown        ...    Move cursor down the specified number of
                              rows.
     cursorleft        ...    Move cursor left the specified number of
                              columns.
     cursoroff         ...    Turn cursor off, making it invisible.
     cursoron          ...    Turn cursor on, making it visible.
     cursorright       ...    Move cursor right a specified number of
                              columns.
     cursorup          ...    Move cursor up the specified number of rows.
     dsp               ...    Writes a string directly to the video
                              buffer.
     dspat             ...    Writes a string directly to the video
                              buffer at the specified coordinates in a
                              given attribute.
     dspcolour         ...    Writes a string directly to the video buffer
                              in a given attribute.
     dspend            ...    Write a string directly to the video buffer
                              and clears the remaining characters.
     dspjust           ...    Writes a string directly to the video buffer
                              justifying it against a specified column and
                              row position.
     dspln             ...    Writes a string directly to the video buffer.
     dsplncolour       ...    Writes a string directly to the video buffer
                              in a given attribute.
     dsppart           ...    Writes a portion of a string directly to the
                              video buffer at specified coordinates an a
                              specified  attribute.
     dspvert           ...    Write and string vertically directly to the
                              video buffer.
     formatleft        ...    Writes a string directly to the video ram
                              with left formatting.
     formatright       ...    Writes a string directly to the video ram
                              with right formatting.
     getcolour         ...    Get the attribute of a specified screen
                              position.
     getpage           ...    Gets the current page.
     intenseoff        ...    Set text attribute to intensity off.
     intenseon         ...    Set text attribute to intense on.
     normal            ...    Set text attribute to normal.
     reverse           ...    Set text attribute to reverse.
     rowcolour         ...    Change the attribute of a row of text.
     screencolour      ...    Change the attribute of a boxed area.
     setcolour         ...    Set the attribute of a character at the
                              specified screen position.
     setpage           ...    Set the a particiular page to be current
                              and active.
     swappage          ...    Exchage all memory allocated by a page to
                              a buffer.



     3.5  Text graphics:
     -------------------


     copyclear         ...    Copy the contents of a screen area.
     drawbox           ...    Draws a simple box on the screen.
     fillscreen        ...    Fills an area of the screen with a specified
                              character and attribute.
     restorescreen     ...    Restores a previously saved screen image.
     savescreen        ...    Saves a screen area.
     screendown        ...    Moves an area of the screen down 1 row.
     screenleft        ...    Moves an area of the screen left 2 columns.
     screenright       ...    Moves an area of the screen right 2 columns.
     screenup          ...    Moves an area of the screen up 1 row.
     scrollx           ...    Scroll a defined area of the screen left or
                              right.
     scrolly           ...    Scroll a defined area of the screen up or down





     3.6  Strings:
     -------------




     changechar        ...    Changes every instance of a character in a
                              string.
     compare           ...    Compares two strings, ignoring case.
     deletechar        ...    Deletes all occurances of a specified
                              character.
     deleteleft        ...    Deletes all characters from the begining of a
                              string until a specified character is reached.
     deleteright       ...    Deletes all characters from the end of a
                              string until a specified character is reached.
     leftend           ...    Return the left end of a string up to a
                              specified character.
     lowercase         ...    Convert a string to lowercase.
     overwrite         ...    Overwrites part of a string with a substring.
     padcentre         ...    Pads a string to a specified length at any
                              position in a character.
     padends           ...    Extends a string by padding it at both ends.
     padleft           ...    Pads the begining of a string and extends
                              it to a specified length.
     padright          ...    Pads the end of a string and extends it a
                              specified length.
     replace           ...    Deletes a specified number of characters and
                              inserts new substring.
     rightend          ...    Return the right end of a string up to a
                              specified character.
     seekstring        ...    Searches for a substring within a string.
     stringend         ...    Returns a specified number of characters
                              from the end of a string.
     stringof          ...    Makes a new string made up of repetitions of
                              a substring.
     uppercase         ...    Convert a string to uppercase.
     wordcount         ...    Counts the number of words in a string.





     4.  Detailed Reference:
     -----------------------

          The following text describes in detail all the functions in the
          library.  When  I say functions I am  refering to procedures as
          well as they are the same thing in my books. The layout is very
          straight forward and needs no clarification. All the  functions
          are listed in alpabetical order, so  should be  fairly easy  to
          find.




     4.1  Bit wise
     -------------



     --------------------------------------------------------------------------
     bytetohex


     DESCRIPTION  ...    Converts a byte to hex.

     DECLERATION  ...    function bytetohex (num  :byte) :stype;

     PARAMETERS   ...    num         - the byte that is converted

     RETURNS      ...    A hexadecimal string represented by the byte.


     --------------------------------------------------------------------------
     rotatebyteleft


     DESCRIPTION  ...    Rotate the bits of a byte left.

     DECLERATION  ...    function rotatebyteleft (num,nbits  :byte) :byte;

     PARAMETERS   ...    num         - the byte that is converted
                         nbits       - number of bits to be rotated

     RETURNS      ...    The new modified byte.


     --------------------------------------------------------------------------
     rotatebyteright


     DESCRIPTION  ...    Rotate the bits of a byte right.


     DECLERATION  ...    function rotatebyteright (num,nbits  :byte) :byte;


     PARAMETERS   ...    num         - the byte that is converted
                         nbits       - number of bits to be rotated

     RETURNS      ...    The new modified byte.


     --------------------------------------------------------------------------
     rotatewordleft


     DESCRIPTION  ...    Rotate the bits of a word left.

     DECLERATION  ...    function rotatewordleft (num : word; nbits  :byte)
                                                 :word;

     PARAMETERS   ...    num         - the word that is converted
                         nbits       - number of bits to be rotated

     RETURNS      ...    The new modified byte.


     --------------------------------------------------------------------------
     rotatewordright


     DESCRIPTION  ...    Rotate the bits of a word right.

     DECLERATION  ...    function rotatewordright (num :word;
                                                 nbits  :byte): word;

     PARAMETERS   ...    num         - the word that is converted
                         nbits       - number of bits to be rotated

     RETURNS      ...    The new modified byte.


     --------------------------------------------------------------------------
     wordtohex


     DESCRIPTION  ...    Convert a word variable to hex.

     DECLERATION  ...    function bytetohex (num : word) :stype;


     PARAMETERS   ...    num       - the word theat is converted

     RETURNS      ...    A hexadecimal string represented by the word.





     4.2  Files:
     -----------


     --------------------------------------------------------------------------
     fclose

     DESCRIPTION  ...    Closes a file

     DECLERATION  ...    function fclose(handle :integer) :boolean;


     PARAMETERS   ...    handle      - the dos file handle.

     RETURNS      ...    true        - file closed ok
                         false       - file didn't close ok


     --------------------------------------------------------------------------
     fcreate

     DESCRIPTION  ...    Create a file with specified attributes. The
                         attributes are identical as those provided by the
                         standard runtime but AnyFile is not valid. Use the
                         logical or operator for combined attributes
                         eg (0 or 2 or 5) etc etc...

     DECLERATION  ...    function fcreate(fname:string; attribute :integer)
                                         :integer;


     PARAMETERS   ...    fname       - the name of the file to be created
                         attribute   - the attribute of the file to be created
                                         0 = read only
                                         1 = hidden
                                         2 = system file
                                         3 = volume label entry
                                         4 = subdirectory
                                         5 = archive file

     RETURNS     ...     >= 0        - ok (returns file handle)
                         -3          - path not found
                         -4          - too many open files
                         -5          - access denied


     --------------------------------------------------------------------------
     ferase

     DESCRIPTION  ...    Erases a specified file

     DECLERATION  ...    function ferase(name:string) :integer;


     PARAMETERS   ...    name        - the name of the file to be erased

     RETURNS      ...    0           - ok
                        -2           - file not found
                        -5           - access denied

     --------------------------------------------------------------------------
     fopen

     DESCRIPTION  ...    Opens a file with specified access.

     DECLERATION  ...    function fopen(name :string; access :integer)
                                       :integer;


     PARAMETERS   ...    name        - the name of the file to be created
                         access      - the access required for the file
                                        0 - read only
                                        1 - write
                                        2 - read and write

     RETURNS     ...     >= 0        - ok (returns file handle)
                         -2          - file not found
                         -4          - too many open files
                         -5          - access denied
                         -12         - invalid access


     --------------------------------------------------------------------------
     fread

     DESCRIPTION  ...    Reads a file to a buffer

     DECLERATION  ...    function fread(handle :integer; amount:word; var buff)
                                        :integer;


     PARAMETERS   ...    handle      - handle identifier of the file
                         amount      - number of bytes to read
                                       record size <= $7FFF bytes
                         buff        - pointer to address of data buffer


     RETURNS      ...   >= 0         - ok (returns bytes read)
                        -5           - access denied
                        -6           - invalid handle


     --------------------------------------------------------------------------
     fseek


     DESCRIPTION  ...    Change logical read/write position in a file

     DECLERATION  ...    function fseek (handle :integer; mode :integer;
                                         offset:longint; var location:
                                         longint) :boolean;


     PARAMETERS   ...    handle      - handle of the file
                         mode        - method code of pointer movement e.g.
                                       0 - move from beginning of file
                                       1 - move beyond current position
                                       2 - move beyond end of file

                         offset      - offset in file relative to mode
                         location    - new file pointer location after move


     RETURNS      ...    true        - ok
                         false       - something went wrong


     --------------------------------------------------------------------------
     fwrite

     DESCRIPTION  ...    Writes to a file

     DECLERATION  ...    function fwrite(handle :integer; nwrite:word;
                                         var buff) :integer;


     PARAMETERS   ...    handle      - handle identifier of the file
                         nwrite      - number of bytes to write
                                       record size <= $7FFF bytes

                         buff        - pointer to address of data buffer


     RETURNS      ...    >= 0        - ok (returns bytes written)
                         -5          - access denied
                         -6          - invalid handle


     --------------------------------------------------------------------------
     getverify

     DESCRIPTION  ...    Returns the dos verification flag for disk writing

     DECLERATION  ...    function getverify  :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true         - verify flag is set
                         false        - verify flag is clear


     --------------------------------------------------------------------------
     readsector

     DESCRIPTION  ...    Reads 512 bytes of a specified disk sector to a
                         buffer

     DECLERATION  ...    procedure readsector(segment,offset,drive,sector,
                                              number: word);



     PARAMETERS   ...    segment     - the segment of the array buffer object
                         offest      - the offset for the segment
                         drive       - the specified drive
                                       1 = a, 2 = b, 3 = c etc.
                         sector      - the logical sector number
                         number      - number of sectors to read


     TPFError    ...     0           - ok
                         1           - invalid format on disk
                         2           - write protection error
                         3           - sector number is invalid
                         4           - hardware failure

     --------------------------------------------------------------------------
     setverify


     DESCRIPTION  ...    Change the the dos verification flag for disk writing

     DECLERATION  ...    procedure setverify (setting: boolean);


     PARAMETERS   ...    setting     - true for verification
                                     - false for no verification


     --------------------------------------------------------------------------
     writesector

     DESCRIPTION  ...    Writes 512 bytes from a buffer to a specified disk
                         sector.

     DECLERATION  ...    procedure writesector(segment,offset,drive,sector,
                                               number :word);


     PARAMETERS   ...    segment     - the segment of the array buffer object
                         offest      - the offset for the segment
                         drive       - the specified drive
                                       1 = a, 2 = b, 3 = c etc.
                         sector      - the logical sector number
                         number      - number of sectors to read


     TPFError     ...    0           - ok
                         1           - invalid format on disk
                         2           - write protection error
                         3           - sector number is invalid
                         4           - hardware failure










     4.3  Keyboard:
     --------------





     --------------------------------------------------------------------------
     altkeydown


     DESCRIPTION  ...    Report if <alt> key is pressed

     DECLERATION  ...    function altkeydown  :boolean;


     PARAMETERS   ...    none

     RETURNS      ...    true        - if <alt> key is pressed.
                         false       - otherwise.


     --------------------------------------------------------------------------
     capslockdown


     DESCRIPTION  ...    Report if <caps lock> key is pressed

     DECLERATION  ...    function capslockdown :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <caps lock> key is pressed.
                         false       - otherwise.


     --------------------------------------------------------------------------
     capslockon


     DESCRIPTION  ...    Report if <caps lock> key is currently on

     DECLERATION  ...    function capslockdon :boolean;


     PARAMETERS   ...    none

     RETURNS      ...    true        - if <caps lock> key is set.
                         false       - otherwise.




     --------------------------------------------------------------------------
     clearbuffer


     DESCRIPTION  ...    Clears the keyboard buffer.

     DECLERATION  ...    procedure clearbuffer;

     PARAMETERS   ...    none



     --------------------------------------------------------------------------
     clearcapslock


     DESCRIPTION  ...    Clears the <caps lock> key.

     DECLERATION  ...    procedure clearcapslock;

     PARAMETERS   ...    none


     --------------------------------------------------------------------------
     clearins


     DESCRIPTION  ...    Clears the <ins> key.

     DECLERATION  ...    procedure clearins;

     PARAMETERS   ...    none


     --------------------------------------------------------------------------
     clearnumlock


     DESCRIPTION  ...    Clears the <num lock> key.

     DECLERATION  ...    procedure clearnumlock;

     PARAMETERS   ...    none


     --------------------------------------------------------------------------
     clearscrolllock


     DESCRIPTION  ...    Clears the <scroll lock> key.

     DECLERATION  ...    procedure clearscrolllock;

     PARAMETERS   ...    none


     --------------------------------------------------------------------------
     ctrlkeydown


     DESCRIPTION  ...    Report if <ctrl> key is pressed

     DECLERATION  ...    function ctrlkeydown :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <ctrl key> key is pressed.
                         false       - otherwise.



     --------------------------------------------------------------------------
     ekeypressed


     DESCRIPTION  ...    Checks if an enhanced key was pressed. This is
                         similar to keypressed by the standard run-time but
                         this function also supports enhanced keystrokes
                         such as the F11 and F12 keys.

     DECLERATION  ...    ekeypressed  :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true         - enhanced key was pressed
                         false        - enhanced key was not pressed


     --------------------------------------------------------------------------
     freshchar


     DESCRIPTION  ...    Clears the keyboard buffer and returns the next
                         keystroke.

     DECLERATION  ...    function freshchar :char;

     PARAMETERS   ...    none

     RETURNS      ...    The next keystroke. If an extended code was issued
                         then chr(0) is returned only.


     --------------------------------------------------------------------------
     getekey


     DESCRIPTION  ...    Gets a character from the keyboard buffer and waits
                         if the buffer is empty. This function will return
                         any extended keystrokes including F11 and F12  keys
                         provided the machine supports them. This function
                         will only work on (AT model 339,XT2,XT286,PS)
                         systems.

     DECLERATION  ...    function getekey   :word;

     PARAMETERS   ...    none

     RETURNS      ...    A unique word that holds the character and the scan
                         code. See the "const" section of the TPFAST.PAS file
                         for the key constants. You can also use the HI,LO
                         functions to extract the char and scan code.

                         e.g

                         HI(x) - returns the scan code
                         LO(x) - returns the char



     --------------------------------------------------------------------------
     getkey


     DESCRIPTION  ...    Gets a character from the keyboard buffer and waits
                         if the buffer is empty. This function will discard
                         any extended keystrokes returning only when a
                         non-extended keystroke is available. Use this if you
                         do not have an extended keyboard.

     DECLERATION  ...    function getkey   :word;

     PARAMETERS   ...    none

     RETURNS      ...    A unique word that holds the character and the scan
                         code. See the "const" section of the TPFAST.PAS file
                         for the key constants. You can also use the HI,LO
                         functions to extract the char and scan code.

                         e.g

                         HI(x) - returns the scan code
                         LO(x) - returns the char


     --------------------------------------------------------------------------
     inskeydown


     DESCRIPTION  ...    Report if <ins> key is pressed

     DECLERATION  ...    function inskeydown: boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <ins key> key is pressed.
                         false       - otherwise.


     --------------------------------------------------------------------------
     inskeyon


     DESCRIPTION  ...    Report if <ins> key is currently on

     DECLERATION  ...    function inskeyon :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <ins key> key is on.
                         false       - otherwise.


     --------------------------------------------------------------------------
     keypause


     DESCRIPTION  ...    Makes any key a push-on and release-off switch. This
                         is a powerfull function that can differentiate a key
                         press and a key release.

     DECLERATION  ...    procedure keypause (code :char; ascii:
                                             boolean; wait_a,wait_b :byte);



     PARAMETERS   ...    code        -  the key that is used in keypause
                         ascii       -  true  - code is 1 byte ascii code
                                        false - code is second byte of extended code

                         wait_a      - time for buffer refresh signal on
                                       press
                         wait_b      - time for buffer refresh signal on
                                       release


     --------------------------------------------------------------------------
     lastkey


     DESCRIPTION  ...    Gets the last keyboard code from the keyboard buffer.

     DECLERATION  ...    function lastkey :char;

     PARAMETERS   ...    none

     RETURNS      ...    The last key press in the buffer. If the keyboard
                         buffer was empty the routine returns 255. If the
                         last keystroke was extended then chr(0) is returned
                         only.


     --------------------------------------------------------------------------
     leftshiftdown

     DESCRIPTION  ...    Report if <left shift> key is pressed

     DECLERATION  ...    function leftshiftdown :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <left shift key> key is pressed.
                         false       - otherwise.


     --------------------------------------------------------------------------
     nextkey


     DESCRIPTION  ...    Extracts next keystroke from buffer without removing
                         it.

     DECLERATION  ...    function nextkey :char;

     PARAMETERS   ...    none

     TPFError     ...    0           - normal ascii return
                         1           - extended code return
                         2           - buffer is empty


     --------------------------------------------------------------------------
     numlockdown


     DESCRIPTION  ...    Report if <num lock> key is pressed

     DECLERATION  ...    function numlockdown :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <num lock key> key is pressed.
                         false       - otherwise.



     --------------------------------------------------------------------------
     numlockon


     DESCRIPTION  ...    Report if <num lock> key is currently on

     DECLERATION  ...    function numlockon :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <num lock key> key is on.
                         false       - otherwise.



     --------------------------------------------------------------------------
     rightshiftdown


     DESCRIPTION  ...    Report if <right shift> key is pressed

     DECLERATION  ...    function rightshiftdown :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <right shift key> key is pressed.
                         false       - otherwise.


     --------------------------------------------------------------------------
     scrolllockdown


     DESCRIPTION  ...    Report if <scroll lock> key is pressed

     DECLERATION  ...    function scrolllockdown :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <scroll lock> is pressed.
                         false       - otherwise.


     --------------------------------------------------------------------------
     scrolllockon


     DESCRIPTION  ...    Report if <scroll lock> key currently on

     DECLERATION  ...    function scrolllockon :boolean;

     PARAMETERS   ...    none

     RETURNS      ...    true        - if <scroll lock> is on.
                         false       - otherwise.


     --------------------------------------------------------------------------
     setcapslock


     DESCRIPTION  ...    Set the <caps lock> key.

     DECLERATION  ...    procedure setcapslock;

     PARAMETERS   ...    none


     --------------------------------------------------------------------------
     setins


     DESCRIPTION  ...    Set the <ins> key.

     DECLERATION  ...    procedure setins;

     PARAMETERS   ...    none

     --------------------------------------------------------------------------
     setnumlock


     DESCRIPTION  ...    Set the <num lock> key.

     DECLERATION  ...    procedure setnumlock;

     PARAMETERS   ...    none


     --------------------------------------------------------------------------
     setscrolllock


     DESCRIPTION  ...    Set the <scroll lock> key.

     DECLERATION  ...    procedure setscrolllock;

     PARAMETERS   ...    none





     4.4  Video:
     -----------





     --------------------------------------------------------------------------
     blinkoff

     DESCRIPTION  ...    Sets text attribute to not blink. On EGA and VGA
                         system this gives you extra colours like black on
                         a yellow background.

     DECLERATION  ...    procedure blikoff;

     PARAMETERS   ...    none


     --------------------------------------------------------------------------
     blinkon


     DESCRIPTION  ...    Set text attribute to blink, this is the default
                         state of all video adaptors.

     DECLERATION  ...    procedure blinkon;

     PARAMETERS   ...    none




     --------------------------------------------------------------------------
     clearpage


     DESCRIPTION  ...    Clears a previously saved page from memory. See
                         getpage for more information.

     DECLERATION  ...    procedure clearpage(pagenumber,colour :byte);


     PARAMETERS   ...    pagenumber  - the page number
                         colour      - the colour attribute to which the page
                                       is to be  cleared.



     --------------------------------------------------------------------------
     colourx


     DESCRIPTION  ...    Change the attribute of a column of text.
                         The text is not altered in any way.

     DECLERATION  ...    procedure colourx (x,y,yy,colour :byte);



     PARAMETERS   ...    x          - column position coordinate
                         y          - row position coordinate
                         yy         - number of columns deep
                         colour     - the attribute



     --------------------------------------------------------------------------
     cursordown


     DESCRIPTION  ...    Move cursor down the specified number of rows.

     DECLERATION  ...    procedure cursordown(rows :integer);


     PARAMETERS   ...    rows        - number of rows to move down.



     --------------------------------------------------------------------------
     cursorleft


     DESCRIPTION  ...    Move cursor left the specified number of columns.

     DECLERATION  ...    procedure cursorleft(columns :integer);


     PARAMETERS   ...    columns       number of columns to move left.



     --------------------------------------------------------------------------
     cursoroff


     DESCRIPTION  ...    Turn cursor off, making it invisible.

     DECLERATION  ...    procedure cursoroff;


     PARAMETERS   ...    none



     --------------------------------------------------------------------------
     cursoron


     DESCRIPTION  ...    Turn cursor on, making it visible.

     DECLERATION  ...    procedure cursoron;


     PARAMETERS   ...    none



     --------------------------------------------------------------------------
     cursorright


     DESCRIPTION  ...    Move cursor right the specified number of columns.

     DECLERATION  ...    procedure cursorright(columns :integer);



     PARAMETERS   ...    columns     - number of columns to move right.


     --------------------------------------------------------------------------
     cursorup


     DESCRIPTION  ...    Move cursor up the specified number of rows.

     DECLERATION  ...    procedure cursorup (rows :integer);



     PARAMETERS   ...    rows        - number of rows to move up.


     --------------------------------------------------------------------------
     dsp

     DESCRIPTION  ...    Writes a string directly to the video buffer.
                         The string can be written to any page and the colour
                         attribute of the string is set to the global
                         variable textattr. No CR+LF is sent (see dspln).

     DECLERATION  ...    procedure dsp (s: stype);


     PARAMETERS   ...    s           - the string to write



     --------------------------------------------------------------------------
     dspat


     DESCRIPTION  ...    Writes a string directly to the video buffer at the
                         specified coordinates in a given attribute.
                         The string can be written to any page. No CR+LF is
                         sent (see dspln).

     DECLERATION  ...    procedure dspat(s: stype; x,y,colour :byte);


     PARAMETERS   ...    s           - the string to write
                         x           - the column location position
                         y           - the row location position
                         colour      - the colour attribute of the string


     --------------------------------------------------------------------------
     dspcolour


     DESCRIPTION  ...    Writes a string directly to the video buffer in a
                         given attribute.
                         The string can be written to any page.
                         No CR+LF is sent (see dspln).

     DECLERATION  ...    procedure dspcolour(s: stype; colour :byte);



     PARAMETERS   ...    s           - the string to write
                         colour      - the colour attribute of the string


     --------------------------------------------------------------------------
     dspend


     DESCRIPTION  ...    Write a string directly to the video buffer and
                         clears the remaining characters following the
                         string until the length is met.


     DECLERATION  ...    procedure dspend(s: stype; x,y,length,colour :byte);



     PARAMETERS   ...    s           - the string to write
                         x           - the column position starting coordinate
                         y           - the row position starting coordinate
                         length      - the length to end the string at


     --------------------------------------------------------------------------
     dspjust


     DESCRIPTION  ...    Writes a string directly to the video buffer
                         justifying it against a specified column and row
                         position.

     DECLERATION  ...    procedure dspjust(s: stype; x,y,colour :byte);


     PARAMETERS   ...    s           - the string to write
                         x           - the column staring position
                         y           - the row staring position
                         colour      - the colour attribute of the string

     --------------------------------------------------------------------------
     dspln


     DESCRIPTION  ...    Writes a string directly to the video buffer.
                         The string can be written to any page and the colour
                         attribute of the string is set to the global
                         variable textattr. A CR+LF is sent is appended
                         to the string.


     DECLERATION  ...    procedure dspln(s: stype);

     PARAMETERS   ...    s           - the string to write



     --------------------------------------------------------------------------
     dsplncolour


     DESCRIPTION  ...    Writes a string directly to the video buffer in a
                         given attribute. The string can be written to any
                         page. A CR+LF is appended to the string.

     DECLERATION  ...    procedure dsplncolour(s: stype; colour :byte);


     PARAMETERS   ...    s           - the string to write
                         colour      - the colour attribute of the string (0-255)



     --------------------------------------------------------------------------
     dsppart


     DESCRIPTION  ...    Writes a portion of a string directly to the video
                         buffer at specified coordinates an a specified
                         attribute.

     DECLERATION  ...    procedure dsppart (s: stype; start,numch,
                                               x,y,colour :byte);


     PARAMETERS   ...    s           - the string to write
                         start       - starting position in s
                         numch       - number of characters to write
                         x           - the column staring position
                         y           - the row starting position
                         colour      - the colour attribute of the string


     --------------------------------------------------------------------------
     dspvert


     DESCRIPTION  ...    Write and string vertically directly to the video
                         buffer.

     DECLERATION  ...    procedure dspvert(s: stype; x,y,colour :byte);



     PARAMETERS   ...    s           - the string to write
                         x           - the column staring position
                         y           - the row staring position
                         colour      - the colour attribute of the string


     --------------------------------------------------------------------------
     formatleft


     DESCRIPTION  ...    Writes a string directly to the video ram with
                         formatting. The string is written to the right of
                         the cursor. If how_many is a positive value then
                         cursor is offset to the right from the initial
                         position. if how_many is negative then the cursor
                         is moved to a position directly below the starting
                         point.

     DECLERATION  ...    procedure formatleft(s: stype; how_many :integer;
                                              colour :byte);


     PARAMETERS   ...    s           - the string to write
                         how_many    - distance between starting cursor
                                       position and return cursor position.
                         colour      - the colour attribute



     --------------------------------------------------------------------------
     formatright


     DESCRIPTION  ...    Writes a string directly to the video ram with
                         formatting. The string is written to the left of
                         the initial cursor position so the final character
                         is at the starting position. If how_many is a
                         positive value then cursor is offset to the right
                         from the initial position. If how_many is negative
                         then the cursor is moved to a position directly
                         below the starting point.

     DECLERATION  ...    procedure formatright (s: stype; how_many :integer;
                                                colour :byte);


     PARAMETERS   ...    s           - the string to write
                         how_many    - distance between starting cursor
                                       position and return cursor position.
                         colour      - the colour attribute



     --------------------------------------------------------------------------
     getcolour


     DESCRIPTION  ...    Get the attribute of a specified screen position.

     DECLERATION  ...    function  getcolour(x,y :byte) :byte;


     PARAMETERS   ...    x           - column starting position
                         y           - row starting position

     RETURNS      ...    The attribute


     --------------------------------------------------------------------------
     getpage


     DESCRIPTION  ...    Gets the current page.

     DECLERATION  ...    function  getpage :integer;

     PARAMETERS   ...    none

     RETURNS      ...    The current active page.


     --------------------------------------------------------------------------
     intenseoff

     DESCRIPTION  ...    Set text attribute to intensity off.

     DECLERATION  ...    procedure intenseoff;

     PARAMETERS   ...    none



     --------------------------------------------------------------------------
     intenseon


     DESCRIPTION  ...    Set text attribute to intense on.

     DECLERATION  ...    procedure intenseon;

     PARAMETERS   ...    none


     --------------------------------------------------------------------------
     normal


     DESCRIPTION  ...    Set text attribute to normal.

     DECLERATION  ...    procedure normal;

     PARAMETERS   ...    none



     --------------------------------------------------------------------------
     reverse


     DESCRIPTION  ...    Set text attribute to reverse.

     DECLERATION  ...    procedure reverse;

     PARAMETERS   ...    none



     --------------------------------------------------------------------------
     rowcolour


     DESCRIPTION  ...    Change the attribute of a row of text, the text is
                         not altered in any way.

     DECLERATION  ...    procedure rowcolour(x,y,xx,colour :byte);



     PARAMETERS   ...    x           - top left column position
                         y           - top left row position
                         xx          - number of rows affecting attribute
                         colour      - the attribute


     --------------------------------------------------------------------------
     screencolour


     DESCRIPTION  ...    Change the attribute of a boxed area, the text is
                         not altered in any way.

     DECLERATION  ...    procedure screencolour(x,y,xx,yy,colour :byte);



     PARAMETERS   ...    x           - column position coordinate
                         y           - row position coordinate
                         xx          - number of columns wide
                         yy          - number of rows deep
                         colour      - the attribute


     --------------------------------------------------------------------------
     setcolour


     DESCRIPTION  ...    Set the attribute of a character at the specified
                         screen position. The text is not altered in any
                         way.

     DECLERATION  ...    procedure setcolour(x,y,colour :byte);

     PARAMETERS   ...    x           - column starting position
                         y           - row starting position
                         colour      - the attribute


     --------------------------------------------------------------------------
     setpage


     DESCRIPTION  ...    Set the a particiular page to be current and active.
                         VGA and EGA cards support 8 pages, that is 0-7, and
                         MONOCHROME cards support only one page.

     DECLERATION  ...    procedure setpage(pagenumber :integer);

     PARAMETERS   ...    pagenumber  - the page number


     --------------------------------------------------------------------------
     swappage


     DESCRIPTION  ...    Exchage all memory allocated by a page to a buffer.
                         Also see getpage for more information.

     DECLERATION  ...    procedure swappage(box :pointer; pagenumber :byte);


     PARAMETERS   ...    box         - array for storing the image
                         pagenumber  - the page number








     4.5  Text graphics:
     -------------------



     --------------------------------------------------------------------------
     copyclear


     DESCRIPTION  ...    Copy the contents of a screen area into a byte array
                         and then clear the area. This is a much faster
                         method but is equivalent to  calling the savescreen
                         and clrscr procedures.

     DECLERATION  ...    procedure copyclear (box :pointer; x,y,xx,yy,colour
                                             :byte);


     PARAMETERS   ...    box         - byte array pointer that holds screen
                                       contents
                         x           - the top left column position
                         y           - the top left row position
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen
                         colour      - the colour attribute of the area.



     --------------------------------------------------------------------------
     drawbox


     DESCRIPTION  ...    Draws a simple box on the screen, using double or
                         single lines or a combination. If a combination is
                         used the corner chars are automatically calculated.

     DECLERATION  ...    procedure drawbox (chx,chy :char; x,y,xx,yy,
                                           colour :byte);


     PARAMETERS   ...    chx         - the character used for horizontal lines
                                       'd','D'  - double lines
                                       's','S'  - single lines
                         chy         - the character used for vertical lines
                                       'd','D'  - double lines
                                       's','S'  - single lines
                         x           - the top left column position
                         y           - the top left row position
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen
                         colour      - the colour attribute of the characters.


     --------------------------------------------------------------------------
     fillscreen


     DESCRIPTION  ...    Fills an area of the screen with a specified
                         character and attribute.

     DECLERATION  ...    procedure fillscreen (ch :char; x,y,xx,yy,
                                               colour :byte);


     PARAMETERS   ...    ch          - the character used for filling
                         x           - the top left column position
                         y           - the top left row position
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen
                         colour      - the colour attribute of the character.



     --------------------------------------------------------------------------
     restorescreen


     DESCRIPTION  ...    Restores a previously saved screen image to the
                         current screen. See the savescreen procedure before
                         using this.


     DECLERATION  ...    procedure restorescreen (box :pointer;
                                                  x,y,xx,yy :byte);


     PARAMETERS   ...    box         - byte array pointer that holds screen
                                       contents
                         x           - the top left column position
                         y           - the top left row position
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen



     --------------------------------------------------------------------------
     savescreen


     DESCRIPTION  ...    Copy the contents of a screen area into a byte array
                         including screen attributes. The 'box' pointer
                         should be an array of of bytes the size of the screen
                         you wish to save, keeping in mind one byte is used
                         for the character, and one byte for the attribute.
                         eg. to save the whole screen box should be an array
                         [1..4000] of byte. Remember to pass the address of
                         the box pointer  eg  svaescreen(@boxptr,1,1,80,25);


     DECLERATION  ...    procedure savescreen(box :pointer; x,y,xx,yy :byte);


     PARAMETERS   ...    box         - byte array pointer that holds screen
                                       contents
                         x           - the top left column position
                         y           - the top left row position
                         xx          - the number of columns of the screen
                         yy          - the number of rows of the screen



     --------------------------------------------------------------------------
     screendown


     DESCRIPTION  ...    Moves an area of the screen down 1 row. The screen
                         area should be saved prior to calling this routine
                         with savescreen so the box pointer is initialised
                         correctly. Variables x and y are updated to the new
                         coordinates.

     DECLERATION  ...    procedure screendown (box :pointer; var x,y:
                                          byte; xx,yy :byte);


     PARAMETERS   ...    box         - byte array pointer that holds screen
                                       contents
                         x           - the top left column position of the
                                       screen
                         y           - the top left row position of the screen
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen



     --------------------------------------------------------------------------
     screenleft


     DESCRIPTION  ...    Moves an area of the screen left 2 columns. The
                         screen area should be saved prior to calling this
                         routine with savescreen so the box pointer is
                         initialised correctly. Variables x and y are updated
                         to the new coordinates.


     DECLERATION  ...    procedure screenleft (box :pointer; var x,y :byte;
                                             xx,yy :byte);


     PARAMETERS   ...    box         - byte array pointer that holds screen
                                       contents
                         x           - the top left column position of the
                                       screen
                         y           - the top left row position of the screen
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen



     --------------------------------------------------------------------------
     screenright


     DESCRIPTION  ...    Moves an area of the screen right 2 columns. the
                         screen area should be saved prior to calling this
                         routine with savescreen so the box pointer is
                         initialised correctly. Variables x and y are updated
                         to the new coordinates.


     DECLERATION  ...    procedure screenright (box :pointer; var x,y:byte;
                                              xx,yy :byte);


     PARAMETERS   ...    box          - byte array pointer that holds screen
                                        contents
                         x            - the top left column position of the
                                        screen
                         y            - the top left row position of the screen
                         xx           - the number of colums of the screen
                         yy           - the number of rows of the screen



     --------------------------------------------------------------------------
     screenup


     DESCRIPTION  ...    Moves an area of the screen up 1 row. The screen area
                         should be saved prior to calling this routine with
                         savescreen so the box pointer is initialised
                         correctly. Variables x and y are updated to the new
                         coordinates.

     DECLERATION  ...    procedure screenup (box :pointer; var x,y:
                                          byte; xx,yy :byte);


     PARAMETERS   ...    x           - the top left column position of the
                                       screen
                         y           - the top left row position of the
                                       screen
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen



     --------------------------------------------------------------------------
     scrollx


     DESCRIPTION  ...    Scroll a defined area of the screen left or right and
                         clears the remaining lines in a given attribute.


     DECLERATION  ...    procedure scrollx (where :char; x,y,xx,yy,
                                             cols,colour :byte);


     PARAMETERS   ...    where       -  the direction characters e.g.
                                        'l','L'   -  scroll left
                                        'r','R'   -  scroll right
                         x           - the top left column position
                         y           - the top left row position
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen
                         cols        - the number of columns to be shifted
                         colour      - the attribute to clear empty lines


     --------------------------------------------------------------------------
     scrolly


     DESCRIPTION  ...    Scroll a defined area of the screen up or down and
                         clears the remaining lines in a given attribute.


     DECLERATION  ...    procedure scrolly (where :char; x,y,xx,
                                             yy,lines,colour :byte);


     PARAMETERS   ...    where       - the direction characters e.g.
                                       'u','U'   -  scroll up
                                       'd','D'   -  scroll down
                         x           - the top left column position
                         y           - the top left row position
                         xx          - the number of colums of the screen
                         yy          - the number of rows of the screen
                         lines       - the number of rows to be shifted
                         colour      - the attribute to clear empty columns









     4.6  Strings:
     -------------






     --------------------------------------------------------------------------
     changechar


     DESCRIPTION  ...    Changes every instance of a character in a string.

     DECLERATION  ...    procedure changechar(var s: stype;
                                              search,replace :char);


     PARAMETERS   ...    s           - the string to be manipulated
                         search      - character that is searched
                         replace     - character that replaces search

     TPFError     ...    0           - ok
                         1           - character not found


     --------------------------------------------------------------------------
     compare


     DESCRIPTION  ...    Compares two strings, ignoring case.

     DECLERATION  ...    function compare(s1,s2: stype): boolean;


     PARAMETERS   ...    s1          - first compare string
                         s2          - second compare string


     RETURNS      ...    true        - strings are the same
                         false       - strings are not the same



     --------------------------------------------------------------------------
     deletechar


     DESCRIPTION  ...    Deletes all occurances of a specified character.

     DECLERATION  ...    procedure deletechar(var s: stype; ch :char);


     PARAMETERS   ...    s           - the string to be manipulated.
                         ch          - the character to be deleted.

     TPFError     ...    0           - ok
                         1           - character not found


     --------------------------------------------------------------------------
     deleteleft


     DESCRIPTION  ...    Deletes all characters from the begining of a string
                         until a specified character is reached.

     DECLERATION  ...    procedure deleteleft(var s: stype; border :char);


     PARAMETERS   ...    s           - the string to be manipulated.
                         border      - the character at which deletion stops

     TPFError     ...    0           - ok
                         1           - character not found


     --------------------------------------------------------------------------
     deleteright


     DESCRIPTION  ...    Deletes all characters from the end of a string
                         until a specified character is reached.

     DECLERATION  ...    procedure deleteright(var s: stype; border :char);


     PARAMETERS   ...    s           - the string to be manipulated.
                         border      - the character at which deletion stops

     TPFError     ...    0           - ok
                         1           - character not found


     --------------------------------------------------------------------------
     leftend


     DESCRIPTION  ...    Return the left end of a string up to a specified
                         character.

     DECLERATION  ...    function leftend(var s: stype; border :char): stype;


     PARAMETERS   ...    s           - the string to be manipulated.
                         border      - the character at which the search stops

     RETURNS      ...    The new string.

     TPFError     ...    0           - ok
                         1           - character not found


     --------------------------------------------------------------------------
     lowercase


     DESCRIPTION  ...    Convert a string to lowercase.

     DECLERATION  ...    procedure lowercase(var s: stype);

     PARAMETERS   ...    s           - the string to be manipulated.


     --------------------------------------------------------------------------
     overwrite


     DESCRIPTION  ...    Overwrites part of a string with a substring.

     DECLERATION  ...    procedure overwrite (var s: stype; subs: stype;
                                              position :integer);


                         s           - the string to be manipulated.
                         subs        - the string that replaces s
                         position    - the position at which overwriting
                                       begins.

     TPFError    ...     0           - ok
                         1           - error


     --------------------------------------------------------------------------
     padcentre


     DESCRIPTION  ...    Pads a string to a specified length at any position
                         in a character.

     DECLERATION  ...    procedure padcentre (var s: stype; ch :char;
                                              position,length :integer);


     PARAMETERS   ...    s           - the string to be manipulated.
                         ch          - character used for padding
                         position    - the position at whic padding comences
                         length      - the new length of s

     TPFError    ...     0           - ok
                         1           - error


     --------------------------------------------------------------------------
     padends


     DESCRIPTION  ...    Extends a string by padding it at both ends.

     DECLERATION  ...    procedure padends(var s: stype; ch :char;
                                           length :integer);


     PARAMETERS   ...    s           - the string to be manipulated.
                         ch          - character used for padding
                         length      - the new length of s

     TPFError    ...     0           - ok
                         1           - error


     --------------------------------------------------------------------------
     padleft


     DESCRIPTION  ...    Pads the begining of a string and extends it a
                         specified length.

     DECLERATION  ...    procedure padleft(var s: stype; ch :char;
                                           length :integer);


     PARAMETERS   ...    s           - the string to be manipulated.
                         ch          - character used for padding
                         length      - new length of s

     TPFError    ...     0           - ok
                         1           - error


     --------------------------------------------------------------------------
     padright


     DESCRIPTION  ...    Pads the end of a string and extends it a specified
                         length.

     DECLERATION  ...    procedure padright(var s: stype; ch :char;
                                            length :integer);


     PARAMETERS   ...    s           - the string to be manipulated.
                         ch          - character used for padding
                         length      - new length of s

     TPFError    ...     0           - ok
                         1           - error


     --------------------------------------------------------------------------
     replace


     DESCRIPTION  ...    Deletes a specified number of characters and inserts
                         new substring.

     DECLERATION  ...    procedure replace(var s: stype; subs: stype;
                                           position,chars :integer);



     PARAMETERS   ...    s           - the string to be manipulated.
                         subs        - the string to be inserted
                         position    - the position at which replacement
                                       starts
                         chars       - the number of characters deleted prior
                                       to insertion.

     TPFError    ...     0           - ok
                         1           - error


     --------------------------------------------------------------------------
     rightend


     DESCRIPTION  ...    Return the right end of a string up to a specified
                         character.

     DECLERATION  ...    function rightend(var s: stype; border :char): stype;


     PARAMETERS   ...    s           - the string to be manipulated.
                         border      - the character at which the search stops

     RETURNS     ...     The new string.


     TPFError    ...     0           - ok
                         1           - character not found


     --------------------------------------------------------------------------
     seekstring


     DESCRIPTION  ...    Searches for a substring within a string.

     DECLERATION  ...    function seekstring (s,subs: stype;
                                            startpt :integer) :integer;


     PARAMETERS   ...    s           - the string to be manipulated.
                         subs        - the string that is searched
                         startpt     - the starting position of the search

     RETURNS     ...     The position of the substring.

     TPFError    ...     0           - ok
                         1           - error


     --------------------------------------------------------------------------
     stringend


     DESCRIPTION  ...    Returns a specified number of characters from the end
                         of a string.

     DECLERATION  ...    function stringend(s: stype; numberchars :integer)
                                            :stype;

     PARAMETERS   ...    s           - the string to be manipulated.
                         numberchars - the number of characters returned

     RETURNS     ...     The new string.

     TPFError    ...     0           - ok
                         1           - s is null
                         2           - other error


     --------------------------------------------------------------------------
     stringof


     DESCRIPTION  ...    Makes a new string made up of repetitions of a
                         substring.

     DECLERATION  ...    function stringof(s: stype; length :integer): stype;


     PARAMETERS   ...    s           - the string to be manipulated.
                         length      - length of the string returned.

     TPFError    ...     0           - ok
                         1           - error


     --------------------------------------------------------------------------
     uppercase


     DESCRIPTION  ...    Convert a string to uppercase.

     DECLERATION  ...    procedure uppercase(var s: stype);


     PARAMETERS   ...    s           - the string to be manipulated.



     --------------------------------------------------------------------------
     wordcount


     DESCRIPTION  ...    Counts the number of words in a string. A word is
                         considered to be any series of characters  not
                         including the space character (#32).

     DECLERATION  ...    function wordcount(s: stype) :integer;

     PARAMETERS   ...    s          the string to be manipulated.


