dtSearch Text Retrieval Engine Programmer's Reference
External Thesaurus API

Implements synonym expansion in an external DLL.

An external thesaurus is a DLL that supplies synonyms to the dtSearch Engine during a search for query expansion. In a search with external thesaurus synonym expansion enabled, the dtSearch Engine will call the external thesaurus with each word in a search request to obtain synonyms of that word.


The dtSearch Engine will automatically load an external thesaurus DLL if the DLL is in the Viewers folder underneath the dtSearch Engine "home" directory. (This is the same folder where external file parsers are kept.) 

An external thesaurus must implement all of the following exported functions:

extern "C" { __declspec(dllexport) dtsThesaurusLookupHandle dtsThesaurusStartLookup(const char *word); __declspec(dllexport) long dtsThesaurusGetNextWord(dtsThesaurusLookupHandle hLookup, char *dest, long maxLen); __declspec(dllexport) void dtsThesaurusEndLookup(dtsThesaurusLookupHandle hLookup); __declspec(dllexport) void dtsThesaurusGetName(char *dest, int maxLen); };

For each word in a search request, the dtSearch Engine will call dtsThesaurusStartLookup so the thesaurus DLL can look up the word. If the word is found, the DLL should return a dtsThesaurusLookupHandle representing the results of the thesaurus search. If the word is not found, the DLL should return 0. 

When a dtsThesaurusLookupHandle is returned, the dtSearch Engine will then call dtsThesaurusGetNextWord repeatedly to obtain each synonym for the word. On each call, the thesaurus DLL should return the next synonym in the buffer pointed to by dest, and return the number of characters stored. When there are no more synonyms, the thesaurus DLL should return -1. 

After a thesaurus DLL has returned -1 from a dtsThesaurusGetNextWord call, the dtSearch Engine will call dtsThesaurusEndLookup so the thesaurus DLL can release any resources associated with the synonym lookup. 

dtsThesaurusGetName is used by the dtSearch end-user product to provide a description of the external thesaurus in the user interface. 

For sample code demonstrating implementation of an external thesaurus, see the ExternalThesaurus C++ sample.


To enable synonym searching with an external thesaurus, set the dtsSearchSynonyms and dtsSearchExternalSynonyms search flags in a dtsSearchJob or set the Synonyms and ExternalSynonyms properties in a Visual Basic SearchJob.

Wildcards and Search Features

Search terms passed to dtsThesaurusStartLookup may include wildcards and other search punctuation such as the % fuzzy searching operator. To disregard this information, implementations may remove all punctuation characters from the input before searching for it.