------------------------------------------
PTMDB MODULE - db_get_row_where() FUNCTION
------------------------------------------

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

    Where @row is a returned row array (list format):

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

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

    Fetches a row 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 $low_limit (zero-based) to to select which row, out of a known many, to
    return.
    Returns an array containing 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 read from. This is the
      row number (zero based), out of the rows matched by your query, that you
      would like to retrieve.

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

    An array containing 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 Row From Database Table 'MyTable' with a WHERE Statement
    -------------------------------------------------------------------------

      <?
          print(join(', ', &db_get_row_where($dbobj, 'MyTable',
                     "((`col1` = 'val1') AND (`col2` LIKE 'val2'))")
                )
          );
      ?>

  --------
  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_row()
      PTMDB - db_get_row_like()