BAT::Database - Database connection for BAT

Back to top ^

NAME

BAT::Database - Database connection for BAT

Back to top ^

SYNOPSIS

  require BAT::Database;
  my $dbh = $BAT::Database::dbh;

  # data retrieval

  $data = BAT::Database->anlaysis_unit_data_distinct(%params);
  $data = BAT::Database->anlaysis_unit_data_full(%params);
  $score = BAT::Database->max_score($session_id,$analysis_type);
  $record_count = BAT::Database->record_count($session_id);
  $score_count = BAT::Database->score_count($session_id,$analysis_type);
  $data = BAT::Database->score_summary($session_id,$analysis_type);
  $data = BAT::Database->select_menu_values($parent_value,$select_name);

  # session management

  $session_id = BAT::Database->new_session(%params);
  $data = BAT::Database->session_data($session_id);
  BAT::Database->delete_session($session_id);
  BAT::Database->expire_sessions($verbose);
  BAT::Database->extend_session($session_id,$check_existence);

  # heavy process management

  $registered = BAT::Database->register_heavy_process($description);
  BAT::Database->deregister_heavy_process();

  # data creation

  $record_count = BAT::Database->assign_analysis_units(%params);
  BAT::Database->insert(%record);

Back to top ^

DESCRIPTION

Uses connection parameters specified in BAT::Config and sets RaiseError, PrintError and FetchHashKeyName handle attributes.

Delegates database interaction procedures to their platform-specific modules. eg a call to BAT::Database->insert() will delegate to BAT::Oracle::insert::insert() if the $Database global in BAT::Config is set to Oracle.

Back to top ^

METHODS

analysis_unit_data_distinct()

  my $analysis_unit_data = BAT::Database->analysis_unit_data_distinct(
                             session_id => $session_id,
                             analysis_unit_id => $analysis_unit_id,
                             analysis_type => $analysis_type
                           );

Returns a hashref containing values for analysis_unit_id, score, north, south, east, and west. This summary information. The hashref also contains a key called observations, which contains an arrayref of distinct species (kingdom, phylum, class, order, family, genus, species, subspecies, scientific name) which occur in the given analysis_unit_id. The hashref is suitable for use in Template Toolkit templates.

analysis_unit_data_full()

  my $analysis_unit_data = BAT::Database->analysis_unit_data_distinct(
                             session_id       => $session_id,
                             analysis_unit_id => $analysis_unit_id,
                             analysis_type    => $analysis_type
                           );

Exactly like analysis_unit_data_distinct(), except that it's list of observations contains all observations for the given analysis_unit_id.

assign_analysis_units()

  my $number_of_observations_assigned =
    BAT::Database->assign_analysis_units(
      session_id     => $session_id,
      analysis_layer => 'NEWCALEDONIA_15_MINUTE_GRID',
      field_name     => 'Family',
      field_value    => 'Scarabaeidae',
      provider_url   => 'http://www.deh.gov.au:80/biodiversity/digir/www/DiGIR.php',
      resource_code  => 'dungbeetles'
    );

Assigns observation records from the specified resource to analysis units in the given analysis layer where the given field_name is equal to the given field_value. The latitude and longitude values for the observation record are compared to the north, south, east, west attributes in the analysis_layer.

delete_session()

  BAT::Database->delete_session($session_id);

Deletes a session and it's associated data and analysis results from the database, regardless of it's age.

deregister_heavy_process()

See register_heavy_process().

expire_sessions()

  BAT::Database->expire_sessions($verbose);

Deletes all data associated with sessions whose creation date is older than the $BAT::Config::Session_Timeout constant. If the optional $verbose parameter is provided with a true value, the deleted session ids will be printed to STDOUT.

extend_session()

  BAT::Database->extend_session($session_id,$check_existence);

Extends a BAT session by updating its creation time to the current time, preventing it from being deleted by the expire_sessions() method. If the optional $check_existence value is true, the existence of the session in the sessions table will be checked first and an exception thrown if the session doesn't exist.

insert()

  BAT::Database->insert(%record);

Inserts a record into the observations table.

max_score()

  my $max_score = BAT::Database->max_score($session_id,'Endemism');

Returns the maximum score for a given session and analysis type.

new_session()

  my $session_id = BAT::Database->new_session(%params);

Creates a new BAT session and stores it in the database. Further information available in BAT::Session

session_data()

  my $session_data = BAT::Database->session_data($session_id);

Returns session data as a hashref for a given session_id. Further information available in BAT::Session

record_count()

  my $record_count = BAT::Database->record_count($session_id);

Returns the number of observation records that are included in a given session. Will be zero unless it's run after assign_analysis_units().

register_heavy_process()

  if (BAT::Database->register_heavy_process('analyse')) {
    # it's safe to attempt a heavy process
    ...
    BAT::Database->deregister_heavy_process();
  }
  else {
    # report server load is too high for this kind of process
    ...
  }

Manages processes which may cause high load on the server by keeping count of how many heavy processes are currently running. If the number of current heavy processes exceeds the value of $BAT::Config::Heavy_Process_Max, then register_heavy_process() will return false. Will always return true if $BAT::Config::Heavy_Process_Max is set to zero. All processes that are successfully register should deregister themselves by calling deregister_heavy_process().

score_count()

  my $score_count = BAT::Database->score_count($session_id,'Endemism');

Returns the number of scores produced for a given session and analysis type. Used by the BAT::Map::Classify modules.

score_summary()

  my $score_summary = BAT::Database->score_summary($session_id,'Richness');

Returns an arrayref of distinct scores and the number of times they occur in a given analysis. Used by the BAT::Map::Classify modules.

select_menu_values()

  my $menu_values = BAT::Database->select_menu_values('Coleoptera','family');

Returns an arrayref of values for including in select elements. The first value is the value of the parent menu. The second value is the name of the menu for which values are selected. Valid menu names are data_source_id, grid_size, class, order, and family. No parent value is required for data_source_id.

Back to top ^

SEE ALSO

BAT::Config, BAT::Session, DBI

Back to top ^

AUTHOR

  Bryn Honeyman 2005

Back to top ^

 BAT::Database - Database connection for BAT