Chapter 6: Database Inspector

Introduction

The Database Inspector, DBInspector 1.0, is a standalone Java application that allows you to browse class schema, and also browse, modify, and delete objects in databases.

WARNING: modifying and deleting objects from databases requires thorough knowledge of their dependencies. Do NOT modify or delete objects unless you know how to modify all dependent objects as well.

The DBInspector has a graphical interface and is very easy to use. This chapter explains the use of the interface, so you will be able to perform these actions:

• View entire databases

• View objects (class instances) within databases

• browse the objects in detail

• browse variable storage attributes in detail

• Add new objects to a database

• Modify objects (you can modify multiple objects simultaneously)

• Delete objects from a database

• Query on databases (you can save queries and load them later)

• Export data from databases to ASCII files

• View, add and delete indexes on object attributes

Your DBInspector comes with predefined keyboard shortcuts, toolbars and help files to aid you in quickly accessing the databases and objects that you want to manipulate. This chapter also explains these features.

The DBInspector uses Java Foundation Classes (JFC) Swing graphical components from Sun Microsystems. The JFC system rests on top of JDK 1.1.2 (and later versions). The system uses Java Fundamental Binding to access the database for schema information and data.

Setting Up and Running Your DBInspector

Your VERSANT system comes bundled with the DBInspector. When your system is installed, change directories to the directory in which your VERSANT system resides. For instance, on NT, you might enter:

cd C:\VERSANT\DBInspector

and on Unix you might type:

cd /VERSANT/DBInspector

Once there, set the environment variable VBROWSER_HOME to the current directory.

NT — Set VBROWSER_HOME = c:\...
UNIX — setenv VBROWSER_HOME /versant/....

If you put the directory containing DBInspector in your PATH variable, you can launch DBInspector from any directory.

Now you are ready to run your browser. Launch the application by typing:

vbrowser

DBInspector Components

There are five componenets of your DBInspector:

• List of Databases

• Browser Window

• Object Browser

• Vstr Inspector

• Query Tool Window

Each of these components provides access to the next level down. For instance, clicking on a database in the List of Databases brings up the Browser Window. Clicking on a particular class in the Browser Window brings up the Object Browser, and so forth.

List of Databases

The first window you see when your DBInspector comes up is the BroswerWindow, with a List of Databases dialog box. Figure 1 shows an example of this dialog box.

Figure 1: Browser Window with List of Database Dialog Box

Notice at the bottom of the dialog box is an item Hostname. The databases you see listed are those that reside on the specified host. This defaults to localhost. If you want to access databases on a remote machine, type in the hostname of the machine, and a new listing appears. Select the database you would like to view.

Note — Only view one personal database at a time.

Browser Window

Your main Browser Window looks like the example in Figure 2:

Figure 2: Browser Window With Schema Tree and Object Table

You see two main areas in the Browser Window:

• a schema tree

On the left side of the Broswer Window is a directory-like view of the current database (the one you selected). This side shows you the schema of the database, with the database name next to a storage disk icon. Clicking on this brings up the classes in the database. Clicking on a class shows you the attributes of the class. This tree structure is similar to the directory structure used by NT. Figure 2 shows a database that has six classes, one of which is Car. This class has five attributes.

• a table of objects in a selected attribute

If you click on a single class, the right side of your Browser Window shows you a table of the instances of that class (your database objects). This table has columns for the OID that identifies each separate object, and the attributes associated with the object. In Figure 2, you can see that the attributes are for car name, model, year, and color. Each object has its own separate information, which you can easily see in this table.

Object Browser

When you see a table of objects on the right side of your Browser Window, you have the capability of calling up an Object Browser. You can do this by double clicking on the selected row of the table. The Object Browser shows you more detail about your selected object. From the Object Browser you can modify or delete an object. For example, in Figure 3 we have selected the object whose OID is 6.0.18462, whose name is car7, whose model is Mitsubishi, year 96, and is blue. You see this information in a table that has the name of the attribute on the left side and the a text description of the attribute on the right side. You can change the color to red, and commit that change to the database by clicking on the toolbar icon that looks like a floppy diskette.

