fListFile (Function)

ONLINE HELP
FOR WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Functions for managing external files

fListFile

Presentation

Example

Procedure that handles each listed file (syntax 2 only)

Full interruption of fListFile (syntax 2)

Partial interruption of fListFile (syntax 2)

Managing errors

Equivalence

Listing the sub-directories of a directory

Related examples

See also

fListFile (Function)

In french: fListeFichier

Lists the files found in a directory and returns the list of files. The listed files are sought from the given directory.

Other use: For each file found, fListFile can automatically call a specific procedure written in WLanguage. This procedure is used to handle the current file. In this case, fListFile returns the number of listed files.

Note: In 64-bit Windows, the access to a system directory from a 32-bit executable can be performed in a directory that differs from the expected one. See Native 64-bit and native 32-bit for more details.

Versions 15 and later

This function is now available for the Android applications.

New in version 15

This function is now available for the Android applications.

Versions 16 and later

This function is now available for the Windows Phone applications.

New in version 16

This function is now available for the Windows Phone applications.

Versions 17 and later

This function is now available for the iPhone/iPad applications.

New in version 17

This function is now available for the iPhone/iPad applications.

Versions 18 and later

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

This function is now available in the code of stored procedures.

New in version 18

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

This function is now available in the code of stored procedures.

This function is now available in Android Widget mode.

This function is now available in Windows Store apps mode.

This function is now available in the code of stored procedures.

Versions 21 and later

This function is now available in Universal Windows 10 App mode.

New in version 21

This function is now available in Universal Windows 10 App mode.

Example

See additional examples

AFile, ResFileList are strings
// Lists the ".BMP" files found in "C:\MyDocuments".
// The browse is also performed in the sub-directories and it can be interrupted.
ResFileList = fListFile("\MyDocuments\*.BMP", frRecursive + frInterruptible)
// For each file found
FOR EACH STRING AFile OF ResFileList SEPARATED BY CR
// Add the file into TABLE_FileTable
TableAdd(TABLE_FileTable, AFile)
END

AFile, ResFileList are strings
// Lists the ".BMP" files found in "\MyDocuments".
// The browse is also performed in the sub-directories and it can be interrupted.
ResFileList = fListFile("\MyDocuments\*.BMP", frRecursive + frInterruptible)
// For each file found
FOR EACH STRING AFile OF ResFileList SEPARATED BY CR
// Add the file into TABLE_FileTable
TableAdd(TABLE_FileTable, AFile)
END

// Lists the ".BMP" files found in "C:\MyDocuments".
// The FileAttribute procedure returns the number of read-only files.
ResFileList = fListFile("C:\MyDocuments\*.BMP", "FileAttribute")

// Lists the ".BMP" files found in "\MyDocuments".
// The FileAttribute procedure returns the number of read-only files.
ResFileList = fListFile("\MyDocuments\*.BMP", "FileAttribute")

Syntax

Listing the files found in a directory Hide the details

<Result> = fListFile(<Path and Generic Name of Files> , <Options>)

<Result>: Character string

Full name of listed files, separated by CR characters (Carriage Return).

Caution: The function can return files whose short name corresponds to the filter used (while the long name does not correspond to this filter).

<Path and Generic Name of Files>: Character string (with quotes)

Path and generic name of files to list. The generic characters (* and?) are allowed. Special cases:
if the directory and the drive are not specified: the search path is built from the current drive and from the current directory for this drive.
if the drive is not specified while the directory is specified: the search path is built from the current drive and from the directory passed in parameter.
if the drive is specified while the directory is not specified, the search path is built from the specified drive and from the current directory for this drive.
Versions 15 and later
This parameter can be in Ansi or Unicode format.
New in version 15
This parameter can be in Ansi or Unicode format.
This parameter can be in Ansi or Unicode format.
Path and generic name of files to list. The generic characters (* and?) are allowed.
This parameter can correspond to a full path or to a relative path in relation to the current directory (returned by fCurrentDir). This parameter is case sensitive.
Reminder: In Android, the file system is read-only on the device and on the emulator. An application has the rights to write into its setup directory or into one of its sub-directories, as well as onto the external memory (SDCard).
Versions 16 and later
In Windows Phone: The file path corresponds to a relative path in relation to the current directory. The current directory corresponds to the data directory of application.
Reminder: In Windows Phone, only the files found in the data directory associated with the application can be handled.
New in version 16
In Windows Phone: The file path corresponds to a relative path in relation to the current directory. The current directory corresponds to the data directory of application.
Reminder: In Windows Phone, only the files found in the data directory associated with the application can be handled.
In Windows Phone: The file path corresponds to a relative path in relation to the current directory. The current directory corresponds to the data directory of application.
Reminder: In Windows Phone, only the files found in the data directory associated with the application can be handled.
Versions 17 and later
This parameter can correspond to a full path or to a relative path in relation to the current directory (returned by fCurrentDir). This parameter is case sensitive.
Reminder: On iPhone/iPad, an application has the rights to write into its setup directory or into one of its subdirectories.
New in version 17
This parameter can correspond to a full path or to a relative path in relation to the current directory (returned by fCurrentDir). This parameter is case sensitive.
Reminder: On iPhone/iPad, an application has the rights to write into its setup directory or into one of its subdirectories.
This parameter can correspond to a full path or to a relative path in relation to the current directory (returned by fCurrentDir). This parameter is case sensitive.
Reminder: On iPhone/iPad, an application has the rights to write into its setup directory or into one of its subdirectories.

