dbext.txt

*dbext.txt*	For Vim version 7.0.  Last change: 2010 Jul 15


                	  VIM REFERENCE MANUAL 
                                by 
                     David Fishburn <dfishburn dot vim at gmail dot com>
                     Peter Bagyinszki <petike1 at dpg dot hu>

	  	Database extension plugin (dbext.vim) manual
	  	dbext.vim version 12.00

For instructions on installing this file, type
	:help add-local-help
|add-local-help| inside Vim.

Homepage: http://vim.sourceforge.net/script.php?script_id=356

*dbext* *dbext.vim* *db_ext* *db_ext.vim* *database-extension* *pgsql* *mysql*
*asa* *ase* *ingres* *interbase* *sqlite* *sqlsrv* *ora* *oracle* 
*db2* *DBI* *ODBC* *sqlanywhere* *firebird*

1.  Getting Started			      |dbext-getting-started|
2.  Whats New   			      |dbext-new|
3.  Overview				      |dbext-overview|
4.  Installation                              |dbext-install|
5.  Configuration		              |dbext-configure|
    5.1 Displaying Results                    |dbext-configure-results|
    5.2 Script Variables                      |dbext-configure-variables|
    5.3 Database Specific Options             |dbext-configure-options|
    5.4 DB2 Modes                             |dbext-configure-db2|
    5.5 DBI Installation                      |dbext-configure-dbi|
6.  Mappings and commands		      |dbext-mappings|
7.  Adding new database types		      |dbext-newdb|
8.  Prompting for input parameters	      |dbext-prompting|
9.  Setting up connection information	      |dbext-connect|
    9.1 Connection Parameters                 |dbext-connect-parameters|
    9.2 Prompting for Parameters              |dbext-connect-prompting|
    9.3 Connection profiles                   |dbext-connect-profiles|
    9.4 Connection profile examples           |dbext-connect-profiles-examples|
    9.5 Connection information in modelines   |dbext-connect-modelines|
    9.6 Asking for connection parameters      |dbext-connect-ask|
    9.7 Using autocmds to setup parameters    |dbext-connect-autocmd|
10. Creating mappings using dbext commands    |dbext-in-mappings|
11. Object Completion                         |dbext-completion|
12. Listing Objects in the Database           |dbext-list-objects|
13. Plugin integration             	      |dbext-integration|
    13.1 OMNI completion integration          |dbext-omni-completion|
    13.2 Intellisense integration             |dbext-intellisense|
14. Filetype support                          |dbext-filetypes|
    14.1 Using filetype support               |dbext-filetypes-using|
    14.2 Adding new filetypes                 |dbext-filetypes-adding|
15. Using SQL History                         |dbext-history|
16. Open Source                               |dbext-sourceforge|
17. Tutorial                                  |dbext-tutorial|
    17.1  Creating the connection             |dbext-tutorial-connection|
    17.2  The result buffer                   |dbext-tutorial-results|
    17.3  Executing commands                  |dbext-tutorial-execute|
    17.4  Selecting from tables               |dbext-tutorial-select|
    17.5  Describing objects                  |dbext-tutorial-describe|
    17.6  Connection Profiles                 |dbext-tutorial-profile|
    17.7  Login Script                        |dbext-tutorial-login|
    17.8  Listing object                      |dbext-tutorial-objects|
    17.9  Object Completion                   |dbext-tutorial-completion|
    17.10 Host variable replacement           |dbext-tutorial-variables|
    17.11 Filetype support                    |dbext-tutorial-filetype|
    17.12 History                             |dbext-tutorial-history|
    17.13 DBI Tutorial                        |dbext-tutorial-dbi|

{Vi does not have any of this}

==============================================================================
1. Getting Started					*dbext-getting-started*

If you are looking for a tutorial that will take you through the
features and the "best way" to use this plugin start here |dbext-tutorial|.
This tutorial is a must before beginning to use dbext.

If you have used dbext for a bit and want to start using some more of it's
advanced features you can read this entire document.

dbext is also integrated with the OMNI SQL Completion script which is
included in the Vim distribution.  See :h |omni-sql-completion|
The sqlcomplete.vim plugin is occassionally updated before a new
release of Vim and newer versions of this file can be found here:
http://www.vim.org/scripts/script.php?script_id=1572

You can also post questions to the Vim mailing list.  I routinely monitor
the list.  Comments, feedback and suggestions are always welcome.

David Fishburn

==============================================================================
2. What's New						*dbext-new*

Version 12.00

 New Features
 ---------
 - A number of changes around the Oracle formating instructions.
   Support for packages when describing certain objects.
   These changes were provided by Sergey Khorev.
 - Improved the parsing of Perl strings when prompting for 
   variables.
 - Made some additional changes to the variable_def_regex for how you 
   can specify it from Vim modelines and DBSetOption.  This makes it 
   much more flexible.

 Bug Fixes
 ---------
 - If the word "profile" was used in a dbext profile name dbext would report
   the error: "dbext: Profiles cannot be nested" (Chris Cierpisz).
 - Corrected the regex used to find object owner names (Sergey Khorev).


Version 11.01

 Bug Fixes
 ---------
 - If a large result set is retrieved, there is a significant performance
   delay which was introduced in 11.00.  This was related to the new 
   g:dbext_rows_affected feature (Tocer).
 - Error E15: Invalid expression: b:dbext_sqlvar_mv[var] is reported if
   you are using saved variables and then modified the query with a new 
   variable.  Now the saved variables are used for the known variables 
   and you are prompted for the unknown.


Version 11.00

 New Features
 ------------
 - When autoclose is enabled, a message is displayed indicating autoclose is
   enabled.  This message will now also include the number of rows affected
   by the last statement (if applicable).  This is available for all 
   database interfaces which can provide this information.  Vim scripts or
   mappings have access to this value by referencing the g:dbext_rows_affected
   variable (Philippe Moravie).
 - The Select, Update, Delete, Alter and Drop commands will now complete 
   table names.
 - Revamped the saved variables (see |dbext-tutorial-variables|).  dbext 
   checks your queries and will prompt for variables (see |dbext-prompting|).
   dbext uses regular expressions to determine which variables should be 
   prompted.  To see how you can easily extend the regular expressions follow
   the tutorial.  This replaces the previous method which was too limiting.
   The new technique uses Vim's standard regular expressions.  This introduces
   the variable_def_regex dbext option and deprecates the variable_def dbext
   option.
 - With the introduction of saved variables, you are now prompted during 
   SQL execution to determine whether the previously saved variables 
   should be substituted.

 Bug Fixes
 ---------
 - If you re-sourced plugin/dbext.vim you would receive the following error:
   E227: mapping already exists for <Leader>sas
 - Errors were reported about undefined variable, dbext_sqlvar_temp_mv,  if
   executing a SQL statement directly from a filetype which was not SQL 
   (i.e. PHP).
 - If saved variables were in use, it was possible for dbext to used the 
   replaced variables without the user knowing.  For example stored 
   procedures could be created with the replaced strings instead of the 
   variables.


Version 10.00

 New Features
 ------------
 - Added new database support for SQL Anywhere UltraLite (11.x).
 - Added new database support for Firebird (2.x).
 - Added "@@variable" style to the list of bypassed variable names along 
   with IN, OUT, INOUT and DECLARE.
 - When listing stored variables, you can now remove multiple lines 
   using visual mode.
 - When closing the result window (using "q" or DBResultsClose) you are
   intentionally returned to the buffer which opened the window
   instead of allowing Vim to choose which window.

 Bug Fixes
 ---------
 - The version 9.00 release of dbext broke modeline support.
 - When listing variables the following error could be reported:
   E121: Undefined variable
 - It was not possible to retrieve more than 500 characters from a character
   or binary column in the database when using DBI or ODBC.  Adding 
   driver_parms=LongReadLen=4096 now works correctly.  You can also 
   change this after you are connected to the database using 
   DBSetOption LongReadLen=4096.  Running DBListConnections will display 
   the current setting for each database connection currently open.


