Legacy Document

Inside Macintosh: Text /

Chapter 8 - Dictionary Manager / Using the Dictionary Manager

Modifying a Dictionary

This section tells you how to use the Dictionary Manager routines to add, replace, or delete dictionary records.

You can use the InsertRecordToDictionary function to add or replace a record in a specified dictionary. Because there cannot be two separate records with the same key value in a dictionary, adding a new record may nullify an existing one. To avoid such a problem, you can specify the insertion mode, which notifies the Dictionary Manager how you want the new record treated. The insertion mode determines whether to put the record into the dictionary

• only if it does not replace an existing record with the same key
• only if it does replace an existing record with the same key
• regardless of whether it adds a record or replaces another record

You can effectively insert and replace individual entries in records, in that you can obtain a record from a dictionary (with FindRecordInDictionary or FindRecordByIndexInDictionary), modify parts of the record, and then put the record back into the dictionary with InsertRecordToDictionary.

In Listing 8-5, the routine prompts the user for a key word and data for a new dictionary record. It then constructs the new record--in proper dictionary format--by calling the application routine NewDictionaryEntry. Finally, it calls InsertRecordToDictionary, providing a dictionary reference number to the desired dictionary file, a Pascal string representing the key, a handle to the new record, and a specification of how to insert the record into the dictionary.

Listing 8-5 Inserting a record into a dictionary

PROCEDURE AddNewRecord (dictionaryReference: LongInt);
VAR
   keyStr, descriptionStr: Str255;
   descriptionHandle:      Handle;
   err:                    OSErr;
BEGIN
   IF dictionaryReference <> 0 THEN BEGIN
      keyStr := Ask('Enter key:', '<key word>');
      IF keyStr <> '' THEN BEGIN
         descriptionStr := Ask(CONCAT(CONCAT
                              ('Enter description for "', 
                              keyStr), '"'), '<record data>');
         IF descriptionStr <> '' THEN BEGIN
            descriptionHandle := NewDictionaryEntry 
                                       (descriptionStr, 128, '');
            IF descriptionHandle <> NIL THEN BEGIN
               err := InsertRecordToDictionary 
                                       (dictionaryReference, 
                                       keyStr, descriptionHandle, 
                                       kInsertOrReplace);

               IF err <> noErr THEN
                  DebugErrStr(err, 'InsertRecordToDictionary');
               DisposeHandle(descriptionHandle);
            END;
         END;
      END;
   END;
END;  {AddNewRecord}

To remove a record from a dictionary, call the DeleteRecordFromDictionary function. When you call DeleteRecordFromDictionary you specifiy the key of the record to be deleted and the dictionary reference number of the dictionary file that contains the record.

Remember that deleting records from a dictionary, or replacing them with shorter records, does not make the dictionary file any smaller. It simply creates garbage data.