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

Function:    GETFILE()

Purpose:     Full featured user dialog box for GETing filenames.

Syntax:      GETFILE( [ filespec [, header [, mustexist [, confirm;
                      [, toprow [, restore ] ] ] ] ] )

Arguments:   filespec    - Optional character file name or file
                           specification.  If omitted or a non-character
                           parameter is passed, the default is blank.

             header      - Optional character title to display in the
                           header area of the filename entry dialog box.
                           If omitted or a non-character argument is
                           given, the default header text is "Enter
                           Filename".

             mustexist   - Optional logical value indicating whether or
                           not to verify that the filename entered exists.
                           If omitted or a non-logical argument is given,
                           the default value is False (.F.)

             confirm     - Optional logical value indicating whether or
                           not to confirm a file overwrite if the file
                           exists.  The default value is True (.T.)

             toprow      - Optional numeric top row of the filename entry
                           dialog box.  Valid rows are from row 0 to row
                           20.  If not specified or an invalid row value
                           or a non-numeric value is given, the default
                           row is row number 8.

             restore     - Optional logical value indicating whether or
                           not to save and restore the screen region
                           underneath the file entry box on exit.  If not
                           specified or a non-logical value is given, the
                           default is to restore the screen on exit, or
                           true.

Returns:     The filename entered or a null string ("") if escape pressed.

Description: GETFILE() is a file/screen function that puts up an entry
             dialog box in the following format:

                         +----------------------------------------+
                         |             Enter Filename             |
                         |----------------------------------------|
                         |                                        |
                         +----------------------------------------+

             The major use of this function is to query the user for a
             file name.  The arguments permit control over certain aspects
             such as whether or not to verify that the file entered
             already exists.

Notes:       All arguments are optional.  However a dummy must be passed
             to get at a trailing argument.

             The file entry box is drawn in double lines as show above,
             and is centered on the screen beginning at the top row
             specified.

             The filename is retrieved using the @ x,y GET...READ
             commands.  Therefore, in Clipper Summer '87 this function
             must not be embedded within a pending READ, such as in a
             VALID statement.  This is because nested READ's are not
             supported directly in the Summer '87 version of Clipper.

             In the Clipper 5.0 version of RLIB, GETFILE() declares
             GETLIST as a LOCAL which allows a call to GETFILE() to be
             nested within other READS.

             The width of the file entry dialog box is 42 characters.
             Since fully qualified filenames may be longer the @GET
             display scrolls horizontally by virtue of the @S40 function
             in the PICTURE template.

             GETFILE() uses the CHECKFILE() function to perform the edit
             checks specified by the various arguments.

Example:     *-- get a target file for a set printer command
             target = GETFILE("", "Enter target output file", .F., .T.)
             IF EMPTY(target)
                RETURN
             ENDIF
             SET PRINTER TO (target)


             *-- in this example, the default target file is OUTPUT.PRN
             *-- accepting all other GETFILE() defaults
             target = GETFILE("OUTPUT.PRN")
             SET PRINTER TO (target)


Source:      RL_GETFI.PRG

See also:    CHECKFILE(), BORDERBOX(), PATHTO(), PARENT(), TARGET()