
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, Access, MS SQL Server, Paradox, dBase, and Interbase.
Other SGBD support is planned for next versions.



Setup
_____

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 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.



Usage
_____

The DBViewer component is designed 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 very 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.

DBViewer is able to recognize cases where two composite foreign keys of a table share one or more components. (Paradox tables 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

 
Published properties
____________________

MaxPassInDepth : (Byte)

Maximum number of pass by the same table when recursivity is present in database structure. (default 2).


NRecordAdd : (Integer)

Maximum height of the grids created for insertion or modification of fields carrying a foreign key. (default 10).


OuterJoin : (Boolean)

If True, outer joins are used in generated select SQL statements, if False inner joins are used instead. (default True).


PopupMenu : (TPopupMenu)

Link to the PopupMenu component displaying contextual menus for writing and navigating. This PopupMenu should also be attributed to the grid receiving the data flow from the DBViewer.


Prefiltered : (Boolean)

If True, allows choosing prefiltering criteria that will be included in the query. (default False).


RegistCode : (string)

This is where you have to type your registration code. This can only be done at design time.


Selection : (Boolean)

If True, allows selection of master tables contained in the query. (default False).


ShowForeignKeyFields : (Boolean)

If True, foreign keys fields are visible unless you have explicitly hidden them in master tables TreeView.
If False, foreign keys are hidden. (default True).


ShowHint : (Boolean)

If True, hints will be shown. As a descendant of TDataSet TDBViewer is invisible and shouldn't show any hints. Nevertheless it will create many visible controls for inserting, updating, or just showing table relationships. ShowHint relates to these controls. (default True).


ShowPrimaryKeyFields : (Boolean)

If True, primary keys fields are visible unless you have explicitly hidden them in master tables TreeView.
If False, primary keys are hidden. (default True).


ShowSQL : (Boolean)

If True, shows SQL statements before sending them to database. (default False).


ShowTree : (Boolean)

If True, shows the tree of master tables. (default True).


State images : (TImageList)

ImageList to be used for state images of the TreeView representing master tables.



Public properties
_________________


FieldLabels : (TStringList)

Contains field labels automatiquely provided by DBViewer. These labels are of the pattern "tx.<field name>" where tx is the table alias used by DBViewer.


ForeignKeyFields : (TStringList)

Contains foreign key field display labels


PrimaryKeyFields : (TStringList)

Contains primary key field names


FTree : (TForm)

The form created by DBViewer for showing the tree of master tables.


OrderFields : (TStringList)

Contains field names used for sorting data flow. This property can be used for sorting data on whatever field you like, be it physically in the accessed table or in one of
its master tables.


OrderDesc : (Boolean)

If True, specify decreasing order. When sorting on more than one column, order is reversed only on last column.


Trace : (TStringList)

Keeps master records fields values during navigation from master towards detail. This property can be used to trace navigation in a Memo component, for example.


Version : (String)

Version number of the TDBViewer class. (read only).



Public Methods
______________


Constructor Create(AOwner: TComponent);


Destructor  Destroy;


Procedure EditField(AField:TField);

Works for field types ftMemo, ftFmtMemo, and ftGraphic. Opens a windows showing field content. Fields of type ftMemo or ftFmtMemo can be modified.


Procedure ForceReadStruct;

Forces a new reading of database structure and clears all changes made in the Master Tables TreeViews. This method should be called whenever a structure change occurs to a database DBViewer is (or has been) connected to.


Procedure PreOpen

Shows the tree of master tables and wait for user selection of tables to be included in the query.


Procedure RefreshView

Refreshs the data flow issued from the DBViewer.


Procedure Registration(RegCode:string)

Open a dialog box to register DBViewer with your user code.



Events
______


OnCloseTree:TCloseEvent;

Occurs when the form showing the tree of master tables is closed


TFieldStateEvent=procedure(FieldIndex:smallint;visible:boolean) of object;
OnChangeFieldState:TFieldStateEvent;

Occurs when a field node is hidden or shown in the tree of master tables. FieldIndex is the index of the field in the list of DBViewer fields. FieldIndex is -1 if field node is not in the result set. Visible is true if the field was made visible, else false.


OnPrefiltering:TNotifyEvent;

Occurs just before the form allowing for choose of filtering criteria is shown


OnRefreshTable:TNotifyEvent;

Occurs after each refresh of the DBViewer


OnSetSelection:TNotifyEvent;

Occurs when user sets property selection on or off


OnSetShowTree:TNotifyEvent;

Occurs when user sets property ShowTree on or off 


TLabelClick=procedure(FieldIndex:smallInt) of object;
OnTreeLabelClick:TLabelClick;

Occurs when user clicks on a selected table label in the tree of master tables. FieldIndex is the index in the DBViewer field list of the first visible field of the clicked table label.




Warnings
________

The DBViewer component will only work with Delphi 3.0 and 4.0 (and perhaps later).

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

This component will not work with most ODBC drivers which are unable to recognize foreign keys.

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.

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 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 SGDBs).

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.


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 20 openings of tables in the evaluation version.
This limitation is eliminated by typing a registration code in the RegistCode property.


Next versions
_____________

If you are interested in receiving by e-mail the next evaluation versions of DBViewer, Please let me know.



Registration
____________

DBViewer is a FreeWare since 10/15/1998. A registration code is still needed to eliminate the evaluation limitation. It can be obtained for free. Just send an email to cdary@usa.net with your first and last names and company name (if any).

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

Source code is available upon request.



                              					Christophe Dary, 3D Xmakina

								cdary@usa.net