dtsSearchJob Structure

Define a search to be performed.

File

File: dtsearch.h

Syntax

C++

struct dtsSearchJob : public dtsJobBase { char request[256]; char fileConditions[256]; struct dtsSearchJobAction action; struct dtsFileSpec filesToSearch; const char * indexesToSearch; long totalFiles; long totalHits; const char * request2; void * resultsHandle; const char * fileConditions2; dtsDataSource * dataSourceToSearch; long maxWordsToRetrieve; struct dtsRetrievedFileTable * resultsBuffer; short maxFilesToRetrieve; short unindexedSearchFlags; short searchFlags; short fuzziness; long autoStopLimit; long searchFlags2; dtsSearchFilterHandle searchFilterHandle; const char * booleanConditions; long maxFilesToRetrieve2; dtsSearchFilterHandle outputSearchFilterHandle; const char * fieldWeights; long maxSearchRequestLength; dtsIndexCacheHandle indexCacheHandle; };

Data Members

Data Member	Description
action	Type of search to perform. Set action.searchIndexes=true for an indexed search, and action.searchFiles=true for an unindexed search.
autoStopLimit	Set to a non-zero value to make the search automatically stop when this many documents were found. AutoStopLimit causes a search to halt automatically when a specified number of documents have been found. This provides a way to limit the resources consumed by searches that retrieve a very large number of documents. When the number of files retrieved reaches the autoStopLimit value, the search will immediately halt, and the code dtsErSearchLimitReached will be returned through the error handler for the search job. If the AutoStopLimit is 0, the search will not halt.
booleanConditions	Additional boolean conditions that a document must meet to be retrieved in a search.
dataSourceToSearch	In an unindexed search, the contents of the dtsDataSource will be searched along with any files specified by filesToSearch.
fieldWeights	Specify a relevance weight for hits that occur in listed fields (example: Subject:10,HtmlTitle:20)
fileConditions	Deprecated; use fileConditions2
fileConditions2	In an indexed search, filename, date, or size criteria that a file must meet to be retrieved. If both fileConditions and a request are provided, both must be matched.
filesToSearch	Identifies files to search in an *unindexed search only
fuzziness	If non-zero, the engine will match words that are close to but not identical to a search term. Fuzziness can range from 1 to 10. The higher the fuzziness value, the more differences are tolerated when matching words, and the closer to the front of the word these differences can occur.
indexCacheHandle	Optional handle to a dtsIndexCache to use for faster high-volume searching
indexesToSearch	Null-delimited string set identifying indexes to search. For each index, supply the full path to the index folder.
maxFilesToRetrieve	Obsolete -- use maxFilesToRetrieve2;
maxFilesToRetrieve2	Limit the maximum size of search results to a specified number of files.
maxSearchRequestLength	Specify the maximum length of a search request.
maxWordsToRetrieve	A per-search override to the dtsOptions.maxWordsToRetrieve setting
outputSearchFilterHandle	A search filter to hold the results of the search (possibly in addition to resultsHandle). If outputSearchFilterHandle is the handle of a valid dtsSearchFilter object, then every document retrieved in the search will also be selected in the search filter
request	Deprecated: use request2
request2	A null-terminated string containing the search request. See dtSearch User's Manual for information about search requests. The string can be up to 32,000 characters in length.
resultsBuffer	Obsolete
resultsHandle	Handle of a dtsSearchResults to store the results of this search. To obtain a handle, declare a dtsSearchResults object and call its getHandle() method. After the search, you can use the dtsSearchResults object to access the results of the search.
searchFilterHandle	Handle to a dtsSearchFilter to use to limit the documents that can be retrieved in this search.
searchFlags	Obsolete -- use searchFlags2
searchFlags2	SearchFlags values controlling various search options
totalFiles	Following a search, contains the number of files retrieved
totalHits	Following a search, contains the number of hits retrieved in all files.
unindexedSearchFlags	UnindexedSearchFlags values controlling an unindexed search

Group

Classes

Members

Data Members

