-------------------------------------------
PTMDB MODULE - db_get_row_hashes() FUNCTION
-------------------------------------------

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

    Where @rows is a returned array of hash references:

    @rows = &db_get_row_hashes($db_object, $table);
    @rows = &db_get_row_hashes($db_object, $table, $column, $value);
    @rows = &db_get_row_hashes($db_object, $table, $column, $value,
                               $sort_column);
    @rows = &db_get_row_hashes($db_object, $table, $column, $value,
                               $sort_column, $descending);
    @rows = &db_get_row_hashes($db_object, $table, $column, $value,
                               $sort_column, $descending, $count);
    @rows = &db_get_row_hashes($db_object, $table, $column, $value,
                               $sort_column, $descending, $low_limit, $count);

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

    Based on db_get_rows(), fetches rows from a given database table.
    If no $column/$value pair is set, "1" is put in its place in the SQL WHERE
    statement.
    Set $column and $value to use a `column` = 'value' comparison.
    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 $count to retrieve [up to] a given amount of rows.
    Set $low_limit (zero-based) and $count to retrieve a particular range of rows.
    Returns an array of hash references, each of which contains a database table row in column => value pairs
    Within each 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.

    $column

      OPTIONAL

      The column name to use in a `column` = 'value' test comparison.

    $value

      OPTIONAL / REQUIRED

      Only required if $column is specified -- The value to use in a
      `column` = 'value' comparison.

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

    $count

      OPTIONAL

      The number of rows you wish to pull from the database. If no value is
      specified for $count all matched rows will be read.

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

    An array of hash references. Each hash reference contains one row's
    contents in column => value pair format. Within each 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:

      @rows = (
        {
          _keys => ['col1', 'col2', 'col3'],
          col1 => 'val1',
          col2 => 'val2',
          col3 => 'val3'
        },
        {
          _keys => ['col1', 'col2', 'col3'],
          col1 => 'val4',
          col2 => 'val5',
          col3 => 'val6'
        },
        {
          _keys => ['col1', 'col2', 'col3'],
          col1 => 'val7',
          col2 => 'val8',
          col3 => 'val9'
        }
      );

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

    --------------------------------------------------------------
    Example 1: Print First 5 Rows with Column Names from 'MyTable'
    --------------------------------------------------------------

      <?
        foreach $row (
          &db_get_row_hashes($dbobj, 'MyTable', '', '', '', 0, 5)
        ) {
          foreach $col (@{$row->{_keys}}) {
            print("$col: " . $row->{$col} . "<br>\n");
          }
          print("<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_like()
      PTMDB - db_get_row_hashes_where()