Legacy Document

Inside Macintosh: Files /

Chapter 2 - File Manager / File Manager Reference

Low-Level HFS Routines / Searching a Catalog

PBCatSearch

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): 
                        OSErr;

paramBlock

A pointer to a csParam variant of an HFS parameter block.

async

A Boolean value that specifies asynchronous (TRUE) or synchronous (FALSE) execution.

-->	ioCompletion	ProcPtr	A pointer to a completion routine.
<--	ioResult	OSErr	The result code of the function.
-->	ioNamePtr	StringPtr	A pointer to a volume name.
-->	ioVRefNum	Integer	A volume specification.
-->	ioMatchPtr	FSSpecArrayPtr	A pointer to an array of matches.
-->	ioReqMatchCount	LongInt	The maximum match count.
<--	ioActMatchCount	LongInt	The actual match count.
-->	ioSearchBits	LongInt	Enable bits for fields in criteria records.
-->	ioSearchInfo1	CInfoPBPtr	The values and lower bounds.
-->	ioSearchInfo2	CInfoPBPtr	The masks and upper bounds.
-->	ioSearchTime	LongInt	The maximum allowed search time.
<->	ioCatPosition	CatPositionRec	The current catalog position.
-->	ioOptBuffer	Ptr	A pointer to optional read buffer.
-->	ioOptBufSize	LongInt	The length of optional read buffer.

DESCRIPTION

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.

SPECIAL CONSIDERATIONS

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:

• AFP volumes do not use the ioSearchTime field. Current versions of the AppleShare server software search for 1 second or until 4 matches are found. The AppleShare workstation software keeps requesting the appropriate number of matches until the server returns either the number specified in the ioReqMatchCount field or an error.
• AFP volumes do not support both logical and physical fork lengths. If you request a search using the length of a fork, the actual minimum length used is the smallest of the values in the logical and physical fields of the ioSearchInfo1 record and the actual maximum length used is the largest of the values in the logical and physical fields of the ioSearchInfo2 record.
• The fsSBNegate bit of the ioSearchBits field is ignored during searches of remote volumes that support AFP version 2.1.
• If the AFP server returns afpCatalogChanged, the catalog position record returned to your application (in the ioCatPosition field) is the same one you passed to PBCatSearch. You should clear the initialize field of that record to restart the search from the beginning.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for PBCatSearch are

Trap macro	Selector
_HFSDispatch	$0018

RESULT CODES

noErr	0	No error (entire catalog has not been searched)
nsvErr	-35	Volume not found
ioErr	-36	I/O error
eofErr	-39	Logical end-of-file reached
paramErr	-50	Parameters don't specify an existing volume
extFSErr	-58	External file system
wrgVolTypErr	-123	Volume is an MFS volume
catChangedErr	-1304	Catalog has changed and catalog position record may be invalid
afpCatalogChanged	-5037	Catalog has changed and search cannot be resumed

SEE ALSO

See "Searching a Volume" on page 2-38 for a description of how to use PBCatSearch.