PUTFILE( ) Function

  • Article

Invokes the Save As dialog box and returns the file name you specify.

PUTFILE([cCustomText] [, cFileName] [, cFileExtensions])

Return Values

Character

Parameters

  • cCustomText
    Specifies custom text to appear in the Save As dialog box.

  • cFileName
    Specifies the default file name displayed in the text box.

  • cFileExtensions
    Specifies file name extensions. Only file names with the specified extension are displayed in the scrollable list of the Save As dialog box when the All Files check box is cleared. The first extension in cFileExtensions is automatically appended to the file name entered if an extension isn't included with the file name. The cFileExtensions parameter cannot exceed 254 characters in length. For a list of Visual FoxPro file extensions and corresponding creator types, see the File Extensions and File Types online topic.

    The character expression cFileExtensions can take one of the following forms:

    • cFileExtensions can contain a single extension, such as PRG, and only file names with that extension are displayed.
    • cFileExtensions can contain a list of file name extensions separated by semicolons. For example, if you include PRG;FXP, Visual FoxPro displays all file names with the extensions .prg and .fxp.
    • If file names have the same root name but different extensions (for example, Customer.prg and Customer.fxp), Visual FoxPro displays only the file name with the extension that appears first in cFileExtensions.
    • cFileExtensions can contain a list of file name extensions separated by vertical bars, such as PRG|FXP. In such a case, Visual FoxPro displays all file names with listed extensions, even if the files have the same root name.
    • If cFileExtensions contains only a semicolon (;), Visual FoxPro displays all file names that don't have an extension.
    • If cFileExtensions is an empty string, Visual FoxPro displays the names of all files in the current directory or folder.
    • If cFileExtensions contains MS-DOS wildcards, such as the question mark (?) and asterisk (*), Visual FoxPro displays all file names with extensions that meet the wildcard criteria. For example, if cFileExtensions is ?X?, all file names with the extensions .fxp, .exe, .txt, and so on, are displayed.

Remarks

Use PUTFILE( ) to choose an existing file name or specify a new file name. PUTFILE( ) returns the file name with its path. If you don't enter a file name, PUTFILE( ) returns the default file name (specified with cFileName) and extension (specified by cFileExtensions). If you choose Cancel or press ESC, PUTFILE( ) returns an empty string. You can use the file name that PUTFILE( ) returns to name a file and save it to disk.

Example

The following example creates a delimited data file from any existing table the user chooses. GETFILE( ) is used to find and open a table and PUTFILE( ) is used to return the name of the target file.

gcTableName = GETFILE('DBF', 'Open Table:')
USE (gcTableName)
gcDelimName = ALIAS( ) + '.DLM'
gcDelimFile = PUTFILE('Delimited file:', gcDelimName, 'DLM')
IF EMPTY(gcDelimFile)  && Esc pressed
   CANCEL
ENDIF
COPY TO (gcDelimFile) DELIMITED   && Create delimited file
MODIFY FILE (gcDelimFile) NOEDIT

See Also

FILE( ) | GETEXPR | GETFILE( ) | GETPICT( ) | LOCFILE( )