ADC Home > Reference Library > Reference > Carbon > Text & Fonts > Dictionary Manager Reference (Not Recommended) >

< Previous PageNext Page > Hide TOC

Legacy Documentclose button

Important: The Dictionary Manager is deprecated as of Mac OS X v10.5 and is not available to 64-bit applications. Instead, use the APIs presented by Dictionary Services, which are described in Dictionary Services Programming Guide and Dictionary Services Reference.

Deprecated Dictionary Manager Reference (Not Recommended) Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

DCMAddRecord

Add a new record to a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMAddRecord (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ByteCount keySize,
   ConstLogicalAddress keyData,
   Boolean checkOnly,
   const AEDesc *dataList,
   DCMUniqueID *newUniqueID
);

Parameters
dictionaryRef

A reference to the dictionary to which you want to add a record. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

The field tag that specifies the record you want to add.

keySize

The size of the keyData parameter.

keyData

The key data of the record you want to add. You are responsible for allocating this buffer.

checkOnly

If true is specified, only a duplication check of records is carried out, and actual addition of records is not carried out.

dataList

A pointer to the data contained in the record you want to add. The AEDesc data structure contains two fields: A four-character code that specifies the type of data in the structure and an opaque storage type that points to the storage for the descriptor data. Each of the data structures in the dataList array specifies a field name (the four-character code) in the dictionary record and the data associated with that field. You must first call the function DCMCreateFieldInfoRecord to create this array of data structures. When you create the data list, you must include all of the fields specified by the masks kDCMIndexedFieldMask, kDCMRequiredFieldMask, and kDCMIdentifyFieldMask as attributes of the field properties of the applicable dictionary.

newUniqueID

On output, the unique ID of the added record. If the added record is a duplicate record, the function returns the result dcmDupRecordErr and the unique ID of the existing record is returned in the newUniqueID parameter.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

When checkOnly is specified as true, if duplicate records do not exist, noErr is returned, and the newUniqueID value is undefined. When checkOnly is specified as false, if the same record exists, only the field data within that record is overwritten, and the unique ID of that record is returned as newUniqueID, and dcmDupRecordErr is returned as the return value. If the same record does not exist, the record is added, and the uniqueID of the added record is returned as newUniqueID, and noErr is returned as the return value.

Availability
Declared In
Dictionary.h

DCMCloseDictionary

Closes a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMCloseDictionary (
   DCMDictionaryRef dictionaryRef
);

Parameters
dictionaryRef

A reference to the dictionary you want to close. You obtain a dictionary reference when you call the function DCMOpenDictionary.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMCompactDictionary

Compacts a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMCompactDictionary (
   DCMDictionaryID dictionaryID,
   DCMProgressFilterUPP progressProc,
   UInt32 userData
);

Parameters
dictionaryID

The ID of the dictionary you want to compact. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

progressProc

A universal procedure pointer (UPP) to your progress callback function. This callback is not supported.

userData

Data needed by your progress callback function.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

The function DCMCompactDictionary organizes the contents of a dictionary to reduce the size of the dictionary as much as possible. You cannot add additional records to a dictionary after you have compacted it unless you call the function DCMReorganizeDictionary to expand the capacity of the dictionary.

Availability
Declared In
Dictionary.h

DCMCountObjectIterator

Obtains the number of dictionaries in a list. (Deprecated in Mac OS X v10.5.)

ItemCount DCMCountObjectIterator (
   DCMObjectIterator iterator
);

Parameters
iterator

The list of available dictionaries. You obtain this list by calling the function DCMCreateDictionaryIterator or DCMCreateAccessMethodIterator.

Return Value

The number of dictionaries contained in the list specified by the iterator parameter.

Availability
Declared In
Dictionary.h

DCMCountRecord

Return number of records in a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMCountRecord (
   DCMDictionaryID dictionaryID,
   ItemCount *count
);

Parameters
dictionaryID

The ID of dictionary whose records you want to count. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

count

On output, the number of records in the dictionary.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMCountRecordIterator

Returns the number of records contained in a list of search results. (Deprecated in Mac OS X v10.5.)

ItemCount DCMCountRecordIterator (
   DCMFoundRecordIterator recordIterator
);

Parameters
recordIterator

A reference to list of search results. You obtain a list of search results by calling the function DCMFindRecords.

Return Value

The number of records in the list specified by the recordIterator parameter.

Availability
Declared In
Dictionary.h

DCMCreateAccessMethodIterator

Obtains a list of the available access methods. (Deprecated in Mac OS X v10.5.)

OSStatus DCMCreateAccessMethodIterator (
   DCMAccessMethodIterator *accessMethodIterator
);

Parameters
accessMethodIterator

On output, a list of access methods.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

