ADO Data Sources 1.1 - FS plugin for Total Commander
====================================================

This software is provided "as-is". No warranty is provided.
You use this program at your own risk.
The author is not responsible for any data loss, damages, etc.

This plugin is freeware.

====================================================

The plugin gives you access to the objects of server-based and local databases
that can be connected using Microsoft ADO technology: OLE DB providers (MS SQL
Server, Oracle, DB2, Sybase, InterBase, MySQL, MS Access...) and ODBC drivers
(Paradox, dBASE, FoxPro, Excel, CSV...).

This plugin enhanced functionality of author's previous plugin - MS SQL Servers.
It was written using ADO component set - native components for access to MS SQL
servers. Moreover, author works every day with MS SQL Server. Therefore this
plugin has more features for working with MS SQL servers compared with other
data sources.

Information for the users of MS SQL Server plugin.
==================================================
Below I use some common ADO terms instead of ones more specific for MS SQL Server
that I used in previous plugin description:
  "Connection" instead of "Server" ,
  "Catalog"    instead of "Database" and
  "Scheme"     instead of "Owner".
Be facile to me %-)

Plugin features:
================
- List of used connections is created using simple visual mode.
    Add connection        - F7 or double-click on the item '- Add Connection -'.
    Delete connection     - F8, Del or Right Menu - Delete.
    Connection properties - Alt+Enter or Right Menu - Properties.
  List of used connections is stored in the file connections.ini in plugin folder.

- Connection properties:
    Connection Name - you can use any name available in the file system.
    Connection String - you can type the connection string directly, build it 
    using an ADO-supplied dialog box, or place the string in a data link file.
    Login type - if your connection requires authentication (user ID and
    password) you can use one of authentication modes:
      - Login once when you use the connection first. User ID and password
        will be stored in the plugin memory until current Total Commander
        session terminate.

      - Login every time when you open a new connection. Your access to
        connection catalogs and objects doesn't require additional login
        dialogs. (Sometimes extra login dialogs can be required if you
        work with the plugin in both TC panels, use Directory hotlist (Ctrl+D), 
        TC tabs (TC 6.0 and above), or list of already visited directories
        (Alt+Right/Left/Down). It happens because of specifics of the TC
        interaction with the file system plugins.)

      - Keep your ENCRYPTED login and password in the file connection.ini.
        Library crsqlwfx.dll should be located in the plugin folder to enable
        this feature. See more details in the section "Installation".

      - Keep your login and password "as-is" in the connection string in the
        file connection.ini.
        ATTENTION: This is the least desirable mode.
                   Take care of your sensitive information!

- Plugin shows you the hierarchy:
    Connection
     |
     +-->  Catalog
            |
            +-->  Object group (user tables, system tables,
                   |            views, stored procedures)
                   |
                   |  (some groups can be empty)
                   |
                   +-->  Database objects

- Displayed TC columns:
    Names of connections, catalogs and DB objects are displayed as (Name).
    If connection supports different schemes, scheme name is displayed as
    an object extension (for example, employee.dbo).
    If OLE DB provider returns creation dates for catalogs and objects, they
    are displayed as (Date).

- Pressing Enter or double-click on some object (table, view, SP) calls Query
  Viewer - internal query lister/editor. Query such as
    EXECUTE <SP_Name> @Par1 = ?, @Par2 = ?
  is formed (but isn't executed) in the Query Viewer for stored procedures.
  You can add required parameters and execute the query manually.
  See more details about the Query Viewer below.

- F3 shows you an object description:
  For tables - CREATE TABLE... (columns, indexes, primary and foreign keys).
  For views - CREATE VIEW...
  For  - CREATE PROCEDURE...
  Unfortunately, many OLE DB providers return no information for the views
  and stored procedures, so the plugin shows you nothing, respectively.

  F5 copies the object description as a text file to another TC panel.

  ATTENTION:
  The plugin doesn't allow to change/add/delete any database objects.
  Therefore, F4 and F6 works only like F3 and F5.
  F7, F8, and F5 to the plugin panel don't work as well (except F7 and F8 for
  connection list).

- Alt+F7 allows to find objects in the plugin. 
  "Find text" option is also available.

- Objects with irregular names are supported (if name contains spaces, non-Latin
  letters, some special characters or coincident with reserved keywords).
  List of MS SQL Server reserved keywords is used now.

- Folder "- Saved Queries -" in the plugin root folder contains set of saved
  queries for a quick access. Read how to save queries below in the section
  about the Query Viewer.
  You can delete some saved queries from that folder with F8 (only description
  will be deleted, not the real data!)

Internal Query Viewer features:
===============================
- QV allows to execute any SQL-queries, including the queries that don't return
  dataset result (such as INSERT, UPDATE, DELETE...).

- You can edit rows in updateable SELECT queries.

