Inside Macintosh: Text /

Chapter 8 - Dictionary Manager

Summary of the Dictionary Manager

Pascal Summary

Constants

CONST    {Data Insertion Modes}
   kInsert              = 0;  {only insert input entry if nothing in }
                              { dictionary matches key}
   kReplace             = 1;  {only replace entries that match key with }
                              { input entry}
   kInsertOrReplace     = 2;  {insert entry if nothing in the dictionary }
                              { matches key; if already matched }
                              { entries exist, replace them with the }
                              { input entry}
CONST {Key Attribute Constants}
   kIsCaseSensitive           = 16;    {diacritical mark is case sensitive}
   kIsNotDiacriticalSensitive = 32;    {diacritical mark not case sensitive}
CONST {Registered Attribute Types}
   kNoun       =  -1;   {noun}
   kVerb       =  -2;   {verb}
   kAdjective  =  -3;   {adjective}
   kAdverb     =  -4;   {adverb}

Data Types

TYPE
   InsertMode = Integer;
   AttributeType = Integer:
   DictionaryInformation = 
      RECORD
         dictionaryFSSpec:    FSSpec;        {file system specification }
                                             { record for this dictionary}
         numberOfRecords:     LongInt;       {number of records in }
                                             { this dictionary}
         currentGarbageSize:  LongInt;       {current size of garbage }
                                             { (unusable) data in dictionary}
         script:              ScriptCode;    {script system supported by }
                                             { this dictionary}
         maximumKeyLength:    Integer;       {maximum length of any key }
                                             { in this dictionary}
         keyAttributes:       UnsignedByte;  { key search criteria}
      END;

Routines

Making a Dictionary

FUNCTION InitializeDictionary
                          (theFSSpecPtr: FSSpecPtr; 
                           maximumKeyLength: Integer; 
                           keyAttributes: Byte;
                           script: ScriptCode): OSErr;

Accessing a Dictionary

FUNCTION OpenDictionary   (theFSSpecPtr: FSSpecPtr;
                           accessPermission: SignedByte;
                           VAR dictionaryReference: LongInt):
                           OSErr;
FUNCTION CloseDictionary  (dictionaryReference: LongInt):
                           OSErr;
FUNCTION GetDictionaryInformation
                          (dictionaryReference: LongInt;
                           VAR theDictionaryInformation:
                           DictionaryInformation): OSErr;

Locating Records in a Dictionary

FUNCTION FindRecordInDictionary
                          (dictionaryReference: LongInt;
                           key: Str255;
                           requestedAttributeTablePointer: Ptr;
                           recordDataHandle: Handle): OSErr;
FUNCTION FindRecordByIndexInDictionary
                          (dictionaryReference: LongInt;
                           recordIndex: LongInt;
                           requestedAttributeTablePointer: Ptr;
                           VAR recordKey: Str255;
                           recordDataHandle: Handle): OSErr;

Modifying a Dictionary

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

Compacting a Dictionary

FUNCTION CompactDictionary (dictionaryReference:LongInt)
OSErr;

C Summary

Constants

/* Dictionary data insertion modes. */
enum {
 kInsert = 0,              /* Only insert the input entry if there is nothing 
                              in the dictionary that matches the key. */
 kReplace = 1,             /* Only replace the entries which match the key 
                                 with the input entry. */
kInsertOrReplace = 2       /* Insert the entry if there is nothing in the 
                              dictionary which matches the key. If there are
                              already matched entries, replace the existing 
                              matched entries with the input entry. */
};
/* Key attribute constants. */
#define kIsCaseSensitive 0x10                /* case-sensitive = 16 */
#define kIsNotDiacriticalSensitive 0x20      /* non-diac-sensitive = 32 */
/* Registered attribute type constants.*/
enum {
 kNoun = -1,
 kVerb = -2,
 kAdjective = -3,
 kAdverb = -4
};

Data Types

typedef short InsertMode;
typedef short AttributeType;
/* Dictionary information record.*/
struct DictionaryInformation{
   FSSpec         dictionaryFSSpec;
   long           numberOfRecords;
   long           currentGarbageSize;
   ScriptCode     script;
   short          maximumKeyLength;
   unsigned char  keyAttributes;
};
typedef struct DictionaryInformation DictionaryInformation;

Routines

Making a Dictionary

pascal OSErr InitializeDictionary
                    (FSSpecPtr theFsspecPtr, 
                     short maximumKeyLength, 
                     unsigned char keyAttributes, 
                     ScriptCode script)

Accessing a Dictionary

pascal OSErr OpenDictionary
                     (FSSpecPtr theFsspecPtr, 
                     char accessPermission, 
                     long *dictionaryReference)
pascal OSErr CloseDictionary
                    (long dictionaryReference)
pascal OSErr GetDictionaryInformation
                    (long dictionaryReference, DictionaryInformation *theDictionaryInformation)

Locating Records in a Dictionary

pascal OSErr FindRecordInDictionary
                    (long dictionaryReference, ConstStr255Param key, 
                     Ptr requestedAttributeTablePointer, 
                     Handle recordDataHandle)
pascal OSErr FindRecordByIndexInDictionary
                    (long dictionaryReference, 
                     long recordIndex, 
                     Ptr requestedAttributeTablePointer, 
                     Str255 recordKey, Handle recordDataHandle)

Modifying a Dictionary

pascal OSErr InsertRecordToDictionary
                    (long dictionaryReference, 
                     ConstStr255Param key, Handle recordDataHandle, InsertMode whichMode)
pascal OSErr DeleteRecordFromDictionary 
                    (long dictionaryReference, ConstStr255Param key)

Compacting a Dictionary

pascal OSErr CompactDictionary
                    (long dictionaryReference)

Assembly-Language Summary

Trap Macros

Trap Macro Names

Pascal name	Trap macro name
InitializeDictionary	_InitializeDictionary
OpenDictionary	_OpenDictionary
CloseDictionary	_CloseDictionary
InsertRecordToDictionary	_InsertRecordToDictionary
DeleteRecordFromDictionary	_DeleteRecordFromDictionary
FindRecordInDictionary	_FindRecordInDictionary
FindRecordByIndexInDictionary	_FindRecordByIndexInDictionary
GetDictionaryInformation	_GetDictionaryInformation
CompactDictionary	_CompactDictionary

Result Codes

notBTree	-410	File not a dictionary
btNoSpace	-413	Insufficient disk space to store dictionary information
btDupRecErr	-414	Record already exists
btRecNotFnd	-415	Record cannot be found
btKeyLenErr	-416	Key length too great or equal to zero
btKeyAttrErr	-417	Dictionary Manager doesn't understand an attribute
unknownInsertModeErr	-20000	No such insertion mode
recordDataTooBigErr	-20001	Entry data bigger than buffer size
invalidIndexErr	-20002	Invalid index