Version 9.00

 New Features
 ------------
 - Added the ability to set and store SQL variables for each buffer.  
   This will reduce prompting for statements which are often 
   re-used.  Added support for listing and deleting SQL variables.
   Initial prototype by Garrison Yu.
 - Added option, g:dbext_default_variable_remember, to control whether 
   SQL variables should be stored when prompted.
 - Improved the parsing of SQL statements to account for procedural 
   language.  If a IN, OUT, INOUT or DECLARE statement is found prior
   to the use of the variable, it is stored for later use.  When the 
   variable is encountered, if the declaration was found we skip 
   prompting for it's value.  This should reduce the number of prompts
   you receive when executing SQL (i.e. Functions, Procedures, Events,
   Packages and so on depending on the naming convention you use for
   your variables.
 - Updated the tutorial and added more links to different sections
   see |dbext-tutorial-variable|
 - Added VB filetype support (Garrison Yu).
 - Added escaping to allow specifying an new Oracle URL syntax for 
   server connection parameters (Anton Sharonov).
 - Renamed DBCloseResults, DBOpenResults, DBRefreshResult, 
   DBToggleResultsResize to DBResultsClose, DBResultsOpen, 
   DBResultsRefresh, DBResultsToggleResize to be more consistent.

 Bug Fixes
 ---------
 - DBextPostResult was passed in a string for the buf_nr which required
   conversion if passed to Vim's builtin functions like getbuflines
   (Ying Chen).
 - If g:dbext_default_menu_mode was set to an invalid value an error
   would occur when starting Vim.
 - Renamed some of the <Plug> names so a delay of timeoutlen is avoided
   when using the mappings (DBExecVisualTopXSQL, DBExecSQLUnderTopXCursor,
   DBSelectFromTopXTable).
 - The dbext menu item "List Connections (DBI)" did not work.
 - You are often repeatedly prompted for connection information.  
   This change reduces the number and allows you to cancel out
   of the prompt dialogs.
 - Added an unconditional quit command to exit out of Oracle's 
   SQLPlus (Anton Sharonov).


Version 8.00

 New Features
 ------------
 - When defining a profile or running DBPromptForBufferParameters, 
   you can now optionally specify a file containing commands you want to
   execute against the database when you first connect (James Horine).
 - A new global variable, g:dbext_default_login_script_dir allows you 
   to override the 2 default directories which are searched for these 
   files.
 - The dbext tutorial has been updated to demonstrate the login_script
   see |dbext-tutorial-login|
 - Doc update demonstrating the use of integrated logins (Daren Thomas).
 - Added a new user defined autocommand dbextPreConnection which is 
   triggered prior to dbext connecting to the database.  This allows you 
   to customize settings based on your buffer and environment (Tim Pope).
 - Added escaping to allow specifying an new Oracle URL syntax for 
   server connection parameters (Anton Sharonov).

 Bug Fixes
 ---------
 - Setting LongReadLen for DBI and ODBC connections did not work.
 - DBextPostResult was passed in a string for the buf_nr which required
   conversion if passed to Vim's builtin functions like getbuflines
   (Ying Chen).
 - If g:dbext_default_menu_mode was set to an invalid value an error
   would occur when starting Vim.
 - Renamed some of the <Plug> names so a delay of timeoutlen is avoided
   when using the mappings (DBExecVisualTopXSQL, DBExecSQLUnderTopXCursor,
   DBSelectFromTopXTable).
 - The dbext menu item "List Connections (DBI)" did not work.


Version 7.00

 New Features
 ------------
 - Large change between how the error handling between DBI and ODBC 
   connections were reported and displayed.
 - Non-printable characters are now dealt with for DBI and ODBC
   connections.

 Bug Fixes
 ---------
 - Using ODBC to connect to SQL Server, dbext did not handle informational
   messages appropriately leading to "not connected" messages
   (Albie Janse van Rensburg).
 - When executing SQL if you were prompted for a variable replacement 
   and cancelled the query the dbext history window was displayed 
   instead of returning to the buffer you were editing.


Version 6.20

 New Features
 ------------
 - None

 Bug Fixes
 ---------
 - Changed the DB2 TOP X syntax (DBExecSQLTopX).
 - Changed the query used to retrieve the current line for
   DBExecSQLUnderCursor when no text is selected (Sergey Alekhin).
 - When parsing a SQL statement for host variables it was possible
   to miss excluding the INTO clause correctly (Sergey Alekhin).


Version 6.10

 New Features
 ------------
 - The result window inherits the connection parameters of the
   buffer which last executed SQL (Antony Scriven).  For example, 
   if you retrieve a list of tables, you may want to describe
   a table or generate a list of columns for one of the tables.  
   Using the usual maps will generate the result you need without 
   prompting for connection parameters.  This is especially useful 
   if you have more than 1 buffer and each buffer connects to
   different databases.
 - Added the ability to choose where to put the Result window.
   When the window is split you can choose vertical or horizontal,
   bottom or top, and choose the the width of the window for
   horizontal switches (Clinton Jones).
 - Modified DBExecSQLUnderCursor to select all text until end of 
   line if no valid command terminator is found rather than just
   one letter (David Venus).
 - DBGetOption displays the output from :ver for debugging.

 Bug Fixes
 ---------
 - Tutorial update (Nico Coetzee).
 - Tutorial update (Clinton Jones).
 - DBGetOption reported an exception E730: using List as a String.


Version 6.01

 Bug Fixes
 ---------
 - On dbext startup an error was reported indicating mapleader was not defined
   (Matt).


Version 6.00

 New Features
 ------------
 - dbext now supports table and column names which can contain 
   spaces (Antony Scriven).  There is a corresponding change
   to sqlcomplete.vim to support this.
 - Added an autoclose option.  If you execute SQL which does not 
   return a result set you can choose to have the dbext results
   window automatically close (unless of course there was an error).
   See the autoclose option for more details.
 - Added the map shortcuts to each of menu items under the dbext 
   menu so that users can learn them more easily (Alexander Langer).
 - Using the menu_mode option you can control if and where the
   dbext menu is created (Marty Grenfell).  See the menu_mode option 
   for more details.
 - For MySQL, added -t as part of the default command line parameters setting.
   This will properly format the data into tabs or spaces to make it more
   readable (Luke Cordingley).
 - A message is displayed indicating the time a SQL command began 
   executing.  The result window also contains the time the SQL
   finished executing.
 - DBI or ODBC can now fetch BLOB columns from the database.  By 
   default these are truncated at 500 characters, but that can
   be changed by issuing: DBSetOption driver_parms=LongReadLen=4096

 Bug Fixes
 ---------
 - If a database column had an emdedded double quote this would be 
   displayed as \" in the dbext result window (Jean-Christophe Clavier).
 - When loading the plugin, it will now check to ensure the map
   does not already exist before attempting to create it.  This
   will prevent errors when mappings clash (Antony Scriven).
 - If you prompt for connection parameters using the DBI or
   ODBC types we need to disconnect any existing connections
   or the existing connection will continue to be used.
 - In some cases when using DBI or ODBC an error was not reported
   and only a blank result set was returned.  Now the database
   error is reported back to the user.
 - Data retrieved via DBI or ODBC which contained a backslash
   were not escaped properly and could disappear.


Version 5.20

 New Features
 ------------
 - When using DBI or DBI::ODBC null fields are now displayed as NULL
   instead of empty spaces (now you can distinguish between them).
 - When using DBI or DBI::ODBC you can specify the column separator let
   g:dbext_default_dbi_column_delimiter="\t" (Jean-Christophe Clavier)
 - When using DBI or DBI::ODBC and you use a vertical orientation for the
   result set, if there are any embedded newline characters in your
   data this will be displayed and shifted to align with the column
   above.  Prior to this all newlines were stripped from the output
   when printing to preserve standard horizontal output (Jean-Christophe
   Clavier).


Version 5.11

 New Features
 ------------
 - Added support for Oracle Rdb on an Open VMS Node.  
   For vim on Open VMS look at http://www.polarhome.com/vim/.  
   For Open VMS http://h71000.www7.hp.com/openvms/.
   Development of support by Andi Stern.


Version 5.00

 New Features
 ------------
 - Added Perl's DBI and DBI::ODBC support.  This opens additional database
   support without having to adjust the scripts.  You must have a Perl enabled
   Vim (:echo has('perl')).  Using the DBI layer offers some advantages over
   using the native binary tools:
        - Transaction support which allows you to maintain a transaction during 
          your editing session and either commit or rollback any changes.
          This is not possible without using the DBI layer.
        - Speed improvements, since the database connection is maintained, the
          there is less overhead per command.  You are also not shelling out
          to execute commands but using an already loaded DLL, shared object.
 - New commands are available to select only a few rows instead of an entire
   result set.  In most databases this is referred to as TOP X.
   DBExecSQLTopX, DBExecVisualSQLTopX, DBExecSQLUnderCursorTopX have been
   added plus associated mappings (Albie Janse van Rensburg).
 - Made Cygwin detection a bit easier using the shellslash option (Steve
   Gibson).

 Bug Fixes
 ------------
 - SQL Server support had issues with the queries when running DBCompleteTable,
   DBCompleteProcedure, DBCompleteView which also affected the sqlcomplete.vim
   plugin included with Vim7 (Albie Janse van Rensburg).
 - Oracle reported "rows will be truncated", added "set linesize 10000" to the
   Oracle headers (Stuart Brock)
 - When prompting for connection parameters if you choose a profile of "0" 
   which is no profile, you had to re-run the wizard to prompt for the rest
   of the parameters, now the wizard continues as expected.


Version 4.20

 New Features
 ------------
 - Improved support for Cygwin.  If you are using a Cygwin compiled Vim (on
   Windows) and are accessing Windows compiled binaries (i.e. sqlplus.exe)
   the binary will complain since it does not understand Unix path names.
   Added the option g:dbext_default_use_win32_filenames which allows you to
   indicate the binaries must use translated Windows paths instead. (Richard)
 - DBGetOption displays more information.

 Bug Fixes
 ------------
 - SQL Server support had issues with the queries when running DBCompleteTable,
   DBCompleteProcedure, DBCompleteView which also affected the sqlcomplete.vim
   plugin included with Vim7 (Albie Janse van Rensburg).


Version 4.10

 New Features
 ------------
 - Updated DBGetOption to additionally display a list of all database profiles
   and their types.  All dbext options that have been overriden via the
   vimrc are also displayed.

 Bug Fixes
 ------------
 - db2 support had issues with the queries when running DBCompleteTable,
   DBCompleteProcedure, DBCompleteView which also affected the sqlcomplete.vim
   plugin included with Vim7 (Peter Princz).
 - The documentation was still indicating there was a plugin dependency which
   has been removed with Vim7.


Version 4.00

 New Features
 ------------
 - dbext.vim now requires Vim7.
 - dbext.vim required 2 additional plugins multvals and genutil to operate.
   These dependencies have been removed by taking advantage of the new Vim7
   features (Lists and Dictionaries).
 - When using the DBCompleteTable, DBCompleteProcedure, DBCompleteView
   commands errors are displayed instead of silently ignored.  This makes
   them more useful with the sqlComplete plugin (see |sql.txt|).
 - Added new option, dbext_default_MYSQL_version, for MySQL to indicate the
   version you using.
 - You can optionally define a function, DBextPostResult, in your .vimrc, this
   function will be called each time the result window is updated.  This
   function can be used to do anything, for example, syntax highlighting the
   result set in the result window.

 Bug Fixes
 ------------
 - Added version support with MySQL to control what SQL is sent for version
   4 and 5 servers.


Version 3.50

 New Features
 ------------
 - g:dbext_default_inputdialog_cancel_support = 0 will prevent 
   inputdialog from providing a cancel option.  This works around
   a Vim7 bug.  dbext will automatically detect this and set the
   option the first time it is encountered.
 - Changed the order of some of the text in the dialog boxes to 
   make them more readable when using the console version of Vim.
 - dbext can parse SQL statements and prompt the user to replace
   variables with values prior to sending the statement to the database
   to be executed.  This is useful for testing SQL which is embedded
   in your code without having to manually replace variables and string
   concatentation.  A new identifier (the until flag) allows you to 
   specify the beginning of a string and what to prompt for until a 
   finishing string.  This makes it more flexible for you to configure
   what you would like prompting for when looking for variables.

 Bug Fixes
 ------------
 - DBPromptForBufferParameters can report "E180: Invalid complete value: -1"
   if running the console version of Vim.  dbext will detect this problem 
   and automatically set g:dbext_default_inputdialog_cancel_support = 0 to 
   work around this Vim7 bug.


Version 3.00

 New Features
 ------------
 - dbext supports a history of previous commands.  The DBHistory 
   command will display a numbered list of previous SQL statements.
   Pressing <enter> or double clicking on one of the items will
   execute the statement.  The number of items in the list is 
   configurable via your vimrc.  The history items are stored in a
   file, dbext_sql_history.txt.  The location of the file can also 
   be controlled.
 - The 'refresh' feature added in version 2.30 has been updated to take
   advantage of the history feature.
 - The PHP parser has improved and can handle single or double quoted
   strings, string concatenation and host variables.  It will correctly
   strip the quotes, join the concatenated strings and prompt the user
   for host variables before executing the SQL statement.
 - Updated documentation for Vim 7 SQL code completion.
 - Table, procedure and view dictionaries include the owner name of the 
   object.  This is on by default, but can be controlled via a new global
   option, dbext_default_dict_show_owner.  This has not been enabled for all
   databases it depends on whether the database supports this feature.  The
   autoload\sqlcomplete.vim plugin takes advantage of this feature.
 - Added support for stored procedures / functions in MySQL 5.

 Bug Fixes
 ------------
 - Updated the PHP parser to work with a more varied string quotes and
   string concatenation.
 - The "extra" feature did not add a leading space for MySQL.  Using the
   tabbed output required updates to the parsing of the output generated 
   by MySQL.
 - Miscellaneous documentation updates.


Version 2.30

 New Features
 ------------
 - The result window has a local buffer mapping 'R', which will 'refresh'
   the window.  This means it will re-run the previous statement which is
   useful if you are repeatedly checking something in the database.
 - SQL Anywhere (ASA) no longer relies on the jcatalogue tables to be 
   installed in the database.  System views are used instead.
 - Support for MySQL 5.0 has been added, which includes stored procedures
   and views (as much as the beta allowed).
 - For Postgress SQL you can now optionally enter an owner name to filter by
   when showing list of objects (tables, procedures, views).

 Bug Fixes
 ------------
 - The |alternate-file| is no longer changed the first time the result buffer
   is opened.
 - Using DB2 with db2cmd incorrectly specified the command terminator with
   td, instead of -t.  
 - On win32 platforms, if the bin_path has been specified for DB2, then 
   add this to the system path since db2cmd relies on other batch files to
   operate correctly.
 - The connection string is displayed by both the Result buffer (first line)
   and the titlestring to the buffer (if enabled).  This was not correctly
   appending the user used to connect to the database.
 - When parsing Vim scripts we did not correctly remove a leading line 
   continuation slash from the from of a query.


Version 2.20

 New Features
 ------------
 - Added new connection parameter called "extra", you can place any 
   additional command line parameters in this option.
 - DBGetOption displays all options including the dbext version.
 - Better support for command terminators that have newline or special
   characters in them.  For example ASE/SQLSRV use "\ngo\n", now the
   command DBExecSQLUnderCursor will correctly find the statement.
 - Use_tbl_alias defaults to "ask", instead of "default on".
 - For most supported databases, when displaying the Table / Procedure / View
   List, you can now enter a partial string "DBA.", and if a . is included
   it will only display objects created / owned by that userid.
 - DBExecSQLUnderCursor would sometimes stop in the middle of a query 
   if the command terminator was included (inside a quoted string), now
   it ensures there is no text following the terminator.
 - The result window also includes the error code returned by the binary
   used to execute the command.  This can be useful for debugging.
 - The first line of the result window includes a line showing the connection
   information, if you have many buffers open, it can be difficult to 
   determine which database you are executing commands against.  A glance at
   this line will tell you immediately.
 - g:dbext_default_always_prompt_for_variables = 0 will prevent you from
   being prompted for substitution parameters.  Setting this value to 1
   will always prompt the user.
 - You can now abort the execution of a statement if you are prompted
   for substitution parameters.
 - If you are prompted for parameters, if you choose "Stop Prompting" the
   command will be executed immediate.  If "Never Prompt" is chosen, no
   further prompting will occur for this buffer.

 Bug Fixes
 ---------
 - SQLSRV did not have a default command terminator, now it is "\ngo\n".
 - Changed the Oracle command terminator to ";", and the routine that
   executes the statements automatically adds the "\nquit;\n" so that
   sqlplus will complete.
 - Spaces were not correctly removed from column lists in all cases, this
   showed up as an issue with the SQL Intellisense plugin.
 - When executing SELECT statements the INTO clause (if present) is 
   removed so the results are displayed in the result window.  Refined the
   removal of the INTO clause to ensure it does not interfer with an
   INSERT or MERGE statement.


Version 2.11

 Bug Fixes
 ---------
 - On some platforms the temporary file created to execute SQL statements must
   end in ".sql".  Corrected this for all databases


Version 2.10

 New Features
 ------------
 - Added support for the database SQLite (thanks to Ron Aaron).
 - Added a tutorial in the documentation for first time users.
 - New functionality for better integration with the Intellisense SQL plugin.
 - Ability to change the title of the window/buffer.
 - Integrated Login support for windows.
 - Added new functionality to these commands:   |dbext-mappings|
     DBGetOption
     DBSetOption
     DBExecRangeSQL
 - Added 4 new options:                         |dbext-configure-variables| 
     replace_title                                
     custom_title
     use_tbl_alias
     delete_temp_file

 Bug Fixes
 ---------
 - dbname was not defaulting correctly.
 - Overhauled the DB2 support. 
 - bin_path did not work correctly on windows platforms.
 - Updated the connection text in the Result buffer.


Version 2.00

 New Features
 ------------
 - In version 2.00 the following new features have been added to dbext.
 - Connection Profiles                          |dbext-connect-profiles|
 - Modeline Support                             |dbext-connect-modelines|
 - Object Completion                            |dbext-completion|
 - Viewing Lists of Objects                     |dbext-list-objects|
         Tables
         Procedures
         Views
         Columns
 - FileType Support Added                       |dbext-filetypes|
         Supported PHP, Java, JSP, JavaScript, jProperties, Perl, SQL, Vim
 - Intellisense Addin Support                   |dbext-intellisense|

==============================================================================
3. Overview						*dbext-overview*

 This plugin contains functions/mappings/commands to enable Vim to access 
 several databases. List of currently supported databases:
        DB2 
        Firebird
        Ingres
        Interbase
        Microsoft SQL Server
        MySQL
        PostgreSQL
        Oracle
        Oracle Rdb on an Open VMS Node
        SQLite
        Sybase Adaptive Server Anywhere
        Sybase UltraLite
        Sybase Adaptive Server Enterprise
 When using a Perl enabled Vim ( :echo has('perl') ):
        DBI
        ODBC

 It does this by shelling out to the operating system and calling the 
 command line tools that come with the client software for the database.
 For example, if you are connecting to an Oracle database, dbext.vim will call
 sqlplus to execute the SQL statements, for MySQL it uses the
 mysql binary, for ASA it uses the DBISQL binary.
 
 When a command is executed, a read only buffer (Result) is opened (see
 options |dbext-configure-variables|): >
     :DBGetOption use_result_buffer 
     :DBGetOption buffer_lines
<
 The output from the command is displayed in this buffer.  The buffer can be
 moved or deleted.  The next time a command is executed, it will be created,
 or cleared out and the new results will be placed within.

 If a select statement is executed, its results will be displayed in this
 buffer.  If a syntax error occurs during a command (for example running a
 statement that has a syntax error in it) the output error messages from the
 database will be displayed in the Result buffer.

 In addition to the 10 currently supported relation databases (RDBMS), you can
 easily add support for new database's. See |dbext-newdb| for details.  

 On the supported databases you can execute any SQL statements (insert,
 update, delete, create, alter, drop ...), describe tables, describe stored
 procedures, see table lists, create column lists and so on. >

 TIP:
<You can create dbext modelines |dbext-connect-modelines| in your files to
 automatically specify connection information.  In your |.vimrc| you can
 also create dbext connection profiles |dbext-connect-profiles| to specify
 common connection information (for example by projects).  The first time you
 execute SQL, you will be prompted to choose these profiles (if not already
 set via a modeline or default profile).  This is the easiest and most
 efficient use of specifying connection information.  It also has the added
 benefit of hiding userids, passwords and so on, in your |.vimrc| instead
 of in the files themselves.

 In the event of an error, the command line used to execute the command
 against the database is displayed in the Result buffer.  This is done to 
 help determine what is the cause of the problem might be.  

==============================================================================
4. Installing the plugin				*dbext-install*

 You can use this script as a plugin by copying it to your plugin directory. 
 See |add-global-plugin| for instructions.
 
 You can also |:source| it from your |.vimrc|.

 To install this help file |add-local-help| inside Vim.
 	:help add-local-help
	:helptags $VIM/vimfiles/doc (Windows)
	:helptags $VIM/.vim/doc     (Unix)

==============================================================================
5. Configuration					*dbext-configure*

 The behavior of dbext.vim are governed by several variables. These variables
 are used as the default database connection information.  These variables can
 be assigned global defaults which can be set in your |.vimrc|. See the script
 for details.  Otherwise, each buffer maintains its own values.  So each
 buffer can be connected to different databases, even different relational
 databases (one buffer connect to Oracle, another buffer to MySQL).

 A menu has been added to gvim with available commands in all modes.

5.1 Displaying Results                          *dbext-configure-results*

 When any command is run, by default a window is opened with a read-only 
 buffer.  By default, the window is called Result.  Each buffer will clear
 out and re-populate this buffer with the results of the last command.
 To control the size of the Result window, you can set the following: >
        let g:dbext_default_buffer_lines = 5 (default)
<If you want each buffer to have its OWN Result buffer, you can define: >
        let g:dbext_default_use_sep_result_buffer = 1 (default=0)
<
 There are a few local buffer mapping created in the Results buffer:
    R       - Pressing 'R' calls the DBResultsRefresh command.  This will
              to re-run the statement which populated the result window.  

    q       - Quick way to close the window if you have finished with
              the results and essentially want to hide it until the 
              next time you need it.

    a       - Toggle the autoclose feature.
              the results and essentially want to hide it until the 
              next time you need it.

    O       - Change the result orientation (only with DBI and ODBC).

    <Space> - If using a vertical window will toggle the width to make
              it easier to read.

 If you define a function, DBextPostResult, in your .vimrc (or elsewhere)
 it will be called automatically each time the Result buffer is updated.
 This can be used to do anything you need, the initial request for the 
 feature was for the ability to use Vim's syntax highlighting to make
 the results displayed from a MYSQL query more readable.

 The function takes two parameters: >
    db_type
<       - The database type specified for the buffer which caused the
          Result buffer to be updated.  It will be one of the following:
          ASA,ASE,DB2,INGRES,INTERBASE,MYSQL,ORA,PGSQL,SQLSRV,SQLITE >
    buf_nr
<       - The buffer number of the result window    
 Here is a very simple example which will:
    - Do nothing if connected to a database other than MYSQL
    - Highlight any numeric values at the beginning of a line  >
        function! DBextPostResult(db_type, buf_nr)
            " If dealing with a MYSQL database
            if a:db_type == 'MYSQL'
                " Assuming the first column is an integer
                " highlight it using the WarningMsg color
                syn match logWarn '^\d\+'
                hi def link logWarn		WarningMsg
            endif
        endfunction
<

5.2 Script Variables                            *dbext-configure-variables* 

 Global variables: >
    dbext_default_profile
<       - Predefined favourite connection information >
    dbext_default_type
<       - Default relational database to connect to >
    dbext_default_integratedlogin
<       - On Windows, whether to use integrated login for ASA and SQLSRV >
    dbext_default_user
<       - Default user id >
    dbext_default_passwd
<       - Default password >
    dbext_default_dbname
<       - Default database to connect to >
    dbext_default_host
<       - Default host the server is running on >
    dbext_default_port
<       - Default port to connect to >
    dbext_default_extra
<       - Customization string if the above options are not enough >
    dbext_default_use_result_buffer
<       - Whether to use the result buffer, or echo the results of the command >
    dbext_default_use_sep_result_buffer
<       - Whether to use separate result buffers for each file >
    dbext_default_buffer_lines
<       - How many lines the Result window should be >
    dbext_default_parse_statements 
<       - Which statements are parsed for input parameters (See |dbext-newdb|) >
    dbext_default_prompt_for_variables 
<       - Allows you to specify if dbext should check for host variables >
    dbext_default_always_prompt_for_variables 
<       - If host variables are found, you are asked if you want to be
          prompted, setting this variable assumes you always want to be
          prompted, so it saves you a dialog.
        - This option can have 3 values:
             1 - Always prompt for variables
             0 - Ask if you want to (if variables are found)
            -1 - Never prompt for variables >
    dbext_default_stop_prompt_for_variables 
<       - This is used internally by dbext.  Each time a query is executed
          and the user is prompted for variables, if you press "Ok" without
          entering anything, you are prompted asking whether you want to:
                1.  Skip the replacement for this string
                2.  Replace it with a blank
                3.  Stop prompting for just this query 
                4.  Never prompt for variables (including subsequent queries)
                5.  Abort the query and do NOT execute it
        - If option 3 is chosen, dbext sets this variable and resets it for
          the next query. >
    dbext_default_display_cmd_line 
<       - When the command is run, the results are displayed in the Result
          buffer, setting display_cmd_line = 1, will also display the command
          that was run to generate the output.  Useful for debugging.  >
    dbext_default_variable_def
<       - List of variables and rules on how to search and prompt for variable
          names within a statement that starts with any of the words listed in
          dbext_parse_statements. >
    dbext_default_replace_title 
<       - Changes the title of the buffer to show connection information.
          This is useful if you are using a scratch buffer to test statements, 
          it will show you which database you are connected to visually by
          glancing at the buffer title. >
    dbext_default_custom_title 
<       - If the default format of the replace title feature does not meet
          your needs, you can set a custom title.  To retrieve settings
          from the dbext plugin you can use: >
            :let new_title = 'Srvr: ' . DB_listOption('srvname')
            :exec 'DBSetOption custom_title='.new_title
    dbext_default_use_tbl_alias
<       - DBListColumn (by default) will create a column list with an
          alias attached to each column.  This option has three 
          settings: >
            n - do not use an alias
            d - use the default (calculated) alias
            a - ask to confirm the alias name
<       - An alias is determined following a few rules:
            1. If the table name has an '_', then use it as a separator: >
               MY_TABLE_NAME --> MTN
               my_table_name --> mtn
               My_table_NAME --> MtN
<           2. If the table name does NOT an '_', but DOES use mixed case 
               then the case is used as a separator: >
               MyTableName --> MTN
<           3. If the table name does NOT an '_', and does NOT use mixed case 
               then the first letter of the table is used: >
               mytablename --> m
               MYTABLENAME --> M
<       - The option can be turned on and off via the DBSetOption command. >
            :DBSetOption use_tbl_alias=n
    dbext_default_delete_temp_file 
<       - If debugging, it can be useful to view the SQL file that
          dbext generated to be executed by the database.  Setting this
          option to 0 (off) will leave the temporary file in the
          $TEMP directory for viewing. >
            :DBSetOption delete_temp_file=0
    dbext_default_history_file
<       - The SQL history is stored within a file.  This was done for 
          a couple of reasons:
              1.  No upper bound on the size of the history.
              2.  If you have multiple instances of Vim running, each
                  will see the current history without overwriting
                  each other (thereby loosing history).
              3.  The history can easily be removed if necessary.
          Each SQL statement has it's newline characters replaced with 
          @@@ so the statement fits on one line.  The default history
          file varies by the OS:
              Unix:     $HOME/dbext_sql_history.txt
              Windows:  $VIM/dbext_sql_history.txt
          If you wish to override the file location you can via your
          |vimrc|.  To see the current setting run :DBGetOption. >
            :let  g:dbext_default_history_file = '/your/loc/file.txt'
            :let  g:dbext_default_history_file = 'c:\your\loc\file.txt'
    dbext_default_history_size 
<       - Controls how many SQL statements should be stored within the
          history.  The default value is 50.  This option must be
          set within your |vimrc|.  To see the current setting run
          :DBGetOption. >
            :let  g:dbext_default_history_size = 50
    dbext_default_history_max_entry
<       - You can limit the size of the entries dbext records in the
          history file.  The current default is 4K.  Statements longer
          than 4K are not stored within the history file.  Setting this
          value to 0, removes any limits on the size of a single entry. >
            :let  g:dbext_default_history_max_entry = 4096
    dbext_default_dict_show_owner
<       - When creating a dictionary of tables, procedures and views
          the owner name can also be included.  The omni sql complete
          plugin uses this setting.  The default is enabled, to disable 
          add the following to your vimrc: >
            :let  g:dbext_default_dict_show_owner = 0
    dbext_default_use_win32_filenames
<       - If using Cygwin on Windows and the 3rd party binaries (sqlplus.exe,
          mysql.exe, dbisql.exe, ...) are Windows compiled then they will not
          understand Unix style filenames (with forward slashes).  Setting
          this option to 1, forces all filenames to be referenced with
          double backslashes instead.  It also uses the Cygwin utility,
          cygpath, to identify the absolute filename from a Windows
          perspective.  The default is 0, to enable add the following to your
          vimrc: >
            :let  g:dbext_default_use_win32_filenames = 1
    dbext_default_DBI_dict_proc_<DBI Driver Name>
<       - DBI has meta data for tables and views but not for procedures.
          If you use stored procedure completion with DBI you can define
          the SQL statement DBI will use to retrieve the list of stored
          procedures from the database.  For the current supported databases
          these settings have already been defined (if this was supported
          by version 4.20). >
            :let  g:dbext_default_DBI_dict_proc_SQLAnywhere = 
                      \ 'SELECT u.user_name ||''.''|| p.proc_name '.
                      \ '  FROM SYS.SYSPROCEDURE as p, '.
                      \ '       SYS.SYSUSERPERM as u '.
                      \ ' WHERE p.creator = u.user_id '.
                      \ ' ORDER BY u.user_name, proc_name')
    dbext_default_DBI_list_proc_<DBI Driver Name>
