=================================
``grail.dsn`` Module
=================================
.. include:: ..\version.h
.. include:: ..\Library_Reference\lib-reference.h


.. contents:: Table of Contents
   :backlinks: top


--------
Overview
--------

The ``grail.dsn`` module provides clients with the ability to dynamically
manipulate Data Source Names (DSNs). The DSN is typically used
to identify the location of databases.

-------
Example
-------

Although it is true that you can use the low level :f:`config` function to
generate DSNs for any database, the following example will concentrate on
using the higher level functions for generating a DSN for a MS Access Database.

This example will create a "test_db" DSN, list out the
existing DSN, remove the "test_db" and re-list out the existing DSNs afterwards,

  .. Python::
 
    # (1) ADD a SYSTEM DSN called 'test_db'.
    dsn.mdb_add(
       dsn.LEVEL_SYSTEM,
       "test_db",
       r"C:\tmp\testdb"
    )
  
    # (2) Display the existing DSN Names
    userDsnNameList = dsn.list_user()
    sysDsnNameList = dsn.list_system()
    print "user: %s" % (str(userDsnNameList))
    print " sys: %s" % (str(sysDsnNameList))

    # (3) Remove the "test_db" 
    dsn.mdb_remove_if_exists(
        dsn.LEVEL_SYSTEM,
        "test_db"
    )
    
    # (4) Display the existing DSN Names
    userDsnNameList = dsn.list_user()
    sysDsnNameList = dsn.list_system()
    print "user: %s" % (str(userDsnNameList))
    print " sys: %s" % (str(sysDsnNameList))
   
In step (1) we will have a new system level DSN called "test_db" that will
point to the database at :file:`C:\\tmp\\testdb`, which we will confirm by
inspecting the results of step (2). In step (3) we will remove the
"test_db" DSN, and visually confirm the results in test (4).

.. Note::
     
  In order to execute the above example you will need to have
  a :file:`c:\\tmp\\test.mdb` file. Otherwise the :f:`mdb_add` function
  will generate a :e:`IOError`.
     
     
--------------------
High Level Functions
--------------------

:df:`exists(dsnName)`
  Returns TRUE (:d:`1`) if the :a:`dsnName` exists in either the user or
  system dsn entries. This will generate a :e:`ValueError` exception
  if the :a:`dsnName` is not valid.

:df:`exists_user(dsnName)`
  Returns TRUE (:d:`1`) if the :a:`dsnName` exists in either the user dsn entries.
  This will generate a :e:`ValueError` exception if the :a:`dsnName` is
  not valid.

:df:`exists_system(dsnName)`
  Returns TRUE (:d:`1`) if the :a:`dsnName` exists in either the system dsn entries.
  This will generate a :e:`ValueError` exception if the :a:`dsnName` is
  not valid.
  
:df:`list_user()`
  Returns a list of DSNs for the user entries.
  
:df:`list_system()`
  Returns a list of DSNs for the system entries.
  
:df:`mdb_add(level, dsnName, mdbPath)`
  Convenience function for quickly adding "Microsoft Access Database (\*.mdb)"
  database DSN entries. The :a:`level` can either be :d:`LEVEL_USER` for
  user level entries or :d:`LEVEL_SYSTEM` for system level entries.
  
  This function will generate a :e:`ValueError` if the :a:`level` is invalid.
  It will also generate a :e:`ValueError` if the :a:`dsnName` is not valid.
  Finally, it will generate an :e:`IOError` if the :a:`mdbPath` does not
  point to a valid MS Access Database file.  
  
:df:`mdb_remove(level, dsnName)`
  This function will remove a DSN entry described by the :a:`dsnName` for
  the appropriate :a:`level`. The :a:`level` can either be :d:`LEVEL_USER`
  or :d:`LEVEL_SYSTEM`.
  
  This function will fail with an :e:`IOError` if you attempt to remove
  a :a:`dsnName` that does not exist. Consider using the
  :f:`mdb_remove_if_exists` otherwise.  
  
  This function will generate a :e:`ValueError` if the :a:`level` is invalid.
  It will also generate a :e:`ValueError` if the :a:`dsnName` is not valid.
  
:df:`mdb_remove_if_exists(level, dsnName)`
  Works like the :f:`mdb_remove` function except that if the :a:`dsnName`
  does not exist, this function does nothing.

