PUTFILE( )

Topic group Related topics

Displays a dialog box within which the user can choose an exisiting file to overwrite or a new file name, and returns the file name.

Syntax

PUTFILE([<title expC>
[, <filename expC>
[, <extension expC>
[, <suppress database expL>>],
[<file types list expC> | <file group name expC> (<file types list expC>)]]]])

<title expC >

A title that is displayed at the top of the dialog box.

<filename expC >

The default file name that is displayed in the dialog box's entryfield. Without <filename expC >, PUTFILE( ) displays an empty entryfield.

<extension expC >

A default extension for the file name that PUTFILE( ) returns.

<suppress database expL>

Whether to suppress the combobox from which you can choose a database. The default is true; the Database combobox is not displayed. If you want to specify a value for <suppress database expL>, you must also specify a value or empty string ("") for <filename skeleton>, <title expC>, and <extension expC>.

<file types list expC>

A character expression containing zero, or more, file types to be displayed in the "Files of Type" combobox. If this parameter is not specified, the following file types will be loaded into the “Files of Type” combobox:

Projects (*.prj)

Forms (*.wfm;*.wfo)

Custom Forms (*.cfm;*.cfo)

Menus (*.mnu;*.mno)

Popup (*.pop;*.poo)

Reports (*.rep;*.reo)

Custom Reports (*.crp;*.cro)

Labels (*.lab;*.lao)

Programs (*.prg;*.pro)

Tables (*.dbf;*.db)

SQL (*.sql)

Data Modules (*.dmd;*.dmo)

Custom Data Modules (*.cdm;*.cdo)

Images (*.bmp;*.ico;*.gif;*.jpg;*.jpeg;*.pje;*.xbm)

Custom Components (*.cc;*.co)

Include (*.h)

Executable (*.exe)

Sound (*.wav)

Text (*.txt)

All (*.*)

If an empty string is specified, "All (*.*)" will be loaded into the Files of Type combobox.

<file type group name expC>

A character expression denoting a custom or built in file type goup name to use in the dialog.

For a custom file type group name

   Specify the group name followed by a list of one or more file types within parenthesis

      For example,  "Web Images (*.jpg,*.jpeg,*.bmp)"

For a built-in file type group name

   Specify the group name followed by a set of empty parenthesis

      For example, "Images ()"

dBASE will detect the left and right parenthesis and search for a matching built-in group name. If found, the list of file types associated with the built-in group will be added to the string that is added to the File Types combobox in the GetFile() or PutFile() dialog.

File Types between parenthesis must be separated by either a comma or a semi-colon and can be specified in any of the following formats:

<ext> or .<ext> or *.<ext>

where <ext> means a file extension such as jpg or txt. If a File Type List string is specified that contains unbalanced parenthesis or right parenthesis before left parenthesis, a new error will be triggered with the message:

"Unbalanced parenthesis in file type list"

Examples using file group name:

f = PUTFILE("Title","","",true,"Web Images (*.jpg,*.png,*.gif,*.bmp)")

or if you want to use one of the built in file type groups:

f = PUTFILE("Title","","",true,"FILE ()")

If one or more file types are specified, dBASE will check each file type specified against an internal table.

If a match is found, a descriptive character string will be loaded into the "Files of Type" combobox.

If a matching file type is not found, a descriptive string will be built, using the specified file type, in the form

   "<File Type> files (*.<File Type>)"

and will be loaded into the "Files of Type" combobox.

When the expression contains more than one file type, they must be separated by either commas or semicolons.

File types may be specified with, or without, a leading period.

The special extension ".*" may be included in the expression to specify that "All (*.*)" be included in the Files of Type combobox.

File types will be listed in the Files of Type combobox, in the order specified in the expression.

Note: In Visual dBASE 5.x, the GETFILE( ) and PUTFILE( ) functions accepted a logical value as a parameter in the same position as the new <file types list expC> parameter. This logical value has no function in dBASE Plus. However, for backward compatibility, dBASE Plus will ignore a logical value if passed in place of the <file types list expC>

Examples of <file types list expC> syntax.can be viewed here

Description

Use PUTFILE( ) to present the user with a dialog box from which they can choose an existing file or table or specify a new file or table name. If they choose an existing file, and SET SAFETY is ON, the user gets the standard "Replace existing file?" dialog box. If they choose "No", their choice is ignored and they are left in the PUTFILE( ) dialog box. PUTFILE( ) does not actually create or write anything to the specified file.

The PUTFILE( ) dialog box includes names of files whether they are currently open or closed. dBASE Plus returns the full path name of the file whether SET FULLPATH is ON or OFF.

By default, the dialog box opened with PUTFILE( ) displays file names from the current directory the first time you issue PUTFILE( ). After the first time you use PUTFILE( ) and exit successfully, the subdirectory you choose becomes the default the next time you use PUTFILE( ).

If <suppress database expL> is false, you can also choose from a list of databases. When a database is selected, the dialog box displays a list of tables in that database instead of files in the current directory.

The dialog box is a standard Windows dialog box. Users can perform many Windows Explorer-like activities in this dialog box, including renaming files, deleting files, and creating new folders. They can also right-click on a file to get its context menu. These features are disabled when the dialog is displaying tables in a database instead of files in a directory.

PUTFILE( ) returns an empty string if the user chooses the Cancel button or presses Esc.