*dbext.txt*	For Vim version 7.0.  Last change: 2017 Nov 17


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

	  	Database extension plugin (dbext.vim) manual
	  	dbext.vim version 26.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* *ultralite* *hana* *firebird*
*CrateIO* *RDBMS*

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-maps-commands|
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. Job Support                               |dbext-job|
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*

The following different databases are supported by dbext:
    SAP Sybase SQL Anywhere (SA/ASA)
    SAP Sybase IQ
    SAP Sybase Adaptive Server Enterprise (ASE)
    SAP HANA
    SAP Sybase UltraLite (UL)
    Oracle
    Oracle RDB
    SQL Server
    MySQL
    PostgreSQL
    DB2
    Firebird
    Ingres
    Interbase
    SQLite

If you have a Perl enabled Vim and install the required packages then any of
the databases supported by DBI or ODBC are also included.

NOTE: Connecting through the Perl interface is much faster than they other
database types.  SQL Anywhere is supported either way, I always connect to it
via DBI as once the shared library is loaded the access is nearly instant and
a new database connect need not be made on each request.

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 occasionally 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 26.00 (Nov 17, 2017)

 New Features
 ------------
 - New option g:dbext_default_job_show_msgs to control whether information
   messages are displayed when starting and stop jobs.  Regular status
   messages continue to display.
 - New option g:dbext_default_job_pipe_regex to control how to identify
   and strip piped in files and specify it separately via job options.
 - Renamed option g:dbext_default_use_jobs to g:dbext_default_job_enable
   to better support tab completion for the DBSetOption command.

 Bug Fixes
 ---------
 - Also check for 'timers' when checking for job support.
 - Revamped job support.  Tested on Windows, Linux and OSX.  Works on
   long running and very short jobs where it was erratic on first release.

Version 25.00 (Jan 30, 2017)

 New Features
 ------------
 - Added support for using Vim's Job / Channel feature for asynchronous
   execution.  If the job fails to start, the usual synchronous way
   of launching the process happens (after displaying a message).
   The main purpose for this feature is to allow you to continue
   editing your files while waiting for the results from SQL 
   statements to complete.  Prior to Vim's Job feature, this 
   was a synchronous process which could interrupt your development
   needlessly.
 - New commands DBJobStatus, DBJobStop, DBJobTimerStart, DBJobTimerStop.
 - New options g:dbext_default_use_jobs defaults to 1 (enabled),
   g:dbext_default_job_status_update_ms defaults to 2000.

 Bug Fixes
 ---------
 - None

