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 / 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:
ConstantValueDescription
kInsert0Insert 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.
kReplace1Insert 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.
kInsertOrReplace2Insert 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.
noErr0No error
notBTree-410File is not a dictionary
btNoSpace-413Insufficient disk space to store dictionary
btDupRecErr-414Record already exists
btRecNotFnd-415Record cannot be found
btKeyLenErr-416Key length too great or equal to zero
unknownInsertModeErr-20000No such insertion mode
recordDataTooBigErr -20001Entry 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.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996