--------------------------------------------
PTMDB MODULE - db_get_table_stats() FUNCTION
--------------------------------------------

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

    Where @stats is a returned array of array references:

    @stats = &db_get_table_stats($db_object);
    @stats = &db_get_table_stats($db_object, $db_name);

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

    Retrieves table statistics from a given database. If a database has already
    been selected, the only required parameter is the database object. If a
    database has not been selected, or you wish to list tables from another
    database, a database name is required as well. Returns an array of array
    references, each containing table information.

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

    $db_name

      OPTIONAL / REQUIRED

      The name of the database from which to pull table statistics. This is only
      required if a database has not yet been selected using the
      db_select_database() function or an SQL 'USE' statement, or alternately if
      you wish to pull table stats from a different database than the one
      currently selected.

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

    An array of array references. Each array reference contains table
    information. This information can vary depending on database type.
    See your database documentation for the "SHOW TABLE STATUS" SQL query.
    MySQL, for example, returns table information in the following order:

      Table Name, Engine, Version, Row Format, Row Count,
      Avg Row Length (bytes), Data Length (bytes), Max Data Length (bytes),
      Index Length (bytes), Data Free, Auto-Increment, Creation Time,
      Update Time, Check Time, Collation, Checksum, Create Options, Comment

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

    MODULES

      PTMDB

    FUNCTIONS

      PTMDB - db_select_database()