------------------------------------
PTMDB MODULE - db_connect() FUNCTION
------------------------------------

  ------------
  USAGE FORMAT
  ------------

    Where $db_object is a database handler object return value:
    
    $db_object = &db_connect($db_type, $user, $password);
    $db_object = &db_connect($db_type, $user, $password, \%argument_hash);
    $db_object = &db_connect($db_type, $user, $password, \%argument_hash,
                             \%attribute_hash);

  -----------
  DESCRIPTION
  -----------

    Connects to the requested database server.
    Returns a DBI database handler object.

  ---------
  ARGUMENTS
  ---------

    $db_type

      REQUIRED

      The type of database you are attempting to connect to. For example, if
      connecting to a MySQL database, $db_type is 'mysql'. Likewise, if
      connecting to an Oracle database, $db_type is 'ora'. See DBI documentation
      for a list of supported database types. Though most host servers support
      at least MySQL (DBD::mysql), database DBI packages must be individually
      installed. To find out if your database type is supported, contact your
      server administrator.

    $user

      REQUIRED / OPTIONAL

      This is the user name to use to log into the database. This field is
      required. However, occassionally anonymous database access is permitted
      using no user name. In such a case this variable may be left empty.

    $password

      REQUIRED / OPTIONAL

      This is the password to use to log into the database. This field is
      required. However, occassionally database access is granted to certain
      accounts without a password. In such a case this variable may be left
      empty.

    \%argument_hash

      OPTIONAL (see details)
      
      A reference to a hash containing a list of arguments to provide while
      connecting. These arguments could include, but are not limited to,
      host, port, and database name. See your database documentation, as well
      as the DBI documentation for your database type to determine which
      arguments you may use.
      
      Though this is listed as being optional, it is usually used to select at
      least the name of the database to log into. If no host is provided,
      'localhost' is assumed. If no port is provided the standard port for
      the given database service type is used.

    \%attribute_hash

      OPTIONAL
      
      A reference to a hash containing DBI connection attributes such as, but
      not limited to, RaiseError, PrintError, and AutoCommit. Applicable
      attributes are determined by the database type in use. See your database
      documentation as well as the DBI documentation for your database type
      to determine which attributes you may use.

  -------
  RETURNS
  -------

    A database handler object. This object stores the connection information and
    is to be used in all subsequent PTMDB database function calls. This object
    is of the same type as is returned by a DBI->connect function call.

  --------------
  USAGE EXAMPLES
  --------------

    ------------------------------------------------------------------------
    Example 1: Connecting to a MySQL Database Named 'MyDB' on the Local Host
    ------------------------------------------------------------------------

      <? $mysql = &db_connect('mysql', 'user', 'pass', {database => 'MyDB'}); ?>

    ----------------------------------------------------------------------------
    Example 2: Remote Host, Non-Standard Port, Errors Raised, Errors Printed
    ----------------------------------------------------------------------------

      <?
        $mysql = &db_connect(
                   'mysql',
                   'user',
                   'pass',
                   {
                     database => 'MyDB',
                     host =>     '192.168.1.100',
                     port =>     12345
                   },
                   {
                     RaiseError => 1,
                     PrintError => 1
                   }
                 );
      ?>

  --------
  SEE ALSO
  --------

    TAGS

      DO

    MODULES

      PTMDB

    FUNCTIONS

      PTMDB - db_select_database()