Find a string in a low level file.
──────────────────────────────────────────────────────────────────────────────

 Syntax

        GT_FLocate(<nFileHandle>,<cString>,[<lCaseSensitive>],;
                   [<nStartPos>]) --> nLocation

 Arguments:

      <nFileHandle> is the handle of a file that has been opened or
      created with one of Clipper's low level file functions.

      <cString> is the string you are looking for.

      <lCaseSensitive> is an optional logical value to describe the
      type of search. If True (.T.) the search will be a case sensitive
      search. The default is False (.F.)

      <nStartPos> is an optional numeric value to describe the position
      at which the search will start. The default is 0.

 Returns:

      The byte location of the string if a match is found. -1 if there
      was an error reading the file. -2 if a match could not be found.

 Description:

      GT_FLocate() can be used to find a text string in a file that has
      been opened with one of Clipper's low level file functions.

      Note that as well as returning the location of the hit GT_Flocate()
      will also place the file pointer at the first byte of the match. If
      no match was found the file pointer will be in it's original
      location.

 Examples:

      // The following example opens a file and prints every byte location
      // of the target word.

      local nFile := fopen("LIFE.42")
      local nHit  := 0
      do while nHit >= 0
         if (nHit := GT_FLocate(nFile,"Meaning")) >= 0
            ? nHit
         endif
      enddo
      fclose(nFile)

 Source: FLOCATE.PRG

 Author:  Dave Pearson