-------------------------------------
PTMDB MODULE - db_get_rows() FUNCTION
-------------------------------------

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

    Where @rows is a returned array of array references:

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

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

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

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

      <?
        foreach $row (
          &db_get_rows($dbobj, 'MyTable', '', '', '', 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_like()
      PTMDB - db_get_rows_where()