ScreenFile() - Save a screen to disk
 Writesthe screen to a file
──────────────────────────────────────────────────────────────────────────────

 Syntax

     ScreenFile( <cFileName>, [<lAppend>],
        [<nOffset>]), [<lTrim>] --> nBytesWritten

 Arguments

     <cFileName> is the filename and path of the screen file.

     <lAppend> controls whether you will append a screen to the file (.T.)
     or overwite the existing file (.F.).  The default is overwrite (.F.).

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

     <lTrim> is an optional parameter that specifies whether the file
     should be truncated after the curetn screen or not.  The default is
     (.F.) do not truncate file.

 Returns

     ScreenFile() returns the number of bytes written to disk.

 Description

     ScreenFile() may be used to save either a screen or many screens to a
     disk file. Whereas CA-Clipper's SAVE and RESTORE screen comnmand and
     function will work only on the currently active window, ScreenFile()
     works on the entire application window.

     Specifying the <lAppend> parameter as .T. will allow you to store more
     than one screen shot to a file.

     You can only use the <nOffset> parameter when you specify a .T.
     <lAppend>.  <nOffset> determines which position in the screen file the
     new screen data is to be written from.  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.

 Notes

     ■  Wildcards within the file name are not permitted here.

     ■  This function does not alter the cursor position.

 Examples

     ■  An existing file is overwritten:

        ScreenFile("C:\Screens\Demo1.Sht")              // Result:  4000

     ■   On a VGA card in 50-line mode:

        ScreenFile("C:\Screens\Demo1.Sht")              // Result:  8000

     ■  The file is appended:

        ScreenFile("C:\Screens\Demo1.Sht", .T.)         // Result:  4000

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

        ScreenFile("C:\Screens\Demo1.Sht", .T., 4000)   // Result:  4000

     ■  Insert a screen after the third screen:

        ScreenFile("C:\Screens\Demo1.Sht", .T., 12000)  // Result:  4000


 Files:  Library is MRWINDOW.LIB.