DP_FileFind CFML Custom Tag

Download | Revision History | Usage | Ideas for Use

This ColdFusion 4.5+ CFML custom tag provides the ability to recursively search for specific file types (extensions) across the server from any starting point. Results can be sent to the screen, to a file, to an HTML table, or to a CFQuery object.

Download back to top

This tag requires Macromedia's Cold Fusion development enviroment, version 4.5x or later. All downloads and code are covered by our Source Code Policy.

DP_FileFind.zip, 2.83kb Zip-Format Archive

Revision History back to top

July 25, 2004 Version 1.0

Removed documentation from the downloadable archive to ease maintenance.

November 24, 2002: Minor Update.

Fixed a problem with null "attribute" returns.

July 10, 2001

Initial Release.

Usage back to top

This tag can traverse a server-side directory structure and return as output all the files sporting specific extensions. For example you could find all "BAK" and "TMP" files on the C: drive or all the "GIF" files in the d:\wwwroot\ folder. DP_FileFind is, at its simplest, a wrapper for the CFDirectory tag. The tag enhances CFDirectory functionality with multiple output options, recursive capability, and multiple file type searching.

Here are a few tips and tidbits that you should probably be aware of before using the tag.

DP_FileFind is quite fast over small structures, but if set to recurse over a very large directory structure this tag can take quite a while to run. You may want to set a "RequestTimeOut" to ensure that the tag has enough time to finish.
As mentioned DP_FileFind is a recursive tag. This means that the tag calls itself internally to complete its tasks. Since each instance of the tag creates its own memory allocation space this may get memory and processor intensive over very large directory structures. You should be prepared to split very large tasks into groups of smaller tasks.
If the tag is configured to output a Query object an internal request variable will be set: "Request.FileFindResults". This variable is required to allow the recursive child tags to collect output in a centrally accessible location. Because of this you should not use the variable name "Request.FileFindResults" in any templates that use DP_FileFind.
If you're interested in recursion in ColdFusion you may want to explore the source of the tag a bit. We're not saying it's the best example that's out there, but it should get the neurons firing.

Tag Usage

DP_FileFind takes six parameters:

Directory	Required. The directory you want to search over. For example "C:\WinNT\".
Recurse	"Y" or "N" (Default). If "Y" the tag will search all sub directories of the search directory. If "N" only the search directory will be examined.
ExtensionsToFind	Defaults to null. A comma-separated list of the extensions you wish to find, if left blank all files will be returned. For example "gif,cfm,htm". Leading dots should not be included and the search is case-insensitive.
OutputStyle	This attribute dictates the style of the tag's output. Note that the actual data output is the same regardless of the style used. The attribute can accept four values: "Screen" (Default): The results are dumped to the screen as pipe ("\|") separated lists. Each line ends with a <br> tag. "File": The results are dumped to a pipe ("\|") separated text file named in the "OutputFile" attribute. Each record is delimited by a newline. "Query": The results are dumped into a CF Query recordset object. The Query's name is determined by the value of the "OutputQuery" attribute. The query will be placed in the "Caller" scope. "HTML": The results are dumped to an HTML formatted table suitable for printing.
OutputQuery	Defaults to "FileFindResult". The name of the query to create and populate with the results of the tag. If the OutputStyle attribute is not "Query" this attribute is ignored.
OutputFile	Defaults to "FileFindResult.txt". The name of the file to append the tag results to. If the file does not exist it will be created. Note that if no path is given the file will be created in the system root folder ("C:\winnt\win32" in NT). If OutputStyle attribute is not "File" this attribute is ignored.

Tag Output

Although the location and type of the tag's output varies with the "OutputStyle" attribute the data is always in the same format. For each file that matches the extensions being searched for the following fields are returned (the values of each field match the output of the CFDirectory tag):

File: The full system path and file name of the file.
Size: The size, in bytes, of the file.
DateLastModified: The datetime stamp of the file's last modification.
Attributes.: The system attributes of the file.

Tag Example

This example searches for "EXE", "COM", and "BAT" types files in the C:\WinNT folder and subfolders. A file, FileFindResults.txt, is created at the root of the C: drive to hold the results. Note that if C:\FileFindResults.txt already existed the results would be appended to it instead:

<cfmodule template="DP_FileFind.cfm"
          Directory = "C:\WinNT"
          Recurse = "Y"
          ExtensionsToFind = "EXE,COM,BAT"
          OutputStyle = "File"
          OutputFile = "C:\FileFindResults.txt">
</cfmodule>

The following example searches for all "GIF" files on the server's C: drive and collects the results in a query named "QueryOne":

<cfmodule template="DP_FileFind.cfm"
          Directory = "C:"
          Recurse = "Y"
          ExtensionsToFind = "GIF"
          OutputStyle = "Query"
          OutputQuery = "QueryOne">\
</cfmodule>

Query output is best if more data needs to be culled from the results. For example if you'd like to calculate the total disk space being used by "PDF" files on your server you would need to first search for PDF, then total the values in the "Size" column.

Ideas for Use back to top

Here are some ideas for using this tag in your applications:

You can easily count the number of any specific file type on your server. Counting CFM or HTML files might offer you a rough figure for the number of pages in your site.
By looping over the query output and totaling the sizes of files you can create reports of disk space utilization per file type.
TXT files created with the tag can be compared to create custom reports of new files and file changes.
A TXT file can be created of the server's root before a migration. Another TXT file created after the migration can be compared to it to ensure that the file lists are identical and the migration went smoothly.
The query output can be used to populate a database with names and sizes of downloadable media files available. DP_FileFind can then be run periodically to update the database with new files that are available. This may be more performant than dynamic file listings for each request.
You could create a simple file type (media) search over a directory structure allowing your customers to find all MP3 or AVI files, for example. This is especially useful if the directory can be uploaded to by the public.
The tag is fairly simple and can be easily modified for many tasks. You can use the CFFile READ action to search within found HTML files for specific strings. You could create a more advanced, wildcard based, file matching routine. This code could be used simply as a framework to create your own recursive file system worms for nearly any purpose.