-------------------------------------------
PTMDB MODULE - db_get_rows_where() FUNCTION
-------------------------------------------

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

    Where @rows is a returned array of array references:

    @rows = &db_get_rows_where($db_object, $table);
    @rows = &db_get_rows_where($db_object, $table, $where);
    @rows = &db_get_rows_where($db_object, $table, $where, $sort_column);
    @rows = &db_get_rows_where($db_object, $table, $where, $sort_column,
                               $descending);
    @rows = &db_get_rows_where($db_object, $table, $where, $sort_column,
                               $descending, $count);
    @rows = &db_get_rows_where($db_object, $table, $where, $sort_column,
                               $descending, $low_limit, $count);

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

    Fetches rows from a given database table.
    If no $where statement 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 $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 array references, each of which contains a database
    table row in list format.

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

    $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 array references. Each array reference contains one row's
    contents in list format in the order in which it was returned from the
    database. Use the db_get_columns() function to match with column headers.

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

    -------------------------------------------------------------------
    Example 1: Print First 5 Rows from 'MyTable' with a WHERE Statement
    -------------------------------------------------------------------

      <?
        foreach $row (
          &db_get_rows_where($dbobj, 'MyTable', 
                             "((`col1` = 'val1') AND (`col2` LIKE 'val2'))",
                             '', 0, 5)
        ) {
          print(join(', ', @{$row}) . "<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_rows_like()