Diagnostic Tools for Visual Basic and ASP Developers
Article: dts0146
Applies to: dtSearch Engine Web
The dtSearch Text Retrieval Engine includes several diagnostic tools to help isolate problems that arise during execution of a program. These include: (1) detailed error reporting through the dtsErrorInfo structure, (2) debug logging to a text file, and (3) generation of a stack trace when a program crashes.
Error Reporting
Most of the dtSearch Engine's API functions involve a "Job" structure of some type (a SearchJob, an IndexJob, etc.). After a Job has been executed, the Errors property of the job will contain a JobErrorInfo that provides the text and error codes of each error that occurred. Documentation on the meaning of the error codes appears in the "Error Codes" topic in the dtSearch Engine help file (dtengine.chm).
Debug Logging
dtSearch Engine can generate a debug log that provides detailed information about internal processing of an API call. To enable debug logging in the dtSearch Engine, call the SetDebugLogging method of the Server object.
SetDebugLogging(LogName as String, flags as Long)
SetDebugLogging tells the dtSearch Engine to start recording a debug log in the specified file. The flags argument controls optional logging behavior. To turn off debug logging, call SetDebugLogging with a blank LogName.
Note: Debug logging will not work if the process creating the log lacks write access to the folder containing the log file. For example, an ASP application running inside IIS may not be permitted to write to some folders. If SetDebugLogging does not work,
(1) Create an empty folder with a simple name like c:\log
(2) Right-click the c:\log folder in Windows Explorer and select "Permissions"
(3) Set the permissions for c:\log to grant "Everyone" "Full Control" access
(4) Use c:\log\debuglog.txt as the name of the log file
|
Flag |
Effect |
|---|---|
|
dtsLogTime |
Each line in the log will have include the time, in hundredths of a second, since the start of execution. |
|
dtsLogCommit |
The log will be committed to disk after each line is written. This slows execution considerably but ensures that the log will survive a system crash. |
|
dtsLogAppend |
Log data is appended to the file if it already exists. Otherwise the file will be overwritten. |
Crash Diagnostics
The dtSearch Engine can set up a crash handler so that if a General Protection Fault or other unhandled exception occurs during execution of the program, a stack trace file will be created.
To set up a crash handler, call SetDebugLogging (as above) with the dtsCrashLog flag, like this:
server.SetDebugLogging "c:\temp\error.txt", dtsCrashLog
After a crash occurs, the text file will contain a stack trace file identifying the state of the calling program and the dtSearch Engine when the crash occurred.
Object Leaks
The dtSearch Engine keeps a table of the number of each type of object (SearchJob, IndexJob, SearchResults, etc.) currently allocated. This table can be used to detect leaks due to failure to release an object. For example, an application that does not release SearchResults objects after each search will accumulate SearchResults objects in memory over time, resulting in a steady increase in the memory consumed by the application.
To check the table, examine the Server.AllocatedObjectList property. This property is a simple string with the names of each object type followed by the number of currently-allocated instances of each.
Visual Basic and VBScript are supposed to automatically release objects when they go out of scope, but in practice this sometimes does not happen. To minimize the risk of this type of leakage, set any object reference to Nothing when you are done with it, like this:
Dim res as dtengine.SearchResults
Dim sj as dtengine.SearchJob
Set sj = Server.NewSearchJob
... set up search job and execute it ...
Set res = sj.Results
... display search results ...
Set res = Nothing
Set sj = Nothing