<       - DBI has meta data for tables and views but not for procedures.
          If you use stored procedure completion with DBI you can define
          the SQL statement DBI will use to retrieve the list of stored
          procedures from the database.  For the current supported databases
          these settings have already been defined (if this was supported
          by version 4.20).  dbext prompts for search criteria.  The SQL
          statement should support place holders to fill in both the
          owner name and the beginning of the procedure name.  In the 
          example below you can see if no owner or procedure name supplied
          a match to '%' is used which retrieves all procedures.  Simply
          add similar support to your own SQL statement.  >
            :let  g:dbext_default_DBI_list_proc_SQLAnywhere = 
                      \ 'SELECT p.proc_name, u.user_name '.
                      \ '  FROM SYS.SYSPROCEDURE as p, '.
                      \ '       SYS.SYSUSERPERM as u '.
                      \ ' WHERE p.creator = u.user_id '.
                      \ '   AND p.proc_name like ''dbext_replace_name%''   '.
                      \ '   AND u.user_name like ''dbext_replace_owner%''  '.
                      \ ' ORDER BY proc_name')
    dbext_default_DBI_desc_proc_<DBI Driver Name>
<       - DBI has meta data for tables and views but not for procedures.
          To "describe" a stored procedure (usually means seeing the
          parameters required) you must supply the SQL statement to send
          to the database.  Since each SQL statement will be different 
          depending on what database you are connected to the DBI driver
          name is used to distinguish what statement to send.  
          For the current supported databases
          these settings have already been defined (if this was supported
          by version 4.20).  The dbext_replace_name name is automatically
          replaced by dbext before being executed against the database.
          Simply add similar support to your own SQL statement.  >
            :let  g:dbext_default_DBI_desc_proc_SQLAnywhere = 
                      \ 'SELECT * '.
                      \ '  FROM SYS.SYSPROCPARMS as pp '.
                      \ ' WHERE pp.parmtype = 0 '.
                      \ '   AND pp.procname = ''dbext_replace_name''  '
    dbext_default_DBI_max_rows
<       - By default, we will only retrieve 300 rows from the DBI / ODBC 
          layer.   You can temporarily override the max row count using
          the :DBSetOption command.  DBI_max_rows is used by both the DBI
          and DBI / ODBC layer.  Setting this value to 0 removes the 
          limit.  >
            :let  g:dbext_default_DBI_max_rows = 500
            :DBSetOption DBI_max_rows=500
            :DBSetOption DBI_max_rows=     " Resets back to the default
            :DBSetOption DBI_max_rows=0    " Retrieve all rows
    dbext_default_DBI_commit_on_disconnect
<       - By default, when disconnecting from a DBI or ODBC datasource
          and AutoCommit is set to 0, a COMMIT will be issued against
          the database.  If you would prefer any outstanding changes
          to be rolled back on disconnect you can change this option. >
            :let  g:dbext_default_DBI_commit_on_disconnect = 0
            :DBSetOption DBI_commit_on_disconnect=1
            :DBSetOption DBI_commit_on_disconnect=     " Resets back to the default
    dbext_default_DBI_disconnect_onerror
<       - By default, if an error is reported by the database the 
          DBI / ODBC layer will disconnect from the database.  The next 
          time a command is sent to the database it will automatically 
          reconnect.  When disconnecting, the DBI_commit_on_disconnect
          option will be used.  Setting this value to 0 prevents the
          disconnect.  >
            :let  g:dbext_default_DBI_disconnect_onerror = 0
            :DBSetOption DBI_disconnect_onerror=0
            :DBSetOption DBI_disconnect_onerror=     " Resets back to the default
    dbext_default_DBI_split_on_pattern
<       - The DBI driver you are using dictates whether you can send 
          multiple statements (usually ; delimited) to the driver and have
          it execute each statement.  For example, in the MySQL 3.x DBI
          driver, you cannot send ; delimited statements, the driver
          will report an error.  This has apparantly been updated in the
          MySQL 4.x DBI driver.  For SQL Anywhere and SQL Server you
          can send multiple statements delimited by ;, but if you use
          the command terminated "go", the DBI layer will report errors.
          To work around these limitations, you can specify a regex
          pattern to instruct dbext on how to split the group of 
          statements into individual ones and execute independently.
          If an error is encountered during the execution, it will stop
          executing the statements and report the error.  The current 
          default pattern is: >
            "\n".'\s*\<go\>\s*'."\n"
<            
          If "go" is the only text found on a line, the statement will
          be split and set individually.  Notice the double quotes are 
          used to represent the newline, which is a special string in 
          Vim's regex.  You can define your own, or use the DBSetOption
          to override it for a particular buffer.  For example, if you
          are still using a MySQL DBI driver < version 4.x you can set
          the pattern to be a ";".  This would mean you cannot create
          stored procedures since each statement within the procedure
          is terminated with a ";".  That would send the entire procedure
          as individual statements which would result in syntax errors. >
            :let  g:dbext_default_DBI_split_on_pattern = ';'
            :DBSetOption DBI_split_on_pattern=';'
            :DBSetOption DBI_split_on_pattern=     " Resets back to the default
    dbext_default_DBI_cmd_terminator
<       - Most databases support the ";" as a command terminator, which
          is the default for the DBI / ODBC layer.  This is used by
          the DBI_read_file_cmd.  It can be overriden using: >
            :let  g:dbext_default_DBI_cmd_terminator = ';'
            :DBSetOption DBI_cmd_terminator=';'
            :DBSetOption DBI_cmd_terminator=     " Resets back to the default
    dbext_default_DBI_read_file_cmd
<       - Often you need to place common SQL statements in a file and 
          execute them with other statements.  You can consider this 
          similar to an IMPORT or INCLUDE command in other languages.
          The dbext plugin will look for the DBI_read_file_cmd and check
          if the following text is a filename.  If the filename exists, 
          the contents of the file will replace the DBI_read_file_cmd
          and filename plus an optional DBI_cmd_terminator. By default
          the DBI_read_file_cmd is set to "read ".  Notice the space after
          the word, which is important.  You could override this to something
          like '@', in which case no space is required since that is more
          like a control character.  It would not be confused with part
          of the following filename.  If the DBI_read_file_cmd command is
          found within a line which has been commented out, it will not
          be replaced.  Comments are determined by Vim's |comments| option. 
          The DBI_read_file_cmd can be nested indefinitely. >
            :let  g:dbext_default_DBI_read_file_cmd = '\.'
            :DBSetOption DBI_read_file_cmd='\.'
            :DBSetOption DBI_read_file_cmd=     " Resets back to the default
            
            read c:\temp\my.sql;
            read /temp/my.sql;
    dbext_default_DBI_orientation
<       - By default, result sets returned by the database are displayed
          in a tablular format: >
                ID   GivenName  Surname       
                ---  ---------  ------------  
                101  Michaels   Devlin        
                102  Beth       Reiser        
<         There are times when a vertical (versus horizontal) view is more
          appropriate.  The DBI layer also has this capability.  If the
          format is set to "horizontal" the standard output is used.
          Setting the format to anything other than "horizontal" will
          result in a vertical output: >
            :let  g:dbext_default_DBI_orientation = 'vertical'
            :DBSetOption DBI_orientation='v'
                ****** Row: 1 ******
                       ID: 101
                GivenName: Michaels 
                  Surname: Devlin      
                ****** Row: 2 ******
                       ID: 102
                GivenName: Beth     
                  Surname: Reiser      
                (2 rows)

            :DBSetOption DBI_orientation=     " Resets back to the default
                ID   GivenName  Surname       
                ---  ---------  ------------  
                101  Michaels   Devlin        
                102  Beth       Reiser        
    dbext_default_DBI_column_delimiter
<       - By default, each column is separated by 2 spaces.  It is often 
          desirable to tab delimit the columns.  You can specify whatever
          string you like by setting (NOTE: the use of the double quotes): >
            :let  g:dbext_default_DBI_column_delimiter = "\t"
    dbext_default_autoclose
<       - If you are executing a lot of statements without result sets
          (for example running a script which creates your schema)
          and you want to suppress the dbext result window from appearing
          (unless there is an error) you can enable this using several methods.
          Override this from within your vimrc file, or by pressing 'a' in 
          the result window or using the DBSetOption command.
          This option is disabled by default.
          Each time you execute a statement and the results are 
          automatically closed, a small reminder is displayed indicating
          how to disable it.  This also allows you to determine
          when the command has completed.
          WARNING: If autoclose is enabled, it can only be disabled by
          executing a DBSetOption command: >
            :let  g:dbext_default_autoclose = 1
            :DBSetOption autoclose=0
            :DBSetOption autoclose=1
    dbext_default_autoclose_min_lines
<       - Due to the large number of databases and different output 
          formats each of these support, dbext determines if the result
          window can be closed based on the number of lines (when no
          errors are detected) in the result window.  This option
          defaults to a value of 2. >
            :let  g:dbext_default_autoclose_min_lines = 2
            :DBSetOption autoclose_min_lines=2
    dbext_default_menu_mode
<       - Menus are useful for a number of reasons:
              See a list of available commands.
              Remember what the shortcut maps are.
              Have a floating menu when using the plugin a lot.
              Quick reference guide.
          There are four settings that will control the placement
          of the menu: 
              "0": Turns the menu off.
              "1": Turns the 'dbext' menu on with no menu shortcut.
              "2": Turns the 'dbext 'menu on with <alt>-d as the shortcut.
              "3": Turns the 'Plugin -> dbext' menu on with <alt>-d as 
                   the shortcut.
          This option defaults to a value of 3 and can be changed
          by adding the following to your vimrc: >
            :let  g:dbext_default_menu_mode = 3
    dbext_default_window_use_horiz
