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

 SCREENFILE()
 Writes screen content to a file
------------------------------------------------------------------------------
 Syntax

     SCREENFILE(<cFileName>, [<lOverwrite>],
        [<nOffset>]), [<lTrim>] --> nBytesWritten

 Arguments

     <cFileName>  Designates the name and path of the screen file.

     <lOverwrite>  Designates whether you are to append to an existing
     file (.T.), or to overwrite it (.F.).  The default is overwrite (.F.).

     <nOffset>  Designates the file offset from which you append, when
     <lOverwrite> is designated as .T..  The default is the end of file.

     <lTrim>  If this optional parameter is designated as .T., the
     function trims the file when the written data ends and before the last
     byte of the file.  The default is do not trim (.F.).

 Returns

     SCREENFILE() returns the number of bytes written to the screen file.

 Description

     SCREENFILE() saves the contents of a screen to a file.  Since the
     CA-Clipper SAVE SCREEN and RESTORE SCREEN also work with windows when
     you use the CA-Clipper Tools Extended Drivers, use SCREENFILE() to save
     the entire screen.  The number of characters you can write this way
     depends on the respective screen mode.  For example, in a 50-line VGA
     mode you can write 8000 instead of 4000 characters.  Use SCREENSIZE() to
     determine the exact screen size at any given time.  You can only use the
     <nOffset> parameter when you specify <lOverwrite> at the same time.
     <nOffset> then specifies from which position in the screen file the new
     screen data is to be written.  If the <nOffset> position lies before the
     end of the file, the file is overwritten.  If it exceeds the end of the
     file, the data is appended.  The default value for <nOffset> is
     selected, so if you omit it and designate <lOverwrite> as .T., the file
     is appended.  This behavior allows you to save the contents of several
     screens to a file.

     It is possible that a screen could be written to an already existing
     file, and that everything beyond this screen is trimmed off.  The
     <lTrim> logical parameter must be designated as .T..

 Notes

     .  If SCREENFILE() creates a new file, use SETFCREATE() to create
        an alternate attribute for this new file .

     .  If you turn on the CA-Clipper Tools CSETSAFETY() internal
        switch, the target file is not overwritten, even if the <lOverwrite>
        parameter is designated as .F..

     .  Wildcards within the file name are not permitted here.

 Examples

     .  An existing file is overwritten:

        SCREENFILE("screen.tst")                        // Result:  4000>
        SCREENFILE("\screen.tst")                       // Result:  4000>
        SCREENFILE("a:\screen.tst")                     // Result:  4000

     .   On a VGA card in 50-line mode:

        SCREENFILE("screen.tst")                        // Result:  8000

     .  The file is appended:

        SCREENFILE("screen.tst", .T. )                  // Result:  4000

     .  Insert a screen from an offset of 4000 ( i.e., after the first
        screen):

        SCREENFILE("screen.tst", .T., 4000)             // Result:  4000

     .  Insert a screen after the third screen:

        SCREENFILE("screen.tst", .T., 12000)            // Result:  4000

     .  Overwrite an existing file in the fourth screen and trim off
        the rest of the file:

        SCREENFILE("screen.tst", .T., 12000, .T.)       // Result:  4000

     .  Wildcards not permitted:

        SCREENFILE("screen.*")                          // Result:  0