+---------------------------------+
|            LOCFILE()            |
+---------------------------------+
LOCFILE(<expC1>
        [, <expC2>] [, <expC3>])

-----------------------------------
Locates a file on disk.
Return value - Character
-----------------------------------

The LOCFILE() function locates a file on disk and returns the file name
with its fully qualified path.  If the file cannot be located, the Open
file dialog is brought forward so you may search for the file.

<expC1>
        Include the name of the file to locate in the character expression
<expC1>.  If just a file name is included in <expC1>, FoxPro first looks
in the default directory for the file.  If the file isn't in the default
directory, the FoxPro path is then searched.  If the file is located,
the file's fully qualified path is returned with the file name.  If
<expC1> has no extension, it applies extensions from <expC2> in order in
an attempt to locate the file.

        If you include a directory specification with the file name in <expC1>,
the specified directory is searched.  If the file cannot be found in the
specified directory, the default directory is searched, and then the
FoxPro path is searched.  If the file is located, the file's fully
qualified path is returned with the file name.

        If the file cannot be located in the default directory, along the
FoxPro path or in a specified directory, the Open file dialog is
displayed.  The Open file dialog can be used to locate the file.  When a
file is chosen from the dialog, the file name is returned with the
file's fully qualified path, and the file's path is appended to the
FoxPro path.

        If the Open file dialog is exited by choosing the Cancel push button or
by pressing Esc, an alert 'File does not exist.' (error message 1) is
displayed.

<expC2>
        The optional character expression <expC2> specifies the extensions of
the files displayed in the Open File dialog's scrollable list when the
All Files check box is not checked.  For a complete list of the file
extensions used by FoxPro, see the File Extensions section in this help
facility.

        The file extension expression <expC2> can take a variety of forms:

        . <expC2> can contain a single extension (for example, 'PRG'), and only
files that have that extension are displayed.

        . <expC2> can contain a list of file extensions separated by semicolons
(for example, 'PRG;FXP').  In this example, LOCFILE() displays all files
with the extensions PRG and FXP.

        However, if files have the same name but different extensions (for
example, CUSTOMER.PRG and CUSTOMER.FXP), only the file with the first
extension in the file extension list is displayed.  In this example, if
the file extension list contains 'PRG;FXP', just the CUSTOMER.PRG file
is displayed.

        . <expC2> can contain a list of file extensions separated by vertical
bars (for example, 'PRG|FXP').  In this case, ALL files with these
extensions are displayed, even if the files have the same names.

        . If <expC2> contains just one semicolon (';'), all files without an
extension are displayed in the scrollable list.

        . If <expC2> is the null string, all files in the current directory are
displayed.

        . <expC2> can also contain DOS wildcard characters (* and ?).  All
files with extensions that meet the wildcard criteria are displayed.
For example, if <expC2> is '?X?', all files with the extensions FXP,
EXE, TXT and so on are displayed.

<expC3>
        The optional character expression <expC3> is the prompt displayed at
the top of the Open File dialog.

-----------------------------------

See Also:  FILE(), GETFILE(), PUTFILE()

-----------------------------------