getFile() [Array]

Displays a dialog box from which a user can select multiple files.

Syntax

<oRef>.getFile( [<filename skeleton expC> [, <title expC> [, <suppress database expL>], [<file types list expC>]]] )

<oRef>

A reference to the array in which the selected filenames, or database aliases, will be stored.

A character string that specifies which files are to be displayed in the getFile( ) dialog. It may contain a valid path followed by a filename skeleton.

If a path was specified, it is used to set the initial path from which getFile( ) displays files.

If a path was not specified, the path from any previously run getFile( ) method, GETFILE( ) function, or PUTFILE( ) function will be used as the new initial path. If no previous path exists, the getFile( ) method uses the current dBASE directory - the path returned by the SET("DIRECTORY") function - as the initial path.

If no filename skeleton is specified, "*.*" is assumed and the getFile( ) method displays all files in the initial path described above.

A title displayed in the top of the dialog box. Without <title expC>, the getFile( ) methods' dialog box displays the default title. If you want to specify a value for <title expC>, you must also specify a value, or empty string (""), for <filename skeleton expC>.

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 expC> and <title 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.

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 the getFile( ) method to display a dialog box from which the user can choose, or enter, one or more existing file names. Any elements already in the array will be released.

Pressing the dialog's "Open" button closes the dialog and adds the selected files to the array.

The resulting array will contain a single column. Each element of the array will contain a single file path and name or, if selected from a database, the database alias followed by the table name.

The getFile( ) method returns the number of files selected, or zero if none are selected or the dialog is cancelled.

Example

a = new array

if ( a.getFile("*.*", "Choose Files", true) > 0 )

// Do something with the chosen files

endif

File list size

During file selection, selected file names are stored in a buffer with quotes around each file name and a space between them. The maximum number of files that can be selected is limited by the size of this buffer due to the Windows common file dialog requirement that the buffer be preallocated before opening the dialog.

When the.getFile( ) method is executed, it attempts to allocate a buffer with the sizes shown below. However, if the memory allocation is unsuccessful it cuts the requested size in half and tries again. It continues looping in this fashion until a successful allocation occurs, or the requested size becomes equal to zero. Should the requested file size become equal to zero, multifile selection is disabled and only a single file selection is allowed.

The maximum buffer sizes are:

Win 9x:

512*260 = 133120 filename characters

Win NT, 2000, XP:

4030*260 characters (approximately 1 megabyte of filename characters).