Legacy Document

Inside Macintosh: Text /

Chapter 8 - Dictionary Manager / Using the Dictionary Manager

Accessing a Dictionary

Before you can use a dictionary you must first open it. Once it is open, you can get information about it and you can use it. When you are finished with the dictionary, you must close it.

Opening and Closing the Dictionary

To open and use a dictionary, you must create an access path to the dictionary file using the OpenDictionary function. You provide a pointer to the file system specification record that defines the file, and you specify the read and write permission for the
access path.

The OpenDictionary function returns a long integer, called a dictionary reference number, that specifies the open dictionary. You use that same dictionary reference number whenever you use the dictionary, and finally when you close the dictionary with the CloseDictionary function.

Listing 8-2 gives an example of how to create and close this access path. It consists of portions of the CASE statement from a sample application's menu-dispatching routine.

Listing 8-2 Opening and closing a dictionary file

      {if user selects "Open dictionary" menu item:}
      iOpenDictionary: 
         IF gDictionaryReference = 0 THEN BEGIN
            {only open my own dictionary file types}
            fileTypes[0] := kMyDictionaryFileType;


            StandardGetFile(NIL, 1, fileTypes, fileReply);
            IF fileReply.sfGood THEN BEGIN
               gDictionaryFile := fileReply.sfFile;
               {open file with read-write permission}
               err := OpenDictionary(@gDictionaryFile, 
                                    fsRdWrPerm, 
                                    gDictionaryReference);
            END;
         END;
      {if user selects "Close dictionary" menu item:}
      iCloseDictionary: 
         IF gDictionaryReference <> 0 THEN BEGIN
            err := CloseDictionary(gDictionaryReference);
            gDictionaryReference := 0;
         END;

Obtaining Information About the Dictionary

You can use the GetDictionaryInformation function to obtain the following information about a dictionary file:

• its file system specification record
• the number of records it contains
• the current size in bytes of its unused (garbage) data
• the script code of the script system it belongs to
• its maximum key length
• its search criteria

To identify the desired dictionary file, you use the dictionary reference number obtained when you open a dictionary file with the OpenDictionary function.

The GetDictionaryInformation function returns its information in a dictionary information record. The dictionary information record is defined by the DictionaryInformation data type as follows:

TYPE DictionaryInformation = 
   RECORD
      dictionaryFSSpec:    FSSpec;        {file system spec}
      numberOfRecords:     LongInt;       {total no. of records}
      currentGarbageSize:  LongInt;       {size of unusable data}
      script:              ScriptCode;    {script system}
      maximumKeyLength:    Integer;       {maximum length of keys}
      keyAttributes:       UnsignedByte;  {key search criteria}
   END;

See page 8-25 for a complete description of these fields. Listing 8-3 shows a call to GetDictionaryInformation to obtain the number of records in a dictionary.

Listing 8-3 Obtaining information about a dictionary

FUNCTION GetNumberOfRecordsInDictionary(dictionaryReference: 
                                          LONGINT): INTEGER;
VAR
   err:              OSErr;
   dictionaryInfo:   DictionaryInformation;
   numRecords:       Integer;
BEGIN
   numRecords := -1;          {return result in case of error}
   IF dictionaryReference <> 0 THEN BEGIN
      {get the dictionary information record}
      err := GetDictionaryInformation(gDictionaryReference, 
                                       dictionaryInfo);
      IF err <> noErr THEN
         numRecords := dictionaryInfo.numberOfRecords
      ELSE
         DebugErrStr(err, 'GetDictionaryInformation');   {error}
   END;
   GetNumberOfRecordsInDictionary := numRecords;
END;  {GetNumberOfRecordsInDictionary}