FILESTR()
 Reads a portion of a file into a string
------------------------------------------------------------------------------
 Syntax

     FILESTR(<cFile>, [<nLength>], [<nOffset>],
        [<lCtrl-Z>]) --> cCharacterstring

 Arguments

     <cFile>  Designates the file from which a string is read.

     <nLength>  Designates how many characters you want to read from a
     file (up to a maximum of 65520 bytes).  The default is read all
     characters.

     <nOffset>  Designates an offset within the file from which the
     <nLength> characters or the rest of the file, are read.  The default is
     from the first character (0).

     <lCtrl-Z>  If this parameter is designated as .T., only data up to
     the first Ctrl-Z is read in.  The default is read all data (.F.).

 Returns

     FILESTR() returns the string read in from the designated file.

 Description

     FILESTR() also offers the capability to read files or a portion of them,
     into a string.  This is only possible with a function call, where the
     file name may contain a drive and path designation.  If you implement
     the <lCtrl-Z> parameter, you can be sure the function only reads data up
     to the first Ctrl-Z and ignores whatever might remains in of the file.

     In contrast to the CA-Clipper Fxxxx() functions, a disadvantage of
     FILESTR() is a slower access speed, since the file you want to read
     cannot be held open.

 Notes

     .  This function reads all available bytes in working memory (up
        to 65520).  The amount of available free memory is determined by
        calling MEMORY(1).

     .  As recommended in share mode, no other programs should write
        in the net through SETSHARE(2) for the duration of the read.

 Examples

     .  Read in a file completely:

        ? FILESTR("C:\TEXT\TEST.TXT")            // Displays file text

     .  Read in everything to the first Ctrl-Z:

        cVar  := FILESTR("C:\TEXT\TEST.TXT", .T.)

     .  The file TEST.TXT contains "ABCDEFGHIJ".  Four characters,
        beginning from position 3, are to be read:

        ? FILESTR("C:\TEXT\TEST.TXT", 4, 3)      // "CDEF"

     .  Read the maximum that fits into the available working memory:

        cVar  := FILESTR("C:\TEXT\TEST.TXT", MEMORY(1) *1024 -100)

See Also: STRFILE() SETSHARE() ALLOFREE()*