<       Default: 1
        When the Result window is opened, it uses a horizontal split at the
        bottom of the Vim window.  It can optionally use a vertical split by
        setting this option to 0.  >
            let g:dbext_default_window_use_horiz = 0  " Use vertical split
    dbext_default_window_use_bottom
<       Default: 1
        If using a horizontal split, this option control whether the window is
        opened at the top or bottom of the Vim window.  Setting this option to
        0 forces the window to open at the top of the Vim window.  >
            let g:dbext_default_window_use_bottom = 1  " Bottom
            let g:dbext_default_window_use_bottom = 0  " Top
    dbext_default_window_use_right
<       Default: 1
        If using a vertical split, this option control whether the window is
        opened on the left or right side of the Vim window.  To force the
        window to open on the left side, set this option to 0.  >
            let g:dbext_default_window_use_right = 1   " Right
            let g:dbext_default_window_use_right = 1   " Left
    dbext_default_window_width
<       Default: 1
        If using a vertical split, this option controls how wide to make the
        window.  Controlling the height of the horizontal split is already
        controlled by the dbext_default_buffer_lines option. >
            let g:dbext_default_window_width = 30
    dbext_default_window_increment
<       Default: 1
        If using a vertical split the default width of the vertical window may
        be too narrow to view enough of the elements.  Pressing [<space>] will
        increase the size of the window by this number of columns.  Pressing
        [<space>] again will toggle it back to the original size.  >
            let g:dbext_default_window_increment = 50
    dbext_default_login_script_dir
<       Default: ''
        Through a connection profile or the DBPromptForBufferParameters 
        command you can specify a filename containing commands to be 
        executed each time you connect to the database.  By default 
        the following directories are searched for these files: >
            :echo expand('$VIM')
            :echo expand('$HOME')
<       You can also customize where these files should be found by
        specifying the directory via a global variable in your |.vimrc|.
        You can include environment variables in the string as they 
        will be expanded automatically.  See the |dbext-tutorial| for 
        an example. >
            let g:dbext_default_login_script_dir = 'C:\MyScripts'
            let g:dbext_default_login_script_dir = '$HOME\MyScripts'
    dbext_default_variable_remember
<       Default: 1
        New feature to version 9.0.  SQL variables can now be stored
        for the buffer to save repeated prompting.  By default, when
        prompted, the value will be stored for later use.  To turn
        this feature off, add the following to your .vimrc: >
            let g:dbext_default_variable_remember = '0'


<
 Buffer variables
    You can check all options for the buffer without specifying an option name
    this will open the Result buffer and list all settings: >
        :DBGetOption 
< 
    You can check the value of a specific option by: >
        :DBGetOption user
< 
    Both DBGetOption and DBSetOption support completion.  This saves you
    having to figure out what the various options are.  Pressing the <Tab>
    button will cycle through the various options the plugin supports.
    This also works when entering a partial name, so if you type "u" and hit
    the <Tab> repeatedly, you will cycle through the 3 options which begin
    with the letter "u". >
        :DBGetOption <Tab>
        :DBGetOption u<Tab>
        :DBSetOption di<Tab>
<  
    For database specific options, you can include the type first: >
        :DBGetOption ASA<Tab>
        :DBGetOption ORA<Tab>
        :DBSetOption MYSQL<Tab>
< 
    These are set initially by the above defaults.
    Many of these can also be set by running PromptForBufferParameters.
    For each buffer these variables can be changed by running >
        :DBSetOption user=DBA
        :DBSetOption type=ASA
        :DBSetOption dsnname=Can Include Spaces
        :DBSetOption user=DBA
 
    profile
<       - Current profile specified (if any) >
    type
<       - Relational database to connect to >
    integratedlogin
<       - On win32, whether integrated logins are used >
              let g:dbext_default_profile_mySQLServer  = 'type=SQLSRV:integratedlogin=1:dbname=myDB'
    user
<       - User id >
    passwd
<       - Password >
    dsnname
<       - ODBC DSN to connect to >
    srvname
<       - Server name >
    dbname
<       - Which database on the server to connect to >
    host
<       - Machine name or IP address of server >
    port
<       - Port server is running on >
    extra
<       - Based on the database you are connecting to, you can add 
          additional items to the tools command line.  For example, 
          using ASA, I could run: >
              DBSetOption extra=CON=myconn
<
          From within a profile (set within your vimrc): >
              let g:dbext_default_profile_mysql = 'type=MYSQL:user=root:passwd=:dbname=mysql:extra=-t'
<
          This has the net result of creating the following command line: >
              dbisql -c "UID=dba;PWD=sql;CON=myconn"
    driver
<       - When using the DBI interface specify the driver name to use.
          Some common examples: SQLAnywhere, Oracle, MySQL. This is
          the name of the .pm module installed under the Perl 
          subdirectories. >
              DBSetOption driver=SQLAnywhere
    conn_parms
<       - When using the DBI interface specify the additional connection
          parameters which are passed to the DBI driver.
          These parameters vary based on which vendor's DBI module you
          are using. >
              " SQL Anywhere
              DBSetOption conn_parms=ENG=demo10;DBN=demo
              " MySQL
              DBSetOption conn_parms=database=mysql;host=localhost
    driver_parms
<       - When using the DBI interface specify the additional driver
          parameters which are passed to the DBI driver.
          Generally, the only time this option is required is if you
          wish to maintain a transaction during a editing session.  The
          default behaviour is AutoCommit.  Each statement executed is
          automatically committed by the DBI layer.  If you wish to be
          able to rollback any changes, you can add the AutoCommit=0
          to your driver line.  The commands :DBCommit and :DBRollback 
          can be used to control the transaction.
        - By default the DBI and ODBC interface will only retrieve the
          first 500 characters of a BLOB.  You can increase this value
          by specifying the LongReadLen on the connection string: >
              DBSetOption driver_parms=AutoCommit=0
              DBSetOption driver_parms=AutoCommit=0;LongReadLen=1000
    bin_path
<       - If tools provided by the database are not in the path, you can 
          optionally supply full path to the binaries.  This is also useful
          if two different buffers need to use different versions of the
          client software. >
    use_result_buffer
<       - You can turn on or off the use of the Result buffer >
    buffer_lines
<        - How large the Result buffer is >
    display_cmd_line
<       - Optionally display the command line used to execute the command
          in the Result buffer useful for debugging >
    parse_statements 
<       - Which statements are parsed for input parameters |dbext-prompting| >
    variable_def 
<       - List of variables and rules on how to search and prompt for variable
          names within a statement that starts with any of the words listed in
          parse_statements. >
    bin 
<       - Name of the binary which dbext uses to execute commands >
    cmd_header
<       - SQL statements sent before the command you are executing.  This
          setting is usually used to set temporary options, or output 
          options. >
    cmd_terminator
<       - Command terminator (varies per database, see
          |dbext-configure-options|) >
    cmd_options
<       - Optionally specify (or override) additional command line switches
          for the database tool. >
    on_error
<       - Dictates the behaviour of the tool if an error is encountered during
          execution. >
    suppress_version_warning
<       - If a user had a previous version version of dbext installed
          a warning message is displayed if some configuration parameters
          still exist.  This will prevent the message from begin 
          displayed. >
    autoclose
<       - See dbext_default_autoclose >
              DBSetOption autoclose=0
              DBSetOption autoclose=1
    autoclose_min_lines
<       - See dbext_default_autoclose_min_lines >
              DBSetOption autoclose_min_close=2


5.3 Database Specific Options                   *dbext-configure-options*
    The command terminator is automatically added to a command before it is
    sent to the database.  The command options are also added to the command
    line used to execute the statement. >
        dbext_default_PGSQL_bin                = 'psql'
        dbext_default_PGSQL_cmd_header         = ''
        dbext_default_PGSQL_cmd_terminator     = ''
        dbext_default_PGSQL_cmd_options        = ''
        dbext_default_MYSQL_bin                = 'isql'
        dbext_default_MYSQL_cmd_header         = ''
        dbext_default_MYSQL_cmd_terminator     = ''
        dbext_default_MYSQL_cmd_options        = ''
        dbext_default_MYSQL_version            = '5'
        dbext_default_ASA_bin                  = 'dbisql'
        dbext_default_ASA_cmd_header           = ''
        dbext_default_ASA_cmd_terminator       = ';'
        dbext_default_ASA_cmd_options          = '-nogui'
        dbext_default_INGRES_bin               = 'sql'
        dbext_default_INGRES_cmd_header        = ''
        dbext_default_INGRES_cmd_terminator    = '\p\g'
        dbext_default_INGRES_cmd_options       = ''
        dbext_default_ASE_bin                  = "isql"
        dbext_default_ASE_cmd_header           = ""
        dbext_default_ASE_cmd_terminator       = "\ngo\n"
        dbext_default_ASE_cmd_options          = '-w 10000'
        dbext_default_INTERBASE_bin            = ''
        dbext_default_INTERBASE_cmd_header     = ''
        dbext_default_INTERBASE_cmd_terminator = ''
        dbext_default_INTERBASE_cmd_options    = ''
        dbext_default_SQLITE_bin               = 'sqlite'
        dbext_default_SQLITE_cmd_header        = ".mode column\n.headers ON\n"
        dbext_default_SQLITE_cmd_terminator    = ';'
        dbext_default_SQLSRV_bin               = "osql"
        dbext_default_SQLSRV_cmd_header        = ""
        dbext_default_SQLSRV_cmd_terminator    = ""
        dbext_default_SQLSRV_cmd_options       = '-w 10000 -r -b -n'
        dbext_default_ORA_bin                  = "sqlplus"
        dbext_default_ORA_cmd_header           = 
                                \ "set pagesize 10000\n" .
                                \ "set wrap off\n" .
                                \ "set sqlprompt \"\"\n" .
                                \ "set sqlprompt \"\"\n" .
                                \ "set flush off\n" .
                                \ "set colsep \"\t\"\n" .
                                \ "set tab off\n\n"
        dbext_default_ORA_cmd_terminator       = ";"
        dbext_default_ORA_cmd_options          = '-S'
        dbext_default_DB2_use_db2batch         = 0
        dbext_default_DB2_bin                  = 'db2batch'
        dbext_default_DB2_cmd_header           = ''
        dbext_default_DB2_cmd_terminator       = ';'
        dbext_default_DB2_cmd_options          = '-q del -s off'
        dbext_default_DB2_db2cmd_bin           = 'db2cmd'
        dbext_default_DB2_db2cmd_cmd_options   = '-c -w -i -t db2 -s'

    dbext_default_MYSQL_version
<       - MySQL version 5 supports stored procedures, views and new system
          tables.  By default dbext takes advantage of these new
          INFORMATION_SCHEMA tables.  If you are using dbext with MySQL 4
          add the following to your vimrc to prevent the use of the new
          system tables: >
            let g:dbext_default_MYSQL_version = '4'


5.4 DB2 Modes                                           *dbext-configure-db2*
    DB2 provides two different binaries to execute commands: db2batch, db2cmd.  
    The dbext plugin supports both.  To change modes for the current buffer
    you can execute this command: >
        :DBSetOption DB2_use_db2batch = 1
        :DBSetOption DB2_use_db2batch = 0
<
    To change on a permenant basis add the following to your vimrc: >
        let dbext_default_DB2_use_db2batch = 1
<
    Each has their own advantages or disadvantages.  Depending on your 
    platform you may only have access to one or the other.  Please
    try both to see which fits your needs.


5.5 DBI Installation                                    *dbext-configure-dbi*
    To use the DBI interface you must first have a Perl enabled Vim.
    You can test your installation by running this command: >
        :echo has('perl')
<
    If you Vim is not Perl enabled you can:
        1.  Compile your own Vim and enable it.  Tony Mechelynck has posted
            some instructions on how to compile your own:
            - For Windows
                http://users.skynet.be/antoine.mechelynck/vim/compile.htm
            - For Unix
                http://users.skynet.be/antoine.mechelynck/vim/compunix.htm

        2.  Download a pre-built version of Vim with Perl already enabled
            - Steve Hall's Cream site which includes a non-cream version of
              Vim.  He routinely updates these builds which includes all 
              patches to the source as of his build.  This link includes only
              Perl, not the additional Cream add-ons.
                http://cream.sourceforge.net/download.html

    In order to use DBI, the Perl DBI modules must be installed.

    Install these perl modules, using ActiveState Perl on Windows you can do
    it as follows:
        cd Perl_Root_dir\bin
        ppm.bat
            install DBI
            install DBD::ODBC
            quit

    Installing the SQL Anywhere DBI module (ensure you are using 10.0.1.3525
    or above)
        cd %SQLANY10%\src\perl
        copy "%SQLANYSAMP10%\demo.db"
        dbeng10 demo

        Make sure SQLANY10 is in your path before any other versions of SQL
        Anywhere.
        "C:\Program Files\Microsoft Visual Studio .Net 2003\Common7\Tools\vsvars32.bat"
        or
        "C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat"
            perl Makefile.PL
            nmake
            nmake test
            nmake install

    Installing the Oracle DBI module
        cd Perl_Root_dir\bin
        ppm-shell.bat
            install DBD::Oracle
            quit

    Installing the Sybase (ASE) DBI module
        "C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat"
        cd Perl_Root_dir\bin
        perl -MCPAN -e shell
            install DBD::Sybase
            quit

    Installing the DB2 DBI module
        Make sure your DB2_HOME directory has been set
        cd Perl_Root_dir\bin
        perl -MCPAN -e shell
            install DBD::DB2
            quit

    Installing the binary MySQL DBI module
        cd Perl_Root_dir\bin
        ppm-shell.bat
            install DBD-mysql
            quit

    Installing the Sybase ASE or SQL Server DBI module
        http://lists.ibiblio.org/pipermail/freetds/2001q3/004748.html
        "C:\Program Files\Microsoft Visual Studio .Net 2003\Common7\Tools\vsvars32.bat"
        or
        "C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat"
        cd Perl_Root_dir\bin
        ppm-shell.bat
            install Sybase-TdsServer
            install DBD-mysql
            quit

