FileSystem.FindFileByName
Method | FindFileByName | ||||||
---|---|---|---|---|---|---|---|
Module | FileSystem | ||||||
Library | Core | ||||||
Action | Finds a file by name. | ||||||
Parameters | WarningUsing a wildcard such as NoteCase insensitive wildcards are supported only on Windows. | ||||||
NoteIgnored for non-NTFS filesystems. Unix | |||||||
NoteTurning off recursion will force use of safe (non-fast) search mode, even if fast mode is requested. However, since folders are then not recursed into, a non-recursive search ought in most cases to complete quite quickly. | |||||||
NoteSpecifying a folder will force use of slow search mode, even if fast mode is requested. | |||||||
| |||||||
NoteOn Windows, excluded paths can contain drive letters on Windows (e.g. C:\\), to skip scanning whole volumes. Ensure the exclude paths are complete paths starting from root. | |||||||
Return values | For each file found:
Old unicode filenames and v5.1+Disks that contain files that could have been created over two decades ago could well have filenames that were valid UCS-2 characters (in the range 0xd800 → 0xdfff), but that are not actually UTF-16 surrogate pairs, or just plain encoding may incorrectly exist on the file system quite happily, as NTFS allows them to still exist. However, when these filenames are converted to UTF-8, which is the preferred internal representation in the 1E Client, then they fail to translate exactly, so it is possible to lose the original reference to the exact file name. This translation problem will cause a warning like this to be issued in the client logs: 2020-03-30 14:50:37,048 WARN - Invalid UTF-16 sequence found starting at offset 24 just after this UTF-8 version [C:\dev\research\ucs2\bad??] Because the logging is also in UTF-8 then the 1E Client cannot write the UTF-16 character into the log, so the post conversion UTF-8 characters are presented and as in this case, the incorrect unicode values have been replaced with question marks because they are not UTF-16 so are not possible to convert to UTF-8; this just indicates where the issue is in the string. This is fundamental and applies to any string conversions in general, not just filenames specifically, but this method (and similar ones) is likely to find badly formed UTF-16 on the aged disk file system. When this occurs in this method, then the result set will contain a row like this:
This is because the filename cannot actually be found once it has been mutated into UTF-8 with missing character markers. The likelihood of encountering file names like this is very low, they have to be constructed by a scripting language, and are unlikely to work with most modern programs anyway. For further context, Windows started using UCS-2 from Windows NT 3.0 (1993) onwards and switched to UTF-16 from Windows 2000 (NT 5.0) but obviously any UCS-2 filenames had to remain usable. However this is ancient history. | ||||||
Example | FileSystem.FindFileByName(FileName:"ips.txt", Fast:true); @exclude = SELECT column1 AS Path FROM ( VALUES ("C:\\"), ("E:\\IgnoredFolder") ); FileSystem.FindFileByName(FileName:"ips.txt", Exclude:@exclude); | ||||||
Platforms |
| ||||||
Notes | This will search all fixed disks which is an expensive process and may take some time. Where possible, use a specific folder search and/or disable recursion to speed up the search. On Non-Windows, symbolically linked files will be ignored. |