StrFile

Writes a string to a file

Syntax

      StrFile(<cCharacterstring>, <cFile>, [<lOverwrite>],
             [<nOffset>], [<lCutOff>]) --> <nRecordedByte>

Arguments

<cCharacterstring> : the character string to write to a file. <cFile> : File name. Drive and path designations are permitted, but no wildcards. <lOverwrite> : If NIL or .F., determines whether or not a new file is created. When .T., it writes to an existing file. The default is create new file (.F.).

<nOffset> : An offset within the file from which the <cCharacterstring> string is to be written. The default is End of file. <lCutOff> : When this optional parameter is designated as .T., the function truncates the file if data written ends before the last file byte. The default is no cut off (.F.).

Returns

<nRecordedByte> : the actual number of bytes written.

Description

This function provides another capability besides writing the contents of a string to a file. In contrast to the Fxxxx() functions, only one function call is necessary to write data to a file. However, it can result in some speed disadvantages, since files acted on by StrFile() cannot be held open. If the target file is unavailable, the StrFile() function always creates it.

Notes

. The attribute to create a new file, can be designated with the SETFCREATE() function.

. As recommended with the share mode, reads and writes from other network programs should be locked out with SETSHARE() for this period of time.

. This function acknowledges the setting for CSETSAFETY().

Examples

      .  Add to the end of a file:
         ? StrFile("ABCDEFGH", "TEST.TXT", .T.)             // Result: 8

      .  A file with drive and path designations, result: 10:

         ? StrFile("0123456789", "C:\TEXT\TEST.TXT", .T.)

      .  Data in an existing file is overwritten from position 20 with
         a designated string:

         ? StrFile("NANTUCKET", "TEST.TXT", .T., 20)        // Result: 9

      .  A 5-character string is written starting at position 10 in an
         existing file 20-characters long.  Since the final parameter is
         specified as .T. once, and specified as .F. once, you see different
         results:

         ? StrFile(REPLICATE("X", 20), "TEST.TXT")
         ? StrFile("AAAAA", "TEST.TXT", .T., 10, .F  // "XXXXXXXXXXAAAAAXXXXX"
         ? StrFile("AAAAA", "TEST.TXT", .T., 10, .T  // "XXXXXXXXXXAAAAA"

Seealso

FileStr()

 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()*