*dbext.txt*	For Vim version 6.0.  Last change: Tue Dec 19 2006 10:40:50 PM


                	  VIM REFERENCE MANUAL 
                                by 
                     Peter Bagyinszki <petike1@dpg.hu>
                     David Fishburn <fishburn@ianywhere.com>

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

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
SourceForge: $Revision: 1.23 $

*dbext* *dbext.vim* *db_ext* *db_ext.vim* *database-extension* *pgsql* *mysql*
*asa* *ase* *ingres* *interbase* *sqlite* *sqlsrv* *ora* *db2*

1.  Overview					|dbext-overview|
2.  Installation				|dbext-install|
3.  Configuration				|dbext-configure|
    3.1 Displaying Results                      |dbext-configure-results|
    3.2 Script Variables                        |dbext-configure-variables|
    3.3 Database Specific Options               |dbext-configure-options|
    3.4 DB2 Modes                               |dbext-configure-db2|
4.  Mappings and commands			|dbext-mappings|
5.  Adding new database types			|dbext-newdb|
6.  Prompting for input parameters		|dbext-prompting|
7.  Setting up connection information		|dbext-connect|
    7.1 Connection Parameters                  	|dbext-connect-parameters|
    7.2 Prompting for Parameters                |dbext-connect-prompting|
    7.3 Connection profiles                     |dbext-connect-profiles|
    7.4 Connection information in modelines     |dbext-connect-modelines|
    7.5 Asking for connection parameters        |dbext-connect-ask|
8.  Creating mappings using dbext commands	|dbext-in-mappings|
9.  Object Completion                          	|dbext-completion|
10. Listing Objects in the Database            	|dbext-list-objects|
11. Plugin integration             	        |dbext-integration|
    11.1 OMNI completion integration            |dbext-omni-completion|
    11.2 Intellisense integration             	|dbext-intellisense|
12. Filetype support                         	|dbext-filetypes|
    12.1 Using filetype support                 |dbext-filetypes-using|
    12.2 Adding new filetypes                   |dbext-filetypes-adding|
13. Using SQL History                         	|dbext-history|
14. Open Source                         	|dbext-sourceforge|
15. Tutorial                             	|dbext-tutorial|

{Vi does not have any of this}

------------------------------------------------------------------------------
What's New						*dbext-new*

Version 4.20

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

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


Version 4.10

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

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


Version 4.00

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

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


Version 3.50

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

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


Version 3.00

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

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


Version 2.30

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

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


Version 2.20

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

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


Version 2.11

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


Version 2.10

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

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


Version 2.00

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

------------------------------------------------------------------------------
1. Overview						*dbext-overview*

 This plugin contains functions/mappings/commands to enable Vim to access 
 several databases. Currently Mysql, PostgreSQL, Ingres, Oracle, 
 Sybase Adaptive Server Anywhere, Sybase Adaptive Server Enterprise, 
 SQLite, Microsoft SQL Server, DB2 and Interbase are supported.

 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.  

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

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

3.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 is a local buffer mapping created to re-run the statement which
 populated the result window.  Pressing 'R' calls the DBRefreshResult 
 command.

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

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

3.2 Script Variables                            *dbext-configure-variables* 

 Global variables: >
    dbext_default_profile
<       - Predefined favourite connection information >
    dbext_default_type
<       - Default relational database to connect to >
    dbext_default_integratedlogin
<       - On Windows, whether to use integrated login for ASA and SQLSRV >
    dbext_default_user
<       - Default user id >
    dbext_default_passwd
<       - Default password >
    dbext_default_dbname
<       - Default database to connect to >
    dbext_default_host
<       - Default host the server is running on >
    dbext_default_port
<       - Default port to connect to >
    dbext_default_extra
<       - Customization string if the above options are not enough >
    dbext_default_use_result_buffer
<       - Whether to use the result buffer, or echo the results of the command >
    dbext_default_use_sep_result_buffer
<       - Whether to use separate result buffers for each file >
    dbext_default_buffer_lines
<       - How many lines the Result window should be >
    dbext_default_parse_statements 
<       - Which statements are parsed for input parameters (See section 6) >
    dbext_default_prompt_for_variables 
<       - Allows you to specify if dbext should check for host variables >
    dbext_default_always_prompt_for_variables 
<       - If host variables are found, you are asked if you want to be
          prompted, setting this variable assumes you always want to be
          prompted, so it saves you a dialog.
        - This option can have 3 values:
             1 - Always prompt for variables
             0 - Ask if you want to (if variables are found)
            -1 - Never prompt for variables >
    dbext_default_stop_prompt_for_variables 
