FlipMartin.net

v07 (24/03/2005)
© 2005 André Radke, Philippe Martin

Description

dbSpy is a low-level database analysis tool for Frontier. It provides information about the structure and the contents of a GDB, in the form of a Frontier hierarchy of tables (detailing used, free or orphaned nodes and other similar information) and optionally in the form of a graphical representation of the GDB.

Why would you want to do such a thing? To quote Seth paraphrasing André: "its purpose is to analyze the low-level format of corrupted or bloated databases, to help the operator (programmer) learn what went wrong and what might be fixed (or fixable) in the kernel to prevent it from happening again." (thank you for pointing out that this wasn't clear, Seth!).

dbSpy is intended to be cross-platform and doesn't require any third party program (except for a Web browser).

Important

This is a work in progress and as such should be used with the precautions applying to any beta software!

Screenshot (click to see a larger version)

Download

http://media.flipmartin.net/files/dbSpy_07.zip" (23KB)

Requirements

Installation

You'll then be prompted to locate the destination folder of dbSpy reports.

Notes

dbSpy creates a new GDB for each GDB it analyses, where it stores the results of its analysis. Note that depending on the size of the analyzed GDB and the analysis method used, the resulting GDB can be quite large (up to three times the size of the analyzed GDB!). Also, when generating the graphical view of a GDB, dbSpy creates into the destination folder you chose a new folder for each analyzed GDB, where it stores one or several html files (that depends on the size of the analyzed GDB).

The path of the destination folder you choose at that step is stored at:
dbSpyData.prefs.resultsFolderPath.

You can empty out or delete this entry to get prompted for a new destination folder the next time you run an analysis.

Usage

dbSpy can run two different kinds of analysis, namely Quick Analysis and Full Analysis.

1. Quick Analysis: This method doesn't extract any data from the analyzed GDB and doesn't look for orphaned nodes. Therefore it produces much lighter results than the other method (the result of a Quick Analysis will always be much smaller than the analyzed GDB). Select the menu item "Tools>DbSpy>Quick Analysis..." to run such an analysis. You'll be prompted to select the GDB to analyse. If the GDB you select is already open in Frontier, you'll be asked to close it and try again.

2. Full Analysis: This method detects orphaned nodes, extract the data from the analyzed GDB, and more. But the counterpart is that it may result in a very large GDB (up to three times the size of the analyzed GDB). Select the menu item "Tools>DbSpy>Full Analysis..." to run such an analysis. You'll be prompted to select the GDB to analyse. If the GDB you select is already open in Frontier, you'll be asked to close it and try again.

The result of these analysis is stored in a (possibly new) GDB named "dbSpy_[analyzedGdbName]", saved in the folder you chose as destination folder. That GDB will be taken to the front when the analysis completes.

Graphical View

Optionally, you can also generate and see a graphical representation of the analyzed GDB. To do so, select the menu item "Tools>DbSpy>Build Graphical View". When this menu item is checkmarked, the graphical view will be generated at the end of the Quick or Full analysis you run and opened in your default browser.

Note

The progress indication displayed in Frontier's About window being based on the number of nodes in the GDB, the progress may appear to hang for some time when processing very large nodes. So be patient before deciding that Frontier is hung!

Files of a graphical view

The graphical view is made of html and the result may sometimes be larger than the analyzed GDB. So when a GDB is more than a few hundred KB, several html files will be generated, each showing roughly 1000 nodes at the most.

These html files are named "dbSpyAnalysis[N].html where N is a number, and are stored in a sub-folder named "dbSpy_[analyzedGdbName]" of the folder you selected as destination. If this sub-folder already exists, you'll be given the possibility to replace it, or to create and select another folder.

When the analysis is done, the first of the generated html files will be opened in your default browser (with one exception in Mac OS X, see known bugs bellow). Of course, when several files are used to display a GDB representation, all these files will point to each others.

Aspect of the graphical views

The graphical view shows each node of the analyzed GDB in the form of an horizontal colored segment whose length is relative to the size of the node. Position the cursor over a node to see a tooltip giving more info about it, like type, size, address, status, etc.

To make the graph easier to read, the display is wrapped into lines whose length can be controlled from a user preference. Each line is divided in columns representing roughly 10 bytes each. The user preference (stored at dbSpyData.prefs.graphicalViewWidth) defines the number of colums to use. It defaults to 40.

The aspect of the graph (font, colors, etc) is controlled by a CSS that can be edited by the user. It's stored at:
dbSpyData.templates.graphicalLayout

Privacy

By default, the graphical view of a full analysis shows (in a tooltip) the UserTalk address of each used node. If the analyzed GDB contains objects named with sensible data (like email addresses or bank accounts) and the result of the analysis is meant to be sent to a third party, it is possible to set dbSpy to not display addresses.

To do so, check the menu item "Tools>dbSpy>Protect Privacy".

In this case, the path of the GDB isn't displayed either (but its name is).

Known bugs

- dbSpySuite.unpackMenubar is broken because it doesn't take into account that menu bar scripts are stored in their own node. Therefore, menu bars aren't reconstructed and nodes containing menu bar scripts are currently counted as orphaned even though they really aren't.

- Due to a bug in Frontier, the graphical representation of an analyzed GDB (when that option is checked) isn't opened automatically on Mac OS X if the user's home directory is not on the boot volume. At the moment, such a user will have to locate the file (its path is indicated in the analysis GDB) and double-click it.

Versions History

- 24/03/2005 - v0.7 - First "public" release