==============================================================================
6. Mappings and commands				*dbext-mappings*

 Default visual/normal mode mappings (|:vmap|,|:nmap|):
 
    mnemonic s - sql

 Visual mode mapping (|:vmap|) and commands:
 
    " Execute SQL visually selected
    " mnemonic sql - execute
    vnoremap <unique> <Leader>se <Plug>DBExecVisualSQL
    :'<,'>DBExecVisualSQL

    " select * from the table visually selected
    " Very useful if you need to include an owner name for a table
    " ie DBA.Customer
    " mnemonic sql - table
    vnoremap <unique> <leader>st <Plug>DBSelectFromTable
    :DBSelectFromTable

    " Describe the table visually selected
    " Very useful if you need to include an owner name for a table
    " ie DBA.Customer
    " mnemonic sql - describe - table
    vnoremap <unique> <Leader>sdt <Plug>DBDescribeTable
    :DBDescribeTable

    " Describe the procedure visually selected
    " Very useful if you need to include an owner name for a table
    " ie DBA.sp_GetCustomerList
    " mnemonic sql - describe - procedure
    vnoremap <unique> <Leader>sdp <Plug>DBDescribeProcedure
    :DBDescribeProcedure

    " Display a list of tables with a specified prefix
    " sql - list - table
    vnoremap <unique> <Leader>slt <Plug>DBListTable
    :DBListTable
    
    " Display a list of procedures/packages/functions with a specified prefix
    " sql - list - procedures
    vnoremap <unique> <Leader>slp <Plug>DBListProcedure
    :DBListProcedure
    
    " Display a list of views with a specified prefix
    " sql - list - views
    vnoremap <unique> <Leader>slv <Plug>DBListView
    :DBListView
    
    " Display a list of columns for a given table
    " sql - list - column
    vnoremap <unique> <Leader>slc <Plug>DBListColumn
    :DBListColumn
    
 Normal mode mapping (|:nmap|):

    " Execute SQL query under cursor. You need a semicolon at the 
    " end of the query.
    " sql - execute
    nnoremap <unique> <Leader>se <Plug>DBExecSQLUnderCursor
    :DBExecSQLUnderCursor

    " Execute SQL query under cursor. You need a semicolon at the 
    " end of the query.  Prompt the user for how many rows to
    " return from the result set.
    " sql - Execute (capital E indicating a difference)
    nnoremap <unique> <Leader>sE <Plug>DBExecSQLTopX
    :DBExecSQLTopX

    " Execute a range of lines
    " sql - execute - all
    nnoremap <unique> <Leader>sea :1,$DBExecRangeSQL

    " Execute the current line
    " sql - execute - line
    nnoremap <unique> <Leader>sel :.,.DBExecRangeSQL

    " Execute the previous range
    " sql - execute - previous
    nnoremap <unique> <Leader>sep :'<,'>DBExecRangeSQL

    " select * from the table under the cursor
    " sql - table
    nnoremap <unique> <Leader>st <Plug>DBSelectFromTable
    :DBSelectFromTable

    " select * from the table under the cursor
    " Prompt the user for how many rows to return 
    " from the result set.
    " sql - Table (capital T indicating a difference)
    nnoremap <unique> <Leader>sT <Plug>DBSelectFromTableTopX
    :DBSelectFromTableTopX

    " select * from the table under the cursor prompt for where clause
    " sql - table - where 
    nnoremap <unique> <Leader>stw <Plug>DBSelectFromTableWithWhere
    :DBSelectFromTableWithWhere

    " Ask for the table name and select * from it
    " sql - table - ask 
    nnoremap <unique> <Leader>sta <Plug>DBSelectFromTableAskName
    :DBSelectFromTableAskName

    " Describe the table under the cursor
    " sql - describe - table
    nnoremap <unique> <Leader>sd <Plug>DBDescribeTable
    :DBDescribeTable

    " Describe the table prompt for the name
    " sql - describe - table - ask name
    nnoremap <unique> <Leader>sda <Plug>DBDescribeTableAskName
    :DBDescribeTableAskName

    " Describe the procedure under the cursor
    " sql -  describe - procedure
    nnoremap <unique> <Leader>sdp <Plug>DBDescribeProcedure
    :DBDescribeProcedure

    " Describe the procedure prompt for the name
    " sql - describe - procedure - ask name
    nnoremap <unique> <Leader>sdpa <Plug>DBDescribeProcedureAskName
    :DBDescribeProcedureAskName
    
    " Display a list of tables with a specified prefix
    " sql - list - table
    nnoremap <unique> <Leader>slt <Plug>DBListTable
    :DBListTable
    
    " Display a list of procedures/packages/functions with a specified prefix
    " sql - list - procedures
    nnoremap <unique> <Leader>slp <Plug>DBListProcedure
    :DBListProcedure
    
    " Display a list of views with a specified prefix
    " sql - list - views
    nnoremap <unique> <Leader>slv <Plug>DBListView
    :DBListView
    
    " Display a list of columns for a given table
    " sql - list - column
    nnoremap <unique> <Leader>slc <Plug>DBListColumn
    :DBListColumn
    
    " Display a list of all buffer specific SQL variables
    " sql - list - vaRiables
    nnoremap <unique> <Leader>svr <Plug>DBListVar
    :DBListVar
    
    " Assigns a buffer SQL variable
    :DBSetVar set @var1 = '3'
    " Removes a buffer SQL variable
    :DBSetVar set @var1 =
    " Executes a SQL statement to assign a SQL variable using 
    " the current line
    " sal - assign - line
    nmap <unique> <silent> <Leader>sal :.,.DBVarRangeAssign<CR>
    " Executes a SQL statement to assign a SQL variable using 
    " the entire buffer
    " saa - assign - all
    nmap <unique> <silent> <Leader>saa :1,$DBVarRangeAssign<CR>
    " Executes a SQL statement to assign a SQL variable using 
    " the previous range
    " sap - assign - previous
    nmap <unique> <silent> <Leader>sap :'<,'>DBVarRangeAssign<CR>
    " Executes a SQL statement to assign a SQL variable using 
    " the current visual range
    " sa - assign
    xmap <unique> <silent> <Leader>sa :DBVarRangeAssign<CR>
    
    " Opens the result window and displays a numbered list of 
    " previous SQL statements.  Pressing <enter> or double clicking 
    " on a SQL statement will execute the SQL.
    " sql - history
    nnoremap <unique> <Leader>sh :DBHistory
    
    " When using the DBI or DBI::ODBC interface you have the option
    " of displaying the results in the standard horizontal layout
    " or in a vertical layout which is especially useful for one
    " or two rows of output.
    " sql - orientation
    nnoremap <unique> <Leader>so :DBOrientation
    
    " Prompt for connection information
    " [Optional] Profile
    " [Required] Database type - MySQL, ASA, Ingress, Oracle (see above) 
    " [Optional] Integrated Login (Win32, ASA, SQLSRV)
    " [Optional] Database user
    " [Optional] User password 
    " [Optional] ODBC DSN
    " [Optional] Server name
    " [Optional] Database name
    " [Optional] Host name
    " [Optional] Port name 
    " [Optional] Directory for database tools (if not in path already)
    " sql - buffer prompt 
    nnoremap <unique> <Leader>sbp <Plug>DBPromptForBufferParameters
    :DBPromptForBufferParameters
		
 These are the default mappings.  If you choose your own keys, the plugin
 will use your mappings and will not create the default mappings.  You can
 also specify the following to disable the default mappings: >
        let g:dbext_default_usermaps = 0
<    
 Commands
    (In addition to the above mappings)
    DBExecSQL             - Enter any command you want sent to the database
    DBExecSQLTopX         - Enter any command you want sent to the database
                            and limit the result set to X rows
    DBExecRangeSQL        - Enter any command you want sent to the database
    Select                - Enter the remainder of a select (ie :Select from
                            customer)
    Update                - Enter the remainder of an update
    Insert                - Enter the remainder of an insert
    Delete                - Enter the remainder of an delete
    Call                  - Enter the remainder of a call/exec statement
    Drop                  - Enter the remainder of a drop
    Alter                 - Enter the remainder of an alter
    Create                - Enter the remainder of a create
    DBSetOption           - Allow you to set options from the command line.
                            This is useful in functions and mappings, see
                            |dbext-in-mappings|
    DBGetOption           - Retrieves current setting
    DBCheckModeline       - Checks the file for a dbext modeline, and sets 
                            the connection information
    DBResultsOpen         - Re-opens the result window if it was closed
    DBResultsClose        - Closes the result window
    DBResultsToggleResize - Toggles the size of the result window
    DBResultsRefresh      - Re-runs the statement currently displayed in the 
                            result window
    DBCompleteTable       - Sets up table name completion for the buffer
    DBCompleteProcedure   - Sets up table name completion for the buffer
    DBCompleteView        - Sets up table name completion for the buffer
    DBListTable           - Lists all tables (optional wildcard)
    DBListProcedure       - Lists all procedures (optional wildcard)
    DBListView            - Lists all views (optional wildcard)
    DBListColumn          - Comma separated list of columns for the given table
    DBListConnections     - Lists all active DBI connections
    DBCommit              - When using the DBI or ODBC layer and in your
                            connection profile you have specified AutoCommit=1,
                            you have the ability to commit any changes on the
                            connection.
    DBRollback            - When using the DBI or ODBC layer and in your
                            connection profile you have specified
                            AutoCommit=1, you have the ability to rollback any
                            changes on the connection.
    DBOrientation         - When using the DBI or DBI::ODBC interface you have
                            the option of displaying the results in the
                            standard horizontal layout or in a vertical layout
                            which is especially useful for one or two rows of
                            output.
                            This will toggle the current display.


==============================================================================
7. Adding new database types				*dbext-newdb*

 Select a unique name for your extension. Add it's uppercase name to 
 the list of other supported databases in the s:DB_buildLists() function.
 
 Next database specific functions need to be created.  Note: You must create
 all the functions, even if a particular feature is not supported by
 the database server you are adding.  Currently the following functions
 must be created for each new database. >
    DB_NEW_describeProcedure
    DB_NEW_describeTable
    DB_NEW_execSql
    DB_NEW_getDictionaryProcedure
    DB_NEW_getDictionaryTable
    DB_NEW_getDictionaryView
    DB_NEW_getListColumn
    DB_NEW_getListProcedure
    DB_NEW_getListTable
    DB_NEW_getListView
    DB_NEW_stripHeaderFooter
<
 Assuming the unique name for your extension was 'NEW'.  To begin with a 
 new database, copy all the DB_ASA_* functions and modify them to suite
 your needs.  Please consult the other databases for more ideas and
 examples.

==============================================================================
8. Prompting for input parameters			*dbext-prompting*

 This plugin has the ability to parse the statement being executed and
 prompt the user for input parameters.  The logic differs based on what type
 of file you are editing.  The default behaviour will only parse the SQL
 statements if the statement begins with any of the following: >
         select, update, delete, insert, call, exec, with
<
 Stored procedures routinely use parameters in SQL statements, so we do not
 want to prompt for values during a CREATE PROCEDURE statement.  
 
 By default the plugin searches the statement for this style of input 
 parameters: >
    ?
    @variable
    :variable
    $variable 
<
 If the statement has any of: (?,@,:,$), then the user will be prompted to ask
 whether the plugin should check and prompt for input parameters.  If your
 response is No, the statement is executed as is.  If you response is Yes,
 there are some rules surrounding the search and replacement of variables.
 Generally, any of the above formats surrounded in single quotes ('), will be
 ignored as input parameters.  

 To turn off this feature: >
        let g:dbext_default_prompt_for_parameters=0  (globally)
        DBSetOption prompt_for_parameters=0          (just for the buffer)
<
 To change which statements get parsed: >
        let g:dbext_default_parse_statements='select,update' (globally)
        DBSetOption parse_statements=select,update   (just for the buffer)
<
 The feature is best described with examples: >
        SELECT varexists('@dave'), column2
          INTO p1, p2
          FROM customer
         WHERE name    = @name
           AND address = ?
           AND phone   = :phone_nbr
           AND email   = 'bob@something.com'
           AND c2      = 'property:name';
<
 In this case we are demonstrating what is parsed from the statement and
 prompted for.
    1.  The INTO clause is removed, so the output is displayed in the Result
        buffer.
    2.  ?, @something, :something are stripped out of the query.  You are
        prompted to enter a suitable value for each one, and the resulting 
        query is sent to the database.
    3.  '@dave','bob@something.com' and 'property:name' are not stripped
        out of the query since they are surrounded in single quotes.
    4.  When prompted for a value for @name, I would enter 'Homer' (including
        the single quotes).
    5.  When prompted for a value for ? it will indicate which ? this is, by
        counting them and prompting you for a value for ? number 6.
 
 To modify what variables that are searched for consider the following
 example: >
        INSERT INTO sync_log ( user_id, table_name, line )
        VALUES( i_user, i_table_name, i_str );
<This is an INSERT statement within a stored procedure.  The stored procedure
 takes 3 input parameters.  The author of the stored procedure places a i_
 ahead of all input variables.  You can modify the buffer variable for this
 file as follows: >
        DBSetOption variable_def_regex=,\<i_\w\+\>
<
 The same regex expression should work when you simply run a find in Vim: >
        /\<i_\w\+\>
<
 This instructs the plugin to find all words that begin with "i_", with a
 series of \w characters following.  If the plugin finds more matches that
 expected, you can choose Cancel when prompted for the variable name, and
 choose Skip, to move to the next match.
 
 For more information on specific filetype support see |dbext-filetypes|

==============================================================================
9. Setting up connection information			*dbext-connect*

 Connection information is setup for each buffer.  This way you can have one
 buffer connected to an Oracle database and another buffer connected to a
 Sybase database.

 If no connection information has been provided, the first time you run a
 command, you will be prompted for connection information before the command
 executes.

 The most efficient use of the dbext plugin is to create connection profiles
 in your|.vimrc|.  When profiles exist, you can choose from a list of these
 profiles when a command is first executed (assuming connection information
 has not already been set via modelines |dbext-connect-modelines| or default
 profiles).

 
9.1 Connection Parameters                         *dbext-connect-parameters*

To specify the type of database you connect to most often, you can place the
 following in your |.vimrc| file: >
        let g:dbext_default_type   = 'ASA'
<
 If you have a standard login, this can also be specified: >
        let g:dbext_default_user   = 'DBA'
        let g:dbext_default_passwd = 'SQL'
<
9.2 Prompting for Parameters                      *dbext-connect-prompting*

 If you want the plugin to prompt you for connection parameters for the
 particular buffer you are in, you can run the command: >
       :DBPromptForBufferParameters
<
       or <Leader>sbp  (default mapping - mnemonic sql buffer prompt)

9.3 Connection profiles                           *dbext-connect-profiles*

 In your |.vimrc| file, you can define global database profiles.  A profile is
 a series of settings for a given database.  This is the easiest and most
 efficient use of specifying connection information.  It also has the added
 benefit of hiding userids, passwords and so on, in your |.vimrc| instead of
 in the files themselves.  When you issue a :PromptForBufferParameters or
 default map <Leader>sbp) if you have any connection profiles defined, you are
 prompted with a number list, which allows you to choose which profile you
 would like to use.  This is convenient since it can be difficult to remember
 the names of your profiles.  This feature can also be used with the dbext
 modelines (see |dbext-modelines|).

 In your |.vimrc| you can define the following: >
     let g:dbext_default_profile_ASA_generic = 'type=ASA:user=DBA:passwd=SQL'
     let g:dbext_default_profile_mySQLServer = 'type=SQLSRV:integratedlogin=1:dbname=myDB'
<
 If you created a dbext modeline in your file (using a comment that is suitable
 to the filetype you are editing): >
     // dbext:profile=ASA_generic:host=my_desktop
<
 This has the same effect as issuing the following commands: >
     DBSetOption type=ASA
     DBSetOption user=DBA
     DBSetOption passwd=SQL
     DBSetOption host=my_desktop
<
 You can create as many profiles in your |.vimrc| file as you like.  The
 dbext modeline is recursive, so if it finds a profile, it will execute all
 settings within it and continue with the remaining settings of the modeline.
 Profiles cannot be nested.

 Profiles are always specified in this format in your |.vimrc| file: >
     let g:dbext_default_profile_[your_profile_name] = 'type=ORA:user=scott'
<
 To create a default profile which will be used for all buffers that have not
 defined their own connection parameters you can add the following to your
 |.vimrc| to reference one of the profiles you have already created: >
     let g:dbext_default_profile = 'ASA_generic'
