*******************************
*    IB_WISQL  version 2.01   *
*******************************

Please send comments via e-mail to Jason at: jwharton@mail.sosaz.com

-------------------------------------------------------------------------------
General info
-------------------------------------------------------------------------------

This tool is written directly to the IB API so no BDE or ODBC is required!

It keeps various information in you system registry in order to store preferences. It should be in the CURRENT_USER, IB_WISQL section.

Most of what this tool does should be self evident but I will write a few things below to help accellerate your knowlege of this tool and what it does.

--------------------------------------------------------------------------------
Connection
--------------------------------------------------------------------------------

The button bar allows you to Create, Connect, Disconnect and Drop an InterBase database.
To create one type in the new filename, Remote or Local, and press the Create button.
To Drop one establish a connection and then press the drop button.
These two operations have a confirmation dialog to help avoid a disasterous mis-click!

The Database dropdown list keeps track of all previous connections made.
Simply choose one or look up a new one by pressing the "Lookup New File" button.
If a new database is selected when a connection is active. The active connection is closed.

Various pieces of information are retreived from the server that are not refreshed until
another connection is made. Consult Interbase documentation for more details.

Buffers is the number of buffers used on the client side in communication with the server. 75 is the InterBase default number. You shouldn't have to change this any. I just put it there in case anyone wants to play with it. I recommend that you do not do so without consulting the InterBase documentation on it.

Forced writes causes all database writes to go straight to disk rather than just going to a buffer in memory. This can critically affect the performance of you system but provides excellent assurance that your changes will not be lost.

--------------------------------------------------------------------------------
Transaction
--------------------------------------------------------------------------------

The button bar allows you to Start, SavePoint, Post all datasets, Cancel all datasets, Commit, Rollback and Close the transaction used in this utility.

There is only one transaction being used for this utility so all info is within one context.

AutoStart and AutoCommit are IB Objects behavioral properties. 
They don't map to some native feature of InterBase.

AutoStart automatically starts a new transaction after a Commit or Rollback.
AutoCommit automatically performs a SavePoint anytime a DDL, DML, EXECPROC, etc has been done.

ReadOnly, LockWait, Isolation and RecVersion do map to native Interbase features.

More information can be obtained on them in the InterBase documentation.

--------------------------------------------------------------------------------
Cursor
--------------------------------------------------------------------------------

This tab is used in processing SELECT statements that are for selecting multiple records.

IB_DataSetbar allows a SELECT statement to be compiled (Prepared) and opens a cursor for fetching.

IB_SearchBar allows a dataset to have QBE search criteria entered to narrow down the number of records retreived from it. The button with the blue question mark on it initiates the dsSearching mode. Then, QBE criteria entered into the data entry fields can be saved, cleared and restored by using the other buttons. The data-entry fields are located in the sub-tab "Search".

The SIGMA button is used to perform a count of how many records meet the search criteria entered. If none has been entered then a count of all records for the dataset is returned.

IB_NavigationBar is used to move through the records selected from the dataset. This also will only operate on records that match the QBE search criteria entered whil in dsSearching mode.
There is no Prior button because Interbase cursors are only unidirectional and there is no built-in buffering in the dataset.
The "Last" button takes you to EOF and not the last record. This is also due to the unidirectional nature of InterBase cursors.

On a large dataset, if "Last" is clicked on there should be a dialog presented giving a count of the number of records fetched. There is also a button which allows you to abort the process of fetching all records of the dataset. This can save a bad problem from happening that would cause you to have to END-TASK or wait quite awhile until all records have been fetched.

IB_UpdateBar is for making modifications to the dataset. There are color contexts to help reflect what action is being taken. Use the fields in the "Search" tab to do the modifications in.

IB_TransactionBar allows changes to be rolledback or committed. 

The SQL tab is where you enter in the SELECT statement. Use InterBase documentation for syntax.
Be sure to include the FOR UPDATE clause if you plan to update or delete any records.

Specific to IB Objects is how named parameters are handled. You can name a parameter simply by
putting it right after the '?' that denotes the parameter. In Delphi the ':' character is used.
Otherwise a default name is assigned to your parameter.

