
This file contains important information. Please read it, especially the Warning section, before using DBViewer.

In case of difficulties contact the free e-mail support at cdary@usa.net.


Short Description
_________________

DBViewer uses foreign keys as a way of navigating from table to table inside a database.
Choose a table, and a TreeView window shows all existing master tables that can be aggregated to the result set. Select a record in the result set, and a context menu instantly gives you access to all existing detail tables. Choose one of these tables to get the detail records.  You no more need to build specific demo applications to validate your data models. Create your tables, define foreign keys, and navigate immediatly inside your database. DBViewer systematically uses logical links and even allows you to fill reference tables on the fly.

The whole of  the DBViewer capabilities are demonstrated by the DemoDBViewer project file. You can use it for example with the DBDEMOS database which comes with Delphi although it is not very rich concerning foreign keys (Select CUSTOMER, then right-click in the grid, go to ORDERS, and then to ITEMS). If you get Interbase installed, go for a trip inside the IBLOCAL database which is more interesting.
You would certainly find DBViewer useful if you have real world databases with foreign keys. DBViewer currently works with Oracle, Informix, DB2, Sybase, Access, MS SQL Server, Paradox, dBase, and Interbase.

DBViewer Pro has enhanced navigation capabilities that let you jump from a master record to its detail records be it belonging to a directly linked table or to a cascade linked table. For example, you may see directly the items ordered by a customer without an intermediate step to the ORDERS table. DBViewer standard includes this options only for a demo purpose, limited to 10 table openings. Click the 'extended' check box to enable this option.



Setup
_____

Delphi VCL version
__________________

You need to have Delphi 3 or 4 in order to install the components.

Unzip the DBViewer.zip file you received, this will give you 4 files and 2 directories containing the DBViewer.dcu, Unit1.dfm, and Unit1.dfm files that are version dependent. Move the content of the directory corresponding to your Delphi version into the same directory as DBViewerReg.pas, then use Component/Install component in your Delphi IDE main menu to add the DBViewerReg.pas to a package. Compile the package. This will install the TView, TreeViewCheck, TDBStruct and TDBViewer components.

TView is a descendant of the TDataset class which automatically aggregate all possible references fields to its result set.

TTreeViewCheck is a descendant of the TTreeView class with some automated recursive state changing that TDBViewer uses for managing master tables trees.

TDBViewer is a descendant of TView which adds the ability to modify data and navigate towards dependent tables.

To connect to Oracle, MS SQL Server, or Interbase you will also need a working SQL link.
Foreign Keys are currently invisibles to BDE via ODBC drivers. So most of DBViewer features are disabled when accessing data via ODBC.


Exe version without BDE included
________________________________

You need to have Borland Database Engine 4.01 or higher installed before working with DBViewer.

BDE updates can be downloaded at http://www.inprise.com/devsupport/bde/


Autonomous Exe version
______________________

BDE 5.01 and SQL links were included in the file you downloaded. After installation you have to configure database aliases in the BDE administrator. See the Utily/BDE Admin menu in DemoDBViewer.exe. Once in the BDE Administrator use the online help. Configuration is database type dependent. In case of difficulties send me an email containing a description of your problem, database type and version, and values you entered in driver and alias configuration pages.


Usage
_____

The DBViewer component is useful for immediate validation of analysis during the process of designing a new database (physical data model, triggers, constraints). DBViewer allows to handle a database easily, following integrity links between tables in an intuitive and exhaustive way. At each analysis step, designors and users can check the database structure pertinence with representative data. Data organization can be quickly demonstrated without building specific demo applications. DBViewer will do it for you in a very rational and systematic way.

Alternatively, DBViewer is useful for parametrization of validated database. Use it for filling all those reference tables for which you don't have time to build a user-friendly interface.

DBViewer reads (thanks to Borland Database Engine and SQL links) the links weawed between tables by the foreign keys. This allows for

1) Automatic aggregation of all reference fields. Each record of each table is completed with values of its master records (1 to 1 link).

2) Navigation from a record to its detail records (1 to n link).

DBViewer takes advantage of dependent and master relationships to allow you a non-stop navigation inside your data models. This is done by right-clicking the row you want to use as a starting point, then choosing the destination table. The later can be one of the directly dependent tables, or you can pass through one of the master table (bottom of the PopupMenu) to go towards one of its dependent table.

When you are inserting data, DBViewer is able to recognize cases where two composite foreign keys of a table share one or more components. (Paradox do not allow this, but most SGBD do) 
Say table AB has a composite foreign key [f1,f2] to table A, and a composite foreign key [f2,f3] to table B. This enforces that records in AB are "compatible" on field f2.
In such situation DBViewer filters reference table B with f2 values in A if you are coming from A, or filters reference table A with f2 values in B if you are coming from B.

