----------------------------------
PTMDB MODULE - db_query() FUNCTION
----------------------------------

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

    Where $rv is the query's return value:

    $rv = &db_query($db_object, $query);

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

    Prepares and executes an SQL query on the database.
    Returns the executed query's return value.

    For advanced SQL users, this function allows for the preparation and
    execution of any SQL query of the developer's choosing.

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

    $query

      REQUIRED

      A full, properly formatted SQL query to run on the given database
      connection.

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

    The return value from the execution of the SQL query.

  --------
  SEE ALSO
  --------

    MODULES

      PTMDB