[<<Previous Entry] [^^Up^^] [Next Entry>>] [Menu] [About The Guide]
 STRFILE()
 Writes a string to a file
------------------------------------------------------------------------------
 Syntax

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

 Arguments

     <cCharacterstring>  Designates the character string to write to a
     file.

     <cFile>  Designates a file name.  Drive and path designations are
     permitted, but no wildcards.

     <lOverwrite>  If not designated or designated as .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>  Designates 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

     STRFILE() returns 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 CA-Clipper 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"


See Also: FILESTR() SETSHARE() SETFCREATE() CSETSAFETY()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility. Written by Dave Pearson