Figure 3: Object Browser With Single Object Selected

Vstr Inspector

The Vstr Inspector is a browser for all variable storage attributes in your Versant Database. You can invoke a Vstr Inspector from an Object Browser by double clicking on the selected attribute on the left side of the Browser Window.

Similar to the Object Browser, the Vstr Inspector shows you more detailed information about attributes that have a varying amount of data. For example, in Figure 4, We see that the Attribute cars is a data structure that contains a variable amount of information about its Garages. Again, you can modify the contents of the Vstrs in the Vstr Inspector.

Figure 4: Vstr Inspector With Vstr Attribute Selected

QueryTool Window

You can query databases for specific objects. You do this in the QueryTool Window, which you bring up by selecting a database and then clicking on the icon that shows a storage disk with binoculars. Figure 5 shows an example of a Query Tool Window.

Figure 5: QueryTool Window With Single Query

The QueryTool Window comes up with your selected class showing in the upper portion of the window. If you want to change this class, you can use the popup menu to select a different class. The middle portion of the window accepts your queries, and in the lower portion are buttons for executing, loading and saving queries.

Answer Set Window

When you execute a query, an Answer Set Window appears, with the results of your query. If there are more than fifty answers, DBInspector shows you only the first fifty in the window and adds a scrollbar. You can scroll down, which causes the system to load the next fifty results. This partitioning of the answer sets keeps you from having to download vast numbers of results unless you want to.

DBInspector Tasks

There are six basic tasks that you can perform with the DBInspector:

• Add New Objects

• Modify Objects

• Delete Objects

• Query for Objects

• Export Data

• Manipulate Indexes

Adding New Objects

To add new objects to the database, select a database from the Browser Window. Under the EDIT menu item, select INSERT.

Adding a new object inserts a new row in the table on the right side, with the default value of the objects in the instance variable. You can open an Object Browser on the new object and change the attribute values. Once you save the new data from the Object Browser, the new row inserted in the table view changes to reflect your modifications. Remember, when you change the data in the tables, you must commit the changes (click on the floppy diskette icon) to actually modify the database.

Modifying Objects

To modify objects in the database, open an Object Browser on an object . Select the attribute you want to change, and then make your changes in the table on the right side of the window.

You can modify attributes that hold a reference to a persistent object. You can also change a link to a NULL value, or to some valid persistent LOID value of format dddd.nnnn.nnnn. For this to take effect, the database that holds your object must be the session database, or be connected to your session. Once you finish your modifications, commit them by clicking on the floppy diskette icon.

NOTE: The system uses pessimistic locking during any modification/update operation to the Database. See your VERSANT Database Fundamentals Manual for more information about pessimistic locking.

Deleting Objects

Select an object or group of objects from the table and press the DELETE key to delete them. Commit your changes by clicking on the floppy diskette icon.

Querying for Objects

To query for objects in the database, enter a VQL query into the middle portion of the QueryTool Window. Click on the EXECUTE button to see the results in an Answer Set Window.

Saving/Loading VQL Queries

You can save VQL queries and load them into the system later. To save a VQL query, enter it into the middle portion of the QueryTool Window and click on the SAVE (or SAVE AS) button. To load a formerly saved query into the system, click on the LOAD button, then navigate to your specified query.

DBInspector uses File Dialog windows to save/load queries.

Exporting Data of Object Instances to an ASCII file

You can export data of object instances and save it to a character (default Comma) delimited ASCII file. To do this, select a class from the left side of the Browser Window, or highlight rows in the table on the right side. Then click on the icon with the storage disk and arrow. You will be prompted by a File Dialog window to enter the file name for the exported data.

Viewing, Adding and Deleting Indexes on Class attributes

