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

Function:    FSAVESCREEN()

Purpose:     Save screen to a disk file to be restored with FRESTSCREEN().

Syntax:      FSAVESCREEN( filename )

Arguments:   filename    - Character filename to which to save the screen.
                           If the filename is not fully qualified, the
                           saved screen file will be placed in the current
                           default directory.

Returns:     True if screen saved successfully.  If a file I/O error
             occurs while opening on writing the file, FSAVESCREEN() will
             return false.

Description: FSAVESCREEN() is a screen function used to save a screen to a
             disk file, to be later restored with the companion
             FRESTSCREEN() function.

Notes:       FSAVESCREEN() opens the disk file with the Clipper low level
             file functions.  If a file create or open failure occurs,
             FSAVESCREEN() returns false.

             Although FSAVESCREEN() uses 4k of memory during operation,
             that memory is released when the function exits.  Saving
             screens to disk can conserve enormous amounts of memory
             rather that storing multiple screens in memory variables.

             FSAVESCREEN() will check for bad parameters or file I/O
             errors and return false if something went wrong.  The way to
             check that you can successfully save a screen to memory is to
             check MEMORY(0) and verify at least 4K of free pool memory is
             available.  Not only does this function conserve memory use
             but also makes error correction a little easier.

             Clipper 5.0

             FSAVESCREEN() uses the values of MAXROW() and MAXCOL() to
             determine the screen size, and hence the number of bytes to
             write to <filename>.  To prevent strange behavior, neither
             MAXROW() nor MAXCOL() must be changed with the SETMODE()
             function between a FSAVESCREEN() and FRESTSCREEN() call.

Example:     *-- save the current screen to file, and save some memory(0)
             FSAVESCREEN("screen1.scr")
             CLEAR
             *-- do something
             FRESTSCREEN("screen1.scr")


             *-- old way of saving screens to memory variables
             IF MEMORY(0) < 4
                *-- error message
             ELSE
                SAVE SCREEN TO memvar
             ENDIF

             *-- new way saves memory and two lines of code
             IF .NOT.  FSAVESCREEN("scrfile1.tmp")
                *-- error message
             ENDIF

Source:      RL_FSAVE.PRG

See also:    FRESTSCREEN()