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


FindRecordByIndexInDictionary

The FindRecordByIndexInDictionary function locates a record in a dictionary by index, and returns entries with the specified attributes.

FUNCTION FindRecordByIndexInDictionary
                           (dictionaryReference: LongInt;
                            recordIndex: LongInt;
                            requestedAttributeTablePointer: Ptr;
                            VAR recordKey: Str255;
                            recordDataHandle: Handle): OSErr;
dictionaryReference
A number that specifies a particular open dictionary.
recordIndex
The index for the record to be searched; its position in the dictionary. The index range for FindRecordByIndexInDictionary is from 0 to one less than the maximum number of records in a dictionary. To obtain the maximum index range of a dictionary, you can use the GetDictionaryInformation function (see page 8-24).
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 at that index.
recordKey
Upon succcessful completion, contains the key of the indexed record.
recordDataHandle
A handle that contains a collection of entries in the indexed record that match the requested attributes.
DESCRIPTION
The FindRecordByIndexInDictionary function returns, in the recordDataHandle parameter, a handle to the record data: a collection of entries from the specified record matching the requested attributes. FindRecordByIndexInDictionary 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 FindRecordByIndexInDictionary. The requested attributes table and a list of defined attribute types are described with the FindRecordInDictionary function, on page 8-26.

SPECIAL CONSIDERATIONS
FindRecordByIndexInDictionary 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, FindRecordByIndexInDictionary may return any of the following
result codes.
noErr0No error
notBTree-410File is not a dictionary
btRecNotFnd-415Record cannot be found

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.

For sample code that uses the FindRecordByIndexInDictionary function, see Listing 8-4 on page 8-17.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996