- Some operations are available with just one mouse click:
  - Left-click on column header executes query ordered by that column.
    Serial clicks toggle modes: ASC sorting/DESC sorting/no sorting.
    Sorted column is marked with column background (as in Windows Explorer), or
    with header color (selected in configuration dialog).
    Shift+Left-click allows to use several columns for sorting.
    Ctrl+Left-click returns unsorted dataset.

  - Alt+Right-click on the grid cell executes query with filter like
    "WHERE <selected column> = <selected value>".
    Alt+Shift+Right-click allows setting multiple filters (combined
    with logical AND).
    Alt+Ctrl+Right-click clears all above filters.
    Original query filter (WHEN clause in the query) can be kept and
    combined (using logical AND) with the one-click filters.
    (See flag "Save original query filter" in the "Options" dialog).

  - Ctrl+Right-click on the column header hides current column.
    Ctrl+Shift+Right-click on any column header shows all hidden columns.
    It allows you to flexibly customize your query layout.

- If you select a part of the query text, only selected part will be executed,
  as in SQL Query Analyzer.
  WARNING: One-click mouse operations DO NOT WORK in this mode!

- If the query returns several datasets, you can navigate through them
  using Alt+P and Alt+N.
  WARNING: One-click mouse operations DO NOT WORK in this mode!

- You can set connection and command timeouts for a query.

- Maximum column width can be limited with appropriate button.

- You can view and edit BLOB fields (TEXT, IMAGE, BYNARY) in the separate
  window. Other operations are also supported: saving to file, loading from
  file, clipboard operations.
  Text/image/hex modes are available (hex mode is read-only).

- You can navigate through a history of earlier executed queries using
  Ctrl+P and Ctrl+N. Queries executed with command "Execute" (F5) are saved
  to the history list, but queries from the quick-mouse operations (sorting
  and filtering) are not.
  If menu item "History"-"Run Immediately" is checked, a query which you
  moved to will be executed immediately.

- Using Ctrl+S you can save your query to the special plugin folder 
  "- Saved Queries -" for later quick executing. Connection parameters, 
  query text, and all column settings are saved.
  Just give an unique informative name to your query!

- Configuration dialog is available via menu item "Options...".

Additional plugin features for MS SQL servers:
==============================================
- Only non-empty object groups are displayed.
  User functions can be displayed in the separate group.

- Some information is displayed in addition:
    For databases
      - total size of DB files in bytes as (Size),
      - DB attributes as (Attr):
          read-only - for read-only databases;
          hidden    - for offline database;
          system    - if only DB owner can use this database (dbo use only).
    For object groups - number of objects as (Size).
    For tables - number of records as (Size).
    (WARNING: queries to the system tables are made without synchronization of
              space-usage counters (dbcc updateusage), so data in the (Size)
              column can be inaccurate both for databases and tables).

- For the fastest table access dataset is initially limited using TOP clause
  depending on the number of table records.

- F3, F5 returns more detailed information about DB objects.
  For tables you'll get DEFAULT, CHECK, PRIMARY KEY and FOREIGN KEY CONSTRAINTS,
  and TRIGGERS in addition to column and index lists.
  Displayed information is close to one generated with command "Generate
  SQL Script..." in the SQL Server Enterprise Manager.

- Component DataGrid in the Query Viewer with one-click sorting and filtering
  features is optimized for using with MS Transact-SQL syntax. Some of its
  features may not work with another providers in case of complex queries
  (using of calculated fields, column aliases, complex table JOINs etc).

Tested configurations:
======================
Plugin was tested in the following configurations:
  Windows - 98, XP.
  MS SQL Server - 7.0, 2000.
  Other server-based DB - Oracle, DB2, Sybase, InterBase, MySQL.
  Local DB - MS Access, Paradox, dBASE, FoxPro, Excel.

Installation:
=============
1. Unpack the archive with the plugin to an empty directory.


2. Install FS plugin "ADO_DS.wfx" (see help for Total Commander).
   You can now access the plugin in "Network Neighborhood" as "ADO Data Sources".

3. You must have at least version 2.10 of the Microsoft Data Access
   Components (MDAC) installed to use the plugin.
   You can download the latest MDAC from the Microsoft site:
      http://www.microsoft.com/data
   Read detailed installation instructions in the Microsoft article
   "MDAC Installation" at
     http://msdn.microsoft.com/library/en-us/dnmdac/html/data_mdacinstall.asp

4. OLE DB provider or ODBC driver installation:
   You must have OLE DB provider or ODBC driver for each database you want to
   have access to.
   Some providers will be installed after installation of MDAC: Microsoft 
   providers for SQL Server, Jet (MS Access), Oracle. Provider for ODBC Drivers
   will be installed also; it gives you access to the most of local databases 
   (Access, dBase, FoxPro, Paradox), to the Excel files, and to the text files 
   in CSV format. 
   Many server databases, such as Oracle, DB2, Sybase, etc., install native 
   OLE DB provider and ODBC driver during their installation.
   For other databases (Interbase, FireBird, MySQL...) you have to find in the
   Internet and download (or buy :-)) appropriate provider or driver.

   ATTENTION: quantity and quality of the information returned by the plugin
              mainly depend on provider choice and its settings.
              I don't have enough experience in the most of databases (except
              MS SQL Server), so I used in plugin testing the most accessieble
              providers with minimum settings (all values by default).
              If you are experienced in any database and are able to test
              different providers and find the best settings for them - share
              your results with all plugin users, please.

