--------------------------------------------
PTMDB MODULE - db_select_database() FUNCTION
--------------------------------------------

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

    Where $ret is returned 1 or 0, depending on success or failure:
    
    $ret = &db_select_database($db_object, $db_name);

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

    Used to select a database for reading/writing. This is equivalent to SQL's
    'USE' statament. If no database was selected upon connection, this function
    must be used to select a database before any modifications can be made.

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

    $db_object

      REQUIRED

      A database handler object. This object stores connection information and
      is returned from a db_connect() function call. This object is of the same
      type as is returned by a DBI->connect function call.

    $db_name

      REQUIRED

      The name of the database to be selected for use. This can be any database
      to which the connected user has access rights.

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

    1 if database selection was successful
    0 (zero) if database selection was not successful.

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

    -------------------------------------------------------------------------
    Example 1: Selecting a Database Named "MyDB" with a MySQL Database Object
    -------------------------------------------------------------------------

      <? $ret = &db_select_database($mysql, 'MyDB'); ?>