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> | <group file name expC> (<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 (*.*)

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:

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:

a.getFile("","Title",true,"Web Images (*.jpg,*.png,*.gif,*.bmp)")

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

a.getFile("","Title",true,"FILE ()")

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).