You can operate on the list of access methods created by the function DCMCreateAccessMethodIterator by calling the functions DCMCountObjectIterator, DCMIterateObject, DCMResetObjectIterator, and DCMDisposeObjectIterator. You use this function along with the function DCMGetAccessMethodIDFromName to obtain the accessMethodID that you supply to the function DCMNewDictionary to create a new dictionary.

Normally you should not need to call this function because the Dictionary Manager handles the mapping of a dictionary to its access method.

Availability
Declared In
Dictionary.h

DCMCreateDictionaryIterator

Obtains a list of the dictionaries available on the system. (Deprecated in Mac OS X v10.5.)

OSStatus DCMCreateDictionaryIterator (
   DCMDictionaryIterator *dictionaryIterator
);

Parameters
dictionaryIterator

On output, a reference to the list of available dictionaries. You are responsible for disposing of this list when you no longer need it.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

The function DCMCreateDictionaryIterator scans the dictionary directories, registers the dictionaries found, and returns a list of dictionaries. In Mac OS X, the Dictionary Manager searches (User's home)/Library/Dictionaries/, /Library/Dictionaries/, and their subdirectories. In Mac OS 9, it searches the Extensions folder, Preferences folder, and their subfolders.

Availability
Declared In
Dictionary.h

DCMCreateFieldInfoRecord

Creates a field information record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMCreateFieldInfoRecord (
   DescType fieldTag,
   DescType fieldType,
   ByteCount maxRecordSize,
   DCMFieldAttributes fieldAttributes,
   AEDesc *fieldDefaultData,
   ItemCount numberOfFindMethods,
   DCMFindMethod findMethods[],
   AEDesc *fieldInfoRecord
);

Parameters
fieldTag

The tag for the field you want to create.

fieldType

The data type of the field.

maxRecordSize

The maximum size of the data in the field.

fieldAttributes

The attributes associated with the field. See “Field Attributes” for more information.

fieldDefaultData

On input, points to the default data for the field.

numberOfFindMethods

The number of search methods associated with the field.

findMethods

On input, an array of search methods associated with the field. See “Search Methods” for more information.

fieldInfoRecord

On output, points to the field information record for the newly-created field.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

You can add multiple fields in the form of an AEDescList data structure by repeatedly calling the function DCMCreateFieldInfoRecord. You use the field information record (fieldInfoRecord) when you call the function DCMNewDictionary. However, when calling the function for the first time, you must set the descriptorType of the fieldInfoRecord to typeNull.

Availability
Declared In
Dictionary.h

DCMDeleteDictionary

Deletes a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMDeleteDictionary (
   DCMDictionaryID dictionaryID
);

Parameters
dictionaryID

The ID of dictionary you want to delete. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

Return Value

A result code. See “Dictionary Manager Result Codes.” Returns the result dcmDictionaryBusyErr if another application has this dictionary open.

Discussion

The function DCMDeleteDictionary deletes the dictionary specified by the dictionaryID parameter.

Availability
Declared In
Dictionary.h

DCMDeleteRecord

Delete specified record from the dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMDeleteRecord (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ByteCount keySize,
   ConstLogicalAddress keyData,
   DCMUniqueID uniqueID
);

Parameters
dictionaryRef

A reference to the dictionary from which you want to delete a record. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

The field tag that specifies the record you want to delete.

keySize

The size of the keyData parameter.

keyData

The key data of the record you want to delete. You are responsible for allocating this buffer.

uniqueID

The unique ID of the record you want to delete.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMDeriveNewDictionary

Create a new dictionary based on an existing dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMDeriveNewDictionary (
   DCMDictionaryID srcDictionary,
   const FSSpec *newDictionaryFile,
   ScriptCode scriptTag,
   Boolean invisible,
   ItemCount recordCapacity,
   DCMDictionaryID *newDictionary
);

Parameters
srcDictionary

The ID of dictionary from which you want to derive a dictionary. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

newDictionaryFile

A pointer to an FSSpec structure that specifies the file name and location for the newly-created dictionary. This is an input parameter.

scriptTag

The script code of the file specified by the newDictionaryFile parameter.

invisible

A Boolean value that specifies whether the dictionary is available through the Dictionary Manager. Pass true if you do not want the dictionary to be available, false otherwise. If you set invisible to true, that dictionary is no longer seen by such functions as DCMCreateDictionaryIterator, so it becomes a dictionary that cannot be accessed from any application other than the application that created the dictionary.

recordCapacity

The number of records that can be stored in the dictionary. You can supply an approximate value if you do not know the exact number.

newDictionary

On output, points to the ID of the newly-created dictionary.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

The function DCMDeriveNewDictionary creates an new dictionary file based on an existing dictionary specified in the srcDictionary parameter, with the same field configuration and properties, but does not contain the data from the source. The new dictionary is created with the name and at the location specified by the newDictionaryFile parameter. The newly-created dictionary is read-write enabled even if the source dictionary is read-only.

Availability
Declared In
Dictionary.h

DCMDisposeObjectIterator

Disposes of a iterator. (Deprecated in Mac OS X v10.5.)

OSStatus DCMDisposeObjectIterator (
   DCMObjectIterator iterator
);

Parameters
iterator

The list of available dictionaries that you want to dispose of.You obtain this list by calling the function DCMCreateDictionaryIterator or DCMCreateAccessMethodIterator.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

You must dispose of a dictionary iterator when you no longer need it by calling the function DCMDisposeObjectIterator.

Availability
Declared In
Dictionary.h

DCMDisposeRecordIterator

Disposes of a list of search results. (Deprecated in Mac OS X v10.5.)

OSStatus DCMDisposeRecordIterator (
   DCMFoundRecordIterator recordIterator
);

Parameters
recordIterator

A reference to the list of search results you want to dispose of. You obtain a list of search results by calling the function DCMFindRecords.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMFindRecords

Obtains a list of dictionary records that meet specified criteria. (Deprecated in Mac OS X v10.5.)

OSStatus DCMFindRecords (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ByteCount keySize,
   ConstLogicalAddress keyData,
   DCMFindMethod findMethod,
   ItemCount preFetchedDataNum,
   DCMFieldTag preFetchedData[],
   ItemCount skipCount,
   ItemCount maxRecordCount,
   DCMFoundRecordIterator *recordIterator
);

Parameters
dictionaryRef

A reference to the dictionary you want to search. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

A tag that specifies the field to search through. See “Field Data Tags” for a list of the fields you can specify for an Apple Japanese dictionary.

keySize

The length of the keyword specified by the keyData parameter.

keyData

The string for which you want to search.

findMethod

The search method to use. See “Search Methods” for a description of the methods you can supply.

preFetchedDataNum

The number of items in the preFetchedData array.

preFetchedData

An array of the tags obtained during the search. See “Field Data Tags” for a list of the field tags that can be obtained for an Apple Japanese dictionary.

skipCount

The number of records you want to skip during the search. You can use this value along with the maxRecordCount parameter to search through a dictionary in chunks. For example, if you want to obtain 10 matches at a time, the first time you search you should set the skipCount parameter to 0 and the maxRecordCount to 10. The second time you search you set skipCount to 10 and maxRecordCount to10. Each subsequent time you search, you increment skipCount by 10, keeping maxRecordCount set to10.

maxRecordCount

The maximum number of results to return. Pass 0 if you want all matching records returned. If the number of matching records is smaller than the maximum number of results to return, the search is terminated and the matching records returned in the recordIterator parameter. See the description of the skipCount parameter for information on how to use maxRecordCount to search through a dictionary in chunks.

recordIterator

On return, a reference to list of search results.

Return Value

A result code. See “Dictionary Manager Result Codes.”If a match is not found, the function returns dcmNoRecordErr, and the recordIterator value is undefined.

Discussion

The function DCMFindRecords uses the specified key and search method to return a list of matching records. Search results are returned as a reference to a list of matching records. After you obtain this list, you can call the function DCMGetFieldData to retrieve each result in the list.

You can use the preFetchedData parameter to obtain a list of tags during the search. Data specified as pre-fetched are actually retrieved at the same time as the search key is retrieved, so you can specify data tags the need to be accessed fast and immediately after searching. In other words, you can avoid accessing and loading data that are not going to be used immediately by omitting those tags from the preFetchedData list. (You can retrieve those data later by calling the function DCMGetFieldData.) For example: An application that searches pictures by date, displays the found titles in the list, and shows the picture only if the title is double-clicked, the key is "date", the pre-fetched data is "title", and the "picture" is retrieved later if needed by calling the function DCMGetFieldData.

You pass the record iterator (recordIterator) as a parameter to the function DCM DCMCountRecordIterator to obtain the number of items in the list. You can obtain the individual items in the list by passing the record iterator to the function DCMIterateFoundRecord. Your application is responsible for disposing of the record iterator when you no longer need it by calling the function DCMDisposeRecordIterator.

Availability
Declared In
Dictionary.h

DCMGetAccessMethodIDFromName

Obtains the ID for access method. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetAccessMethodIDFromName (
   ConstStr63Param accessMethodName,
   DCMAccessMethodID *accessMethodID
);

Parameters
accessMethodName

The name of access method whose ID you want to obtain.

accessMethodID

On output, the ID for the access method specified by the accessMethodName parameter.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

You can use this function to obtain the accessMethodID that you supply to the function DCMNewDictionary to create a new dictionary.

Normally you should not need to call this function because the Dictionary Manager handles the mapping of a dictionary to its access method.

Availability
Declared In
Dictionary.h

DCMGetDictionaryFieldInfo

Obtains field information for a specified field in a dictionary record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetDictionaryFieldInfo (
   DCMDictionaryID dictionaryID,
   DCMFieldTag fieldTag,
   AEDesc *fieldInfoRecord
);

Parameters
dictionaryID

The ID of dictionary from which you want to obtain field information. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

fieldTag

The tag of the field whose field information you want to obtain. If you pass '****' (typeWildCard) as the field tag, all of the field information contained in the specified dictionary is returned in the fieldInfoRecord parameter.

fieldInfoRecord

On return, points to the field information for the specified field. You are responsible for disposing of this structure by calling the Apple Event Manager function AEDisposeDesc.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetDictionaryIDFromFile

Obtains the ID associated with a dictionary file. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetDictionaryIDFromFile (
   const FSSpec *fileRef,
   DCMDictionaryID *dictionaryID
);

Parameters
fileRef

The file specification for the dictionary whose ID you want to obtain.

dictionaryID

On output, points to the ID for the dictionary specified by the fileRef parameter.

Return Value

A result code. See “Dictionary Manager Result Codes.” If the file is not a dictionary, the result dcmNotDictionaryErr is returned. If the dictionary is not yet registered, the result dcmBadDictionaryErr is returned.

Availability
Declared In
Dictionary.h

DCMGetDictionaryIDFromRef

Obtains the dictionary ID associated with a dictionary reference. (Deprecated in Mac OS X v10.5.)

DCMDictionaryID DCMGetDictionaryIDFromRef (
   DCMDictionaryRef dictionaryRef
);

Parameters
dictionaryRef

A reference to the dictionary whose ID you want to obtain. You obtain a dictionary reference when you call the function DCMOpenDictionary.

Return Value

On return, the ID of the dictionary specified by the dictionaryRef parameter. If dictionaryRef is invalid, the result kDCMInvalidObjectID is returned. See page for a description of the DCMDictionaryID data type.

Availability
Declared In
Dictionary.h

DCMGetDictionaryProperty

Obtains the data associated with a property tag. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetDictionaryProperty (
   DCMDictionaryID dictionaryID,
   DCMFieldTag propertyTag,
   ByteCount maxPropertySize,
   ByteCount *actualSize,
   LogicalAddress propertyValue
);

Parameters
dictionaryID

The ID of dictionary whose property you want to obtain. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

propertyTag

The property tag whose data you want to obtain.

maxPropertySize

The size of the data specified by the propertyValue parameter.

actualSize

On output, the actual size of the data specified by the propertyValue parameter.

propertyValue

On output, points to the property data.

Return Value

A result code. See “Dictionary Manager Result Codes.” Returns the result dcmBadPropertyErr if the property tag does not exist.

Discussion

If you don’t know the size of the property whose data you want to obtain, you need to call this function twice as follows:

Availability
Declared In
Dictionary.h

DCMGetDictionaryPropertyList

Obtains a list of property tags from a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetDictionaryPropertyList (
   DCMDictionaryID dictionaryID,
   ItemCount maxPropertyNum,
   ItemCount *numProperties,
   DCMFieldTag propertyTag[]
);

Parameters
dictionaryID

The ID of dictionary whose list of property tags you want to obtain. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

maxPropertyNum

The maximum number of property tags in the list.

numProperties

On output, the number of properties actually contained in the dictionary.

propertyTag

On output, an array of the property tags contained in the dictionary. You are responsible for allocating an array of the appropriate size.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

The function DCMGetDictionaryPropertyList returns a list of property tags in the specified dictionary. You need to call this function twice. The first time you call the function to get the number of properties. Then you must allocate a propertyTag array of the appropriate size. You call the function a second time to get the actual list of tags.

Availability
Declared In
Dictionary.h

DCMGetDictionaryWriteAccess

Obtains write access for an open dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetDictionaryWriteAccess (
   DCMDictionaryRef dictionaryRef,
   Duration timeOutDuration
);

Parameters
dictionaryRef

A reference to the dictionary for which you want to obtain write access. You obtain a dictionary reference when you call the function DCMOpenDictionary.

timeOutDuration

The maximum amount of time to wait for write access. This parameter is currently not used.

Return Value

A result code. See “Dictionary Manager Result Codes.” Returns the result dcmPermissionErr if the dictionary is read-only dictionary or if another application has write access.

Discussion

When you call the function DCMOpenDictionary, the dictionary opens with read-only access. You must call the function DCMGetDictionaryWriteAccess to obtain write privileges. You can obtain write access only if a dictionary is already opened and no other application has write access to that dictionary. You should release write privileges as soon as you no longer need write access, by calling the function DCMReleaseDictionaryWriteAccess.

Availability
Declared In
Dictionary.h

DCMGetFieldAttributes

Obtains the field attributes for a field information record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetFieldAttributes (
   const AEDesc *fieldInfoRecord,
   DCMFieldAttributes *attributes
);

Parameters
fieldInfoRecord

On input, points to the field information record whose attributes you want to obtain.

attributes

On output, points to the attributes obtained from the field information record. See “Field Attributes”for more information.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetFieldData

Obtains data from one or more fields in a specified record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetFieldData (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ByteCount keySize,
   ConstLogicalAddress keyData,
   DCMUniqueID uniqueID,
   ItemCount numOfData,
   const DCMFieldTag dataTag[],
   AEDesc *dataList
);

Parameters
dictionaryRef

A reference to the dictionary that contains the field data you want to obtain. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

A field tag that specifies the data you want to obtain.

keySize

The size of the keyData parameter.

keyData

The key data of the record you whose field you want to obtain. You are responsible for allocating this buffer.

uniqueID

The unique ID of the record whose field you want to obtain.

numOfData

The number of data fields tags in the dataTag array.

dataTag

A list of the data field to obtain.

dataList

On return, points to a list of obtained data. The data obtained is returned in t as an AERecord data structure. You can retrieve data from specific field using the Apple Event Manager function AEGetKeyPtr. You are responsible for disposing of the dataList array by calling the Apple Event Manager function AEDisposeDesc.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetFieldDefaultData

Obtains default data for a field information record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetFieldDefaultData (
   const AEDesc *fieldInfoRecord,
   DescType desiredType,
   AEDesc *fieldDefaultData
);

Parameters
fieldInfoRecord

On input, points to the field information record whose default data you want to obtain.

desiredType

The data type of the default data.

fieldDefaultData

On output, points to the default data obtained from the field information record.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetFieldFindMethods

Obtains the search methods for a field information record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetFieldFindMethods (
   const AEDesc *fieldInfoRecord,
   ItemCount findMethodsArrayMaxSize,
   DCMFindMethod findMethods[],
   ItemCount *actualNumberOfFindMethods
);

Parameters
fieldInfoRecord

On input, points to the field information record whose search methods you want to obtain.

findMethodsArrayMaxSize

The number of elements in the findMethods array.

findMethods

On output, an array of search methods obtained from the field information record. See “Search Methods” for more information.

actualNumberOfFindMethods

On output, the actual number of search methods obtained from the field information array.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetFieldMaxRecordSize

Obtains the maximum data size for a field in a dictionary record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetFieldMaxRecordSize (
   const AEDesc *fieldInfoRecord,
   ByteCount *maxRecordSize
);

Parameters
fieldInfoRecord

On input, points to the field information record whose maximum data size you want to obtain.

maxRecordSize

On output, points to the maximum data size obtained from the field information record.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetFieldTagAndType

Obtains the field tag and type associated with a field information record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetFieldTagAndType (
   const AEDesc *fieldInfoRecord,
   DCMFieldTag *fieldTag,
   DCMFieldType *fieldType
);

Parameters
fieldInfoRecord

On input, points to the field information record whose field tag and type you want to obtain.

fieldTag

On output, points to the field tag obtained from the field information record.

fieldType

On output, points to the field tag type obtained from the field information record.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetFileFromDictionaryID

Obtains the file specification associated with a dictionary ID. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetFileFromDictionaryID (
   DCMDictionaryID dictionaryID,
   FSSpec *fileRef
);

Parameters
dictionaryID

The ID of the dictionary whose file specification you want to obtain. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

fileRef

On output, points to the file specification for the dictionary specified by the dictionaryID parameter.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetNextRecord

Obtains the next specified record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetNextRecord (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ByteCount keySize,
   ConstLogicalAddress keyData,
   DCMUniqueID uniqueID,
   ByteCount maxKeySize,
   ByteCount *nextKeySize,
   LogicalAddress nextKeyData,
   DCMUniqueID *nextUniqueID
);

Parameters
dictionaryRef

A reference to the dictionary whose record you want to obtain. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

The field tag that specifies the data you want to obtain.

keySize

The size of the keyData parameter. If you pass 0, the first record in the dictionary is returned.

keyData

The key data of the reference record.

uniqueID

The unique ID of the reference record.

maxKeySize

The size of the buffer for the nextKeyData parameter.

nextKeySize

On output, the actual size of the buffer for the nextKeyData parameter.

nextKeyData

On output, points to the next key of the specified record. You must allocate this buffer.

nextUniqueID

On output, the unique ID of the found record.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetNthRecord

Return records in a specified order within the dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetNthRecord (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ItemCount serialNum,
   ByteCount maxKeySize,
   ByteCount *keySize,
   LogicalAddress keyData,
   DCMUniqueID *uniqueID
);

Parameters
dictionaryRef

A reference to the dictionary whose record you want to obtain. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

The field tag that specifies the data you want to obtain.

serialNum

A value that specifies the location of the record within the dictionary. You can obtain this value by calling the function DCMGetRecordSequenceNumber.

maxKeySize

The maximum size of the keyData parameter.

keySize

On output, the size of the keyData parameter.

keyData

The key data of the record you want to obtain. You are responsible for allocating this buffer.

uniqueID

On output, the unique ID of the found record.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetPrevRecord

Obtains the previous record. Return the record previous to the specified record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetPrevRecord (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ByteCount keySize,
   ConstLogicalAddress keyData,
   DCMUniqueID uniqueID,
   ByteCount maxKeySize,
   ByteCount *prevKeySize,
   LogicalAddress prevKeyData,
   DCMUniqueID *prevUniqueID
);

Parameters
dictionaryRef

A reference to the dictionary whose record you want to obtain. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

The field tag that specifies the data you want to obtain.

keySize

The size of the keyData parameter. If you pass 0, the last record in the dictionary is returned.

keyData

The key data of the reference record.

uniqueID

The unique ID of the record reference record.

maxKeySize

The size of the buffer for the prevKeyData parameter.

prevKeySize

On output, the actual size of the buffer for the prevKeyData parameter.

prevKeyData

On output, points to the previous key of the specified record. You must allocate this buffer.

prevUniqueID

On output, the unique ID of the found record.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMGetRecordSequenceNumber

Obtains the sequence number for the specified record in a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMGetRecordSequenceNumber (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ByteCount keySize,
   ConstLogicalAddress keyData,
   DCMUniqueID uniqueID,
   ItemCount *sequenceNum
);

Parameters
dictionaryRef

A reference to the dictionary whose record sequence number you want to obtain. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

The field tag that specifies the data you want to obtain.

keySize

The size of the keyData parameter.

keyData

The key data of the record whose sequence number you want to obtain.

uniqueID

The unique ID of the record whose sequence number you want to obtain.

sequenceNum

On output, a value that specifies the order of the record in the dictionary. The first record in a dictionary has the value 1. Subsequent records are numbered sequentially.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMIterateFoundRecord

Retrieves one record from a list of search results. (Deprecated in Mac OS X v10.5.)

OSStatus DCMIterateFoundRecord (
   DCMFoundRecordIterator recordIterator,
   ByteCount maxKeySize,
   ByteCount *actualKeySize,
   LogicalAddress keyData,
   DCMUniqueID *uniqueID,
   AEDesc *dataList
);

Parameters
recordIterator

A reference to list of search results. You obtain a list of search results by calling the function DCMFindRecords.

maxKeySize

The size of the keyData parameter.

actualKeySize

On output, the actual size of the buffer needed for the data specified by the keyData parameter.

keyData

On output, the key of the retrieved data.

uniqueID

On output, the unique ID of the retrieved record. This value is guaranteed to be unique among records with the same key data; but it is not unique among all records in the dictionary. You can use the unique ID in conjunction with the retrieved key data to specify individual records within the dictionary when you call the functions DCMGetNextRecord, DCMGetPrevRecord, DCMGetRecordSequenceNumber, DCMDeleteRecord, DCMGetFieldData, and DCMSetFieldData.

dataList

On output, the data associated with the key specified by the keyData parameter.

Return Value

A result code. See “Dictionary Manager Result Codes.” The function returns the result dcmIterationCompleteErr when the final record is retrieved.

Discussion

The function DCMIterateFoundRecord retrieves one record from a list of search results referenced by a record iterator. You can retrieve all of the records referenced by a record iterator by repeatedly calling the DCMIterateFoundRecord function.

The data associated with the fields specified in the preFetchedData parameter is returned to dataList in the form of an AERecord. (See DCMFindRecords for more information on pre-fetched data). It is possible to retrieve data by specifying the field tag and data type, and use the AEGetKeyPtr and so forth of the Apple Event Manager. You application is responsible for disposing of dataList by calling the Apple Event Manager function AEDisposeDesc.

Only pre-fetched data can be retrieved here since these data are already retrieved. Other data can be retrieved later by calling the function DCMGetFieldData.

Availability
Declared In
Dictionary.h

DCMIterateObject

Obtains the object ID for a dictionary from a list of available dictionaries. (Deprecated in Mac OS X v10.5.)

OSStatus DCMIterateObject (
   DCMObjectIterator iterator,
   DCMObjectID *objectID
);

Parameters
iterator

The list of available dictionaries. You obtain this list by calling the function DCMCreateDictionaryIterator or DCMCreateAccessMethodIterator.

objectID

On output, the object ID of the dictionary.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

The first time you call the function DCMIterateObject it retrieves the object ID of the first dictionary in the list. The next time you call the function, it retrieves the object ID of the next dictionary in the list. You can obtain all object IDs by repeatedly calling this function. If you call the function after you obtain the object ID for the last dictionary, the function returns the result dcmIterationCompleteErr.

You can reset the iterator to the first dictionary in the list by calling the function DCMResetObjectIterator. When you no longer need the iterator, you must dispose of it by calling the function DCMDisposeObjectIterator.

Availability
Declared In
Dictionary.h

DCMLibraryVersion

Obtains the version number of the Dictionary Manager. (Deprecated in Mac OS X v10.5.)

UInt32 DCMLibraryVersion (
   void
);

Parameters
Return Value

The library version number.

Discussion

The function DCMLibraryVersion returns the version of the installed Dictionary Manager in the same format as the 'vers' resource. That is, the version number is returned in Binary-Coded Decimal (BCD) format in the high-order word, and the release stage information is returned in the low-order word. For example, the version 1.1.1 library returns 0x01118000.

Availability
Declared In
Dictionary.h

DCMNewDictionary

Creates a new dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMNewDictionary (
   DCMAccessMethodID accessMethodID,
   const FSSpec *newDictionaryFile,
   ScriptCode scriptTag,
   const AEDesc *listOfFieldInfoRecords,
   Boolean invisible,
   ItemCount recordCapacity,
   DCMDictionaryID *newDictionary
);

Parameters
accessMethodID

The ID of access method to use for the dictionary. You can obtain an access method ID by calling the function DCMGetAccessMethodIDFromName.

newDictionaryFile

On output, a pointer to an FSSpec structure that specifies the dictionary file to be created.

scriptTag

The code of the script system in which the filename of the dictionary file is to be displayed.

listOfFieldInfoRecords

A pointer to an array of AEDesc data structures. The AEDesc data structure contains two fields: A four-character code that specifies the type of data in the structure and an opaque storage type that points to the storage for the descriptor data. Each of the data structures in the listOfFieldInfoRecords array specifies a field name (the four-character code) in the dictionary record and the data associated with that field. You must first call the function DCMCreateFieldInfoRecord to create this array of data structures.

invisible

A Boolean value that specifies whether the dictionary is available through the Dictionary Manager. Pass true if you do not want the dictionary to be available, false otherwise. If you set invisible to true, that dictionary is no longer seen by such functions as DCMCreateDictionaryIterator, so it becomes a dictionary that cannot be accessed from any application other than the application that created the dictionary.

recordCapacity

The number of records that can be stored in the dictionary. You can supply an approximate value if you do not know the exact number.

newDictionary

On output, points to the ID of the newly-created dictionary.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

The function DCMNewDictionary creates a new dictionary file and registers that dictionary with the Dictionary Manager. You need to specify the access method to use in creating the dictionary. The Dictionary Manager does not operate directly on a dictionary. Instead it accesses dictionaries using the access method specified for the dictionary. The access method mediates between the dictionary and the Dictionary Manager, so that the Dictionary Manager does not need to know anything about the physical format of the dictionary. As a result, the dictionary can have an free-form internal structure. You can also to use an existing dictionary as long as the dictionary has its own access method.

Availability
Declared In
Dictionary.h

DCMOpenDictionary

Opens a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMOpenDictionary (
   DCMDictionaryID dictionaryID,
   ByteCount protectKeySize,
   ConstLogicalAddress protectKey,
   DCMDictionaryRef *dictionaryRef
);

Parameters
dictionaryID

The ID of the dictionary you want to open. You obtain a dictionary ID when you register a dictionary by calling the function DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

protectKeySize

The size of the keyword specified by the protectKey parameter. This parameter is optional. Pass 0 if you do not plan to provide a password.

protectKey

The keyword to use when opening the dictionary. An access method can use the protectKey parameter as a password to restrict access to the dictionary. This parameter is optional. Pass NULL if you do not plan to provide a password.

dictionaryRef

On output, a reference to the opened dictionary.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

The function DCMOpenDictionary opens the dictionary specified by the dictionary ID and obtains a reference to the dictionary (dictionaryRef). You can pass this reference as a parameter to other Dictionary Manager functions to access the records in the dictionary.

Availability
Declared In
Dictionary.h

DCMRegisterDictionaryFile

Registers a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMRegisterDictionaryFile (
   const FSSpec *dictionaryFile,
   DCMDictionaryID *dictionaryID
);

Parameters
dictionaryFile

The file specification for the dictionary you want to register.

dictionaryID

On output, points to the ID of the registered dictionary. A dictionary ID is not persistent across system restarts.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

You should use this function only when the target dictionary is not in default location (seeDCMCreateDictionaryIterator). Otherwise, dictionaries should be already registered and you can obtain the dictionaryID by calling the function DCMGetDictionaryIDFromFile or DCMCreateDictionaryIterator.

You can only use registered dictionaries. You pass the dictionary ID obtained from the function DCMRegisterDictionaryFile when you call other Dictionary Manager functions.

Availability
Declared In
Dictionary.h

DCMReleaseDictionaryWriteAccess

Releases write access to a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMReleaseDictionaryWriteAccess (
   DCMDictionaryRef dictionaryRef,
   Boolean commitTransaction
);

Parameters
dictionaryRef

A reference to the dictionary for which you want to release write access. You obtain a dictionary reference when you call the function DCMOpenDictionary.

commitTransaction

A Boolean value that specifies whether or not to write changed to the dictionary. Pass true to write changes to the dictionary. Pass false to cancel changes. The dictionary must support transaction processing for this parameter to have an effect. This parameter is currently not used.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMReorganizeDictionary

Reorganizes a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMReorganizeDictionary (
   DCMDictionaryID dictionaryID,
   ItemCount extraCapacity,
   DCMProgressFilterUPP progressProc,
   UInt32 userData
);

Parameters
dictionaryID

The ID of dictionary you want to reorganize. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

extraCapacity

The number of additional records you want to add. This number can be approximate.

progressProc

A universal procedure pointer (UPP) to a progress callback function. This callback is not supported.

userData

Data needed by your progress callback function.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

The function DCMReorganizeDictionary reorganizes the contents of the dictionary specified by the dictionaryID parameter, expanding the dictionary to allow for the additional number of records specified by the extraCapacity parameter.

Availability
Declared In
Dictionary.h

DCMResetObjectIterator

Resets an iterator to the start of the dictionary list. (Deprecated in Mac OS X v10.5.)

OSStatus DCMResetObjectIterator (
   DCMObjectIterator iterator
);

Parameters
iterator

The list of available dictionaries. You obtain this list by calling the function DCMCreateDictionaryIterator or DCMCreateAccessMethodIterator.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Discussion

If you want to retrieve the object ID for a dictionary in the list, call the function DCMIterateObject. When you no longer need the iterator, you must dispose of it by calling the function DCMDisposeObjectIterator.

Availability
Declared In
Dictionary.h

DCMSetDictionaryProperty

Sets a property for a dictionary. Set the properties to a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMSetDictionaryProperty (
   DCMDictionaryID dictionaryID,
   DCMFieldTag propertyTag,
   ByteCount propertySize,
   ConstLogicalAddress propertyValue
);

Parameters
dictionaryID

The ID of dictionary whose property you want to set. You obtain a dictionary ID when you call the functions DCMRegisterDictionaryFile or DCMGetDictionaryIDFromFile.

propertyTag

The property tag whose data you want to set.

propertySize

The size of data pointed to by the propertyValue parameter.

propertyValue

A pointer to the property data to be set.

Return Value

A result code. See “Dictionary Manager Result Codes.” Returns the result dcmPermissionErr if the property already exists and it is a read-only property.

Discussion

If the specified properties already exists and it is a writable property, the property data is replaced. If the property does not exist, it is created.

Availability
Declared In
Dictionary.h

DCMSetFieldData

Set the data to a specific field of a specified record. (Deprecated in Mac OS X v10.5.)

OSStatus DCMSetFieldData (
   DCMDictionaryRef dictionaryRef,
   DCMFieldTag keyFieldTag,
   ByteCount keySize,
   ConstLogicalAddress keyData,
   DCMUniqueID uniqueID,
   const AEDesc *dataList
);

Parameters
dictionaryRef

A reference to the dictionary that contains the field data you want to set. You obtain a dictionary reference when you call the function DCMOpenDictionary.

keyFieldTag

Tag of applicable key field.

keySize

The size of the keyData parameter.

keyData

The key data of the record you whose field you want to set.

uniqueID

The unique ID of the record whose field you want to obtain.

dataList

A pointer to the list of data you want to set. The AEDesc data structure contains two fields: A four-character code that specifies the type of data in the structure and an opaque storage type that points to the storage for the descriptor data. Each of the data structures in the dataList array specifies a field name (the four-character code) in the dictionary record and the data associated with that field. You must first call the function DCMCreateFieldInfoRecord to create this array of data structures.

Return Value

A result code. See “Dictionary Manager Result Codes.”

Availability
Declared In
Dictionary.h

DCMUnregisterDictionary

Unregisters a dictionary. (Deprecated in Mac OS X v10.5.)

OSStatus DCMUnregisterDictionary (
   DCMDictionaryID dictionaryID
);

Parameters
dictionaryID
Return Value

A result code. See “Dictionary Manager Result Codes.” Returns dcmDictionaryBusyErr if the dictionary is in use by another client.

Discussion

You should use this function only for dictionaries that you registered by calling the function DCMRegisterDictionaryFile.

Availability
Declared In
Dictionary.h

< Previous PageNext Page > Hide TOC

© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.