Programming Microsoft Access 2000 (Microsoft Programming Series)

You use the FileSearch object model (shown in Figure 8-1) to integrate file searches into your applications. You can search the hard drives of a computer and any drives on LAN-linked computers. This object exposes the functionality of the Open and the Find dialog boxes. As Figure 8-1 shows, the FoundFiles object and PropertyTests collection are hierarchically dependent on FileSearch.

Figure 8-1. The FileSearch object is one of the shared Office objects.

There are two basic ways to specify a file search, and each approach corresponds to options in the Open dialog box:

• You can designate a single criterion (a filename or pattern, a file type, or a path).
• You can designate multiple search criteria programmatically using the PropertyTests collection.

With the second approach, you specify arguments that serve as input to the Open dialog box. You can use this dialog box to specify multiple search criteria and rules for concatenating them, such as And and Or operators. Use FoundFiles to enumerate the return set from either approach.

The FileSearch object has two methods: NewSearch and Execute. The NewSearch method resets all FileSearch properties to their default values. You can then edit the properties that require special values for a particular file search. If you do not invoke NewSearch at the beginning of a search specification, your new search inherits its property settings from the previous search.

You invoke the Execute method to launch a file search after you specify it. This method can take several arguments that control the arrangement of filenames in the FoundFiles object and that control whether to update the file index before conducting a new search. The return value from this method is the number of filenames that match the search specification.

Conducting a Basic File Search

Many FileSearch properties permit flexible search specifications. The simple code sample below specifies a search and retrieves its return set. It creates an instance of the FileSearch object by using the FileSearch property of the Application object. Then it restores all FileSearch property settings to their default values by invoking the NewSearch method. Next, it assigns the LookIn and FileName properties, which specify where to look and what to look for. The test machine for this search includes a series of .mdb files with names such as Chapter1 and Chapter2. The SearchSubFolders property accepts a Boolean value that indicates whether to restrict the search to the current folder or extend it to subfolders of the LookIn property setting.

After creating the specification for the search, the procedure invokes the Execute method for the FileSearch object. This method has a return value that indicates the number of files that meet the search criteria. If the value is 0, the criteria yield no matching filenames and the procedure issues a message indicating that no files were found. If the criteria yield one or more matching files, the procedure displays the Count property of the FoundFiles object before presenting each name in FoundFiles.

Sorting the Return Set

The following sample sorts the return set from a search by file size. The first two parameters for the Execute method designate the sort criterion and order, respectively. The constant names for the first parameter indicate the variable on which to sort the returned filenames. These constants are: msoSortByFileName, msoSortByFileType, msoSortByLastModified, and msoSortBySize. The Execute method's second parameter specifies either ascending or descending order. The sample designates a search sorted by file size in descending order. This differs from the previous sample, which returned results in the default ascending order based on filename.

The message box that displays the return set shows the file sizes and filenames. You pass the FoundFiles object to the FileLen function to determine the size of a file. The file sizes are rounded to the nearest 1/1000 of a MB.

NOTE

Searching Based on File Contents

Even with a simple search, such as the two previous samples, you can selectively search for specific text in the document or its DocumentProperty object. The sample below does this. You use the FileSearch object's TextOrProperty property to target a text string in the file's body or its Properties collection. Notice that you can specify folders on remote computers using the Uniform Naming Convention (UNC). (\\cab233\c\cab points to the cab folder in the share named c of a computer named cab233.)

Some file searches can be lengthy. By specifying a restrictive FileSearch property, you can dramatically improve the performance of the Execute method. For example, the sample above finds all Word documents in a folder that contain a specific string. By using the msoFileTypeWordDocuments constant for the FileType property, the sample restricts the search to just Word document files. You might be tempted to specify *.* for the FileName property and then filter the returned results, but this would seriously impair performance. For the sample files in the cab folder on the cab233 computer, the difference is 22 seconds for the msoFileType constant vs. 300 seconds for the *.* FileName specification. (Notice that it takes just three lines to time the operation—one line before the Execute and two more immediately after it.)

Specifying Multiple Search Criteria

The advanced search format lets you specify multiple search criteria for your return set in the FoundFiles object. You use the Add method two or more times to specify multiple criteria for the PropertyTests collection. Your individual criterion specifications must include Name and Condition settings.

The Add method can specify a Connector setting as well as one or two Value settings. The Add method's Condition setting determines whether a criterion requires Value settings. You view the members of the MsoCondition class to see all the available options. (Figure 8-2 shows an excerpt.) Your Connector settings can take one of two values to specify how to combine a criterion with other criteria. This setting enables And or Or operators for merging a criterion with other search criteria. You use Or to treat the criterion separately, and you use And to combine the designated criterion with others. And is the default setting. The Condition, Value, and Connector settings together offer the same functionality as the Find dialog box.

You can enumerate PropertyTests members using a For…Each loop. Each member constitutes a unique search criterion. The Name property identifies the criterion as you enumerate them.

Figure 8-2. You use the members of the msoCondition enumeration group to specify conditions for advanced criteria in the PropertyTests collection of the FileSearch object.

The last FileSearch sample, shown below, has three segments. The first segment specifies the criteria after setting a reference to a FileSearch object. The sample targets all database files between two dates. It shows the correct syntax for invoking the Add method for the PropertyTests collection. The first criterion designates a database type. The second criterion denotes files last modified between January 1, 1996, and June 30, 1999. The msoConnectorOr setting indicates that files must meet both criteria separately to be in the return set. You need not specify a Connector property for the second criterion because it adopts the default msoConnectorAnd value. Before displaying the return set, the procedure enumerates the PropertyTests members in its second segment. The final segment displays the return set.