5. Encryption library installation:
   Library crsqlwfx.dll should be located in the plugin folder to encrypt
   user logins and passwords.

   ATTENTION: without the library all your logins and passwords
              can be stored "as-is".

   Included library crsqlwfx.dll implements a simple encryption algorithm
   using components from DCPcrypt Cryptographic Component Library.

   You can write your own encryption library instead of the original
   crsqlwfx.dll. It must export two functions with following interfaces:

         //  for PASCAL
      function Encode(Source, KeyString: PChar): PChar; stdcall;
      function Decode(Source, KeyString: PChar): PChar; stdcall;

         //  for C
      char* __stdcall Encode(char* Source, char* KeyString);
      char* __stdcall Decode(char* Source, char* KeyString);

   The first function is used for encryption and the second - for decryption of
   string Source using key KeyString.

6. Users of MS SQL Servers plugin!
   You have to reconfigure your connection list. I'm sorry for your
   inconvenience and hope the new connection model will be more useful.

Future plans...
===============
- More flexible plugin setting for different data sources.
- Export of results from the Query Viewer (my old duty).
- ... whatever you want to see in the next versions.

I ask all engaged users to share with me ideas and advices about plugin enhance.

Problem solving:
================
Write me about any plugin problems to address: sqlplugin@comcast.net.
Please, also include:
  - name and version of used OLE DB provider or ODBC data source
    (any links will be helpful also),
  - connection string,
  - your DB features.

Some of problems can happen because of errors in your OLE DB provider.
If you can, try to test your provider first using the same connection 
string and any other application.
(For Borland users I reccomend application
   {Borland_Folder}\Demos\Ado\AdoTest\ADOTest.exe). 
In any case, write me about the problem.

Version history:
================
[!] - Fixed
[+] - Added
[-] - Removed
[*] - Some minor changes

-----------------------
ADO Data Sources v. 1.1 - 10.04.2004

[++] Now plugin works not only with MS SQL Server but with any databases 
     that can be connected using OLE DB providers and ODBC drivers.
[+]  New organization of the connection list.
[+]  Visual settings of the connection properties.
[+]  Views, stored procedures, and functions (for MS SQL Server) are displayed.
[+]  Database object description is available with F3, F5.
[+]  Folder "- Saved Queries -" for quick access to previously saved queries.
[+]  [Query Viewer] Hiding and showing some query columns with one mouse click.
[+]  [Query Viewer] Navigation through the history of executed queries.
[+]  [Query Viewer] Save the query with a datagrid layout for later quick access.

---------------------
MS SQL Servers v. 1.3 - 20.01.2004

[+]  Work with different server lists:
       - servers registered in Enterprise Manager;
       - aliases from Client Network Utility;
       - user-defined list.
[!]  Display servers in nested server groups in Enterprise Manager.
[!]  Work with irregular (delimited) identifiers for object names.
[!]  Release allocated memory when Query Viewer closes.
[!]  Disconnect open connection when Query Viewer closes.
[*]  Interface changes in Configuration dialog.
[+]  Added identification property in connection string
       Application Name=MS SQL Server Plugin for TC.
[+]  Database attributes are displayed.
[+]  [Query Viewer] Separate window for BLOB fields (TEXT, IMAGE, BINARY):
       - save to file/load from file;
       - clipboard operations;
       - text/image/hex view modes.
[+]  [Query Viewer] Execute selected part of command (as in Query Analyzer).
[+]  [Query Viewer] Queries returned several datasets are supported.
[+]  [Query Viewer] Limitation of maximal column width.
[+]  [Query Viewer] Connection and command timeouts for query.
[*]  [Query Viewer] New style in mouse one-click ordering.
[*]  [Query Viewer] Execute query with F5 (as in Query Analyzer).

---------------------
MS SQL Servers v. 1.2 - 01/05/2004

  First public release

Acknowledgements to:
====================
For helpful advices and discussions:
  Gleb Sazonov,
  Vitaly Nevzorov.
Total Commander author:
  Christian Ghisler, www.ghisler.com.
Authors of the freeware components:
  Markus Stephany, merkes@mirkes.de    - component Hex Editor,
  David Barton, www.cityinthesky.co.uk - DCPcrypt Cryptographic Component Library.
Companies:
  Borland,
  Microsoft.

Author:
=======
Oleg Yuvashev, Chicago (USA)
Email: sqlplugin@comcast.net

PS.  Author will read all emails.
     My answer is not guaranteed, but I'll try to consider all your suggestions.