<       - This is used internally by dbext.  Each time a query is executed
          and the user is prompted for variables, if you press "Ok" without
          entering anything, you are prompted asking whether you want to:
                1.  Skip the replacement for this string
                2.  Replace it with a blank
                3.  Stop prompting for just this query 
                4.  Never prompt for variables (including subsequent queries)
                5.  Abort the query and do NOT execute it
        - If option 3 is chosen, dbext sets this variable and resets it for
          the next query. >
    dbext_default_display_cmd_line 
<       - When the command is run, the results are displayed in the Result
          buffer, setting display_cmd_line = 1, will also display the command
          that was run to generate the output.  Useful for debugging.  >
    dbext_default_variable_def
<       - List of variables and rules on how to search and prompt for variable
          names within a statement that starts with any of the words listed in
          dbext_parse_statements. >
    dbext_default_replace_title 
<       - Changes the title of the buffer to show connection information.
          This is useful if you are using a scratch buffer to test statements, 
          it will show you which database you are connected to visually by
          glancing at the buffer title. >
    dbext_default_custom_title 
<       - If the default format of the replace title feature does not meet
          your needs, you can set a custom title.  To retrieve settings
          from the dbext plugin you can use: >
            :let new_title = 'Srvr: ' . DB_listOption('srvname')
            :exec 'DBSetOption type=ASA:replace_title=1:custom_title='.new_title
    dbext_default_use_tbl_alias
<       - DBListColumn (by default) will create a column list with an
          alias attached to each column.  This option has three 
          settings: >
            n - do not use an alias
            d - use the default (calculated) alias
            a - ask to confirm the alias name
<       - An alias is determined following a few rules:
            1. If the table name has an '_', then use it as a separator: >
               MY_TABLE_NAME --> MTN
               my_table_name --> mtn
               My_table_NAME --> MtN
<           2. If the table name does NOT an '_', but DOES use mixed case 
               then the case is used as a separator: >
               MyTableName --> MTN
<           3. If the table name does NOT an '_', and does NOT use mixed case 
               then the first letter of the table is used: >
               mytablename --> m
               MYTABLENAME --> M
<       - The option can be turned on and off via the DBSetOption command. >
            :DBSetOption use_tbl_alias=n
    dbext_default_delete_temp_file 
<       - If debugging, it can be useful to view the SQL file that
          dbext generated to be executed by the database.  Setting this
          option to 0 (off) will leave the temporary file in the
          $TEMP directory for viewing. >
            :DBSetOption delete_temp_file=0
    dbext_default_history_file
<       - The SQL history is stored within a file.  This was done for 
          a couple of reasons:
              1.  No upper bound on the size of the history.
              2.  If you have multiple instances of Vim running, each
                  will see the current history without overwriting
                  each other (thereby loosing history).
              3.  The history can easily be removed if necessary.
          Each SQL statement has it's newline characters replaced with 
          @@@ so the statement fits on one line.  The default history
          file varies by the OS:
              Unix:     $HOME/dbext_sql_history.txt
              Windows:  $VIM/dbext_sql_history.txt
          If you wish to override the file location you can via your
          |vimrc|.  To see the current setting run :DBGetOption. >
            :let  g:dbext_default_history_file = '/your/loc/file.txt'
            :let  g:dbext_default_history_file = 'c:\your\loc\file.txt'
    dbext_default_history_size 
<       - Controls how many SQL statements should be stored within the
          history.  The default value is 50.  This option must be
          set within your |vimrc|.  To see the current setting run
          :DBGetOption. >
            :let  g:dbext_default_history_size = 50
    dbext_default_history_max_entry
<       - You can limit the size of the entries dbext records in the
          history file.  The current default is 4K.  Statements longer
          than 4K are not stored within the history file.  Setting this
          value to 0, removes any limits on the size of a single entry. >
            :let  g:dbext_default_history_max_entry = 4096
    dbext_default_dict_show_owner
<       - When creating a dictionary of tables, procedures and views
          the owner name can also be included.  The omni sql complete
          plugin uses this setting.  The default is enabled, to disable 
          add the following to your vimrc: >
            :let  g:dbext_default_dict_show_owner = 0
    dbext_default_use_win32_filenames
