Legacy Document

Inside Macintosh: Text /

Chapter 8 - Dictionary Manager / Dictionary Manager Reference

Routines / Modifying a Dictionary

InsertRecordToDictionary

The InsertRecordToDictionary function inserts a dictionary record into the specified dictionary file.

 FUNCTION InsertRecordToDictionary
                           (dictionaryReference: LongInt;
                            key: Str255;
                            recordDataHandle: Handle;
                            whichMode: InsertMode): OSErr;

dictionaryReference

A number that specifies a particular open dictionary.

key

A Pascal string that denotes the key of the record to be inserted.

recordDataHandle

A handle containing the data for the new record.

whichMode

A value that determines whether the inserted record is to replace a record in the dictionary whose key matches the key parameter.

DESCRIPTION

The InsertRecordToDictionary function places the specified record into the specified dictionary. The recordDataHandle parameter must be a handle to data formatted like the data of a dictionary record, as shown in Figure 8-2 on page 8-6. Each entry in the data must be formatted as shown in Figure 8-3 on page 8-7. If the data size referenced by the recordDataHandle parameter exceeds the maximum of 4096 bytes, InsertRecordToDictionary returns a recordDataTooBigErr result code.

The whichMode parameter controls the insertion mode, the manner in which the insertion can take place. There are three possibilities, for which the Dictionary Manager defines three constants:

Constant	Value	Description
kInsert	0	Insert the record only if no existing record has a matching key. If a record with a matching key already exists in the dictionary, this function returns the result code btDupRecErr.
kReplace	1	Insert the record only if it replaces an existing record with a matching key. If no existing record in the dictionary has a matching key, this function returns the result code btRecNotFnd.
kInsertOrReplace	2	Insert the new record either way. Add it if no existing record in the dictionary has a matching key; replace the existing record if there is a match.

If InsertRecordToDictionary returns one of the errors listed in "Result Codes," the specified record was not inserted or replaced.

SPECIAL CONSIDERATIONS

InsertRecordToDictionary 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, InsertRecordToDictionary can return one of the following result codes.

noErr	0	No error
notBTree	-410	File is not a dictionary
btNoSpace	-413	Insufficient disk space to store dictionary
btDupRecErr	-414	Record already exists
btRecNotFnd	-415	Record cannot be found
btKeyLenErr	-416	Key length too great or equal to zero
unknownInsertModeErr	-20000	No such insertion mode
recordDataTooBigErr	-20001	Entry data bigger than buffer size

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 InsertRecordToDictionary function, see Listing 8-5 on page 8-19.