Version 24.00 (Sept 30, 2016)

 New Features
 ------------
 - Added missing menu items for Execute All (sea), Execute Line (sel),
   Execute Previous Visual Selection (sep) (pull #18) (Raphaël Bade)
 - When using ?s as input parameters, these can now be remembered
   and used when saving previous values when executing the query.
 - Additional examples of connecting to Oracle using DBI/ODBC
   without a TNSNAMES entry.
 - Strip off ending cmd terminators for the DBI database types
   as some databases (Oracle) complain about them (Bruce Hunsaker).
 - For native Oracle connections, when retrieving database objects
   (tables, procedures, columns, ...) ignore case (Dimitri Belov).

 Bug Fixes
 ---------
 - For Java, CSharp, JSP, HTML and JavaScript files, remove line
   continuation (backslash) characters before sending request to database.
 - Better error handling for the DBI / ODBC databases (Michael Graham, 
   Bruce Hunsaker, Dimitri Belov, Will Wyatt).
 - The @ask[bg] parameter was not supported properly in later 
   releases (Richard Tsai, Nan Jia).
 - Vim error - Invalid range reported for the SQL history (Bruce Hunsaker).
 - DBI / ODBC CommitOnDisconnect driver parameter is not supported by all
   drivers, handle cleanly (Dimitri Belov).
 - DBI / ODBC Disconnect reported a Vim error (Dimitri Belov).

Version 23.00 (Dec 30, 2015)

 New Features
 ------------
 - Added a new database, CrateIO (Mathias Fussenegger)
 - CRATE native database type and Crate via DBI are supported
 - Updated the DBI SQLAnywhere procedure list to respect the option of whether
   to include the object owner names
 - Added a new public function, DB_DictionaryDelete, to be used by the 
   OMNI SQL Completion plugin (autoload/sqlcomplete.vim, which is part of Vim)

 Bug Fixes
 ---------
 - helptags reported duplicate tag MyProjectDir, updated documentation as a 
   work around as there is no way to escape the real syntax (pull #3) (mexpolk)
 - For PGSQL, use the "schemaname" column rather than "tableowner" (pull #15) 
   (Stefan Litsche)


Version 22.00 (August 2, 2015)

 New Features
 ------------
 - Overhauled the prompting for SQL statement variable substitution (i.e. host
   variables, named parameters, question marks, ...).  The actions and user
   interface are hopefully more clear, useful and efficient.  For a full
   updated tutorial on how it works see :h dbext-tutorial-variables
 - Saved variables can now hold multiple values for the same parameter,
   see :h dbext-tutorial-variables for how it works.
 - Added C++ language support for variables (pull #12) (Anatolii Sakhnik).
 - Added the ability to specify special characters (i.e. "\t") for column
   delimiters when using ODBC or DBI database types (Michael Krnac).
 - Added new option, "passwd_use_secret", which is used when entering a
   password, if the value should be masked.  When using a GUI version of Vim,
   the prompt is not displayed in a dialog unlike the other parameters.  This
   option is OFF (0) by default. (pull #13) (petteja)
 - Added new option, "strip_into", which is used when executing statements
   which have variable assignments using the INTO clause.  To test these
   queries, you need to remove the INTO clause so that when they execute the
   query you can see the result set returned.  This was on for all databases,
   but for TransactSQL or TSQL databases like SQLSRV and ASE, stripping the
   INTO clause may be the wrong action.  Now it can be controlled using this
   setting.  This can also be set / overridden using DBSetOption strip_into=1
   or as part of a dbext profile.
 - Added new option, "strip_at_variables", which is executing statements which
   have variable assignments in the SELECT list instead of the INTO clause.  
   To test these queries, you need to remove the assignments when they execute
   to see the result set returned.  This was on for all databases, but for
   TransactSQL or TSQL databases like SQLSRV and ASE, stripping the variable
   assignments in the SELECT list is required. This can be controlled via this 
   setting.  This can also be set / overridden using 
   DBSetOption strip_at_variables=1 or as part of a dbext profile.

 Bug Fixes
 ---------
 - Minor correction to DBSetVar example (Cedric Simon).
 - When deleting a buffer, all syntax highlighting of your existing
   buffer is sometimes lost, which was a problem with one of the
   dbext autocmds (Anatolii Sakhnik).
 - Update Postgres get column list join conditions (pull #9) (Dickson S. Guedes).
 - dbext autocmd for checking for modelines messed up the jumplist (Justin M.
   Keyes)



Version 21.00 (February 1, 2015)

 New Features
 ------------
 - Added new database, SAP Sybase IQ.
 - Added ability to describe SAP HANA stored procedures using DBI/ODBC.
 - Added new command, DBProfilesRefresh, which will repopulate the profile
   list from your global variables without having to restart Vim.
 - Updated dbext profiles and modelines to accept special characters (\t) as
   the column delimiter for DBI connections (Josef Fortier).

 Bug Fixes
 ---------
 - Sometimes after setting a connection profile would still prompt you the
   first time you attempted to use the connection.
 - For PostgreSQL, check for .pgpass on *nix variants and pgpass.conf on
   windows (Collin Peters).
 - Some connection parameters were overridden incorrectly when first applying
   the dbext_default_profile (Lyude, Martin Chabot, Will Wyatt, Bruno Sutic).
 - Worked around an issue with the vim-gitgutter dbext plugin (airblade).
 - There were 3 places where we fetch Vim's variables to check for dbext
   profiles and other dbext settings.  These have changed these to fetch only
   Vim's global variables to reduce the amount returned and hopefully increase
   the response time (Michael Jansen).


Version 20.00 (September 24, 2013)

 New Features
 ------------
 - Added new DBI/ODBC option DBI_max_column_width to restrict the width
   displayed in the DBI result window (Luke Mauldin).
 - Improved the pattern used to find the query under the cursor.  Besides
   finding the command terminator, it will also look for the first blank
   line or the end of the file (Jason Quirk).
 - The dbext menu now uses the maps rather than calls to the commands.
   A new option will control this behaviour, g:dbext_map_or_cmd.
 - Changed the default SQLite binary to be sqlite3 instead of sqlite
   (Greg Kapfhammer).
 - Added a profile example for using the "sqsh" binary to connect to
   SQL Server instead of "osql" (Brian Iván Martínez).
 - The cmd_terminator displayed under Connection Options in the DBGetOption
   output was always blank.
 - Improved support for SAP HANA database, pulling objects from the system
   catalogue.

 Bug Fixes
 ---------
 - Controlling the DBI max rows (:DBSetOption DBI_max_rows=100) and DBI
   column separator did not work on a per buffer basis.
 - Undefined variable, s:dbext_prev_winnr, was reported when using DBI/ODBC
   connections through the sqlcomplete plugin and completing objects
   which require an active database connection (i.e. Tables,
   Procedures, ...) which had failed to connect to the database.
 - dbext was not prompting for ? parameters in PHP files.  This also
   affected all languages (Jérémie).
 - Changing a database's global cmd terminator was not necessarily
   picked up when using that database type (Jason Quirk).
 - ODBC or DBI could report an error about using length() instead
   of scalar() (Micah Duke).
 - Various errors on Linux with DBI (Micah Duke).
 - Using the console version of Vim displayed a number of "debug" messages
   during initialization.


Version 19.00 (April 29, 2013)

 New Features
 ------------
 - Added support for parsing C# files (Raul Segura Acevedo).
 - Updated the PostgreSQL message when the .pgpass file is
   missing (Dav Clark).

 Bug Fixes
 ---------
 - When prompting for connection parameters a second time, the previously
   chosen profile number was not defaulted.
 - If a dbext login script was stored in the $HOME directory it would
   never be found (Tim Teufel).
 - The first host variable was prompted for replacement, but the
   second one was not (Stanimir Mladenov).
 - Selecting a visual region with leading and ending double quotes (like
   a table name) could report invalid arguments for the following
   commands: DBSelectFromTable, DBSelectFromTableTopX, DBDescribeTable,
             DBDescribeProcedure, DBListColumn
 - For DB2 on the mainframe the command line utilities do not support the
   -t switch.  If you override the buffer specific cmd_terminator setting and
   set this value to an empty string the -t will be left off.  This can be
   most easily specified in a dbext connection profile (Michael McDermott):
      let g:dbext_default_profile_MyDB2 = 'type=DB2:user=me:passwd=mypass:dbname=SSD:cmd_terminator='
   Or while within a buffer:
      DBSetOption cmd_terminator=
      DBSetOption cmd_terminator=;


Version 18.00 (Nov 28, 2012)

 New Features
 ------------
 - Added support for parsing C# files (Raul Segura Acevedo).

 Bug Fixes
 ---------
 - Changed the Oracle calls to SQLPlus from using single quotes to using
   double quotes (David Sweeney).
 - The <Leader>sbp and <Leader>tcl mapping were missing with version 17.00.
 - The DBI interface could report: "E15: Invalid expression" when retrieving
   table lists from DB2, but this could also affect other SQL commands
   that returned strings surrounded in double quotes (Charles McGarvey).


Version 17.00 (Oct 10, 2012)

 New Features
 ------------
 - Added new database type, the SAP HANA in memory database.
 - Added new option, ignore_variable_regex, which is used when parsing your
   statement for replaceable input parameters (i.e. placeholders for prepared
   statements).  Certain variables need to be skipped (for example when
   running a CREATE PROCEDURE statement) to leave the logic inside the stored
   procedure intact.  This option allows the user finer control over the regex
   used to decide which SQL syntax should be skipped.
 - Added new option, statement_starts_line, which is used when deciding if
   the query should be parsed for input parameters.  Certain filetypes assume
   the statements can be embedded within strings (like in Java, PHP, Perl and
   so on).
 - When parsing PHP and Java files, leading and trailing quotes are stripped
   automatically when executing the query, which could lead to incorrect
   results.  First check if there is a leading quote.  If so, then only strip
   the corresponding closing quote.
 - Updated documentation describing the default regex for variable_def_regex.
 - Added new option g:dbext_map_prefix which defaults to <Leader>s, this allows
   you to customize the start of all the default maps (Daniel Hahler).

 Bug Fixes
 ---------
 - The default value for variable_def_regex, did not properly escape
   the $, which lead to some query parameters being skipped when
   executing SQL.
 - It was impossible to search and replace input parameters within
   a query if the parameter was enclosed in single quotes.  The above
   new features were required to make this possible (Joshua Dennis).
 - DBCompleteTable, DBCompleteProcedure, DBCompleteView would always
   recreate the object list.  If it has already been created, it should
   simply reuse what was available.  To force the recreation you add
   the bang to the command: DBCompleteTable!, DBCompleteProcedure!,
   DBCompleteView!.
 - Even with the checks it was possible for dbext to report:
   E227: mapping already exists for ... when creating maps where the
   mapping already exists (Daniel Hahler).


Version 16.00 (Jun 12, 2012)

 Bug Fixes
 ---------
 - For Oracle databases, the SQLPlus command had unmatched quotation marks
   which could lead to errors displayed by dbext indicating it could not
   open the file to execute the SQL (JustinF Zhang).


Version 15.00 (May 2, 2012)

 New Features
 ------------
 - A new database configuration parameter, g:dbext_default_DBTYPE_extra, is
   available to allow the user to customize command line parameters passed to
   the database binary used to execute the statement.  This can be overridden
   affecting all new connections via your .vimrc.  Or for a specific buffer
   via connection profile or :DBPromptForBufferParameters (Ken Inglis,
   Michael Berkowski).

 Bug Fixes
 ---------
 - The dbext menu for List Variables displayed the wrong mapping.
 - For SQLite databases, if no database is specified now a warning message
   is displayed instead of an error message.


Version 14.00 (Apr 5, 2012)

 New Features
 ------------
 - For Oracle connection profiles, support this form of server name,
   srvname=(description=(address=(protocol=TCP)(host=dbhost.our.domain.com)(port=1521))(connect_data=(server=dedicated)(service_name=gps03tst.our.domain.com)))
   (Fredrik Acosta).
 - Added a new buffer option to specify which filetype dbext should use when
   parsing the query.  If an existing language already works as you need
   you can tell dbext to use it via the modeline or DBSetOption
   (Albie Janse van Rensburg).
 - Added an example of a function I use to execute blocks of stored procedures
   using dbext's commands.
 - For PostgreSQL, dbext will check for the existence of a .pgpass file.  If
   not found, execution will abort and a warning message will be displayed.
   By default $HOME/.pgpass will be validated (Frank Schwach).

 Bug Fixes
 ---------
 - When closing or deleting buffers it was possible to loose syntax, filetype
   and hidden settings (Alexey Radkov).
 - Parsing VisualBasic and Basic variables let to errors in DB_parseVB
   (Albie Janse van Rensburg).
 - Generating a column list for an ASA database left an extra , at the end
   of the list.  This also affected the SQLComplete plugin.


Version 13.00 (Jun 13, 2011)

 New Features
 ------------
 - Added new command, DBDisconnectAll, for DBI/ODBC.
 - DBDisconnect for DBI/ODBC now can accept an optional parameter
   for the buffer you wish disconnected.
 - DBListConnections also includes the buffer filename in it's output
   to help associate the two more easily.
 - Updated the default variable_def_regex to include an alphabetic
   character after a ":" for host variables to avoid false matches
   with time formats "10:20".
 - Improved the variable substitution to also check if a variable is
   preceded by a single line comment character.  If so, ignore the match.
         CALL myProc( sl_var1  -- p_var1
                    , sl_var2  -- p_var2
                    );

 Bug Fixes
 ---------
 - When clearing the results buffer the default register was updated.
 - Duplicate tag on MyProjectDir when running helptags (Simon Dambe).
 - Some of the variable substitution options Skip, Use Blank had off
   by one errors.


Version 12.00 (Jul 15, 2010)


 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 (Sep 8, 2009)

 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 (Aug 23, 2009)

 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 (Mar 14, 2009)

 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 (Jan 10, 2009)

 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 built-in 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 (Oct 30, 2008)

 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 built-in 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 (Sep 21, 2008)

 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 (Aug 9, 2008)

 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 (Jun 10, 2008)

 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 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 (Apr 29, 2008)

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


Version 6.00 (Apr 28, 2008)

 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 embedded 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 (Sep 15, 2007)

 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 (Sep 10, 2007)

 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 (Sep 3, 2007)

 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 (Dec 19, 2006)

 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 (Dec 5, 2006)

 New Features
 ------------
 - Updated DBGetOption to additionally display a list of all database profiles
   and their types.  All dbext options that have been overridden 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 (Sep 23, 2006)

 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 (Jun 20, 2006)

 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
   concatenation.  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 (May 15, 2006)

 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 (Sep 13, 2005)

 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 PostgreSQL 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 (Mar 10, 2005)

 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 interfere with an
   INSERT or MERGE statement.


Version 2.11 (Sep 24, 2004)

 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 (Sep 15, 2004)

 New Features
 ------------
 - Support for the SQLite database has been added (thanks to Ron Aaron).


Version 2.01 (Jul 22, 2004)

 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:
     DBGetOption
     DBSetOption
     DBExecRangeSQL
 - Added 4 new options:
     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 (Jul 11, 2004)

 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 (SA / ASA)
        Sybase UltraLite
        Sybase Adaptive Server Enterprise (ASE)
        SAP HANA
        CrateIO
 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 which closes the window
              if there is not enough output.

    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,
          RDB,ULTRALITE,FIREBIRD,HANA,CRATE >
    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_query_statements
<       - Which statements are used to determine what query is under the
          cursor.  The default value for this option is:a >
              select,update,delete,insert,create,grant,alter,call,exec,merge,with
<         This can be updated via your vimrc using: >
              let dbext_default_query_statements = 'select,update';
    dbext_default_passwd_use_secret
<       - When entering a password, if the value should be masked.  When using
          a GUI version of Vim, the prompt is not displayed in a dialog unlike 
          the other parameters.  This option is OFF (0) by default. >
    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.  Stop prompting for this variable
                2.  Replace it with a blank or supplied value
                3.  Ignore this match (leave as is)
                4.  Never ask for variables (including subsequent queries)
                5.  Abort the query and do NOT execute it
         The next time a query is executed, and you have saved values
         you will be asked if you want to use the saved values.
         If you say "No", you will be asked for each one as usual,
         but the default value will be the previously used value.
         If you say "Yes", you will not be prompted and the query will be
         exeucted with the previously saved values (unless there are
         additional new variables). >
    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_variable_def_regex
<       - List of regexes (comma separated) used to find input parameters to
          prompt the user for possible replacement when executing the query
          against the database.  Default value is: >
          '\(\w\|'."'".'\)\@<!?\(\w\|'."'".'\)\@<!,\zs\(@\|:\a\|\$\)\w\+\>'
<
        - This is two different regex expressions.  The first one finds the
          question marks and the second one finds any variables
          beginning with "@,:,$". >
                \(\w\|'\)\@<!?\(\w\|'\)\@<!
                    \(\w\|'\)    - Beginning of a word character or a single quote
                    \@<!         - If the above is true do NOT match
                    ?            - Match a question mark
                    \(\w\|'\)    - Beginning of a word character or a single quote
                    \@<!         - If the above is true do NOT match
                    - In otherwords, find a question mark on its own which
                      is not surround in quotes and not embedded in a word
                      SELECT c1 FROM t1 WHERE c2 = ?    -- match this
                      SELECT c1 FROM t1 WHERE c2 = '?'  -- do not match this
                      SELECT c1 FROM t1 WHERE c2 = da?  -- do not match this

                \zs\(@\|:\|$\)\w\+\>
                    \zs          - Start matching now
                    \(@\|:\|$\)  - Match a @ or : or $ character
                    \w\+         - Match at least one or as many word characters as possible
                    \>           - and end on a word boundary
                    - In otherwords, find these types
                      SELECT c1 FROM t1 WHERE c2 = @myVar
                      SELECT c1 FROM t1 WHERE c2 = :hostVar
                      SELECT c1 FROM t1 WHERE c2 = $placeHolder
<
        - These values can be updated via your .vimrc or using DBSetOption.
          When using DBSetOption, if the value begins with "," it will append
          to the existing setting.  Without a leading comma, the value will
          be replaced (for the current buffer).   This example will add
          to the default values and also look for variables that begin
          with p_ or lv_.  >
            autocmd BufRead *.sql DBSetOption variable_def_regex=,\<\(p_\|lv_\)\w\+\>
>
    dbext_default_ignore_variable_regex
<       - List of regexes (comma separated) used to find input parameters to
          prompt the user for possible replacement when executing the query
          against the database.  Default value is: >
          '\(in\|out\|inout\|declare\|set\|variable\|''\|/\|@\)'
<
        - The regex checks the strings before the variable found by variable_def_regex.
          If this is part of a parameter definition:
            IN       @variable CHAR(1)
            OUT      @variable CHAR(1)
            INOUT    @variable CHAR(1)
            DECLARE  @variable CHAR(1)
            VARIABLE @variable CHAR(1)  -- CREATE VARIABLE @variable
          Or part of a string:
            '@variable'
          Or part of path:
            /@variable'
          Or a global variable:
            SET @@variable = ...
          Or the definition of a global variable:
            CREATE VARIABLE variable ...
          If so, ignore the match and do not prompt to replace the variable with
          an input parameter.

        - These values can be updated via your .vimrc or using DBSetOption.
          When using DBSetOption, if the value begins with "," it will append
          to the existing setting.  Without a leading comma, the value will
          be replaced (for the current buffer).   In this example we are
          removing the check to see the variable is enclosed in single quotes. >
            DBSetOption ignore_variable_regex = \(in\|out\|inout\|declare\|set\|variable\|/\|@\)
>
    dbext_default_statement_starts_line
<       - A buffer local variable which is used to check whether the query
          must start at the beginning of the line.  This is useful for SQL
          files, which can have for example CREATE PROCEDURE statements that
          you will execute.  These procedures can have embedded SELECT
          statements.  These statements we do not want to check for input
          parameters, as changing them changes the meaning of the stored
          procedure.  For Java and PHP files, queries are often built up by
          concatenating strings together.  So, we still want to prompt for the
          variables in these cases, yet the SELECT may not start at the
          beginning of the line.  Consider the following examples: >
            CREATE PROECURE sp_test( @p1 INT )
            BEGIN
                DECLARE lv_id INT;
                SET lv_id = @p1;
            END;
<
        - Due to this being a CREATE PROCEDURE, we do not want to prompt
          for any any of the potential input parameters.  For SQL files
          the statement_starts_line is 1, since we will only prompt for
          input parameters if the statement begins with values listed
          in the query_statements option.  >

            String sql = "SELECT c1 FROM T1 "
                       + " WHERE c2 = @p2   ";
<
        - When visually selecting the two lines and executing, dbext
          finds the @p2 and prompts for a value before executing.
          In this case statement_starts_line is 0, since we are assigning
          the statement to a String.
>
    dbext_default_strip_at_variables
<       - A buffer local variable which is used when executing SELECT 
          statements.  This setting is OFF by default and ON for SQLSRV and
          ASE databases.  Most databases support the INTO clause which is used
          to store column values into locally declared
          variables.  TransactSQL does not use the INTO clause, you assign
          local variables values by using an assignment (=) statement in the
          SELECT list.
          Consider the following stored procedures which demonstrates
          TransactSQL syntax for assigning the variables: >
            CREATE PROECURE sp_test( @p1 INT )
            BEGIN
                DECLARE @fname VARCHAR(30);
                DECLARE @lname VARCHAR(30);
                
                -- TransactSQL syntax
                SELECT @fname = FirstName, @lname = Surname
                  FROM Customer
                 WHERE ID = @p1
            END;
<
        - If you visually selected the SELECT statement in this procedure
          to test it, you will get a syntax error indicating "@fname" is 
          not defined.  When the procedure executes, the variable is defined
          and will execute correctly.
        - The "strip_at_variables" is enabled for all SQLSRV and ASE databases
          which use TransactSQL syntax.  When strip_at_variables = 1, 
          and visually selecting the statement and executing, the variable
          assignments are stripped so that the developer can see the result set
          returned by the query (instead of a syntax error): >
                SELECT FirstName, Surname
                  FROM Customer
                 WHERE ID = @p1
<
        - It may be necessary to toggle this setting on and off based
          on the types of statements you are executing.  This can be
          done using the DBSetOption command: >
            :DBSetOption strip_at_variables=1
<
        - This setting can be controlled via a profile as well: >
            let g:dbext_default_profile_SQLSRV = 'type=SQLSRV:user=sa:passwd=Leader:strip_at_variables=0'
>
    dbext_default_strip_into
<       - A buffer local variable which is used when executing SELECT 
          statements.  This setting is ON by default and OFF for SQLSRV and
          ASE databases.  Most databases support the INTO
          clause which is used to store column values into locally declared
          variables.  Consider the following stored procedures: >
            CREATE PROECURE sp_test( @p1 INT )
            BEGIN
                DECLARE @fname VARCHAR(30);
                DECLARE @lname VARCHAR(30);
                
                SELECT FirstName, Surname
                  INTO @fname, @lname
                  FROM Customer
                 WHERE ID = @p1
            END;
<
        - If you visually selected the SELECT statement in this procedure
          to test it, you will get a syntax error indicating "@fname" is 
          not defined.  When the procedure executes, the variable is defined
          and will execute correctly.
        - The "strip_into" is enabled for all databases other than SQLSRV
          and ASE which use TransactSQL syntax.  When strip_into = 1, 
          and visually selecting the statement and executing, the INTO
          clause is stripped so that the developer can see the result set
          returned by the query (instead of a syntax error): >
                SELECT FirstName, Surname
                  FROM Customer
                 WHERE ID = @p1
<
        - For SQLSRV databases, the INTO clause is used to create a 
          temporary table and return the results from it.  So for this
          database, we do not want to strip the INTO clause.  Consider
          this SQL statement: >
            SELECT * 
              INTO dbo.Table_backup 
              FROM dbo.Table;
<
        - It may be necessary to toggle this setting on and off based
          on the types of statements you are executing.  This can be
          done using the DBSetOption command: >
            :DBSetOption strip_into=1
<
        - This setting can be controlled via a profile as well: >
            let g:dbext_default_profile_SQLSRV = 'type=SQLSRV:user=sa:passwd=Leader:strip_into=0'
>
    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 SQLComplete
          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 apparently 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 overridden 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 tabular 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'
    dbext_default_filetype
<       Default: &filetype
        New feature to version 14.0.  By default, dbext will use
        Vim's filetype when parsing queries.  But depending on your
        setup and your language, a different filetype might already
        prompt for variables they way you need.  This will allow
        you to override the dbext default and use the value you
        specify. >
            :DBSetOption filetype=sql
            let g:dbext_default_profile_test = 'type=ASA:user=DBA:passwd=SQL:filetype=sql'
    dbext_default_job_enable
<       Default: 1
        New feature to version 26.0.  Useful when using any of the database
        types that must spawn an executable (i.e. not DBI or ODBC).
        Vim 8 introduced a new Job / Channel feature which allows asynchronous
        execution of background jobs.  So, if executing a query (without jobs)
        you can no longer edit your code until the query finishes execution
        and displays a result.  When using this feature (:echo has('job')) the
        query will take place in the background allowing you to continue
        editing your code until it completes. >
            :DBSetOption job_enable=1
            let g:dbext_default_job_enable = 1
    dbext_default_job_status_update_ms
<       Default: 2000
        New feature to version 25.0.  When running a SQL statement via
        jobs, a status is displayed to the user every 2 seconds. >
            :DBSetOption job_status_update_ms=5000
            let g:dbext_default_job_status_update_ms = 5000
    dbext_default_job_show_msgs
<       Default: 1
        New feature to version 25.0.  When running a SQL statement via
        jobs, a status is displayed to the user every 2 seconds. These
        are echomsgs, rather than messages displayed in the result buffer.
        Version 26 adds additional information into the result buffer
        so this can allow you to reduce some messages. >
            :DBSetOption job_show_msgs=0
            let g:dbext_default_job_show_msgs = 0
    dbext_default_job_pipe_regex
<       Default: \%(@\|<\)
        New feature to version 26.0.  For the database types which run a
        command from a shell which pipe the SQL statements into the utility
        using a pipe command, then when running a job, the input file is 
        specified in a different way.  This allows a configurable way of
        identifing and removing the pipe when setting up the job. >
            let g:dbext_default_job_pipe_regex = '\%(@\|<\)'


<
 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:host=yourServerHostNameOrIP: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'
              let g:dbext_default_profile_mysql_local = 'type=MYSQL:user=root:passwd=whatever:dbname=mysql:extra=--batch --raw --silent'
              let g:dbext_default_profile_mysql_no_password = "type=MYSQL:user=root:dbname=mysql:extra=--password='' "
<
          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 >
    query_statements
<       - Which statements are used to determine what query is under the
          cursor. >
    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. >
    extra
<       - If additional parameters are required on a particular database
          type's command line they can be specified using this option.
          MySQL defaults this to '-t', to format the output with tabs.
          This value can be overridden three different ways:
              1.  Changing the default for a specific database type: >
                  let g:dbext_default_MYSQL_extra = '--batch --raw'
<             2.  Using the "extra" parameter specified in a connection
                  profile: >
                  let g:dbext_default_profile_mysql_local = 'type=MYSQL:user=root:passwd=whatever:dbname=mysql:extra=--batch --raw'
<             3.  Using :DBPromptForBufferParameters and specifying a value
                  for the extra parameter.  If this value is set to an empty
                  string, it will default to #1.  If it is set to a value
                  or a blank space it can be overridden. >
    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_ASA_bin                  = 'dbisql'
        dbext_default_ASA_cmd_header           = ''
        dbext_default_ASA_cmd_terminator       = ';'
        dbext_default_ASA_cmd_options          = '-nogui'
        dbext_default_ASA_extra                = ''
        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_ASE_extra                = ''
        dbext_default_CRATE_bin                = 'crash'
        dbext_default_CRATE_cmd_header         = ""
        dbext_default_CRATE_cmd_options        = ''
        dbext_default_CRATE_cmd_terminator     = ';'
        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_extra                = ''
        dbext_default_DB2_db2cmd_bin           = 'db2cmd'
        dbext_default_DB2_db2cmd_cmd_options   = '-c -w -i -t db2 -s'
        dbext_default_FIREBIRD_bin             = 'isql'
        dbext_default_FIREBIRD_cmd_options     = ''
        dbext_default_FIREBIRD_cmd_terminator  = ';'
        dbext_default_FIREBIRD_version         = '5'
        dbext_default_FIREBIRD_extra           = ''
        dbext_default_HANA_bin                 = 'hdbsql'
        dbext_default_HANA_cmd_terminator      = ''
        dbext_default_HANA_cmd_options         = ''
        dbext_default_HANA_extra               = ''
        dbext_default_INGRES_bin               = 'sql'
        dbext_default_INGRES_cmd_header        = ''
        dbext_default_INGRES_cmd_terminator    = '\p\g'
        dbext_default_INGRES_cmd_options       = ''
        dbext_default_INGRES_extra             = ''
        dbext_default_INTERBASE_bin            = ''
        dbext_default_INTERBASE_cmd_header     = ''
        dbext_default_INTERBASE_cmd_terminator = ''
        dbext_default_INTERBASE_cmd_options    = ''
        dbext_default_INTERBASE_extra          = ''
        dbext_default_MYSQL_bin                = 'isql'
        dbext_default_MYSQL_cmd_header         = ''
        dbext_default_MYSQL_cmd_terminator     = ''
        dbext_default_MYSQL_cmd_options        = ''
        dbext_default_MYSQL_extra              = '-t'
        dbext_default_MYSQL_version            = '5'
        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_ORA_extra                = ''
        dbext_default_PGSQL_bin                = 'psql'
        dbext_default_PGSQL_cmd_header         = ''
        dbext_default_PGSQL_cmd_terminator     = ''
        dbext_default_PGSQL_cmd_options        = ''
        dbext_default_PGSQL_extra              = ''
        dbext_default_PGSQL_pgpass             = expand('$HOME/.pgpass')
        dbext_default_SQLITE_bin               = 'sqlite'
        dbext_default_SQLITE_cmd_header        = ".mode column\n.headers ON\n"
        dbext_default_SQLITE_cmd_terminator    = ';'
        dbext_default_SQLITE_extra             = ''
        dbext_default_SQLSRV_bin               = "osql"
        dbext_default_SQLSRV_cmd_header        = ""
        dbext_default_SQLSRV_cmd_terminator    = "\ngo\n"
        dbext_default_SQLSRV_cmd_options       = '-w 10000 -r -b -n'
        dbext_default_SQLSRV_extra             = ''
        dbext_default_ULTRALITE_bin            = 'dbisql'
        dbext_default_ULTRALITE_cmd_header     = ''
        dbext_default_ULTRALITE_cmd_terminator = ';'
        dbext_default_ULTRALITE_cmd_options    = '-nogui -ul'
        dbext_default_ULTRALITE_extra          = ''

    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.

    For DB2 on the mainframe, specifying a cmd_terminator is not allowed
    and results in an error. >
        DB2100E The option "-;" specified after the 'db2' command or
        in the DB2OPTIONS variable is incorrect.

<   For these cases, I recommend setting up a connection profile and
    overriding the cmd_terminator to the empty string instead of the default ';'.
    This can be done in your .vimrc when you create your dbext connection profile: >
      let g:dbext_default_profile_MyDB2 = 'type=DB2:user=me:passwd=mypass:dbname=SSD:cmd_terminator='

<   It can also be overridden at any time within a buffer using this
    command: >
      DBSetOption cmd_terminator=
      DBSetOption cmd_terminator=;

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-maps-commands*

 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. The statement requires a valid
    " statement terminator at the end of the query.  This is typically
    " a semicolon or "go".
    " DBExecSQLUnderCursor works by starting at the current cursor position
    " and searching backwards for the first keyword defined by the dbext
    " query_statements option.  Then searches forward for a cmd_terminator
    " (usually a semicolon but it depends on database type).
    " The SQL found within these 2 searches is executed.
    " This has a number of downfalls, consider this SQL:
    "    create table xyz_bak as select * from xyz
    " For ambiguous statements, use visual mode to highlight exactly what
    " you would want executed.
    " 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 @var1 = '3'
    " Removes a buffer SQL variable
    :DBSetVar @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
<
 By default the dbext menu will use the default mappings to execute commands.
 You can change the behaviour to use the dbext commands instead by setting
 the following option: >
        let g:dbext_map_or_cmd = 'cmd'
<
 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.
    DBJobStatus           - Shows the status of the currently running job. 
    DBJobStop             - Allows the user to terminate the currently running
                            job.  Command completion has been enabled for this
                            to list the various options Vim supports to cancel
                            jobs.  Though Vim's defaults are usually
                            sufficient.
    DBJobTimerStop        - When a job is started a timer runs which indicates
                            to the user a job is in progress and how many
                            milliseconds it has been running.  Stopping the
                            timer does not does not stop the job it merely
                            stops notifying the user. 
    DBJobTimerStart       - Added for completeness.  Running a SQL statement
                            which starts a job automatically starts a status
                            timer.  This command will allow you to restart the
                            timer, assuming you had stopped it using
                            DBJobTimerStop.


==============================================================================
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 country = ?
           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 1.  Enter
        a value of 'Canada' (again, including quotes).

 The resulting query which is sent to the database will be: >
        SELECT varexists('@dave'), column2
          FROM customer
         WHERE name    = 'Homer'
           AND country = 'Canada'
           AND phone   = :phone_nbr
           AND email   = 'bob@something.com'
           AND c2      = 'property:name';
<
 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:srvname=mySrv: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: >
    " ASA - 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'

    " CrateIO
    let g:dbext_default_profile_CRATE = 'type=CRATE:host=localhost:port=4200:dbname=dummy:bin_path=C:\Crate\crate-0.52.4\bin'
    let g:dbext_default_profile_CRATE_DBI = 'type=DBI:user=:passwd=:driver=Crate'
    let g:dbext_default_profile_CRATE_DBI = 'type=DBI:user=:passwd=:driver=Crate:conn_parms=localhost\:4200'

    " 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'
    let g:dbext_default_profile_MyDB2 = 'type=DB2:user=me:passwd=mypass:dbname=SSD:cmd_terminator='

    " Firebird
    let g:dbext_default_profile_Firebird = 'type=FIREBIRD:user=sysdba:passwd=masterkey:dbname=C:\Programs\Firebird\Firebird_2_1\examples\empbuild\EMPLOYEE.FDB'

    " HANA
    " The instance ID is specified via the extra parameter
    let g:dbext_default_profile_HANA_MySrv = 'type=HANA:user=SYSTEM:passwd=manager:host=myhost:extra=-i 60'
    let g:dbext_default_profile_ODBC_MySrv = 'type=ODBC:user=SYSTEM:passwd=manager:dsnname=My_HANA_DSN'

    " 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 = 'type=MYSQL:user=root:passwd=whatever:dbname=mysql:extra=--batch --raw --silent'
    let g:dbext_default_profile_mysql_local = "type=MYSQL:user=root:dbname=mysql:extra=--password='' "
    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'
    " These 2 examples connect without using an entry in TNSNAMES
    let g:dbext_default_profile_ORA_Extended = 'type=ORA:user=scott:passwd=tiger:srvname=(description=(address=(protocol=TCP)(host=localhost)(port=1521))(connect_data=(server=dedicated)(service_name=10gR2)))'
    let g:dbext_default_profile_ORA_Extended_DBI = 'type=DBI:user=system:passwd=oracle:driver=Oracle:conn_parms=SID=orcl12c;HOST=localhost;PORT=1521'


    " PostgreSQL
    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:srvname=mySrv:dbname=myDB'
    " This SQL Server example uses sqsh to connect instead of the default osql
    " binary by using the SQLSRV_bin connection parameter. Since this binary
    " requires different parameters than osql, the "extra" connection option
    " is used to add additional switches.
    let g:dbext_default_profile_SQLSRV_sqsh='type=SQLSRV:user=User:passwd=Pass:host=Ip:SQLSRV_bin=sqsh:SQLSRV_cmd_options=:extra=-SFreetdsProfile -D dbname'
    let g:dbext_default_profile_SQLSRV_noStripVariables = 'type=SQLSRV:user=sa:passwd=Leader:host='.expand($COMPUTERNAME).':strip_at_variables=0'

    " SQLite
    let g:dbext_default_profile_POPFile = 'type=SQLITE:SQLITE_bin=C:\Programs\POPFile\sqlite.exe:dbname=C:\Programs\POPFile\popfile.db'
    let g:dbext_default_profile_SQLite = 'type=SQLITE:SQLITE_bin=C:\download\OpenSrc\Databases\SQLite\sqlite3.exe:dbname=\vim\test\dbext\sqlite\test.db'
    let g:dbext_default_profile_SQLite_DBI = 'type=DBI:driver=SQLite:conn_parms=dbname=\vim\test\dbext\sqlite\test.db'
    let g:dbext_default_profile_SQLite_diff_cmdT = 'type=SQLITE:dbname=C:\vim\test\dbext\sqlite\test.db:cmd_terminator=~'

    " ULTRALITE
    let g:dbext_default_profile_UL_CustDB = 'type=ULTRALITE:user=dba:passwd=sql:dbname='.expand('$SQLANYSAMP11\ultralite\custdb\custdb.udb')
<
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 preceded 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.  The regex used here is
 explained further in this file, keep looking for variable_def_regex. >
     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>
<
 Here is an example of a custom map which I use to execute a block of SQL from
 a file full of stored procedures.  The function finds the necessary SQL and
 calls dbext's DBExecRangeSQL command.  Add the function to your vimrc.
>
    " Since I repeatedly need to edit stored procedures, the CREATE PROCEDURE
    " statement is preceeded by an IF ... END IF block which will drop
    " the procedure or it uses the CREATE OR REPLACE syntax.  A third alternative
    " is an ALTER PROCEDURE statement.
    " This function will visually select the IF block to the END; statement
    " of the stored procedure and execute it.  Or check for the
    " CREATE OR REPLACE and stop there and look to the end.
    " Here are the 3 structures this will look for (all from column 0):
    " Case 1:
    "     IF ..
    "     END IF;
    "     CREATE PROCEDURE
    "     BEGIN
    "     END;
    " Case 2:
    "     CREATE OR REPLACE PROCEDURE
    "     BEGIN
    "     END;
    " Case 3:
    "     ALTER PROCEDURE
    "     BEGIN
    "     END;
    "
    function! SQLExecuteIfCreateReplace()
        let l:old_sel = &sel
        let &sel = 'inclusive'
        let saveWrapScan=&wrapscan
        let saveSearch=@/
        let l:reg_z = @z
        let &wrapscan=0
        let @z = ''
        let found = 0
        let startLine = 0
        let endLine = 0
        let curLine = line(".")
        let curCol  = virtcol(".")

        " Must default the command terminator
        let l:dbext_cmd_terminator = ";"

        try
            " Search backwards and do NOT wrap
            " Find the line beginning with an IF clause
            "     IF EXISTS( SELECT 1 ...
            " or find an or replace clause
            "     CREATE OR REPLACE PROCEDURE ...
            " or find an ALTER PROCEDURE
            "     CREATE OR REPLACE PROCEDURE ...
            " And execute it until we find an
            "     END
            " at the beginning of a line.
            let startLine = search('\c\(^\<if\>\|^\<alter\s\+procedure\>\|\<or\s\+replace\>\)', 'bcnW' )

            if startLine > 0
                " Search forward and visually select all lines
                " until we find an END; clause
                " exe 'silent! norm! V/^END'.l:dbext_cmd_terminator."\s*$\n\<esc>"
                let endLine = search('^END'.l:dbext_cmd_terminator.'\s*$', 'cnW')
                exec startLine.','.endLine.'DBExecRangeSQL'
            endif
        finally
            call cursor(curLine, curCol)
            noh
            let l:query = @z
            let @z = l:reg_z
            let @/=saveSearch
            let &wrapscan=saveWrapScan
            let &sel = l:old_sel
        endtry
    endfunction
<
 The mapping I use to trigger the function is <Leader>sbe using the
 mnemonic sql - begin - end
>
    nnoremap <Leader>sbe :call SQLExecuteIfCreateReplace()<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 Objects 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.

    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. Job Support                         	*dbext-job*

 If your Vim supports Jobs (:echo has('job')), by default when using a 
 database type other than DBI or ODBC, dbext will create a job to run
 the SQL statement against the database.  The advantage of using jobs
 is they are asynchronous.  This means you can continue to edit your 
 buffer, while waiting for the SQL statement to complete and show the
 results.

 Jobs cannot be used for the DBI and ODBC interfaces, as those use the 
 built in Perl support of Vim and do not run external to Vim.

 Jobs cannot be used when not using the result buffer option 
 (g:dbext_default_use_result_buffer = 0).  This is automatically enabled
 for example when using the OMNI SQL completion functions provided by Vim's
 SQL filetype plugin in conjunction with dbext (|dbext-completion|).

 Only one dbext background job can be running at one time.

 If a job fails to start, it will fall back to synchronous execution.

 There are a few additional commands available to manage the jobs created: >
    DBJobStatus
<       Shows the status of the currently running job. >
    DBJobStop
<       Allows the user to terminate the currently running job.  
       Command completion has been enabled for this to list the various
       options Vim supports to cancel jobs.  Though Vim's defaults are 
       usually sufficient. >
    DBJobTimerStop
<       When a job is started a timer runs which indicates to the user
       a job is in progress and how many milliseconds it has
       been running.  Stopping the timer does not does not stop the job
       it merely stops notifying the user. >
    DBJobTimerStart
<      Added for completeness.  Running a SQL statement which starts a job
      automatically starts a status timer.  This command will allow you to
      restart the timer, assuming you had stopped it using DBJobTimerStop.


==============================================================================
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 :close 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 certain keywords (based on
 the query_statements option).  An example of the default values for this
 option are: >
    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:srvname=mySrv: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 overridden 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 your 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*
 -------------------------------
 The feature has been added to assist developers _testing_ their queries.
 When writing SQL statements, you can often pass in parameters or host
 variables to be replaced at execution time.  When executing these SQL
 statements to test them you need to replace these variables with actual
 values.

 As a developer, you can modify the buffer and put in "valid" values that
 will return SQL rows, but that means modifying the code just to "test".

 You can copy and paste this code into a interactive SQL shell, and then
 once again, remove the host variables and replace this with actual parameters
 to ensure your statement will return the rows you are expecting (a
 successful test).

 This dbext feature, will scan your statement for parameters using the
 "variable_def_regex" option.  When it finds values that match the regex
 it will prompt you to temporarily replace the parameter with the supplied
 value.  This allows you to test the execution of your script without actually
 modifying your code.

 The prompting is controlled via the "always_prompt_for_variables" option.  By
 default it is on.  For an explanation of the prompt screens, continue reading
 through this tutorial.  They are designed for speed and efficiency and
 allowing you quick access to previously stored variable names for testing.

 Any variables which you have supplied (on a per buffer basis) will be stored
 for later use.  You can see the list of saved values executing :DBListVar
 Multiple values for each parameter can be stored and :DBListVar will allow
 you to remove saved values.  The saving of variables is controlled via
 the "variable_remember" option.

 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 <Leader>se (\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.  If you did not remove the
      INTO clause, you would generally get an error indicating
      "@cust_variable_id" does not exist.  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 can 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
            set @var_name = 2
            set @var_name = 3
<       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 define variables: >
            :DBSetVar :myvar1='myvar1'
            :DBSetVar @myvar2='myvar2'
            :DBSetVar @myint3=3

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

    e) Variables can be removed

      To remove a specific variable assignment use :DBSetVar! >
            :DBSetVar! @var_name=2
<      To remove the variable and all previous values, use DBSetVar! with the variable name >
            :DBSetVar @var_name
<

 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 2 different regex expressions.  The first one
 finds the question marks and the second one finds any variables
 beginning with "@,:,$". >
        \(\w\|'\)\@<!?\(\w\|'\)\@<!
            \(\w\|'\)    - Beginning of a word character or a single quote
            \@<!         - If the above is true do NOT match
            ?            - Match a question mark
            \(\w\|'\)    - Beginning of a word character or a single quote
            \@<!         - If the above is true do NOT match
            - In otherwords, find a question mark on its own which
              is not surround in quotes and not embedded in a word
              SELECT c1 FROM t1 WHERE c2 = ?    -- match this
              SELECT c1 FROM t1 WHERE c2 = '?'  -- do not match this
              SELECT c1 FROM t1 WHERE c2 = da?  -- do not match this

        \zs\(@\|:\|$\)\w\+\>
            \zs          - Start matching now
            \(@\|:\|$\)  - Match a @ or : or $ character
            \w\+         - Match at least one or as many word characters as possible
            \>           - and end on a word boundary
            - In otherwords, find these types
              SELECT c1 FROM t1 WHERE c2 = @myVar
              SELECT c1 FROM t1 WHERE c2 = :hostVar
              SELECT c1 FROM t1 WHERE c2 = $placeHolder
<
 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| (NOTE: change the ** to a single * when pasting): >
        autocmd BufRead **/MyProjectDir/** DBSetOption variable_def_regex=\<\(p_\|lv_\)\w\+\>
        autocmd BufRead **/MyProjectDir/** if exists('g:loaded_dbext') | exec 'DBSetOption variable_def_regex=\<\(p_\|lv_\)\w\+\>' | endif
<
 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 (NOTE: change the ** to a
 single * when pasting): >
        autocmd BufRead **/MyProjectDir2/** DBSetOption variable_def_regex=,\<\(p_\|lv_\)\w\+\>
        autocmd BufRead **/MyProjectDir2/** if exists('g:loaded_dbext') | exec 'DBSetOption variable_def_regex=,\<\(p_\|lv_\)\w\+\>' | endif
<

 Prompt screens and options.

 If dbext detects you have some host variables in your query (and all the
 options for prompting and saving variables has been enabled) you receive a
 prompt: >
    Variables detected in statement.  Choose an action:
    1. Prompt for variables
    2. Execute query as is
    3. Use previously saved values
    4. Never ask again
    5. Abort
<
 I will leave the first option to the end.

 Option 2:
    Do not change the query, execute it as is, with all the host parameters in
    tact (unchanged).

 Option 3:
    If there are previously saved values (and each variable can have multiple
    values which are saved in a most recently used List), grab the first one
    and use that value.  This is designed for quick iteration testing.  While
    working on a query (trying to "get it right") I will repeatedly execute
    the query as I build it up.  I don't want to be constantly prompted for
    the parameters I just used, so just use them again.

 Option 4:
    If you find the prompts annoying, but do not want to globally turn them
    off, or you know this type of file, you would always choose option 2, then
    simply choose this option.  For this buffer, you will never be prompted
    again and all queries will execute as is.
    If you want to re-enable the prompts to can execute: >
        :DBSetOption always_prompt_for_variables = 1
<
 Option 5:
    There was a mistake, and you just don't want to execute the query anymore.

 Option 1:
    Lets assume we are executing this SQL query: >
        SELECT *
          FROM EQUIPMENT AS eq
         WHERE eq.EQUNR = p_EQUNR
<
    And that we have no previously saved values for p_EQUNR and we want to be
    prompted for parameters beginning with "p_".
    Executing the query, dbext shows the previous prompt and this time you
    choose option 1.

    This choice opens a sub prompt. >
        Choice for [p_EQUNR]
        1. Use [p_EQUNR]
        2. Use blank value
        3. Enter new value
        4. Show previously saved values
        [...There are additional options, continue reading...]
<
    Option 1
        Assumes you do not want to change the parameter at all, simply
        continue to use the same value.  I wanted this default to be "standard" in
        case you are quickly hitting ENTER through all the prompts.  Nothing
        changes the query.

    Option 2
        Simply replace p_EQUNR with a blank value (just remove it completely).

    Option 3
        Let me choose a new value for p_EQUNR.  A dialog pops up and you enter
        (with the quotes) 'e'.

        At this point, p_EQUNR is replaced directly with 'e', the query which
        executes is: >
            SELECT *
              FROM EQUIPMENT AS eq
             WHERE eq.EQUNR = 'e'
<
        dbext automatically saves this value, which you can see by running
        :DBLisVar.

    Option 4
        If you do not know the values previously saved (though they are
        shown), but perhaps you want to "remove" some of the previously
        saved values, this is just a convienent way to run :DBListVar.
        The saved variable screen is shown and the execution of the
        statement is aborted.

    Now that we have executed this query once, and chose Option 3 and entered
    a new value :DBListVar has begun saving our previous values.  This means
    when we execute this query a 2nd time, our prompt is slightly different: >
        Choice for [p_EQUNR]
        1. Use [p_EQUNR]
        2. Use blank value
        3. Enter new value
        4. Show previously saved values
        5. Use most recent saved value
        6. Use ['e']
<
    Option 5
        Has been added now that we have a saved value.  Option 5 just says use
        the most recently saved value for this variable.  Which in this case
        is 'e', as we only have 1 saved value for p_EQUNR.

    Option 6
        Is the exact same as choosing option 5, but it does allow you to see
        what is the most recent value.

    Choose option 3 again, and this time enter 'f'.

    After running the query, run :DBListVar you will see the following output: >
        ------------------------
        ** Variable List **
        Delete line to remove saved value
        ------------------------
        set p_EQUNR = 'f'
        set p_EQUNR = 'e'
<
    Executing the query for a 3rd time will show the following prompt: >
        Choice for [p_EQUNR]
        1. Use [p_EQUNR]
        2. Use blank value
        3. Enter new value
        4. Show previously saved values
        5. Use most recent saved value
        6. Use ['f']
        7. Use ['e']
<
    Now both 'f' (most recent) and 'e' are displayed allowing you to choose
    which of the saved values to use this time while executing the query.

    Choosing 'e' this time, will move 'e' to the front of the most recently
    used values, so the prompt the 4th time will show: >
        6. Use ['e']
        7. Use ['f']
<
    You can pre-add saved values for the buffer by executing the
    following commands: >
        DBSetVar p_EQUNR = 'e'
        DBSetVar p_EQUNR = 'd'
        DBSetVar p_EQUNR = p_EQUNR
<

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


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