<       - If using Cygwin on Windows and the 3rd party binaries (sqlplus.exe,
          mysql.exe, dbisql.exe, ...) are Windows compiled then they will not
          understand Unix style filenames (with forward slashes).  Setting
          this option to 1, forces all filenames to be referenced with
          double backslashes instead.  It also uses the Cygwin utility,
          cygpath, to identify the absolute filename from a Windows
          perspective.  The default is 0, to enable add the following to your
          vimrc: >
            :let  g:dbext_default_use_win32_filenames = 1
<
 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:dsnname=Can Include Spaces:user=DBA
 
    profile
<       - Current profile specified (if any) >
    type
<       - Relational database to connect to >
    integratedlogin
<       - On win32, whether integrated logins are used >
    user
<       - User id >
    passwd
<       - Password >
    dsnname
<       - ODBC DSN to connect to >
    srvname
<       - Server name >
    dbname
<       - Which database on the server to connect to >
    host
<       - Machine name or IP address of server >
    port
<       - Port server is running on >
    extra
<       - Based on the database you are connecting to, you can add 
          additional items to the tools command line.  For example, 
          using ASA, I could run: >
              DBSetOption extra=CON=myconn
<
          From within a profile (set within your vimrc): >
              let g:dbext_default_profile_mysql = 'type=MYSQL:user=root:passwd=:dbname=mysql:extra=-t'
<
          This has the net result of creating the following command line: >
              dbisql -c "UID=dba;PWD=sql;CON=myconn"
    bin_path
<       - If tools provided by the database are not in the path, you can 
          optionally supply full path to the binaries.  This is also useful
          if two different buffers need to use different versions of the
          client software. >
    use_result_buffer
<       - You can turn on or off the use of the Result buffer >
    buffer_lines
<        - How large the Result buffer is >
    display_cmd_line
<       - Optionally display the command line used to execute the command
          in the Result buffer useful for debugging >
    parse_statements 
<       - Which statements are parsed for input parameters |dbext-prompting| >
    variable_def 
<       - List of variables and rules on how to search and prompt for variable
          names within a statement that starts with any of the words listed in
          parse_statements. >
    bin 
<       - Name of the binary which dbext uses to execute commands >
    cmd_header
<       - SQL statements sent before the command you are executing.  This
          setting is usually used to set temporary options, or output 
          options. >
    cmd_terminator
<       - Command terminator (varies per database, see following section) >
    cmd_options
<       - Optionally specify (or override) additional command line switches
          for the database tool. >
    on_error
<       - Dictates the behaviour of the tool if an error is encountered during
          execution. >
    suppress_version_warning
<       - If a user had a previous version version of dbext installed
          a warning message is displayed if some configuration parameters
          still exist.  This will prevent the message from begin 
          displayed.


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

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


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


------------------------------------------------------------------------------
4. Mappings and commands				*dbext-mappings*

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

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

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

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

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

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

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

    " 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

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

    " 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
    
    " 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
    
    " Prompt for connection information
    " [Optional] Profile
    " [Required] Database type - MySQL, ASA, Ingress, Oracle (see above) 
    " [Optional] Integrated Login (Win32, ASA, SQLSRV)
    " [Optional] Database user
    " [Optional] User password 
    " [Optional] ODBC DSN
    " [Optional] Server name
    " [Optional] Database name
    " [Optional] Host name
    " [Optional] Port name 
    " [Optional] Directory for database tools (if not in path already)
    " sql - buffer prompt 
    nnoremap <unique> <Leader>sbp <Plug>DBPromptForBufferParameters
    :DBPromptForBufferParameters
		
 These are the default mappings.  If you choose your own keys, the plugin
 will use your mappings and will not create the default mappings.  You can
 also specify the following to disable the default mappings: >
        let g:dbext_default_usermaps = 0
<    
 Commands
    (In addition to the above mappings)
    DBExecSQL       - Enter any command you want sent to the database
    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
    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
    DBRefreshResult - Re-runs the statement currently displayed in the 
                      result window

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

------------------------------------------------------------------------------
6. Prompting for input parameters			*dbext-prompting*

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

 To turn off this feature: >
        let g:dbext_default_prompt_for_parameters=0  (globally)
        DBSetOption prompt_for_parameters=0          (just for the buffer)
<
 To change which statements get parsed: >
        let g:dbext_default_parse_statements='select,update' (globally)
        DBSetOption parse_statements=select,update   (just for the buffer)
<
 The feature is best described with examples: >
        SELECT varexists('@dave'), column2
          INTO p1, p2
          FROM customer
         WHERE name    = @name
           AND address = ?
           AND phone   = :phone_nbr
           AND email   = 'bob@something.com'
           AND c2      = 'property:name';