<
9.4 Connection profiles examples                *dbext-connect-profiles-examples*

 Here are some sample profiles I maintain.  These can help when trying to
 setup your own: >
    " SQL Anywhere (Normal, DBI and ODBC)
    let g:dbext_default_profile_cons = 'type=ASA:dsnname=cons'
    let g:dbext_default_profile_ASA_DBI = 'type=DBI:user=dba:passwd=sql:driver=SQLAnywhere:conn_parms=:driver_parms=AutoCommit=1;PrintError=0'
    let g:dbext_default_profile_ASA_DBI_demo10 = 'type=DBI:user=dba:passwd=sql:driver=SQLAnywhere:conn_parms=ENG=demo10;DBN=demo:driver_parms=AutoCommit=0'
    let g:dbext_default_profile_ASA_ODBC = 'type=ODBC:user=dba:passwd=sql:dsnname=SQL Anywhere 10 Demo'
    
    " Sybase ASE
    let g:dbext_default_profile_ASE = 'type=ASE:user=sa:passwd=whatever:srvname=my_server:dbname=ml8'
    
    " IBM DB2
    let g:dbext_default_profile_DB2 = 'type=DB2:user=db2admin:passwd=whatever:dbname=SSD:bin_path=C:\Programs\IBM\SQLLIB\BIN'
    let g:dbext_default_profile_DB2_cons_1d = 'type=DB2:user=mlink:passwd=whatever:dbname=db2_2a:host=my_lab_box:port=60000'
    
    " MySQL
    let g:dbext_default_profile_mysql_local = 'type=MYSQL:user=root:passwd=whatever:dbname=mysql:extra=-t'
    let g:dbext_default_profile_mysql_local_DBI = 'type=DBI:user=root:passwd=whatever:driver=mysql:conn_parms=database=mysql;host=localhost'
    let g:dbext_default_profile_mysql_local_ODBC = 'type=ODBC:user=root:passwd=whatever:dsnname=mysql'
    
    " Oracle
    let g:dbext_default_profile_ORA = 'type=ORA:srvname=ffs42ga:user=john:passwd=whatever'
    " Oracle SQL Connect URL string (notice the : is escaped for the port option)
    let g:dbext_default_profile_ORA_URL = 'type=ORA:srvname=//localhost\:3333/instance_name:user=scott:passwd=tiger'
    
    " Postgress
    let g:dbext_default_profile_PG = 'type=PGSQL:user=postgres'
    
    " Microsoft SQL Server
    let g:dbext_default_profile_SQLSRV        = 'type=SQLSRV:user=sa:passwd=whatever:host=localhost:replace_title=1'
     let g:dbext_default_profile_mySQLServer  = 'type=SQLSRV:integratedlogin=1:dbname=myDB'
    
    " SQLite
    let g:dbext_default_profile_POPFile = 'type=SQLITE:SQLITE_bin=C:\Programs\POPFile\sqlite.exe:dbname=C:\Programs\POPFile\popfile.db'
<
9.5 Connection information in modelines           *dbext-connect-modelines*
                                                  *dbext-modelines*

 See |modeline| for details on what are modelines.  dbext uses a similar
 format to vim modelines.  This feature is enabled if the vim option 'modeline'
 is enabled and the 'modelines' option is > 0.

 When a new buffer is opened the top 5 (vim default for 'modelines' and bottom
 5 lines of of the buffer are checked for the dbext modeline.  If found,
 dbext will iterate through each option and set a corresponding local buffer
 variable to that value.  See |dbext-configure|, "Buffer variables"
 for a list of the variables available.

 Example, assume I had the following commented line in a SQL file on the third
 line of my file: >
     // dbext:type=ASA:user=dba:dsnname=My DSN with spaces:passwd=sql

<This has the same effect as issuing the following commands: >
     DBSetOption type=ASA
     DBSetOption user=dba
     DBSetOption dsnname=My DSN with spaces
     DBSetOption passwd=sql
<
 If you specify a profile in a modeline, it must be the first
 option specified: >
     // dbext:profile=ASA_generic:host=my_desktop
<
 This has the same effect as issuing the following commands: >
     DBSetOption type=ASA
     DBSetOption user=dba
     DBSetOption dsnname=My DSN with spaces
     DBSetOption passwd=sql
     DBSetOption host=my_desktop
<
 To deal with running different versions of database software on your 
 machine you can also set the binary path, or the binary itself from within
 modelines. >
     -- dbext:type=SQLITE:SQLITE_bin=D:\Programs\POPFile\sqlite3.exe:dbname=D:\Programs\POPFile\popfile.db'
<
 Or in the case where the binary has the same name, but the directories are
 different: >
     -- dbext:type=SQLITE:bin_path=D:\Programs\POPFile:dbname=D:\Programs\POPFile\popfile.db'
<
 If you use the variable_def_regex option to specify different variables to
 prompt for, this setting can also be set via the modeline.  All though, due
 to the special regex syntax.  This means to set the variable_def_regex from 
 a modeline, you must use a separate modeline: >
     // dbext:profile=myFavouriteProfile
     // dbext:variable_def_regex=\<\(p_\|lv_\)\w\+\>
<
 If you simply want to add to the existing default settings for this option
 the value can be preceeded by a comma: >
     // dbext:variable_def_regex=,\<\(p_\|lv_\)\w\+\>
<
 Executing :DBGetOption variable_def_regex will display the new values 
 notice the , separating 3 different regexes: >
     variable_def_regex = \(\w\|'\)\@<!?\(\w\|'\)\@<!,\zs\(@\|:\|$\)\w\+\>,\<\(p_\|lv_\)\w\+\>


9.6 Ask for connection parameters	           *dbext-connect-ask*

 Modelines can also take three special values: @askg, @askb, @ask.

 @askg - Will prompt the user and set the value globally for all Vim buffers.
 @askb - Will prompt the user and set the value only for this Vim buffer.
 @ask  - Will prompt the user and set the value each time dbext is used.

 Example, assume I had the following commented line in a SQL file on the third
 line of my file: >
     // dbext:type=@askg:user=@askb:passwd=@ask

<This will prompt you once to specify which database type you want to connect
 to and use this value for all buffers.  It will prompt you once for your
 userid for each buffer.  You will also be prompted for your password each
 time dbext is used.



9.7 Using autocmds to setup parameters	           *dbext-connect-autocmd*

 If you wish to programmatically setup connection parameters based on your
 environment or buffer information you can define an autocmd in your 
 |.vimrc| which will be triggered automatically by dbext when appropriate.

 Example, create the following in your |.vimrc|: >
    augroup dbextExtras
        autocmd!
        autocmd User dbextPreConnection :echo 'dbextPreConnection fired'
        autocmd User dbextPreConnection :DBSetOption 'dbname=bob'
        autocmd User dbextPreConnection :DBSetOption 'host=jim'
        autocmd User dbextPreConnection :DBSetOption 'type=ASA:dsnname=myDSN:user=DBA:passwd=sql'
    augroup END

<Obviously, the echo line is just for debugging, you should be able to see
 that it was called by using the |:messages| command.

 The example demonstrates you can call DBSetOption multiple times setting one
 option at a time or once passing multiple options as you would with a
 modeline.  After this autocmd fires, dbname, host, type, dsnname, user 
 and passwd are all set.  

 If you simply created a new file and ran :DBListTable the autocmd would setup
 your connection information and query the database without prompting you for 
 connection parameters.

==============================================================================
10. Creating mappings using dbext commands        	*dbext-in-mappings*

 dbext's commands can be used within mappings.  Here is a simple example 
 that you can place in your |.vimrc|:
     a) Sets connection information (based on "your_profile"). >
           profile=your_profile
<       This assumes you have the following in your |.vimrc| >
           let g:dbext_default_profile_your_profile = 'type=ASA:..."
<    b) When the mapping is executed, the full command is displayed
        in the dbext result window (useful for debugging). >
           display_cmd_line=1
<    c) Turns off parsing the statement and prompting the user for
        input. >
           prompt_for_parameters=0
<    d) Uses the DBExecSQL command to execute a DELETE statement
        that uses the current buffers file_name as part of the 
        WHERE clause. >
           nnoremap <buffer> <Leader>hx 
           \ :DBSetOption profile=your_profile:display_cmd_line=1<CR>
           \ :DBSetOption prompt_for_parameters=0<CR>
           \ :let sql_cmd = "DBExecSQL delete from xsl " .
           \      "where name = '" . expand("%:t") . "';"<CR>
           \ :exec sql_cmd<CR>
<
==============================================================================
11. Object Completion                                 	*dbext-completion*

 Table/Procedure/View (Keyword) Completion

 dbext has the ability to retrieve a list of all tables, procedures and views 
 and allow keyword completion using Vim's dictionary feature |i_CTRL-X_CTRL-K|.
 For each buffer, to generate the dictionary file run: DBComplete[Object].
 Once the command is completed, you can type in a partial table name, and use
 CTRL-K to cycle through all tables that start with the given prefix. >
        DBCompleteTables
        DBCompleteProcedures
        DBCompleteViews
<        
 If you no longer want to complete these items you can execute the following: >
        DBCompleteTables!
        DBCompleteProcedures!
        DBCompleteViews!
<
 For complete code completion added via various plugins see
 |dbext-integration|.

==============================================================================
12. Listing Ojects in the Database                     	*dbext-list-objects*

 Many times you just want to see what is available in a given database.
 DBListTable, DBListProcedure, DBListView will display a list of objects
 in the result window.  You will be prompted for a prefix (the prefix is
 treated as a wildcard).  The output varies per database you are connected to
 but it usually contains the owner and the table names as a minimum.
 The results are displayed in the usual result window.

 DBList[ Table | Procedure |View ] takes 1 optional parameter.  A wildcard
 pattern can be supplied, if omitted it will prompt the user for a pattern.
 The query sent to the database uses the LIKE 'pattern%' operator.

 DBListColumn is slightly different.  It will create a comma separated list
 of all the columns of a table in the order they were specified in the 
 CREATE TABLE statement used when the table was created.  This list is placed
 in Vim's standard paste buffer, so "p" will paste the results.  This was
 designed so that you could type: >
        SELECT employee
<
 While the cursor is still on table_name you can type: >
        <C-O><Leader>slc
<
 Now the paste buffer has a comma separated list of columns for the "employee"
 table.  Hitting <Esc>diwp, will delete (inner word) the word "employee" and
 replace it with the list of columns from the paste buffer.

 If no table name is supplied, the current word is chosen as the table name.

==============================================================================
13. Plugin integration                     	        *dbext-integration*

 SQL code completion has an interface component which provides a popup window
 that allows the user to choose from a list of values.  The values include
 various static elements (statements, functions, types, keywords, ...).  But
 they can also provide dynamic lists for tables, procedures, views and even
 column lists for tables.

 If you want the code completion to work with dynamic lists, you must ensure
 each buffer can connect to the required database.  You can do this easily by
 creating a profile (|dbext-connect-profiles|), and making it the default
 profile (dbext_default_profile).  If you start editing a new file, dbext will
 automatically connect using the specified default profile.

13.1 OMNI completion integration                     	*dbext-omni-completion*

 Vim 7 has natively included features provide an interface which allows plugin
 developers to provide code completion.  The SQL completion plugin is included
 with Vim 7.  It will detect if dbext.vim is already installed and take
 advantage of it.

13.2 Intellisense integration                     	*dbext-intellisense*

 Intellisense.vim (http://www.vim.org/scripts/script.php?script_id=747) is a
 windows only solution.  It has support for a number of different languages
 and provides a popup window which can be dynamically populated.

 The first version of Intellisense to have the SQL plugin is 1.24.

==============================================================================
14. Filetype support                         	        *dbext-filetypes*

 SQL can be used from a variety of languages.  Each development language (PHP,
 Perl, Java, ...) language has different syntax for creating SQL statements
 that are sent to the database.  dbext has support for several different
 filetypes, so that it can understand and correctly parse a SQL statement.

 The current supported languages are:
        PHP, Java, JSP, JavaScript, JProperties, Perl, SQL, Vim

14.1 Using filetype support                 	*dbext-filetypes-using*

 For example assume you had the following Java code:
>
	String mySQL = 
	    "SELECT s.script, ts.event, t.name                  " +
	    "     , s.script_language, sv.name                  " +
	    "  FROM ml_script s, ml_table_script ts, ml_table t " +
            "     , ml_script_version sv                        " +
	    " WHERE s.script_id   = " + script_version +
	    "   AND ts.version    = "+obj.method() +
	    "   AND ts.table_id   = t.table_id                  ";
< 
 If you visually select from the "SELECT ... to the "; and ran 
 :'<,'>DBExecSQL

 The Java filetype support would concatenate each individual string into 
 one single string.  In this case it removed the " + " and concatenated
 the lines to result in the following (assuming this is on one line): >
 	     SELECT s.script, ts.event, t.name , s.script_language, sv.name
	       FROM ml_script s, ml_table_script ts, ml_table t 
                  , ml_script_version sv
	      WHERE s.script_id   = " + script_version + "
	        AND ts.version    = "+obj.method() +"
	        AND ts.table_id   = t.table_id 
<
 Next, it will prompt you for replacement values for the various variables or
 objects you used in the string.
 Assuming you had the default behaviour turned on, you would be prompted
 to supply a value for: >
                " + script_version + "
                "+obj.method() +"
<
 So assuming you entered: >
                100
                'Project_Yahoo'
<
 Then the resulting string sent to your database would be (again, this would
 technically be on one line): >
 	     SELECT s.script, ts.event, t.name , s.script_language, sv.name
	       FROM ml_script s, ml_table_script ts, ml_table t 
                  , ml_script_version sv
	      WHERE s.script_id   = 100
	        AND ts.version    = 'Project_Yahoo'
	        AND ts.table_id   = t.table_id 
<
 You did not have to test your SQL by cutting and pasting it into a separate
 tool and replacing all the object and host variables yourself.  Just by
 visually selecting the string and running the command DBExecSQL (or the
 default mapping <Leader>se) the SQL statement was executed against the
 database and allowed to you enter host variables.
 

14.2 Adding new filetypes                   	*dbext-filetypes-adding*

 It is very easy to add a new language, as long as you know the rules
 for how strings are joined.  In dbext.vim, there are functions for
 each language, DB_parse[filetype].  To add a new language, find a language
 with rules most similar to the new language.  Copy and paste that function to
 the new name and modify the regular expressions used to adapt to the 
 syntax rules of the language you are adding.  

 These expressions can be a bit complex, but the ones currently used have been
 documented to make your task easier.

 It can take as little as 5 minutes to add a new language.

 If you do add a new language, please forward along the code to 
 David Fishburn -and- Peter Bagyinszki for inclusion into future versions.
 
==============================================================================
15. Using SQL History                         	        *dbext-history*

 As of version 3.0, dbext maintains a history file which is shared between 
 multiple instances of Vim.  A statement added in one instance of Vim
 will be immediately available in a different instance of Vim on the 
 same computer.

 To access the history you can run the command, :DBHistory, or use the
 mapping <Leader>sh (\sh using Vim defaults).  This opens a window similar 
 to the result window.  This buffer is readonly, but has several buffer 
 specific maps to allow you to interact with it.

 To re-run a statement you can either press <enter> on the line, or if you 
 prefer the mouse you can double click on the statement.  When a statement
 is chosen you are switched back to the buffer which opened the history 
 window.  The statement is executed using that buffers connection
 parameters.
 
 There are a few local buffer mapping created in the History buffer:
    <Enter> - Execute the statement.

    q       - Quick way to close the window if you have finished with
              the results and essentially want to hide it until the 
              next time you need it.

    a       - Toggle the autoclose feature.
              the results and essentially want to hide it until the 
              next time you need it.

    dd      - To remove statements from the history you can press "dd" 
              as you would delete a line in a regular Vim buffer.

    <Space> - If using a vertical window will toggle the width to make
              it easier to read.

 To remove statements from the history you can press "dd" as you would 
 delete a line in a regular Vim buffer.

 The history buffer is automatically saved each time it is changed.

 The default file location for the history file is stored in your $HOME
 directory for Unix and in the $VIM directory for Windows.  It can be
 configured via the g:dbext_default_history_file variable.  The number
 of statements stored within the history can be configured via the
 g:dbext_default_history_size variable.   By default statements < 4K
 are stored in the history this can be configured via the
 g:dbext_default_history_max_entry variable.  See |dbext-configure-variables| 
 for more details.
 
==============================================================================
16. Open Source                         	*dbext-sourceforge*

 dbext is now an open source project found at: >
     https://sourceforge.net/projects/dbext/
< 
==============================================================================
17. Tutorial                            	*dbext-tutorial*

 This tutorial is designed to take you through the common features of dbext
 so that:
    a) You gain familiarity with the plugin
    b) Introduced to some of the more common features
    c) Show to customize it to your preferences
    d) Demonstrate "Best of Use" of the plugin (easiest way to configure).

 First, create a new buffer: >
     :e tutorial.sql