If your statement includes a parameter, prepare it and then confirm it by looking into the tab for "Parameters".

The "Plan" tab shows what optimization InterBase has planned for your select statement.
You must prepare the statement before this information can be optained and displayed.

The "Parameters" tab as mentioned is for displaying input parameters from your SELECT statement.
After having prepared the statement you can enter paramter values for them in this tab.

The "Columns" tab gives a detailed description of each output column defined by your select.

The "Search" tab is a set of dynamically created IB_Edit fields for entering in QBE search criteria or actually performing inserts or positioned updates of column data.

There is an explanation of how the QBE search criteria works and its syntax in a section below.

The "Data" tab has a read-only grid that acts as a buffer of each record as it is fetched.

This is very useful since it can be scrolled. Columns are sizable too.

--------------------------------------------------------------------------------
QBE Edit fields
--------------------------------------------------------------------------------

I have adding QBE-like searching capabilities. 
It can be found on the "CURSOR" tab by clicking on the "Search" button. 
The search button has a blue question mark on it.
Make sure a valid Select statement has been entered in the "SQL" tab of the "Cursor" tab.

There is an IB_Edit field created for each column of the SQL statement.
When these are blue this means that you are in search mode.
In this mode search criteria is entered into them to select records.

For example: >1000 could be typed into the field ( when it's blue ) and this clause would be parsed into the SQL statement when the cursor is opened again.

The rules are pretty much just like QBE ( Query by Example ) with the capability to parse off any relational operators at the beginning of the text entry.

Use IS NOT NULL or IS NULL to get at a column's null status.
With strings add in a '%' or '_' character to use the LIKE operator in string stuff.

Others supported are:

BETWEEN <exp1> AND <exp2>
STARTING [WITH] <expr>
IN( <exp1>, <exp2>[,<expn>] )
CONTAINING( <exp> )

Date's are also handled in an interesting fashion. IB dates are in data-time combination so selecting an exact date can be tricky. Mainly because to get an exact match you need to be the same right down to the ten thousandth of a second! When a user enters a date only (ie 01/01/97) in the QBE field it is parsed into a bracketed expression where it is actually seen as: 

<col> >= 01/01/97 00:00:000 and <col> <= 01/01/97 23:59:999

This returns all records for that date and ignores the time. Of course if the user enters any time information then an exact match is sought after.

To be able to see what statements are generated look in the Monitor tab.
Be sure to have the Monitor enabled first.

--------------------------------------------------------------------------------
DSQL
--------------------------------------------------------------------------------

This tab is used in processing all SQL statements that are not for fetching multiple records.
DDL, DML, EXECUTE PROCEDURE, SET GENERATOR, etc are all able to be processed in this tab.

IB_StatementBar allows statements to be compiled and executed.

IB_TransactionBar gives access to the transaction to commit or rollback changes made.

"Previous", "Next" and "New" give a access to past statements prepared and clear to enter another.

The paramters and output work much the same as they do for the "Cursor" tab.

--------------------------------------------------------------------------------
Events
--------------------------------------------------------------------------------

Place up to 15 event names in the memo below the "Register" button and then click it.

Create a stored procedure that posts an event that you have registered.
This can be done by going to the DSQL tab and executing this SQL statement.

CREATE PROCEDURE test_event AS BEGIN post_event "TEST"; END

Be sure to commit the changes. Also, register the event 'TEST' too.

Go to "Extract" tab and select the new stored procedure. It is on the "Procedures" tab.

Select the "test_event" procedure in the list of procedures.
Press the green arrow to run the stored procedure a few times.
Click on the "SavePoint" button and then go back to the "Events" tab.
There should be an entry in the other memo with the event name and the number of posts.
It is a stack style list that also includes the date and time of the event.

If you have a database that is already producing events simply register them and watch for them.

The "Clear" button simply removes all recorded event notifications.
If there are many events there may be a limit on how many will fit in the memo field.

--------------------------------------------------------------------------------
Script
--------------------------------------------------------------------------------

Ideal for multiple DDL or DML statements.
Use only statements with no input or output parameters.

Terminators are ";" for single line statements.
And for multi-line statements like CREATE PROCEDURE type statements that require ';' as a an internal terminator, put the entire statement in a "BEGIN" ... "END;" block.

In order to create the sample procedure mentioned above you would enter:

begin
CREATE PROCEDURE test_event 
AS 
BEGIN 
  post_event "TEST"; 
END
end;

I use the "begin" and "end;" keywords because when editing a file with the SQL extension you get syntax highlighting in the Delphi code editor. Works real nice!

See the SQL monitor to see any errors after executing.

Use of the CREATE DATABASE statement is supported.

--------------------------------------------------------------------------------
Monitor
--------------------------------------------------------------------------------

The SQL monitor included is also a component part of IB Objects.
It shows most everything that is sent to the IB API. System and user.
There are filters to suppress certain types of feedback. Four of the top
level filters are accessed using the checkboxes.

NOTE: For IB Objects developers that use multi-threading and therefore multiple sessions, the monitor is only functional for the default session. This is because it will be a nice piece of work to make the monitor thread-safe. Imagine the performance hit to synchronize all threads through the monitor! Fortunately, with the way it is designed, if the monitor is disabled then there is no performance hit at all! This is done simply by swapping in new function pointer
values to functions that feed the monitor and then calling the actual entry points from the DLL.

When disabled, the monitor simply puts the original entry points back to the default session.

--------------------------------------------------------------------------------
Extract
--------------------------------------------------------------------------------
I have recently added in support for quickly browsing and editing triggers and procedures.

You can also supply procedure parameter values and run them and see the results.

I have also added in the ability to browse and modify stored procedure and table descriptions.

I have added a tab that allows you to see the source code for a view.

All else should be self explanitory and/or follow after direction in the "Cursor" or "DSQL" tabs.

--------------------------------------------------------------------------------
Scrolling DataSet Test
--------------------------------------------------------------------------------

This is the test bed for my TIB_DataSet descendant class that will have buffering and scrollability.
It will be used also to flesh in the Delphi 3 virtual TDataSet layer in order to replace the BDE to allow a native InterBase solution and still be able to take advantage of all of the data-aware controls for Delphi.

This is exciting stuff!

--------------------------------------------------------------------------------
Importing & exporting to GDB, DB, DBF, ASCII, etc. 
--------------------------------------------------------------------------------

These features are next on my platter! 

They are a must for any suite of components like this.

Be asured that I will squeeze the maximum performance I can here!

Also, transporting TABLES across connections. Can you say "replication"?

BDE API & ODBC API? I'll think about it!

--------------------------------------------------------------------------------
Source code included
--------------------------------------------------------------------------------

The PAS, DPR & DFM files are included to show what went into the creation of this tool. 

Also, with the components provided in InterBase Objects you can load up this project into Delphi.

Customize it and re-compile with your preferences.

You may consider adding a bulk import or export function. 
Or a way to register and keep track of UDF's.

With InterBase Objects your imagination ( and time ) is your only limit!

--------------------------------------------------------------------------------
Try this out!
--------------------------------------------------------------------------------

Put a copy of IB_WISQL.EXE on your desktop. ( Or wherever you want it. )
Then, find a GDB file and double click on it.
Browse and select IB_WISQL.EXE and associate it to the GDB extension.
Now, is all you have to do is double-click on them critters and shaazam! You're ready to go.

When browsing directories on a remote server you may need to add in the server's drive letter.

Also, use the delphi code editor for your SQL ddl, dml scripts. It has good syntax highlighting.

Your file's extension needs to be SQL though.

*******************************************************************************

Please enjoy this tool and distributed it far and wide!

If you have any comments or would like to inquire about having your IB C/S
application developed by CPS with InterBase Objects contact the author.

For information about using IB Objects yourself, please contact the author.
Pre-release copies are being sold now and the official release will be at BDEVCOM 97 in Nashville.

If you are using this tool please let me know just so I have a feel for what
kind of community exists for it in the InterBase world. I may bring some even
better stuff out and about if I feel this tool is well received. Thanks.

Author : Jason Wharton
Company: Computer Programming Solutions
E-Mail : jwharton@mail.sosaz.com
CServe : 103757,763

*******************************************************************************

DISCLAIMER: See the "About this demo..." contents from the Connection tab in the demo.