<
 In this case we are demonstrating what is parsed from the statement and
 prompted for.
    1.  The INTO clause is removed, so the output is displayed in the Result
        buffer.
    2.  ?, @something, :something are stripped out of the query.  You are
        prompted to enter a suitable value for each one, and the resulting 
        query is sent to the database.
    3.  '@dave','bob@something.com' and 'property:name' are not stripped
        out of the query since they are surrounded in single quotes.
    4.  When prompted for a value for @name, I would enter 'Homer' (including
        the single quotes).
    5.  When prompted for a value for ? it will indicate which ? this is, by
        counting them and prompting you for a value for ? number 6.
 
 To modify what variables that are searched for consider the following
 example: >
        INSERT INTO sync_log ( user_id, table_name, line )
        VALUES( i_user, i_table_name, i_str );
<This is an INSERT statement within a stored procedure.  The stored procedure
 takes 3 input parameters.  The author of the stored procedure places a i_
 ahead of all input variables.  You can modify the buffer variable for this
 file as follows: >
        DBSetOption variable_def='?WQ,@wq,$wq,i_wq'
<
 or more specifically: >
        DBSetOption variable_def='i_wq'
<
 Adding new search and replace criteria must follow these rules:
        i_ - look for this string
        w  - MUST have word characters after it
        W  - cannot have any word characters after it
        q  - quotes do not matter
        Q  - CANNOT be surrounded in quotes
        ,  - delimits between the identifiers
>
        DBSetOption variable_def='i_wq,'
<
 This instructs the plugin to find all words that begin with "i_", with a
 series of \w characters following, that is NOT surrounded in quotes.  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.
 
 Another type of criteria is specified.  You can also use the "unitl" setting
 which allows you to specify the start of the string, and the everything
 should be replaced "until" another string.  Here is an example: >
        SELECT * FROM Customers WHERE ID = http_variable('cust_id')
<
 In this case, we want dbext to prompt for anything like "http_variable(...)".
 This can be configured using: >
        DBSetOption variable_def='http_varu)'
<
 This option has special rules, and is broken down as:
        http_var - Look for this string
        u        - Assume a match UNTIL
        )        - This string
 So in this case, matching "http_var" until the ")" will force dbext to 
 prompt the user for a replacement of "http_variable('cust_id')".

 For more information on specific filetype support see |dbext-filetypes|

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

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

7.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 section 7.4).

 In your |.vimrc| you can define the following: >
     let g:dbext_default_profile_ASA_generic = 'type=ASA:user=DBA:passwd=SQL'
<
 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'
<
7.4 Connection information in modelines           *dbext-connect-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 section |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'
<


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

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

------------------------------------------------------------------------------
10. Listing Ojects in the Database                     	*dbext-list-objects*

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

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

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

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

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

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

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

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

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

12.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.
 
------------------------------------------------------------------------------
13. 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.
 
 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.
 
------------------------------------------------------------------------------
14. Open Source                         	        *dbext-sourceforge*

 dbext is now an open source project found at: >
     https://sourceforge.net/projects/dbext/
< 
------------------------------------------------------------------------------
15. 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;
<



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



 The result buffer
 -----------------
 When SQL statements are executed, a new split below buffer is created called,
 "Result".  This buffer is readonly, you will not be prompted to save it when
 exiting Vim.  After the buffer has been created, you can move the buffer to a
 location that better suits you.  Assuming you can hide buffers |'hidden'|, if
 you issue a :clo command, you can remove the buffer from the display.  The
 next time a command is executed, it will be made visible again.

 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, see below).
         
 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.


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

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

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

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



 Selecting from tables
 ---------------------
 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:
        :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:
        \stw  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;
<
    
 
 Describing objects
 ------------------
 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:
        \dt  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



 Connection Profiles
 -------------------
 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'
<
 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.
 
 
 
 Listing 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
< 


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


 Host variable replacement
 -------------------------
 When writing SQL statements, you can often pass in parameters or host
 variables to be replaced at execution time.  This feature is enabled by
 default.

 Place your cursor on 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.  With your cursor where the ^ indicates, you can
 either hit \se, or you can visually select the entire SELECT statement and
 hit \se.

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



 Filetype support
 ----------------
 This is an extension of the above host variable replacement.  The following
 filetypes are currently supported:  >
     PHP, Java, JSP, JavaScript, jProperties, Perl, SQL, 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.



 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.



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

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


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