To add an index on a class attribute, select a class attribute, then use the EDIT menu item, selecting the ADD-DELETE INDEX option. Once you have associated an index for that attribute, it appears in red on your screen. You can then view indexes and delete them by selecting the red icon.

DBInspector Features

There are a number of special features that make the DBInspector an easy and powerful tool:

• Supports Copying

• Allows Manipulation of Mulitple Objects Simultaneously

• Includes Short Cut Keys for Frequent Operations

• Includes A Tool Bar

• Handles Multiple Windows Simultaneously

• Includes an Online Help Facility

• Includes Customizable Preferences

Copying From Browser Tables To Other Applications

You can copy from any table to other applications by using the EDIT menu, COPY options, the Tool Bar icon that looks like two documents, or the Cntrl-Insert short cut keys. This data is in a generic format.

Selecting/Editing Multiple Objects Simultaneously

You can select and edit multiple objects at the same time. After selecting the objects in the table, use a menu option to open an edit window. Make changes to one or more attributes, then apply those changes to all selected instances in the database.

Short Cut Keys For Most Operations

Most operations on the Browser have short cut keys for ease of use and efficiency. You can see them when you use the menu items to perform the operations shown in Table 1:

FILE	EDIT	DATABASE	WINDOWS	HELP
Open Database Cntl O	Copy Cntl Insert	Commit Changes Alt C	Close All Sub Windows F4
Export Alt E	Inspect Alt Space	Rollback Changes Alt R
Exit Cntl Q	Find Cntl F
	Select All Cntl A

Table 1: Menu Items with Keyboard Shortcuts

Tool Bar Support

The Browser supports a Tool Bar that house icons for most common operations. The icons are, from left to right on the Tool Bar:

• Open Database: open file folder

• Commit Changes: floppy diskette

• Rollback Changes (undo): X'ed out floppy diskette

• Copy: two documents

• Query For Objects: storage disk with binoculars

• Export Data: storage disk with arrow

• Help: large question mark

Windows Option

DBInspector includes a Windows menu item that keeps track of the various windows you have open within the system. You can switch between windows by selecting any of the windows from this menu item.

Help Functionality

There are "Help topics" and "About Versant Browser" menu options.

The online help system uses HTML documentation, and its invocation opens any installed Internet Browser with the HTML Help documentation as argument. This help system does not provide context sensitive help.

You can open a simple popup window with information about the Browser by selecting the About Versant Browser menu item.

NOTE: There might be more information DBInspector depends on, such as the version of the JDK, that does not appear in the About Versant Browser Window.

Browser Preferences

You can customize your DBInspector by setting preferences in a special preferences window. The preferences reside in an ASCII file in the HOME directory of the current user. This file is called VBrowser.ini on Windows platforms and .vbrowserrc on UNIX platforms. If the Browser is unable to find the perferences file, it uses default preferences and saves them in a new preferences file. Preferences include:

• default hostname

• entry delimiter character

Restrictions and Suggestions

There are a number of restrictions that exist for this release of DBInspector.

• Use only one personal database at a time.

In this release, you can view only one personal database at a time. This restriction will be removed when the multi-thread and multi-session support is available from the VERSANT Java Interface.

• Do not attempt to integrate DBInspector with Report Tool.

In this release, DBInspector does not allow integration to a third party Java-based Report Generating Tool. This feature will be provided in a future release.

• Do not attempt to sort your records.

In this release, you cannot sort records in the table in either an ascending and descending order based on a selected column. This feature will be provided in a future release.

As a suggestion:

• Use the Schema tree's extendability.

You can extend the schema tree to define and/or evolve new database schema. As the graphical interface is so easy to use, you can use DBInspector when creating new classes in your database.

This online documentation is confidential and proprietary to Versant Corporation and is licensed to you, or to your organization, pursuant to the terms of an agreement between you and Versant that restricts the use of this documentation. Please refer to the agreement for more information or call Versant at 510-789-1500 with any questions.