Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Text /
Chapter 8 - Dictionary Manager / Dictionary Manager Reference
Routines / Locating Records in a Dictionary


FindRecordInDictionary

The FindRecordInDictionary function searches a dictionary for a record that matches the specified key, and returns entries with the specified attributes.

FUNCTION FindRecordInDictionary 
                           (dictionaryReference: LongInt;
                            key: Str255;
                            requestedAttributeTablePointer: Ptr;
                            recordDataHandle: Handle): OSErr;
dictionaryReference
A number that specifies a particular open dictionary.
key
A Pascal string that denotes the key to be matched.
requestedAttributeTablePointer
A pointer to a table with attributes that you can request. This parameter provides a way for you to narrow the search to specified types of entries in the record. For instance, you could use the requested attributes table to specify only the verbs in the record that matches the key.
recordDataHandle
On entry, any valid handle. Upon completion, a handle to the
requested data.
DESCRIPTION
The FindRecordInDictionary function returns, in the recordDataHandle parameter, a handle to the record data: a collection of entries matching the key
and the requested attributes. FindRecordInDictionary returns the data in
standard Dictionary Manager data format--as shown in Figure 8-2 on page 8-6 and Figure 8-3 on page 8-7.

The Dictionary Manager uses the Memory Manager procedure SetHandleSize to set the size of the recordDataHandle parameter correctly. If the Dictionary Manager cannot change the size of the handle to accommodate the returned matched data, it returns a Memory Manager error.

To limit the search to specific types of attributes, you construct a requested attributes table and pass a pointer to that table to FindRecordInDictionary. The requested attributes table consists of a byte which specifies the number of attributes, followed by a list of attribute types, as shown in Figure 8-7 on page 8-16.

Table 8-2 lists constants for the currently defined attribute types.
Table 8-2 Defined attribute types for dictionary entries
ConstantValueExplanation
kNoun-1Noun
kVerb-2Verb
kAdjective-3Adjective
kAdverb-4Adverb

SPECIAL CONSIDERATIONS
FindRecordInDictionary may move memory; your application should not call this function at interrupt time.

RESULT CODES
In addition to the standard File Manager, Memory Manager, and Resource Manager errors, FindRecordInDictionary can return any of the following result codes.
noErr0No error
notBTree-410File is not a dictionary
btRecNotFnd-415Record cannot be found
btKeyLenErr-416Key length too great or equal to zero

SEE ALSO
File Manager error codes are described in Inside Macintosh: Files. Memory Manager error codes are described in Inside Macintosh: Memory. Resource Manager error codes are described in Inside Macintosh: More Macintosh Toolbox.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996