Previous Book Contents Book Index Next

Inside Macintosh: Files /
Chapter 2 - File Manager / File Manager Reference
Low-Level HFS Routines / Searching a Catalog


The PBCatSearch function searches a volume's catalog file using a set of search criteria that you specify. It builds a list of all files or directories that meet your specifications.

FUNCTION PBCatSearch (paramBlock: HParmBlkPtr; async: Boolean): 
A pointer to a csParam variant of an HFS parameter block.
A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.
-->ioCompletionProcPtrA pointer to a completion routine.
<--ioResultOSErrThe result code of the function.
-->ioNamePtrStringPtrA pointer to a volume name.
-->ioVRefNumIntegerA volume specification.
-->ioMatchPtrFSSpecArrayPtrA pointer to an array of matches.
-->ioReqMatchCountLongIntThe maximum match count.
<--ioActMatchCountLongIntThe actual match count.
-->ioSearchBitsLongIntEnable bits for fields in criteria records.
-->ioSearchInfo1CInfoPBPtrThe values and lower bounds.
-->ioSearchInfo2CInfoPBPtrThe masks and upper bounds.
-->ioSearchTimeLongIntThe maximum allowed search time.
<->ioCatPositionCatPositionRecThe current catalog position.
-->ioOptBufferPtrA pointer to optional read buffer.
-->ioOptBufSizeLongIntThe length of optional read buffer.

The PBCatSearch function searches the volume you specify for files or directories
that match two coordinated sets of selection criteria. PBCatSearch returns (in the ioMatchPtr field) a pointer to an array of FSSpec records identifying the files and directories that match the criteria.

If the catalog file changes between two timed calls to PBCatSearch (that is, when you are using ioSearchTime and ioCatPosition to search a volume in segments and
the catalog file changes between searches), PBCatSearch returns a result code of catChangedErr and no matches. Depending on what has changed on the volume, ioCatPosition might be invalid, most likely by a few entries in one direction or another. You can continue the search, but you risk either skipping some entries or reading some twice.

When PBCatSearch has searched the entire volume, it returns eofErr. If it exits
because it either spends the maximum time allowed by ioSearchTime or finds the maximum number of matches allowed by ioReqMatchCount, it returns noErr. You
can specify a value of 0 in the ioSearchTime field to indicate that no time limit is to
be enforced.

Not all volumes support the PBCatSearch function. Before you call PBCatSearch to search a particular volume, you should call the PBHGetVolParms function to determine whether that volume supports PBCatSearch. See page 2-147 for details on calling PBHGetVolParms.

Even though AFP volumes support PBCatSearch, they do not support all of its features that are available on local volumes. These restrictions apply to AFP volumes:

The trap macro and routine selector for PBCatSearch are
Trap macroSelector

noErr0No error (entire catalog has not been searched)
nsvErr-35Volume not found
ioErr-36I/O error
eofErr-39Logical end-of-file reached
paramErr-50Parameters don't specify an existing volume
extFSErr-58External file system
wrgVolTypErr-123Volume is an MFS volume
catChangedErr-1304Catalog has changed and catalog position record may be invalid
afpCatalogChanged-5037Catalog has changed and search cannot be resumed
See "Searching a Volume" on page 2-38 for a description of how to use PBCatSearch.

Previous Book Contents Book Index Next

© Apple Computer, Inc.
2 JUL 1996