Reference constraints can be added. Say table A has a reference table B but only some records in B verifying a restricting condition are suitable for inclusion in A. This can be managed by typing this condition as a label for the grid icon located before the fields of each master table in the Master Tables TreeView.

Order in master tables or in fields can be changed by using the up and down red arrows of the Master Tables Tree View.

Master tables and fields can be excluded from result set by clicking on the corresponding square icons in the master Tables TreeView.

DBViewer will remember your changes in the Master Tables TreeViews, even after shuting your computer down. If you want to clear all changes you can call the ForceReadStruct procedure to read the structure again. This should be done every time you change the database structure.

Master Tables TreeViews are navigation dependent. This is because master table trees are not the same if you go to table AB from table A or to table AB from table B.

Tables can be sorted on whatever column you like, belonging to the original table or to one of its masters. This is done by Double-Clicking the column. You can also sort data on more columns by Ctrl-Double-Clicking the next ones. 

Of course you can everywhere modify data, provided you have sufficient privilege on the accessed RDBMS.

When inserting and modifying fields linked to a reference table, DBViewer use other instances of the TDBViewer class which themself allow navigating and writing. This recursivity has no limits and allows you to handle data as deep as you want. Especially you can fill reference tables on the fly.

DBViewer is a descendant of the TDBDataset class and presents many similarities with its  cousins TTable and TQuery. DBViewer is invisible at runtime. You have to branch it a DataSource and then a DBGrid to the DataSource for displaying its data flow.

Important : To allow navigating and writing in the database you have to link a PopupMenu to the PopupMenu property of DBViewer and also to the DBGrid. (see the demo for details)


State images
____________

Master Tables TreeView uses the ImageList as follows :

index	meaning					icon in demo project

1	Table to be in the result set		green inner square

2	Table not to be in the result set	green outer square

3	Plain field to be shown			navy inner square

4	Plain field not to be shown		navy outer square

5	Dependent field to be shown		blue inner square

6	Dependent field not to be shown		blue outer square

7	Primary field to be shown		gray inner square

8	Primary field to be shown		gray outer square

9	Master field to be shown		red inner square

10	Master field not to be shown		red outer square

11	Fields Node				pink outer square

12	Reference Constraint			grid icon

 

Warnings
________

The DBViewer component will only work with Delphi 3.x and 4.x (and perhaps later).

DBViewer autonomous ships with BDE 5.01 and SQL links and works on every Win95, Win98, or WinNT computer.

DBviewer exe ships without BDE nor SQL links and only works if you have a BDE version higher or equal to 4.01.

DBViewer currently works only with dBase, Paradox, Oracle, MS SQL Server, Access, Interbase, Informix, DB2, and Sybase.

This component will not work with ODBC drivers as the BDE currently is unable to recognize foreign keys via ODBC.

If no primary key is found, DBViewer looks for a unique key. If no primary or unique key is found, DBViewer builds a pseudo primary key including all sortable fields in the table.

Do not forget to issue a ForceReadStruct after each database structure change to update DBViewer knowledge of database structure. This is done in the demo project under the 'Read Structure' menu item.

In case of error message when starting to navigate into a database try to issue a ForceReadStruct again to refresh the registry.

The master table TreeViews can be customized to hide or move some tables or fields. These TreeViews are stored in registry. The next time you will open the same database alias and log as the same user you will benefit of the same customizations. This is an easy way to build powerful database demos without having to write a line of code. As said before you have to read the structure again when a change occurs in database structure, by issuing a forceReadStruct call. Currently TreeViews customizations are lost when calling ForceReadStruct. This will be corrected in next versions. If this weakness disturbs you, send me an encouragement mail, I think that few DBViewer users are annoyed or even aware of it.

Take care to the length of identifiers in your database (foreign keys, primary keys). DBViewer use BDE API functions that rely on structures where identifiers length is limited to 31 characters. If you create primary and foreign keys with an administrator tool or case tool, the name generated are often very long. This is the case especially with the MS SQL Server tool 'SQL Enterprise Manager'. If you experience error messages verify the key length and eventually rename them.
 
National preferences must be set for Oracle Databases in order to use Date format Fields and for correct indexing of accentued characters. An example is provided in the Demo project for french language.

Accents are not supported in table names.

Simple quotes (or apostrophes) are not supported in data fields, unless you double them when editing or modify manually the generated SQL through the ShowSQL option.

Order is set by default on first visible field. If this field is not indexed this could lead to a long wait before a large table to be displayed. In such a case make primary key visible.

If you are inserting and don't specify a value for a numeric primary key field, DBViewer supposes that the key will be incremented by a trigger and resynchronizes on the maximum value of the primary key in the table. If the key is not incremented this could lead to resynchronisation on a wrong record.