Data Member	Description
action	Type of search to perform. Set action.searchIndexes=true for an indexed search, and action.searchFiles=true for an unindexed search.
autoStopLimit	Set to a non-zero value to make the search automatically stop when this many documents were found. AutoStopLimit causes a search to halt automatically when a specified number of documents have been found. This provides a way to limit the resources consumed by searches that retrieve a very large number of documents. When the number of files retrieved reaches the autoStopLimit value, the search will immediately halt, and the code dtsErSearchLimitReached will be returned through the error handler for the search job. If the AutoStopLimit is 0, the search will not halt.
booleanConditions	Additional boolean conditions that a document must meet to be retrieved in a search.
dataSourceToSearch	In an unindexed search, the contents of the dtsDataSource will be searched along with any files specified by filesToSearch.
fieldWeights	Specify a relevance weight for hits that occur in listed fields (example: Subject:10,HtmlTitle:20)
fileConditions	Deprecated; use fileConditions2
fileConditions2	In an indexed search, filename, date, or size criteria that a file must meet to be retrieved. If both fileConditions and a request are provided, both must be matched.
filesToSearch	Identifies files to search in an *unindexed search only
fuzziness	If non-zero, the engine will match words that are close to but not identical to a search term. Fuzziness can range from 1 to 10. The higher the fuzziness value, the more differences are tolerated when matching words, and the closer to the front of the word these differences can occur.
indexCacheHandle	Optional handle to a dtsIndexCache to use for faster high-volume searching
indexesToSearch	Null-delimited string set identifying indexes to search. For each index, supply the full path to the index folder.
maxFilesToRetrieve	Obsolete -- use maxFilesToRetrieve2;
maxFilesToRetrieve2	Limit the maximum size of search results to a specified number of files.
maxSearchRequestLength	Specify the maximum length of a search request.
maxWordsToRetrieve	A per-search override to the dtsOptions.maxWordsToRetrieve setting
outputSearchFilterHandle	A search filter to hold the results of the search (possibly in addition to resultsHandle). If outputSearchFilterHandle is the handle of a valid dtsSearchFilter object, then every document retrieved in the search will also be selected in the search filter
request	Deprecated: use request2
request2	A null-terminated string containing the search request. See dtSearch User's Manual for information about search requests. The string can be up to 32,000 characters in length.
resultsBuffer	Obsolete
resultsHandle	Handle of a dtsSearchResults to store the results of this search. To obtain a handle, declare a dtsSearchResults object and call its getHandle() method. After the search, you can use the dtsSearchResults object to access the results of the search.
searchFilterHandle	Handle to a dtsSearchFilter to use to limit the documents that can be retrieved in this search.
searchFlags	Obsolete -- use searchFlags2
searchFlags2	SearchFlags values controlling various search options
totalFiles	Following a search, contains the number of files retrieved
totalHits	Following a search, contains the number of hits retrieved in all files.
unindexedSearchFlags	UnindexedSearchFlags values controlling an unindexed search

Methods

Method	Description
clear	Clear all data
copy	Copy another dtsSearchJob (shallow copy)

Methods

Method	Description
clear	Clear all data
copy	Copy another dtsSearchJob (shallow copy)

Remarks

A dtsSearchJob is used in the dtssDoSearchJob function call to define a search to be performed

Search criteria

There are three components to the search request that can be included in a dtsSearchJob:

(1) request2: The search request, which can be in the "boolean", "all words", or "anywords" syntax, depending on the value of searchFlags2.

(2) booleanConditions: A string in the boolean syntax expressing any conditions that must be satisfied in addition to whatever is in request2. This provides a way to add boolean conditions (such as field criteria) to a user-supplied query, which may be in the all words or any words syntax.

(3) fileConditions2: A string expressing conditions such as filename matches, file size matches, etc., that documents must satisfy. See FileConditions for the syntax.

Search results

Search results are obtained using a search results object. To set up a search job, declare a dtsSearchResults object to hold the results and then attach its handle to dtsSearchResults.resultsHandle. After the search, you can use the dtsSearchResults object to access the results of the search.

Example

dtsSearchResults searchResults; dtsSearchJob searchJob; // ... set up searchJob ... searchJob.resultsHandle = searchResults.getHandle(); short errorFlag; dtssDoSearchJob(searchJob, errorFlag); // .. now searchResults contains the results of the search

Search filters

A search filter represents a set of documents that can be returned in a search. To limit a search to the documents in a search filter, set up a dtsSearchFilter object with the filter to use, and set dtsSearchResults.searchFilterHandle to the handled returned by dtsSearchFilter.getHandle(). Example:

dtsSearchFilter searchFilter; // ... read searchFilter from disk, or generate it by searching, or set allowed values // directly using searchFilter.selectItems() ... dtsSearchJob searchJob; // ... set up searchJob ... searchJob.searchFilterHandle = searchFilter.getHandle(); // Now when searchJob is executed, only documents identified by searchFilter can be // retrieved.

To generate a search filter based on the results of a search, set the outputSearchFilterHandle to the handle of a dtsSearchFilter. Every document retrieved in the search will be selected in the output search filter. Note: maxFilesToRetrieve does not affect outputSearchFilter, which will include *every* item retrieved in the search. However, if autoStopLimit causes the search to terminate before it is complete, then only items found before the search stopped will be selected in the dtsSearchFilter.