Technical Q&A FL05

Searching Directories with PBCatSearch

Q: I need to get a list of files in a particular directory. Should I use PBCatSearch, or should I use indexed PBGetCatInfo or PBGetFInfo requests?

A: The "Cat" in PBCatSearch stands for "Catalog" and that is what PBCatSearch searches: the whole volume catalog. You can specify that matches found by PBCatSearch be limited to a specific directory by setting the fsSBFlParID bit in the ioSearchBits field of the parameter block, and then specify the directory to match on by setting ioFlParID in ioSearchInfo1 and ioSearchInfo2 to the directory ID you're interested in. However, using PBCatSearch may not be what you want to use for a couple of reasons:

• The matches PBCatSearch finds by matching on ioFlParID are only in that one directory -- not from any of that directory's subdirectories.
• Because the whole catalog file is searched, this is usually not the fastest way to look through a specific directory's contents.

If you need matches in both the directory *and* its subdirectories and you don't want to search the whole volume, there's a routine in the DTS sample code MoreFiles named IndexedSearch that is compatible with PBCatSearch's parameter blocks, except that IndexedSearch lets you specify what directory you want to search. IndexedSearch uses indexed PBGetCatInfo calls to search a directory and its subdirectories.

If you only need matches from a single directory (and not from that directory's subdirectories), there's another MoreFiles routine named GetDirItems. GetDirItems uses PBGetCatInfo to index through a directory's entries and returns FSSpecs to the entries found. In this case, indexed PBGetCatInfo calls are much faster than searching the whole catalog with PBCatSearch.