< 
 Add some SQL statements (yank and paste this section into the new buffer): >
    CREATE TABLE customer(
        id              INTEGER NOT NULL,
        cust_name       VARCHAR(30) NOT NULL,
        phone_nbr       VARCHAR(30) NULL,
        PRIMARY KEY(id)
    );

    INSERT INTO customer(id, cust_name, phone_nbr)
    VALUES( 1, 'Bob', '555-1210' );
    INSERT INTO customer(id, cust_name, phone_nbr)
    VALUES( 2, 'Jim', '555-1211' );
    INSERT INTO customer(id, cust_name, phone_nbr)
    VALUES( 3, 'Ted', '555-1212' );
    INSERT INTO customer(id, cust_name, phone_nbr)
    VALUES( 4, 'Sid', '555-1213' );
    INSERT INTO customer(id, cust_name, phone_nbr)
    VALUES( 5, 'Joe', '555-1214' );
    COMMIT;

    CREATE TABLE contact(
        id              INTEGER NOT NULL,
        cont_name       VARCHAR(30) NOT NULL,
        phone_nbr       VARCHAR(30) NULL,
        PRIMARY KEY(id)
    );

    INSERT INTO contact(id, cont_name, phone_nbr)
    VALUES( 10, 'Bob', '555-1210' );
    INSERT INTO contact(id, cont_name, phone_nbr)
    VALUES( 20, 'Jim', '555-1211' );
    INSERT INTO contact(id, cont_name, phone_nbr)
    VALUES( 30, 'Ted', '555-1212' );
    INSERT INTO contact(id, cont_name, phone_nbr)
    VALUES( 40, 'Sid', '555-1213' );
    INSERT INTO contact(id, cont_name, phone_nbr)
    VALUES( 50, 'Joe', '555-1214' );
    COMMIT;

    SELECT id FROM customer;

    SELECT id FROM different_owner.customer;

    SELECT id 
      INTO @cust_variable_id
      FROM customer
     WHERE cust_name LIKE :host_var_name
       AND cust_name LIKE ?
       AND id        =    @var_name;
<



 17.1 Creating the connection                    *dbext-tutorial-connection*
 ----------------------------
 Now, we need to setup connection information for the buffer.  There are many
 ways to do this: use commands, use the menu or use the default mappings.
 Lets start with the most basic method.  You can execute the command: >
     :DBPromptForBufferParameters
<or use the default mapping <Leader>sbp, where the default for <Leader> 
 is the "\".  \sbp is derived from s (SQL) b (buffer) p (prompt).  This
 command will popup a message box (for GUI versions or display the list at the
 bottom of the screen for console versions) listing all the supported database
 types.  Choose the appropriate number from the list for your favourite
 database (or the one running on your machine).  After specifying the database
 type, the following prompts are optional.  Supplying a userid and password is
 usually required.

 Assuming we choose Oracle from the list, dbext.vim assumes that the 
 sqlplus binary is already in the system path.  If not, you can supply 
 the full path to the binary in the final prompt.



 17.2 The result buffer                          *dbext-tutorial-results*
 ----------------------
 When SQL statements are executed, a new split below buffer is created called,
 "Result".  This buffer is readonly, you will not be prompted to save it when
 exiting Vim.  After the buffer has been created, you can move the buffer to a
 location that better suits you.  Assuming you can hide buffers |'hidden'|, if
 you issue a :clo command, you can remove the buffer from the display.  The
 next time a command is executed, it will be made visible again.  There are
 also some local maps to make this easier.  'q' will close the window for you.
 To see the other buffer specific maps for the result window have a look
 at |dbext-configure-results|

 Lets test the connection, run the following command (Note the capital S): >
     :Select * from customer
<     
 Alternately, you can move your cursor to this line: >
    SELECT id FROM customer;
<    ^
 By running the map <Leader>sel - s (sql) e (execute) l (line), you can easily 
 test the connection without having to type anything (other than the map
 command).
 
 We can assume the customer table does not exist, so you should get a SQL
 error back from the database server.  But there is some important information
 returned.
    a) First, notice we issued a "Select" statement, straight from the command
       line.  This is a nice easy mechanism for you to test arbitrary SQL
       statements.  The other supported commands are: >
       Select, Update, Insert, Delete, Call, Drop, Alter, Create
<   b) If the SQL statement resulted in an error (which ours should have) then
       the Result buffer contains: >
         - Native error returned from your database
<        For an ASA database you would see:
             Could not execute statement.
               Table 'customer' not found
               SQLCODE=-141, ODBC 3 State="42S02"
               File: "VIU4E8.tmp" on line 2, column 1
               select * from customer >

         - Instructions on changing connection information
<              To change connection parameters:
               :DBPromptForBufferParameters
               Or
               :DBSetOption user|passwd|dsnname|srvname|dbname|...=<value>
               :DBSetOption user=tiger:passwd=scott  >

         - The "Last command:"
<        This is useful for debugging.  If you are having troubles
         connecting to the database, yank and paste this command into a
         shell window and try running it.  From there, it is often easy to
         determine if you supplied the wrong connection information, or you
         were missing some connection information. >

         - The "Last SQL"
<        If an error was returned, this displays the SQL just executed.
         In our case you would see: "select * from customer".  Again, very 
         useful for debugging, especially when using the
         prompt_for_parameters option (which is on by default).
         
 Let assume the command did successfully execute against your database.

 TIP
 ---
 While your cursor is in the result buffer, you can press 'R', and it will
 re-run the command that created the current results.


 17.3 Executing commands                         *dbext-tutorial-execute*
 -----------------------
 Now, go to the top of the buffer (gg).  Move your cursor to the first
 statement and the word "TABLE" >
    CREATE TABLE customer(
           ^
<We want to execute the CREATE TABLE command.  There are several ways to do
 this:
    a) Command:
        :DBExecSQLUnderCursor
    b) Mapping:
        \se  s (sql) e (execute)
    c) Menu (if available):
        Plugin->dbext->Exec SQL (Under cursor)

 DBExecSQLUnderCursor searches backwards for the following words: >
    select, insert, update, delete, create, grant, alter, 
    call, exec, merge, with
<
 And searches forward for the cmd_terminator for the type of database you are
 connected to.  If you have not specified the connection information, the
 default is the ";".

 Now that the table was successfully created, move your cursor to: >
    INSERT INTO customer(id, cust_name, phone_nbr)
    ^
<This time we will use visual mode to determine which statements to execute.
 From command mode hit capital V |linewise-visual|.  Use the j, or the cursor
 keys to move down to the COMMIT after the INSERTs of the customer table. >
    COMMIT;
    ^
<We want to execute the visually selected lines.  There are several ways to do
 this:
    a) Command:
        :DBExecVisualSQL
    b) Mapping:
        \se  s (sql) e (execute)  - same as non-visual mode
    c) Menu (if available):
        Plugin->dbext->Exec SQL (Visual selection)

 Now do the same for the contact table.  Visually (V) select the CREATE TABLE
 command for the contact table, plus the INSERT statements up to the COMMIT.
 Execute the visual block.



 17.4 Selecting from tables                      *dbext-tutorial-select*
 --------------------------
 There are some very common actions when developing SQL.  For example, when
 coding a SELECT statement, we would like to see what data is currently in the
 table so we can determine what to add to the WHERE clause.

 Place your cursor anywhere on the contact word: >
    INSERT INTO contact(id, cont_name, phone_nbr)
                   ^
<We want to display the contents of the table:
    a) Command:
        :DBSelectFromTable
    b) Mapping:
        \st  s (sql) t (table)
    c) Menu (if available):
        Plugin->dbext->Select Table
        
 This executes "select * from contact", and displays the contents in the
 Result buffer.


 There are a few variants on this, leaving the cursor on the contact word:
    a) Command:
        :DBSelectFromTableTopX
    b) Mapping:
        \sT  s (sql) T (table) - Capital
    c) Menu (if available):
        Plugin->dbext->Select Table TopX

 This will prompt you for the number of rows to return from the query.

 Leaving the cursor on the contact word:
    a) Command:
        :DBSelectFromTableWithWhere
    b) Mapping:
        \stw  s (sql) t (table) w (where clause)
    c) Menu (if available):
        Plugin->dbext->Select Table Where

 This will prompt you to add a WHERE clause.  When you are prompted with: >
    Please enter where clause:
<
 You can type (notice you did NOT type the WHERE word): >
    id = 10 AND phone_nbr LIKE '555%'
<
 Which executes: >
    select * from contact where id = 10 AND phone_nbr LIKE '555%'
<    

 To save typing, you can also execute:
    a) Command:
        :DBSelectFromTableAskName
    b) Mapping:
        \sta  s (sql) t (table) a (ask name)
    c) Menu (if available):
        Plugin->dbext->Select Table Ask

 This will prompt you for the table name: >
    Please enter the name of the table to select from:
<    

 Lastly, you can also use visual mode.  This is useful if the tables are owned
 by a different user than your login.  Move your cursor to: >
    SELECT id FROM different_owner.customer;
                   ^
<Using v |characterwise-visual| select just this part of the line: >
    different_owner.customer
<
 Execute:
    a) Command:
        :'<,'>DBSelectFromTable
    b) Mapping:
        \st  s (sql) t (table)  - same as command mode
    c) Menu (if available):
        Plugin->dbext->Select Table

 This executes: >
    SELECT * FROM different_owner.customer;
<
    
 
 17.5 Describing objects                         *dbext-tutorial-describe*
 -----------------------
 When you need to write SQL statements, or stored procedures, many times you
 need more than just the column names.  You also need the datatypes of the
 columns.

 Many of the commands we just covered are also available, but for describing
 tables.

 Place your cursor anywhere on the contact word: >
    INSERT INTO contact(id, cont_name, phone_nbr)
                   ^
<We want to describe the table:
    a) Command:
        :DBDescribeTable
    b) Mapping:
        \sdt  s(sql) d (describe) t (table)
    c) Menu (if available):
        Plugin->dbext->Describe Table
        
 The output depends on the features of the database you are connected to.  
 For an ASA database, the Result buffer has the following: >
    ... Some columns removed for brevity ...

    TABLE_CAT TABLE_SCHEM TABLE_NAME COLUMN_NAME TYPE_NAME COLUMN_SIZE 
    ------------------------------------------------------------------
    cons      DBA         contact    id          int       10
    cons      DBA         contact    cont_name   varchar   30
    cons      DBA         contact    phone_nbr   varchar   30
<
 You can also describe stored procedures: 
    a) Command:
        :DBDescribeProcedure
    b) Mapping:
        \dp  d (describe) p (procedure)
    c) Menu (if available):
        Plugin->dbext->Describe Procedure



 17.6 Connection Profiles                        *dbext-tutorial-profile*
 ------------------------
 The most efficient way to setup connection information is to create
 connection profiles in your |.vimrc|.  If you work with multiple databases,
 or a different database per project then you can add the following: >
     let g:dbext_default_profile_usual       = 'type=ASA:user=DBA:passwd=SQL'
     let g:dbext_default_profile_ORA         = 'type=ORA:user=scott:passwd=tiger'
     let g:dbext_default_profile_mySQLServer = 'type=SQLSRV:integratedlogin=1:dbname=myDB'
<
 Then in your SQL files, you can add the following line where "//" is simply 
 a comment line marker for SQL files.  Comment indicators change by 
 filetype. >
     // dbext:profile=usual:host=my_desktop
<
 This has the same effect as issuing the following commands: >
     DBSetOption type=ASA
     DBSetOption user=DBA
     DBSetOption passwd=SQL
     DBSetOption host=my_desktop
<
 When you run :DBPromptForBufferParameters and you have profiles defined in
 your |.vimrc|, you are presented with a numbered list of all the profiles.
 You can simply choose the number from the list to setup the buffer.
 
 If you always want dbext to use a specific profile for every new buffer
 (unless overriden in your modelines) you can add the following to your 
 vimrc (using the profile created above): >
     let g:dbext_default_profile = 'usual'
< 
 More examples of connection profiles can be found here: 
 |dbext-connect-profiles-examples|.


 17.7 Login Script                            	 *dbext-tutorial-login*
 -----------------
 For each profile, you can also specify a file of SQL commands to be 
 executed each time a connection is made to the database.  This can be
 useful if you want to set connection level properties within
 the database.  By default dbext will look for these files in the
 $VIM or $HOME directory, but it can also be overridden via your 
 .vimrc, see g:dbext_default_login_script_dir.

 In a SQL Anywhere database I can create a file with the following: >
    SET TEMPORARY OPTION debug_messages = 'On'; 
    SET TEMPORARY OPTION date_order = 'YMD'; 
<
 Then create my connection profile as: >
     let g:dbext_default_profile_usual = 'type=ASA:user=DBA:passwd=SQL:login_script=ASA_defaults.sql'
<
 Each time I connect to this datasource the above 2 options will 
 be set.  The syntax of this file (including command terminators is 
 expected to be syntactically correct for you database.



 17.8 Listing object                            *dbext-tutorial-objects*
 -------------------
 Often, you do not know the name of your table, but just need to browse
 through the database.  dbext can be used to display listings of objects, and
 you can optionally specify a prefix.

 To see a list of all tables:
    a) Command:
        :DBListTable
    b) Mapping:
        \slt  s (sql) l (list) t (table)
    c) Menu (if available):
        Plugin->dbext->Table List
 
 This will prompt you for a prefix value: >
    Enter table prefix:
<
 Do not enter anything, and you will see all tables in the database, including
 system tables.

 Try this now, and ensure the customer and contact table are listed.

 The same functionality existing for listing procedures (\slp) and views
 (\slv).

 When building an INSERT statement, or a SELECT statement, you often need
 to supply a column list for the table (instead of using *).

 Place your cursor anywhere on the contact word: >
    INSERT INTO contact(id, cont_name, phone_nbr)
                   ^
<To generate the column list for that table: 
    a) Command:
        :DBListColumn
    b) Mapping:
        \slc  s (sql) l (list) c (column)
    c) Menu (if available):
        Plugin->dbext->Column List
        
 The column list for the "contact" table is placed in the Vim paste buffer.
 Move to the location in the file where you want the column list placed
 and hit p (paste).

 Running \slc above places the following in the unnamed register: >
    id, cont_name, phone_nbr
< 


 17.9 Object Completion                         *dbext-tutorial-completion*
 ----------------------
 You can usually remember the letter the object (table, procedure, view)
 begins with, but you cannot remember how to quite spell the name (either that
 or you are too lazy).

 dbext uses Vim's |'dictionary'| feature so that as you type, and are in
 insert mode, you can hit CTRL-X CTRL-K |i_CTRL-X_CTRL-K|, and using the
 dictionary, by repeatedly hitting CTRL-K, Vim will scroll through the various
 tables that begin with the string you have typed so far.

 To enable (for a buffer):
    a) Command:
        :DBCompleteTable
    b) Mapping:
        - no mapping, usually a one time command
    c) Menu (if available):
        Plugin->dbext->Complete Tables
        
 Create a new line, and type: >
    SELECT * FROM c

<Now, while still in insert mode, hit: >
    CTRL-X CTRL-K
<
 You will see the "c", is replaced with "contact", hit CTRL-K again, and
 "contact" is replaced with "customer", one more time, and we have looped
 through all the tables beginning with "c", and the string is returned back to
 our original "c".

 The object list also includes system tables, which can be very convenient
 when you need to use those to look up meta data in the database catalogue.

 DBCompleteProcedures and DBCompleteViews perform the same function.  If you
 run each of these, then |i_CTRL-X_CTRL-K| will complete from all the
 dictionaries, so your options will include tables, procedures and views.
 


 17.10 Host variable replacement                *dbext-tutorial-variables*
 -------------------------------
 When writing SQL statements, you can often pass in parameters or host
 variables to be replaced at execution time.  When executing these SQL 
 statements, dbext will prompt you for a substitute value for the variable
 and execute the SQL.  This feature is enabled by default.

 Place your cursor at the ^ in this statement: >
    SELECT id
      INTO @cust_variable_id
      FROM customer
     WHERE cust_name LIKE :host_var_name
       AND cust_name LIKE ?
       AND id        =    @var_name;
           ^
