-----------------------------------------------
PTMDB MODULE - db_get_row_hash_where() FUNCTION
-----------------------------------------------

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

    Where $row is a returned row hash reference:

    $row = &db_get_row_hash_where($db_object, $table);
    $row = &db_get_row_hash_where($db_object, $table, $where);
    $row = &db_get_row_hash_where($db_object, $table, $where, $sort_column);
    $row = &db_get_row_hash_where($db_object, $table, $where, $sort_column,
                                  $descending);
    $row = &db_get_row_hash_where($db_object, $table, $where, $sort_column,
                                  $descending, $low_limit);

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

    Based on db_get_row_hashes_where, Fetches a row from a given database table.
    If no $column/$value pair is set, "1" is put in its place in the SQL WHERE
    statement.
    Set $where to a full comparison string.
    Set $sort_column to a column name to sort the results by a given column's
    values.
    Set $descending to 1 if $sort_column is in use and you wish to sort in
    descending order.
    Set $low_limit (zero-based) to select which row, out of a known many, to
    return.
    Returns a hash reference containing one row from a given database table in
    column => value pairs. Within the hash reference is a key named "_keys"
    which contains the list of column headers in the order in which they were
    provided from the database table, and can be used to display columns in
    the proper order.

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

    $table

      REQUIRED

      The name of the table from which you would like to pull row information.

    $where

      OPTIONAL

      Any SQL "WHERE" statement to be used as part of the "SELECT" statement.
      e.g. "((`column1` = 'value1') AND (`column2` = 'value2'))"

    $sort_column

      OPTIONAL

      The name of a column to use for sorting. Automatically sorts in ascending
      order unless $descending is set.

    $descending

      OPTIONAL

      Set this value to 1 if $sort_column has been set and you wish to sort in
      decending order.

    $low_limit

      OPTIONAL

      The lower limit (zero-based) you would like to start reading from. This
      option may be left out entirely if you wish to start from the beginning
      of the returned rows.

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

    One row's hash reference. The hash reference contains one row's
    contents in column => value pair format. Within the hash reference is a 
    key named "_keys" which contains a reference to a list of column headers
    in the order in which they were provided from the database table, and
    can be used to display the columns in the proper order, as these column
    headers are used to name the hash keys.

    Sample Return Value, Internal Format:

      $row = {
        _keys => ['col1', 'col2', 'col3'],
        col1 => 'val1',
        col2 => 'val2',
        col3 => 'val3'
      };

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

    --------------------------------------------------
    Example 1:
      Print First Row with Column Names from 'MyTable'
      with a WHERE Statement
    --------------------------------------------------

      <?
        $row = &db_get_row_hash_where($dbobj, 'MyTable',
          "((`col1` = 'val1') AND (`col2` LIKE 'val2'))");
        foreach $col (@{$row->{_keys}}) {
          print("$col: " . $row->{$col} . "<br>\n");
        }
      ?>

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

    MODULES

      PTMDB

    FUNCTIONS

      PTMDB - db_connect()
      PTMDB - db_get_column_count()
      PTMDB - db_get_columns()
      PTMDB - db_get_row_count()
      PTMDB - db_get_rows()
      PTMDB - db_get_row_hashes_where()
      PTMDB - db_get_row_hash()
      PTMDB - db_get_row_hash_like()