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

Function:    FRESTSCREEN()

Purpose:     Restore screen from a disk file saved with FSAVESCREEN().

Syntax:      FRESTSCREEN( filename )

Arguments:   filename    - Character filename from which to restore the
                           screen.  This file must have been created with
                           the companion FSAVESCREEN() function.  If the
                           filename is not fully qualified, FRESTSCREEN()
                           will search the current default directory for
                           the given filename.

Returns:     True if screen restored.  If a file I/O error occurs or if
             the <filename> does not exist, FRESTSCREEN() will return
             false.

Description: FRESTSCREEN() is a screen function used to restore a screen
             from a disk file created with the companion FSAVESCREEN()
             function.  Saving many screens to memory variables can
             quickly consume large amounts of free pool memory.  Each
             screen consumes at least 4000 bytes of memory.  Saving
             screens to disk files can limit this potential problem.

Notes:       FRESTSCREEN() opens the disk file with the Clipper low level
             file functions, reads the file contents, then restores the
             screen.  If a file open or read failure occurs, FRESTSCREEN()
             returns false.

             FRESTSCREEN() makes no checks on the contents of the file
             from which to restore a screen.  If the file was not saved
             with FSAVESCREEN() (or another similar save screen to file
             function) then results are guaranteed to be interesting.  For
             instance, FRESTSCREEN("c:bigfile.dbf") is guaranteed to put
             something strange looking on your screen.

             If the file is not at least 4000 bytes in size, or 4000 bytes
             are not read from the file, FRESTSCREEN() will fail and
             return False.

             Clipper 5.0

             FRESTSCREEN() uses the values of MAXROW() and MAXCOL() to
             determine the screen size, and hence the number of bytes to
             read from <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")

Source:      RL_FREST.PRG

See also:    FSAVESCREEN()