:df:`sqlserver_add(level, dsnName, server, database[, desc, trusted])`
  Convenience function for quickly adding "SQL Server" database DSN entries.
  The :a:`level` can either be :d:`LEVEL_USER` for user level entries or
  :d:`LEVEL_SYSTEM` for system level entries.  The :a:`desc` provides an
  optional description. If :a:`trusted` is set to :d:`True` then this will add
  a trusted connection option to the string. By default :a:`trusted` is
  :d:`False`.

  This function will generate a :e:`ValueError` if the :a:`level` is invalid.
  It will also generate a :e:`ValueError` if the :a:`dsnName` is not valid.
  Finally, it will generate an :e:`IOError` if the :a:`mdbPath` does not
  point to a valid MS Access Database file.  

  You can not store a user name and password within a Untrusted DSN. If you use
  a :a:`trusted` DSN it will use Window's authentication.

:df:`sqlserver_remove(level, dsnName)`
  This function will remove a DSN entry described by the :a:`dsnName` for
  the appropriate :a:`level`. The :a:`level` can either be :d:`LEVEL_USER`
  or :d:`LEVEL_SYSTEM`.
  
  This function will fail with an :e:`IOError` if you attempt to remove
  a :a:`dsnName` that does not exist. Consider using the
  :f:`sqlserver_remove_if` otherwise.  
  
  This function will generate a :e:`ValueError` if the :a:`level` is invalid.
  It will also generate a :e:`ValueError` if the :a:`dsnName` is not valid.

:df:`sqlserver_remove_if_exists(level, dsnName)`
  Works like the :f:`sqlserver_remove` function except that if the :a:`dsnName`
  does not exist, this function does nothing.

------------------
Low Level Function
------------------

:f:`config(request, driverName, config_dict)`
  The :f:`config` function is a low-level function that maps directly to the
  Data Source Name configuration routine. With this function you should
  be capable of creating and removing most DSNs if you have supplied the
  correct ODBC parameters.
  
  Most of the time you want to avoid using this function unless you know what
  you are doing. But sometimes, you just need to have the raw power, and this
  function provides it to you.
  
  As an example of its usage, consider creating a DSN for a MS Access Database
  (MDB). You would do it with the following command,
  
  .. Python::
  
    dsn.config(
       dsn.ODBC_ADD_DSN,
       dsn.MSACCESS_DRIVER_NAME_EN,
       {
           "dsn":"test_mdb",
           "dbq":"c:\\tmp\\test.mdb",
           "description":"created from python",
       }
      )
      
  where the first :a:`request` can be one of the :d:`ODBC_XXX` constants
  available from this module. These constants will add/remove a user or system
  DSN entry.
  
  In the above snippet we are using a constant provided by the ``dsn`` module
  to specify the :a:`driverName`. Typically the driver name is same as the one
  shown when you manually add a driver. For example,
  :d:`MSACCESS_DRIVER_NAME_EN` is "Microsoft Access Driver (\*.mdb)".
  
  Finally the :a:`configDict` is used to specify the configuration details
  for the operation. If you have an understanding of what the databases ODBC
  DSN installations require, the above configuration details would result in
  the following string,
  
    ::
  
     "dsn=test_mdb\0dbq=c:/tmp/test.mdb\0description=created from python\0\0"
     
  Suffice it to say that this is a fairly complicated function. Within this
  module their exists easier to use functions for adding and removing
  DSNs.
  
  To complete the above example the following snippet will remove
  the same DSN entry,
  
  .. Python::
  
    dsn.config(
        dsn.ODBC_REMOVE_DSN,
        dsn.MSACCESS_DRIVER_NAME_EN,
        {"dsn":"test_mdb"}
        )
        
.. HACK: closes above block before "title" block below.

---------
Constants
---------

:d:`ODBC_ADD_DSN`
  Used in the :f:`config` function this indicates that you wish to
  add a USER DSN entry.
  
:d:`ODBC_ADD_SYS_DSN`
  Used in the :f:`config` function this indicates that you wish to
  add a SYSTEM DSN entry.

:d:`ODBC_REMOVE_DSN`
  Used in the :f:`config` function this indicates that you wish to
  remove a USER DSN entry.

:d:`ODBC_REMOVE_SYS_DSN`
  Used in the :f:`config` function this indicates that you wish to
  remove a SYSTEM DSN entry.
  
:d:`MSACCESS_DRIVER_NAME_EN`
  Provided to ease spelling mistakes. This is the common English name
  for the Microsoft Access Drivers.
  
:d:`LEVEL_USER`
  Used with the higher level functions, such as :f:`mdb_add` and
  :f:`mdb_remove`, this indicates you wish to create a USER level DSN entry.

:d:`LEVEL_SYSTEM`
  Used with the higher level functions, such as :f:`mdb_add` and
  :f:`mdb_remove`, this indicates you wish to create a SYSTEM level DSN entry.

:d:`SQLSERVER_DRIVER_NAME_EN`
  Provided to ease spelling mistakes. This is the common English name
  for the Microsoft SQL Server driver.