Click above to get retro games delivered to your door ever month!

  Name:     flocate() - locate text in a text file
            _xkey() - specify no abort in flocate()
            _xkeyval() - specify key that aborts flocate()
  Usage:    [<integer>] = flocate(<handle>,<string>,[<case>])
            [<logical>] = _xkey([<logical>])
            [<key>]     = _xkeyval(<key>)
  Params:   integer <handle> from a previous fopen() or fcreate()
            string <string> - the string to locate in the file
            logical <case> - optional case specifier. If <case>
            is .T., then the text of the file is converted to uppercase
            before it is compared to <string>, If <case> is false,
            then the text is converted to lowercase before it is
            compared to <string>. If this parameter is left off,
            then the  text is left as is. To search for non case
            sensitive text, use the appropriate <case> value, and
            then convert the string to be searched for to either upper
            or lower case. Note that converting the text in the file
            to either upper or lower case does not modify the text in
            the file.

            _xkey() tells flocate() if the user is allowed to abort
            an flocate() search via an ESCape key. _xkeyval() tells
            flocate() what the ESCape key is. The default value for
            _xkey() is always .T. (aborting allowed). the default
            abort key is ESCape (27) until you redefine it._xkey()
            parameters are logical .T. to turn user abort on, .F.
            to turn it off. _xkeyval() parameters are any valid
            inkey() value that you want the abort key to be. The
            default is to have abort capability on using ESCape.

  Returns:  integer equal to the offset of the first byte of the
            found string. The file pointer is positioned on the
            first letter of the found string. if a read error occurs
            flocate() returns a -1. If the string is not found, a -2
            is returned and the pointer is returned to the position where
            it started the search. If the user aborted the search, a
            -3 is returned and the pointer is returned to the position
            where it started the search.

            If no parameters are sent to _xkey() it returns the
            current state of the _xkey() flag - .T. equals on, .F.
            equals off. _xkeyval() returns the current abort key
            value as an integer.

 ---------------------------------- Example ---------------------------------

                 use names
                 handle = fopen("names.txt")
                 offset = flocate(handle,"dLESKO")
                 if offset < 0
                      ? "text not found...."
                 else
                      m_name = freadline(handle)
                      m_address = freadline(handle)
                      m_city = freadline(handle)
                      m_state = freadline(handle)
                      m_zip = freadline(handle)
                      replace name with m_name,;
                             address with m_address,;
                             city with m_city,;
                             state with m_state,;
                             zip with m_zip
                 endif

                 fclose(handle)
                 close databases

  Note:     Searching takes a about 1 second per 50k of file depending
            on type of machine used. If a no find occurs, (-2 or -3)
            the file pointer is left where it started. If a read
            error occurs (-1), then the file pointer can be anywhere.
            flocate() starts the search starting at the current
            pointer position and stops at the first occurrence of
            the found string. To search for multiple occurrences, find
            the first occurrence, freadstr() or fseek() past it, and
            start searching for the next occurrence.