GETDIR(), GETFILE(), LOCFILE(), PUTFILE()

Using these functions definitely comes under the category of not reinventing the wheel. They bring up various standard dialogs. GETDIR() displays the Select Directory dialog. GETFILE() shows the Open File dialog. LOCFILE() tries to find the specified file first, but reverts to the Open File dialog if it can’t. PUTFILE() brings up the Save As dialog.

All these functions let you navigate through directories. There’s some internal setting that remembers where you last navigated. Calling one of these functions without specifying an initial directory starts you where you left off—even if you call a different one of the functions. That’s right—they all share this hidden setting. Fortunately, you can override FoxPro’s memory by SETting DEFAULT or CDing to the directory you’d like to start in.

Lately, we use all the functions in this group (except GETDIR()) a lot less than we used to. Instead, in our applications, we usually use the Common Dialogs ActiveX control these days. The Common Dialogs offer more control over various settings than these functions do, and make our apps work more like other Windows apps. (The Common Dialogs control has its own aggravations, too, but for the most part, the advantages of using it outweigh the disadvantages.)

Usage

cDirName = GETDIR( [ cStartDir [ , cCaption [ , cTitle
           [ , nFlags [ , lRootOnly ] ] ] ] ])

VFP 7 uses two separate dialogs depending on how many parameters you pass. If you pass just the first two parameters, it uses its own internal dialog, just like in previous versions. But if you pass more parameters, VFP uses the SHBrowseForFolder function from the Windows API. What’s the difference? First, the SHBrowseForFolder function gives you control over the text in the title bar, so your apps can have more informative dialogs than “Select Directory” (yeah, why am I selecting a directory?).

Another difference allows a myriad of flags to control numerous options in the dialog, such as whether to disable the OK button if the user has selected something that is not in the file system (such as “My Network Places”) and whether to DISPLAY FILES as well as folders. The constants are shown in the table below, and are additive. Add the multiple values together to combine the options. A complete description and more constants are available by searching MSDN for SHBrowseForFolder.

Actually, any integer, positive or negative, works without error. Here are some undocumented values. Only one, 255, offers a capability not accounted for in the table above; the others might be easier to read by defining your own constants and using the following values. Note that these values are not additive, with the possible exception of 255.

Before VFP 5, we used GETDIR() a lot in development. CD GETDIR() was an easy way to change the default directory without having to remember where we are or where we’re going. Since VFP 5, though, we can CD ? for the same effect.

In versions prior to VFP 7, and also in VFP 7 when using the internal GETDIR() version (that is, passing two or fewer parameters), GETDIR() (and CD) can't see directories that are flagged as "system." They simply don't appear. Fortunately, ADIR() can find them if you give it the right values ("DS") for the third parameter. The VFP 7 SHBrowseForFolder interface (pass three or more parameters) shows those directories flagged as "system."

Example

#DEFINE BIF_USENEWUI 64
cDataDir = GETDIR("AppDir\", "Where's the data?")
cDataDir = GETDIR("AppDir\", "Where's the data?", ;
           "Store Your Data", BIF_USENEWUI)

Usage

cFilePath = GETFILE( [ cExtensions [ , cTextCaption
                     [ , cButtonCaption  [ , nButtonChoice
                     [ , cDialogTitle ] ] ] ] ] )
cFilePath = LOCFILE( cFileName [ , cExtensions
                     [ , cTextCaption ] ] )

Use LOCFILE() when you’re looking for a specific file and want to ask the user for help if you can’t find it. (LOCFILE() checks the current directory first, then the FoxPro path.) Use GETFILE() to let the user choose any input file. We use GETFILE() a lot in developer tools where the user specifies a file to process.

These two functions handle Esc/Cancel differently. GETFILE() returns the empty string—good choice. LOCFILE(), since it was looking for a specific file, gives an error (#1—“File Does Not Exist”).

The current incarnation of the Open File dialog has a text box for the file name with a drop-down list underneath labeled “Files of Type”. When you specify multiple extensions, the first extension in the list determines what appears as the current choice in the Files of Type drop-down. However, when you drop it open, you see all the extensions you specified, as well as an All Files choice. Extensions separated by vertical bars or semicolons are listed each on a separate line in the drop-down, while comma-separated lists are listed all on the same line (as in “*.DOC, *.XLS, *.PPT”).

No matter what you specify for nButtonChoice, there’s a Help button on the dialog. In addition, when you set nButtonChoice to 0 (or omit this parameter), there is a disabled Code Page button. With the other choices, that position is occupied by either the New or None button. We haven’t found a way to make the Code Page button come alive.

The cTextCaption parameter specifies a string that appears next to the text box for entering the file name. The space for this caption is pretty limited, so you need to keep this one short.

This one's really a Windows thing. Both these functions let you specify a nonexistent file. They don't create the file. They just hand you back the full path to some file that ain't there. Always use FILE() to check the result of GETFILE() and LOCFILE() for existence.

Example

cInpFile = GETFILE("PJX","Choose a Project","Choose")
IF FILE(cInpFile)
   * Process the project in some way.
ELSE
   * Cancel because the user did.
   DO CleanUp
   RETURN
ENDIF

* Find a particular file.
cCustomer = LOCFILE("Customer.DBF","DBF","Customer")
IF FILE(cCustomer)
  ... process file here
ENDIF

Usage

cFilePath = PUTFILE( [ cTextCaption [ , cFileName
                     [ , cExtensions ] ] ] )

Use PUTFILE() to choose a file for output. It lets you pick an existing file or specify a new one. Regardless of the setting of SAFETY, if the user picks an existing file, he’s prompted with an overwrite message. We haven’t found any way to get rid of this message and substitute our own. The Files of Type drop-down behaves as described above for GETFILE().

PUTFILE() expects parameters in a very different order than the other functions. It’s a real pain and means we always ended up looking up the parameters for this whole group of functions before VFP 7 saved us with IntelliSense. But we do see the point. In every case, the parameters are pretty much in the order of likelihood of their being used.

Example

cOutFile = PUTFILE("Result file:","Results.txt","TXT")
IF NOT EMPTY(cOutFile)
   REPORT FORM MyReport TO FILE (cOutFile) ASCII
ELSE
   WAIT WINDOW "Report Canceled" NOWAIT
ENDIF

See Also

ChDir, File(), Set Default