This utility has been created as a diagnostic aid for use when POPFile reports problems with its database. Although POPFile usually outputs some console messages when there are problems with the SQLite database, these messages do not give much information about what went wrong.

This utility provides an easy way to obtain a DBI trace of database activity which may be of assistance in diagnosing problems. The DBI has a powerful tracing mechanism built in which provides information on what is going on 'behind the scenes', both within the DBI and the database drivers.

The tracing mechanism built in to DBI provides many levels of detail but most of these contain so much obscure detail that they are only of interest to database specialists. Therefore this utility defaults to using trace level 1 for a simple overview of what is happening.

• Trace Level 0 disables DBI Tracing so only the normal console messages will be shown.
• Trace Level 1 is best for a simple overview of what's happening.
• Trace Level 2 is a good choice for general purpose tracing. The trace output is detailed and typically very useful.
• Trace Level 3 is equivalent to level 2 plus some high-level information from the driver and some internal information from the DBI.
• Trace Level 4 is equivalent to level 3 plus more detailed information from the driver.

This utility is based upon POPFile's Message Capture Utility therefore the trace output appears in a scrollable window and can easily be copied to the clipboard (using the right-click menu) and saved in a file for later analysis.

If the utility is started using the command dbicapture.exe then it will display a page offering 5 choices, with trace level 1 pre-selected. Levels 2 to 4 offer increasing amounts of detail. Level 0 disables tracing so its output contains only the normal console messages generated by POPFile (and any warnings or error messages, of course).

As the trace level increases, so does the amount of data produced. Here are some sample report sizes from tests which simply started up POPFile, waited until it had started running and then shut it down:

If the utility is to be called from a batch file or shortcut then the required trace level can be specified on the command-line

 dbicapture.exe /TRACE_LEVEL=1

and in this case the page which allows the trace level to be selected will not appear. The command-line option is not case-sensitive.

The command-line can also be used to specify trace levels higher than level 4. Be warned that these higher levels generate a lot of data.

DBI Capture Utility v0.0.2 or later can be used as a replacement for the msgcapture.exe utility shipped with the Windows version of POPFile. One way to do this is to put dbicapture.exe into the POPFile program folder and rename it as msgcapture.exe. The utility can be then run using this existing shortcut:

Start → All Programs → POPFile → Support → Message Capture utility

To stop the utility from displaying the trace level page, specify the required level of tracing by inserting an appropriate TRACE_LEVEL (or trace_level) option in the shortcut.

The DBI Trace Capture utility is not included in the Windows version of POPFile. It is available as a separate download (48 KB zip file).

If you are not sure where the POPFile program files and/or the 'User Data' files are stored, use the following Start Menu shortcut to find out:

Start → All Programs → POPFile → Support → PFI Diagnostic utility (simple)

See PFI Diagnostic Utility for further details.