<Options>: Combination of Integer constants

Option used to define the information returned as well as the type of browse performed for the directory files:
This parameter is ignored.
Versions 15 and later
fPathUNICODE
New in version 15
fPathUNICODE
fPathUNICODE <Result> will be a string in Unicode format.
This constant is ignored because <Result> is always a Unicode string.
Versions 16 and later
This constant is ignored in Windows Phone.
New in version 16
This constant is ignored in Windows Phone.
This constant is ignored in Windows Phone.
fdFullInformation Each line (separated by carriage return - CR) contains the following information:

<Full File Name> + TAB + <Size in Bytes> + TAB + <Date of Last Modification> + TAB + <File Attributes>

The date is in YYYYMMDDHHMMSS format. The attributes are identical to the ones returned by fAttribute.
Versions 16 and later
This constant is ignored in Windows Phone.
New in version 16
This constant is ignored in Windows Phone.
This constant is ignored in Windows Phone.
fdInterruptible The browse can be interrupted by pressing the ESC key. The function will return the name of the listed files until the interruption.
This constant has no effect in Windows Phone and Windows Store apps.
frNotRecursive The browse is a non-recursive browse. The sub-directories are ignored.
frRecursive
(Default value) The browse is a recursive browse. The sub-directories are automatically taken into account.
frNoHiddenFile If the frFullInformation constant is used, the hidden files are not listed (attribute = "H").
Versions 16 and later
This constant is ignored in Windows Phone.
New in version 16
This constant is ignored in Windows Phone.
This constant is ignored in Windows Phone.
frNoHiddenDirectory If the frFullInformation constant is used, the hidden directories are not listed (attribute = "H").
Versions 16 and later
This constant is ignored in Windows Phone.
New in version 16
This constant is ignored in Windows Phone.
This constant is ignored in Windows Phone.

Listing the files found in a directory by calling a procedure for each file Hide the details

<Result> = fListFile(<Path and Generic Name of Files> , <Procedure name> [, <Pointer> [, <Options>]])

<Result>: Integer

Number of listed files.

<Path and Generic Name of Files>: Character string (with quotes)

Path and generic name of files to list. The generic characters (* and?) are allowed. Special cases:
if the directory and the drive are not specified: the search path is built from the current drive and from the current directory for this drive.
if the drive is not specified while the directory is specified: the search path is built from the current drive and from the directory passed in parameter.
if the drive is specified while the directory is not specified, the search path is built from the specified drive and from the current directory for this drive.
Path and generic name of files to list. The generic characters (* and?) are allowed.
This parameter can correspond to a full path or to a relative path in relation to the current directory (returned by fCurrentDir). This parameter is case sensitive.
Reminder: In Android, the file system is read-only on the device and on the emulator. An application has the rights to write into its setup directory or into one of its sub-directories, as well as onto the external memory (SDCard).
Versions 17 and later
This parameter can correspond to a full path or to a relative path in relation to the current directory (returned by fCurrentDir). This parameter is case sensitive.
Reminder: On iPhone/iPad, an application has the rights to write into its setup directory or into one of its subdirectories.
New in version 17
This parameter can correspond to a full path or to a relative path in relation to the current directory (returned by fCurrentDir). This parameter is case sensitive.
Reminder: On iPhone/iPad, an application has the rights to write into its setup directory or into one of its subdirectories.
This parameter can correspond to a full path or to a relative path in relation to the current directory (returned by fCurrentDir). This parameter is case sensitive.
Reminder: On iPhone/iPad, an application has the rights to write into its setup directory or into one of its subdirectories.

<Procedure name>: Character string (with or without quotes)

Name of WLanguage procedure ("callback" procedure) that will be called for each listed file. This procedure is used to handle the current file.
This procedure has the following format:

PROCEDURE <Procedure Name> (<Path>, <File Name>,
<Change>, <Procedure Pointer>)

The parameters of this procedure are optional.
There is no need to pass parameters to this procedure. Indeed, these parameters are automatically filled whenever a file is processed.
The name of the procedure must correspond to a character string in quotes.

<Pointer>: Optional integer

Pointer passed to the <Procedure name> procedure.
Parameter passed to the function. This parameter is not necessarily an integer (it can be a string, ...).

<Options>: Optional Integer constant (or combination of constants)

Type of browse performed for the directory files:
Versions 15 and later
fPathUNICODE
New in version 15
fPathUNICODE
fPathUNICODE <Result> will be a string in Unicode format.
This constant is ignored because <Result> is always a Unicode string.
fdInterruptible The browse can be interrupted by pressing the ESC key.
This constant has no effect.
frNotRecursive The browse is a non-recursive browse. The sub-directories are ignored.
frRecursive
(Default value) The browse is a recursive browse. The sub-directories are automatically taken into account.
This parameter is ignored. The browse is a non-recursive browse and it cannot be interrupted.

Remarks

Procedure that handles each listed file (syntax 2 only)

For each file found, fListFile automatically calls the <Procedure Name> procedure. This procedure is a local or global procedure.

To create this procedure:

Create a global procedure ("Insert .. New global procedure" in the code editor).Create a global procedure (from the code editor: on the "Code" pane, in the "Procedures" group, expand "New" and select "New global procedure").
Fill the procedure declaration as follows:

PROCEDURE <Procedure Name> (<Path>, <File Name>,
<Change>, <Procedure Pointer>)

<Path> is the path of file used (it always ends with a "\" character ; for example, "C:\WINDEV\").
<File Name> is a character string containing the name of file found.
<Change> is a constant set to:
- flFirstFile when the file is the first file listed in <Path>,
- flChangeDir when the file is the first file listed in a sub-directory of <Path> (which means that a change of directory occurred),
- flFile in all the other cases.
The different values that can be taken by <Change> are as follows:
Current file <Change>
Dir\File 1 flFirstFile
Dir\File n flFile
Dir\SubDir 1\File 1 flChangeDir
Dir\SubDir 1\File m flFile
Dir\SubDir 2\File 1 flChangeDir
Dir\SubDir 2\File x flFile

<Procedure Pointer> is an integer whose value is the one passed to the <Pointer> parameter of fListFile. If <Pointer> is not specified, <Pointer> is set to 0.

To retrieve the value of <Procedure Pointer>, the value of <Procedure Pointer> must be assigned to the value of <Pointer> in the procedure by Transfer (see the detailed example at the top of the page).

Note: The parameters of this procedure are optional: you have the ability to specify the name and the path for example.

Full interruption of fListFile (syntax 2)

fListFile cannot be interrupted as long as all the files have not been browsed.

To force the interruption of the browse, use the following code line in the <Procedure name> procedure:

RESULT False

For example, the "FindProduct" procedure is automatically called by fListFile:

PROCÉDURE FindProduct(Path, FileName)
...
// Stop requested?
Multitask(-1)
IF KeyPressed(kpEscape) = True THEN
Info("The search will be stopped")
RESULT False
END
...
RESULT True

In this case, fListFile returns the number of files browsed until the call to "Result False".
In any other case (to continue the browse), <Procedure name> MUST return True.

An error is generated if <Procedure name> returns no value (neither True nor False).

No error is generated if the procedure returns no value.

Partial interruption of fListFile (syntax 2)

In order for the <Procedure Name> procedure not to be run for a given file, use the following code line:

RESULT True

For example, the "FindProduct" procedure is automatically called by fListFile:

PROCÉDURE FindProduct(Path, FileName)
...
// File to ignore
IF FileName = "WrongFile.XLS" THEN
RESULT True
END
...
RESULT True

In this case, fListFile automatically calls the <Procedure Name> procedure for the next listed file.

An error is generated if <Procedure name> returns no value (neither True nor False).

No error is generated if the procedure returns no value.

Managing errors

Caution: fListFile returns no error code. To find out whether an error was generated by this function, use ErrorInfo associated with the errMessage constant.

Equivalence

The operating mode of fListFile is equivalent to the operating mode of ceListFile.

The only difference is:

fListFile is using a directory found on Pocket PC from a WINDEV Mobile application.
ceListFile is using a directory found on Pocket PC from a WINDEV application.

Listing the sub-directories of a directory

To list the sub-directories of a directory, use fListDirectory.

Tip: fListFile can also be used to list the sub-directories of a directory.
Example:

fListFile("c:\temp\anim\.", proc)
// Don't forget the '.' at the end of string to identify the directories

PROCÉDURE proc(Dir, file, nChange, ptr)
Trace(Dir)

Related Examples:

Unit examples (WINDEV): The fListFile function

[ + ] Using fListFile and its syntax that directly returns the list of files/directories found in string format.

Component : wd240std.dll