When inserting or updating a record whose primary key contains a date field take care to enter a four digit year to insure correct resynchronisation on this record.
 
If you try to make an update which modify the primary key of a master table and ommits one of the primary key fields in the where clause, you will obtain this message : "UPDATE on primary key of a master table may modify more than one record". This is normal and will normally not occur because DBViewer forces all primary key fields to be in the where clause. Unfortunately, if one of the field value happens to be a null value, the BDE believes that the primary key is not entirely specified even if all primary key fields are in the where clause. Consequently you could be unable to modify a multi field key of a master table which shows a null value. You will have no problem if you specify all fields of master tables primary keys not to be null. (This is compulsory with most database types).

If you use blobs (text fields) on MS SQL 6.5, you will need MS SQL Service Pack 4, because of bugs that were only fixed by this SP.

MS Access only : DBViewer does not accept field names that happen to be SQL reserved words. It should work for other databases.


Disclaimer
__________

A great care was given to the design of this component. Nevertheless, the author does not guarantee that the component will fit your need, nor that it will be 100 % bug-free. The author can not be hold responsible for any damage or lost of data. If you use it, do it at your own risks.



Limitations
___________

Navigation has been limited to 10 openings of tables in the evaluation version.
This limitation is eliminated by typing the registration code. This code is free for DBViewer standard.


Next versions
_____________

Every new release will be posted on the web at http://www.geocities.com/SiliconValley/Hills/1623/dbviewer.htm



Registration
____________

The DBViewer component is a FreeWare. It is also royalty free. That is you have the right to distribute softwares you may develop with it as long as you don't hide or alter the copyright window.

A registration code is still needed to eliminate the evaluation limitation. It can be obtained for free for the DBViewer standard version. Just send an email to cdary@usa.net with your first and last names and company name (if any). Please also tell me where you have heard about DBViewer, it helps me knowing about the distribution efficiency. This registration procedure is fast and easy, and is the only way to evaluate the number of people that actually use DBViewer beyond the limitation to 10 openings of table, i.e. that actually use it for productive work. Not surprisingly, it appears there are much more downloads than registrations.

The registration code for DBViewer Pro will be sent to you upon receipt of a $40 cheque.

Source code is available for commercial (or private) purpose for the cost of $199. See details below.

There are two ways to set the registration code.
First way : host-based : Use the TDBViewer.Registration method to store your registration key in your computer registry.
Second way : project-based : Set the registration key in the TDBViewer.RegistCode at design time, the key will be built inside your exe. Thus your end-users will not have to register.

If you downloaded an exe version you can register via the Utilities | Register menu option.

DBviewer has became a FreeWare to be widely distributed, proven, and commented, so do not hesitate !


Source code availability
________________________

Let me now explain the policy about the DBViewer source code :

The full source code of TDBViewer is available in two ways :

----------------------- First way -------------------------

A limited number of peoples who are aware and convinced of DBViewer utility
are invited to join the DBViewer team.
I'm short in time to make evolve and promote this component. I need help for
such things as

        Testing DBViewer intensively to shot (eventually remaining) hidden
bugs,

        Writing a user manual in HTML,

        Writing an online help,

        Promoting DBViewer via links, reviews, comments,

        Making suggestions for future evolutions,

That's not all : Once they have received the source code, team members are
encouraged to make it evolve by the mean of well defined extensions. This
can be components or units. Each member author bind himself to communicate
for free the source of his/her extensions  to the other team members .

Membership can not be granted immediately, but will be after some evidence
that the candidate has good will and is working in the right way.


---------------------Second way -----------------------

Peoples who just want the source code or want it immediately will receive it
for $199. Choosing the second way doesn't forbid to become a DBViewer team member, but no refund
will be done.


------------------ Conditions for the two ways ---------------------

I will remain the only owner and author of the original TDBViewer component
and its source code as well as all what comes in the original unit, even in the
case it was modified or improved by someone else. Nobody will have the right
to distribute the source code without my consent and I will have the right to distribute
it without anybody consent.

------ Added condition for the second way ---------

Every author will be the owner of his/her work as long as it stays in other
units than the original TDBViewer class unit. Nobody, including myself, will
have the right to
distribute it without his/her consent.

-------------------------------------------------------------------------


Current version is 1.40.

I wish you good navigations with DBViewer.

If you meet bugs please let me know, hunt is open.

There was a BIG BUG in releases 1.39 and earlier. Inserting into tables that happened to
have reference tables caused memory leak. Apparently nobody saw it before me...




                              					Christophe Dary, 3D Xmakina
								
								27 promenade Clemenceau
								85100 Les Sables d'Olonne, France
	
								http://www.geocities.com/SiliconValley/Hills/1623/
								
								cdary@usa.net