------------------------------------
PTMDB MODULE - db_get_row() FUNCTION
------------------------------------

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

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

    @row = &db_get_row($db_object, $table);
    @row = &db_get_row($db_object, $table, $column, $value);
    @row = &db_get_row($db_object, $table, $column, $value, $sort_column);
    @row = &db_get_row($db_object, $table, $column, $value, $sort_column,
                       $descending);
    @row = &db_get_row($db_object, $table, $column, $value, $sort_column,
                       $descending, $low_limit);

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

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

    $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 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 Second Row [1] From The Database Table 'MyTable'
    -----------------------------------------------------------------

      <?
          print(join(', ', &db_get_row($dbobj, 'MyTable', '', '', '', 0, 1)));
      ?>

  --------
  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_like()
      PTMDB - db_get_row_where()