Last Reviewed: February 10, 2001
Applies to: dtSearch Text Retrieval Engine 6, 7
A web-Based application built with the dtSearch Engine will generally include the following elements:
(1) The user enters a search request on a search form and click a button to search
(2) The ASP script on the server receives the search request, passes it to the dtSearch Engine in a SearchJob, and obtains a SearchResults object
(3) The script then uses the SearchResults object to write HTML search results with links to view the documents, usually with hits highlighted.
(4) When a user clicks on one of the links, ASP script on the server receives the request and uses the dtSearch Engine to highlight hits in the selected document.
Highlighting hits is done in one of two ways: (1) a dtSearch FileConverter object is used to generate an HTML version of the document text, with hits marked, or (2) in the case of PDF files, an XML stream is sent to Adobe Reader to tell Adobe Reader which words to highlight. (The XML stream for PDF files is generated by the SearchResults object's MakePdfWebHighlightFile method. For more information on this method, please see Article DTS0152, Troubleshooting PDF hit highlighting)
The SearchResults object is helpful for hit highlighting because it provides methods like MakePdfWebHighlightFile that are otherwise difficult or impossible to duplicate. However, a script will have the SearchResults object in step (3) (when writing HTML search results back to the user) but not in step (4) (when a request is received to view a document with hit highlighting, after the user has obtained the list of retrieved documents).
Because of the need to have a SearchResults object to highlight hits, developers will often attach the SearchResults object to the Session variable, making it available to scripts in the application throughout the user's session. Using the Session variable this way has a number of disadvantages:
(1) It is harder to add additional servers to the site, because each user has to be directed to the same computer he or she started with.
(2) The SearchResults object remains in memory until the server's Session timeout is reached, consuming memory during this time (about 1-4k for each search results item).
(3) When the Session timeout limit is reached, the SearchResults object disappears and the user has to search again to see additional documents from search results.
(4) The Session variable is sensitive to the interaction between the browser and the server and to the server's configuration settings, so an application that depends on the Session will be more fragile than one that does not.
Ideally, a web-Based searching application should be stateless, so that the server can retain no information at all about a user after the search results are returned, but the user can click on an item in search results and view it with hits highlighted, regardless of how long it has been since the search.
To provide a Stateless way to access SearchResults, the dtSearch SearchResults object has UrlEncodeItem and UrlDecodeItem methods. These methods let you encode individual search results items in the links written to the search results list, and decode an item when the user clicks on it. UrlEncodeItem creates a query string that identifies the document retrieved and that includes the hit offsets. UrlDecodeItem interprets that query string to make a SearchResults item matching the item that was encoded with UrlEncodeItem.
(1) Writing search results
When writing search results, for each item included in the list, your ASP script would use UrlEncodeItem to make a link for that item, like this:
selfUrl = "http://" & Request.ServerVariables("SERVER_NAME") & _
encodedItem = results.UrlEncodeItem()
link = selfUrl & "?cmd=getdoc&" & encodedItem
Response.Write "<A href=" & quote & link & quote & " target=doc>"
Response.Write results.DocDetailItem("_shortName") & "</A><BR>"
(2) Reconstructing search results
When a user clicks on one of the links from the sample above, the script will receive a query string containing a "cmd=getdoc" value followed by the URL-encoded search results item that the user clicked on. To make a search results object containing only this item, the script would implement the "getdoc" request starting with something like this:
' Reconstruct search results for the item the user clicked on
Set results = Engine.NewSearchResults
UrlDecodeItem is called with the entire query string submitted to the script. It does not matter if this string contains additional values, as long as it also contains the query generated by UrlEncodeItem(). After calling UrlDecodeItem(), the search results object contains a single document record and can be used to highlight hits in that document.
For sample code to a complete ASP application that uses UrlEncodeItem and UrlDecodeItem, please see the dtsearch.asp sample included with the dtSearch Text Retrieval Engine. It will be in your <dtsearch>\examples\asp folder.