You are here: COM Interface > Interfaces > ISearchJob Interface > ISearchJob::StatusHandler Property
dtSearch Text Retrieval Engine Programmer's Reference
ISearchJob::StatusHandler Property
__property IDispatch * StatusHandler;

The object that will receive status notification messages from the engine while the search is in progress.


A search that uses StatusHandler will be much slower than one that does not. There are three ways to execute a search with SearchJob: 

(1) Just call Execute and wait for it to return. 

(2) Call ExecuteInThread and then loop waiting for IsThreadDone() to be true, or for the user to click a "Cancel" button. 

(3) Call Execute and then use the StatusHandler object to receive status updates and to implement a "Cancel" button. 

Because of the large amount of overhead required to implement callbacks through COM, the third option is much less efficient than the first two. If your application must monitor the status of the search as it executes so it can report the number of files retrieved so far or implement a "Cancel" button, ExecuteInThread is the recommended way to do this. For sample code demonstrating use of ExecuteInThread, see the vbsearch sample application.


In a Visual Basic program, the StatusHandler object can be any form or object with some or all of the following methods:

Public Sub ReceiveSearching(ByVal What As String) Public Sub ReceiveFound(ByVal What As String, ByVal HitCount As Long) Public Sub ReceiveFoundWithDetail(ByVal What as String) Public Sub ReceiveHits(ByVal Hits As String) Public Function CheckForAbort As Integer

Methods that are not implemented are ignored. 

The following explains the purpose of each of the interfaces in the StatusHandler object: 

CheckForAbort - Called to determine whether the search should be cancelled. Return values for CheckForAbort are: 0 = do not cancel; -1 = cancel. (Note: in Visual Basic you may need a DoEvents call in CheckForAbort to process any pending mouse clicks before checking whether the user pressed "Cancel".) 

ReceiveSearching - Called when the engine starts searching an index or file. The string identifies the index or file being searched. 

ReceiveFound - Called when the engine finds a document that matches the search request. The string parameter will be the name of the file and the integer parameter will be the number of hits in the file or the unscaled relevancy score in a natural language search. 

ReceiveFoundWithDetail - Called when the engine finds a document that matches the search request. The string parameter will contain a sequence of name = value pairs, delimited with carriage-return/newlines (chr$(13) + chr$(10)). Predefined fields have an underscore (_) in front of the field name. User-defined fields stored in an index using the StoredFields property of an IndexJob follow the predefined fields and do not have an underscore prefix. See the DocDetailItem property of the SearchResults object for information on the predefined fields. 

ReceiveHits - Called before each ReceiveFound() call with a string parameter containing a list of the word offsets of the hits in the document. A FileConverter object can use this string to create an HTML image of the document with hits highlighted. 

Copyright (c) 1995-2023 dtSearch Corp. All rights reserved.