<The above statement includes 3 types of default host variables that get
 prompted for by dbext.  The regular expression used to find these variables
 can easily be extended to support additional formats.  To extended it further
 keep reading through to the end of |dbext-tutorial-variables|.  With your
 cursor where the ^ indicates, you can either hit \se, or you can visually
 select the entire SELECT statement and hit \se.

 Several things happen:
    a) Since you are running a SELECT statement *AND* you provided an INTO
       clause, dbext automatically strips this part of the statement: >
          INTO @cust_variable_id
<      out of the SQL it sends to the database.  Generally, you would get an
       error indicating "@cust_variable_id" does not exist.  But since we are
       trying to test the validity of the SELECT statement, dbext strips the
       INTO clause so we can see what that SELECT statement will return.

    b) Next, we look for host variables, when one is found, you are prompted 
       for a replacement value.  There are very strict rules which dictate how
       dbext determines a string is a host variable (see |dbext-prompting|).
       In the above SELECT statement you are prompted for: >
          Enter the value of ? number 1:
          Enter value for @var_name:
          Enter value for :host_var_name:
<      Enter the following values when prompted (including quotes): >
          'B%'
          1
          '%b'
<      dbext sends the following query to the database: >
          SELECT id
            FROM customer
           WHERE cust_name LIKE '%b'
             AND cust_name LIKE 'B%'
             AND id        =    1;
<      This allows you to test your statements without copying the statement
       into a scratch buffer, and replacing the host variables with values.

    c) For variables which are not question marks, dbext will also 
       temporarily store the value you entered (when prompted) and if you
       were to re-run this statement or run another statement with the 
       same host/variable names, dbext will automatically replace the 
       variables with values used previously.  These values are stored 
       on a per buffer basis.  You can view a list of previously saved 
       values by running :DBListVar (or <Leader>slr (slv was already taken)). >
            Connection: T(ASA)  U(dba)   at 22:43
            ------------------------
            ** Variable List **
            ------------------------
            set :host_var_name = '%b'
            set @var_name = 1
<       Previously stored variables can be removed by placing your 
        cursor on the line above and hitting 'dd' to remove the variable.
        If remembering variables is not desired you can set the 
        g:dbext_default_variable_remember = 0 in your .vimrc.

    d) Variables can also be defined two different ways.  

       Method 1:
       You can used the DBSetVar command to both define and remove 
       variables: >
            :DBSetVar :myvar1='myvar1'
            :DBSetVar @myvar2='myvar2'
            :DBSetVar @myint3=3
<      To remove the variable, use DBSetVar with nothing after the = sign. >
            :DBSetVar @myint3=  
<      DBSetVar supports TAB completion.  
            :DBSetVar <Tab>
            :DBSetVar @m<Tab>
       Will allow you to move through all currently defined variables and 
       their values allowing you to easily change the value (while saving
       some typing!).

       Method 2:
       In a buffer you can have multiple set statements and use mappings
       to define (or execute) the variables: >
            set :myvar4 = 'myvar4';
            set @myvar5 = 'myvar5';
            set @myint6 = 6;
<      If your cursor is on one of these lines you can use <Leader>sal
       (sql - assign - line), or you can visually select all 3 lines 
       and use <Leader>sa or :'<,'>DBVarRangeAssign.

 dbext can be extended via the |.vimrc| to search for additional formats
 of variables.  By default it searches for variables of these formats: >
        column_name = ?
        column_name like :var_name
        column_name > @var_name
<
 Assume you wrote this stored procedure: >
        CREATE PROCEDURE sp_test_var_prompting(
            IN p_input_parm INTEGER
        )
        RESULT (ID INTEGER)
        BEGIN
            DECLARE lv_local_var INTEGER;

            SET lv_local_var = 6;

            SELECT ID
              FROM myTable
             WHERE c1 = p_input_parm
               AND c2 = lv_local_var;
        END;
<
 Visually selecting (using capital V |linewise-visual|) the SELECT
 statement and executing it (\se) you will not be prompted for any
 input parameters since p_input_parm and lv_local_var do not match
 the default variable formats.

 You can view the current option parameters using: >
        :DBGetOption variable_def_regex
            \(\w\|'\)\@<!?\(\w\|'\)\@<!,\zs\(@\|:\|$\)\w\+\>
<
 This is actually 2 different regex expressions.  The first one 
 finds the question marks and the second one finds any variables
 beginning with "@,:,$". >
        \(\w\|'\)\@<!?\(\w\|'\)\@<!
        \zs\(@\|:\|$\)\w\+\>
<
 These are just standard Vim regular expressions which you can
 test on your own by doing a find.  Once you have them correct you
 can add them to dbext via your .vimrc.

 In the case above, we want dbext to check for variables beginning
 with p_ or lv_.  If we want to _only_ look for those then we can 
 overwrite dbext defaults using DBSetOption: >
        :DBSetOption variable_def_regex=\<\zs\(p_\|lv_\)\w\+\>
            \<           - Beginning of a word (:h \< )
            \zs          - Start the match here (:h \zs )
            \(p_\|lv_\)  - Starts with a p_ or lv_
            \w\+         - Any word character(s)
            \>           - Ends on a word boundary
<
 All the search atoms used above are not necessarily required (i.e. \zs)
 but I have added it to introduce you to some of the handy atoms available.
 Now when you execute the SELECT statement in the stored procedure you
 will be correctly prompted for p_input_parm and lv_local_var.

 Each project you work on may have different standards and naming 
 conventions.  This autocmd works by checking if you are opening
 a file somewhere under a directory called MyProjectDir.  If so, it sets
 dbext's current variable_def_regex for this buffer.  This |autocmd| can be
 added to your |.vimrc|: >
        autocmd BufRead /MyProjectDir/ DBSetOption variable_def_regex=\<\(p_\|lv_\)\w\+\>
<
 Or if you simply wanted to extended the existing defaults, you can
 retrieve the existing setting using dbext's DB_listOption function and
 concatenate the new regex separated by a comma: >
        autocmd BufRead /MyProjectDir/ DBSetOption variable_def_regex=,\<\(p_\|lv_\)\w\+\>
<
        

 17.11 Filetype support                         *dbext-tutorial-filetype*
 ----------------------
 This is an extension of the above host variable replacement.  The following
 filetypes are currently supported:  >
     PHP, Java, JSP, JavaScript, jProperties, Perl, SQL, Visual Basic, Vim
<
 Edit a new buffer: >
    :e parse.java
<
 Paste the following into this file: >
    String mySQL = 
        "SELECT s.script, ts.event, t.name                  " +
        "     , s.script_language, sv.name                  " +
        "  FROM ml_script s, ml_table_script ts, ml_table t " +
        "     , ml_script_version sv                        " +
        " WHERE s.script_id   = " + script_version +
        "   AND ts.version    = "+obj.method() +
        "   AND ts.table_id   = t.table_id                  ";
<
 Now visually highlight the entire this portion of the code: >
        "SELECT s.script, ts.event, t.name                  " +
        "     , s.script_language, sv.name                  " +
        "  FROM ml_script s, ml_table_script ts, ml_table t " +
        "     , ml_script_version sv                        " +
        " WHERE s.script_id   = " + script_version +
        "   AND ts.version    = "+obj.method() +
        "   AND ts.table_id   = t.table_id                  ";
<
 Execute it (\se), dbext will join the strings into one statement.  It will
 then search the string for various types of "host variables", as dictated by
 Java.  It will prompt you replacements for the following: >
        Enter a value for " + script_version +   ":
        Enter a value for "+obj.method()+   ":
<
 Assuming you entered the following (including quotes): >
        100
        'Project_Yahoo'
<
 Then the resulting string sent to your database would be: >
        SELECT s.script, ts.event, t.name , s.script_language, sv.name
          FROM ml_script s, ml_table_script ts, ml_table t 
             , ml_script_version sv
         WHERE s.script_id   = 100
           AND ts.version    = 'Project_Yahoo'
           AND ts.table_id   = t.table_id 
<
 The time is saved since you do not need to copy the string to another scratch
 buffer, and manually join the strings, and replace the method() calls to a
 static value, just so you can test.



 17.12 History                            	*dbext-tutorial-history*
 -------------
 History is a new feature of dbext 3.0.  Previous statements are 
 automatically recorded into a history file.  To view these statements
 run :DBHistory or <Leader>sh.  Pressing <enter> or double clicking will
 re-run the statement.  See |dbext-history| for more details.
 To remove an item from the history you can use 'dd'.


 17.13 DBI Tutorial                            	*dbext-tutorial-dbi*
 ------------------

 Assuming you have already followed the main tutorial, the DBI interface
 adds some additional commands and features not available when using the
 native binary tools.

 Creating a profile is by the far the best approach if you are going to
 access a database more than once.  DBI profiles are nearly identical, but
 allow you to specify some additional parameters. >
     " Connect to the first SQL Anywhere engine running
     let g:dbext_default_profile_SA_db1  = 'type=DBI:user=DBA:passwd=SQL:driver=SQLAnywhere'
     " Specify usual SQL Anywhere connection strings
     let g:dbext_default_profile_SA_db2  = 'type=DBI:user=DBA:passwd=SQL:driver=SQLAnywhere:conn_parms=ENG=my_engine;DBN=my_db'

     " Use ODBC (via DBI) with a SQL Anywhere DSN called:my_dsn 
     let g:dbext_default_profile_SA_db3  = 'type=ODBC:user=DBA:passwd=SQL:dsnname=my_dsn'

     " Specify an Oracle Service Name or SID
     let g:dbext_default_profile_ORA_db2 = 'type=DBI:user=scott:passwd=tiger:driver=Oracle:conn_parms=SID_NAME'

     " Specify a MySQL database and the host name where it is running
     let g:dbext_default_profile_mysql_local_DBI = 'type=DBI:user=root:passwd=:driver=mysql:conn_parms=database=my_db;host=localhost'

     " Use ODBC (via DBI) with MySQL DSN called:my_dsn
     let g:dbext_default_profile_mysql_local_ODBC = 'type=ODBC:user=root:passwd=:dsnname=my_dsn'
<
 In some cases you will want to take advantage of the transactional
 capabilities of the DBI layer.  This can be enabled two different ways.
 Using the connection profile you can specify AutoCommit using the 
 driver parameters.  >
     " Connect to the first SQL Anywhere engine running
     let g:dbext_default_profile_SA_db4  = 'type=DBI:user=DBA:passwd=SQL:driver=SQLAnywhere:driver_parms=AutoCommit=1'
< 
 The second way allows you to change the transactional nature of the 
 connection at anytime.  This allows you to maintain the default 
 AutoCommit on behaviour until you may wish to perform actions
 that require transactions spanning multiple calls to the DBI layer. >
     DBSetOption AutoCommit=0
< 
 Each buffer maintains it's own connection to a database.  You can 
 view the DBI (and DBI ODBC) connections via the DBListConnections
 command. >
     DBListConnections
        Connection: T(DBI)  I(SQLAnywhere)  P(AutoCommit=1)  U(dba)  
        Buffers with active Perl DBI database connections:        
        Buffer  Driver       AutoCommit  Connection Parameters          
        ------  ------       ----------  ---------------------          
        1       mysql        1           database=mysql;host=localhost  
        3       SQLAnywhere  1                                          
        (2 rows)

     DBSetOption AutoCommit=0

     DBListConnections
        Connection: T(DBI)  I(Mysql)  C(database=mysql;host=localhost)  U(root)  
        Buffers with active Perl DBI database connections:        
        Buffer  Driver       AutoCommit  Connection Parameters          
        ------  ------       ----------  ---------------------          
        1       mysql        0           database=mysql;host=localhost  
        3       SQLAnywhere  1                                          
        (2 rows)
<
 After performing a transaction (which can be done using the :Update, 
 :Insert, ... commands) you can either commit or rollback the change using >
     DBCommit
     DBRollback
<
 When you delete the buffer or close Vim, an autocmd will fire which will
 disconnect from the database.  You can also manually disconnect from the
 database. >
     DBDisconnect

     DBListConnections
        Connection: T(DBI)  I(SQLAnywhere)  P(AutoCommit=1)  U(dba)  
        Buffers with active Perl DBI database connections:        
        Buffer  Driver  AutoCommit  Connection Parameters          
        ------  ------  ----------  ---------------------          
        1       mysql   0           database=mysql;host=localhost  
        (1 rows)
<
 By default only 300 rows will be retrieved from the database and displayed
 at any one time.  See the dbext_default_DBI_max_rows setting to change 
 this permanently via your vimrc.  You can override this setting for the
 current buffer at anytime by using DBSetOption.  Run a Select statement
 which returns many rows.  Then try setting the max row count to 5, rerun
 the same query.  Setting this option to blank will reset to the default.  >
        DBSetOption DBI_max_rows=5
        DBSetOption DBI_max_rows=
<
 By default, result sets returned by the database are displayed in a tablular
 format: >
        ID   GivenName  Surname       
        ---  ---------  ------------  
        101  Michaels   Devlin        
        102  Beth       Reiser        
<There are times when a vertical (versus horizontal) view is more appropriate.
 The DBI layer also has this capability.  If the format is set to "horizontal"
 the standard output is used.  Setting the format to anything other than
 "horizontal" will result in a vertical output: >
    :DBSetOption DBI_orientation='v'
        ****** Row: 1 ******
               ID: 101
        GivenName: Michaels 
          Surname: Devlin      
        ****** Row: 2 ******
               ID: 102
        GivenName: Beth     
          Surname: Reiser      
        (2 rows)

    :DBSetOption DBI_orientation=     " Resets back to the default
        ID   GivenName  Surname       
        ---  ---------  ------------  
        101  Michaels   Devlin        
        102  Beth       Reiser        
<
 There are two ways to flip back an forth between orientations.
 While in the Result window, you can press "O" (for Orientation) to redisplay
 the current result and toggle the orientation.  If your cursor is in your
 buffer, you can use the <Leader>so (default \so) map to tell the Result
 window to redisplay toggling the orientation.  These maps only redisplay the
 results, they do not re-query the database.

 Often you need to place common SQL statements in a file and execute them with
 other statements.  You can consider this similar to an IMPORT or INCLUDE
 command in other languages.  The dbext plugin will look for the
 DBI_read_file_cmd (default "read ") and check if the following text is a
 filename.  If the filename exists, the contents of the file will replace the
 DBI_read_file_cmd and filename plus an optional DBI_cmd_terminator. By
 default the DBI_cmd_terminator is set to ";".   

 Create a file c:\temp\my.sql with the following content: >
        INSERT INTO my_table (c1, c2)
        VALUES(1,2);
        INSERT INTO my_table (c1, c2)
        VALUES(1,2);
<
 Create a new buffer run the DBSetOption option and add the following
 statements.  Notice, there is no space between between the '\.' and
 the filename.  If there is, you must set the read_file_cmd to '\. ': >
        :DBSetOption DBI_read_file_cmd='\.'
            \.c:\temp\my.sql;
            \./temp/my.sql;
<
 If you execute all statements in this file, the following SQL will be
 executed: >
        INSERT INTO my_table (c1, c2)
        VALUES(1,2);
        INSERT INTO my_table (c1, c2)
        VALUES(1,2);
        INSERT INTO my_table (c1, c2)
        VALUES(1,2);
        INSERT INTO my_table (c1, c2)
        VALUES(1,2);
<            
 The DBI_read_file_cmd, filename, command terminator are replaced with the
 contents of "my.sql".  Since we have 2 DBI_read_file_cmd's, the SQL
 is replaced twice.  If you had not issued the DBSetOption command the 
 default read_file_cmd is "read " and is used as: >
        read c:\temp\my.sql;
        read /temp/my.sql;
<

 Summary
 -------
 Please read through the documentation, the tutorial does a simple job
 explaining the basic concepts, but there are many features embedded within
 that can be customized for your project.

 Above all, enjoy the plugin.  Feedback is always appreciated, please send it
 to both David and Peter.


==============================================================================
  vim:tw=78:fo=tcq2:ts=8:ft=help:norl: