FindFile

FindFile searches for all files that match a given search string.

Syntax

FindFile(strFile, optTagFilesFound, optNumTimeout)

strFile

The name of the file(s). Use wildcards (*) to find multiple files. For example, *.gif to find all GIF files or log*.txt to find all log files in a sequence (log001.txt, log002.txt, log003.txt).

By default, the function only searches the project folder, but you can specify a file path (either relative or absolute) to search elsewhere. For example, if strFile is defined as…

\\<host name or IP address>\Logs\log*.txt

…then the function will search the Logs directory on the specified server.

Note: Follow the conventions of the target platform for the file path and name, and separators. For example, a file path in Windows starts with a drive letter and uses backward slashes as separators (C:\path\to\file), while a file path in Linux starts at the root directory and uses forward slashes as separators (/path/to/file).

optTagFilesFound

An array (of String type) that will receive the names of the matching files. The array name must be enclosed in quotes; if it is not, the function will try to get the contents of the array.

This parameter is optional. If no value is specified, the file names will not be saved and the function will only return the number of files found. For more information, see "Returned value" below.

The specified array will receive only the file names and not their paths, even if you define strFile to search outside the project folder. Also, the file names will be saved starting at array position 1 (for example, MyArray[1]).

Please keep in mind that this function is executed synchronously, so there might be some delay in updating the specified array. As such, you should not develop a project screen so that it tries to use the array immediately after it calls this function. For example, you should not write a VBScript procedure that calls this function on one line and then references the array on the next. You can change this behavior, if necessary, by forcing this function to be executed asynchronously on the client. For more information, see Notes below.

optNumTimeout

The timeout period (in milliseconds) for the function to be successfully executed.

This parameter is optional. If no value is specified, the project runtime will continue searching until it has completely searched the location defined by strFile.

Please keep in mind that this function is executed synchronously, so if optNumTimeout is not specified and strFile is poorly defined, the entire project — both the project runtime server and its clients — might pause while it searches for the files. You can change this behavior, if necessary, by forcing this function to be executed asynchronously on the client. For more information, see Notes below.

Note: This feature is not supported in projects that are configured to run on the Embedded target platform. For more information, see About target platforms, product types, and target systems.

Returned value

This function returns one of the following possible values:

Notes

By default, this function is executed on the project runtime server even when it is called in a screen on a project thin client, which means it only affects directories and files that are located on the server and all paths must be specified in that context. You can change the default behavior to force this function to be executed on the client where it is called, but if you do so, you must keep in mind that the change will affect not just this function but also several other File functions. To change the behavior of these functions, use a text editor to open your project file (<project name>.app) and then edit the following property:

[Options]

ExecuteFileFunctionsOnClient=1

If you change these functions to be executed on the client, also check the scope of the array that is specified for optTagFilesFound. If the scope is Local, the array will be updated only on the client where this function is executed. If the scope is Server, the array will be updated first on the client where this function is executed and then that update will be sent to the server.

Also, when this function is called on the client (regardless of where it is executed), the array that is specified for optTagFilesFound will be updated only after the entire script (for example, Command animation) that contains this function is executed.

As an alternative to calling this function on the client — for example, if you need to have the array updated immediately rather than after the entire script is executed — consider creating a VBScript Global Procedure that contains this function and any other associated code, and then call the RunGlobalProcedureOnServer function on the client in order to run that procedure.

Examples

Find all text files in the project folder:

FindFile("*.txt")

Find all Microsoft Word files in the project folder, and then send the names of the matching files to StringArray, within a timeout period of 1000 milliseconds:

FindFile("*.doc", "StringArray", 1000)