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

Function:    CHECKFILE()

Purpose:     Verify valid filenames, optionally popping up a pick list.

Syntax:      CHECKFILE( @filename [, filelist [, mustexist [, confirm ]]])

Arguments:   @filename   - Character file name to check.  The file name
                           may be fully qualified or have no directory
                           path, in which case the current default
                           directory will be used for file searches.  This
                           parameter must be PASSED BY REFERENCE by
                           prefacing the variable name with the @
                           character as shown above.  Passing this
                           variable by reference lets CHECKFILE() change
                           the value to a new filename selected through
                           the pop-up directory option.

             listfiles   - Optional logical value indicating whether or
                           not to pop-up a file listing window if
                           wildcards are entered.  The default value is
                           True (.T.)

             mustexist   - Optional logical value indicating whether or
                           not to verify that the filename entered exists.
                           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.)

Returns:     True if a valid filename was entered and all optional flag
             conditions are met.  If any of these conditions fail, or if
             the user presses ESCAPE, false is returned.

Description: CHECKFILE() is a high level file function usually used during
             the VALID clause of an @...GET...READ, to test if the
             filename entered is a valid DOS file name.  The optional
             flags permit control over other features provided by
             CHECKFILE() which may or may not be desired, depending upon
             the application.

             The default parameters make CHECKFILE() an ideal VALID clause
             for entering target filenames for such things as reports.
             The defaults are: <mustexist> is False since the target file
             must not exist in this situation, and <confirm> is True to
             notify the user before overwriting a file.  The RLIB function
             GETFILE() makes a call to CHECKFILE() in this way.

Notes:       The <listfiles> parameter is True by default.  If the
             filename that is to be checked contains wildcards (* or ?),
             CHECKFILE() will pop-up a centered file directory window of
             the directory specified in the filename.  If no directory
             path was entered as part of the filename, the directory
             listing will be of the current directory.  This feature can
             be disabled by setting the <listfiles> parameter to False.
             If the <filename> parameter is blank and the <listfiles>
             parameter is True (the default), a directory listing will
             pop-up when ENTER is pressed.

             The pop-up file listing is provided by the RLIB function
             PICKFILE().  See the documentation on PICKFILE() for more
             information.

             If a filename is selected from the pop-up directory listing,
             CHECKFILE() uses Clipper's pass-by-reference feature to
             assign the selected file name to the variable referenced by
             the @filename parameter.  In the case of the READ...VALID
             example cited above, this has the effect of stuffing the
             selected filename into the READ, but in a much more elegant
             manner than KEYBOARDing characters.  However, since the "@"
             pass-by-reference operator cannot be applied to array
             elements, the filename argument to CHECKFILE() may not be an
             array element.  Attempting to do so will result in a compile
             time error - "@ error" in Summer '87 or "Illegal use of @
             (pass by reference) operator" in 5.0.  The bottom line is
             that, fortunately, the compiler won't let you do it.  For
             this reason, only use memory variables as the data being
             READ.

             The <mustexist> parameter is False by default.  Its purpose
             is to optionally force CHECKFILE() to verify that the
             filename entered does in fact exist.  This is useful in
             applications that request the user to enter a filename for a
             function that requires an existing file.  An example would be
             a function that uses MEMOWRITE(MEMOEDIT(MEMOREAD(filename)))
             to implement a rudimentary editor.  The statement to query
             the user for a file name must verify the file exists.
             CHECKFILE() can do all that with one VALID statement.

             The <confirm> parameter is True by default.  Its purpose is
             to optionally force CHECKFILE() to confirm that the user
             wants to overwrite a file that already exists.  This is
             useful in report applications where the user is queried to
             enter a target print file name for disk output.

             If an optional parameter is to be skipped a dummy parameter
             must be supplied in its place.  Use a null ("") for a dummy
             parameter.

             If a condition is not met, CHECKFILE() will BLIP() or BUZZ()
             (depending on the severity) and display a BOXASK() or
             SAYINBOX() error message in color "W+/R" on color monitors or
             "N/W" on monochrome monitors.

             The part of CHECKFILE() that verifies valid DOS filenames
             checks the filename for any of the invalid characters
             ( "/[]*<>|+=;,?) using the ANYCHARSIN() function, and
             displays an error message indicating the offending character
             if one is encountered.

Example:     mfile = SPACE(120)
             @ 10, 0 SAY "Enter target file for report output:";
             @ 10,37 GET mfile PICTURE "@!KS40" VALID CHECKFILE(@mfile)
             READ

Source:      RL_CHECK.PRG

See also:    ANYCHARSIN(), GETFILE(), PICKFILE()