/ 
Pgreet-0.9.7
River stage zero No dependents
/ Pgreet::DaemonUtils

NAME

Pgreet::DaemonUtils - Penguin Greetings shared routines related to daemon

SYNOPSIS

# Constructor:
$Pg_daemon = new Pgreet::DaemonUtils($Pg_default_config, $Pg_error);

# Compute number of days since 1997 to "age" ecards
$DateCode = $Pg_daemon->GetDateCode();

# Back up any number of database files
$Pg_daemon->backup_db_files($db_file-1, $db_file-2, $db_file-3,
                            $db_file-4 ...
                           );

# Copy any number of database files from one location to another
$Pg_daemon->copy_db_files($src_path, $dst_path,
                          $db_file-1, $db_file-2, $db_file-3,
                          $db_file-4 ...
                          );

# Copy the database records (using Berkeley DB) from one path to another
$Pg_daemon->copy_db_records($db_file, $src_path, $dst_path);


# Purge database of ecard records older than $DateLimit
$Pg_daemon->purge_old_cards($path, $DateLimit, $card_name_file,
                            $name_passwd_file, $card_data_file
                            );

# Backup and purge old records in one step.
$Pg_daemon->backup_db_purge_old($path, $DateLimit, $card_name_file,
                                $name_passwd_file, $card_data_file
                               );

DESCRIPTION

The module Pgreet::DaemonUtils is the Penguin Greetings module for any routines that must be shared between the application daemon and command line utilities. This avoids unnecessary code duplication. All of these routines involve database manipulation at this time.

CONSTRUCTING A DAEMONUTILS OBJECT

The Pgreet::DaemonUtils constructor should be called after a Penguin Greeting configuration object Pgreet::Config and error object Pgreet::Error has been made. Since Pgreet::DaemonUtils does not use the configuration configuration information for some of it's routines, It is possible to pass it an undef in a command line utility that is its "configuration-free" routines. An example constructor call is below:

# Constructor:
$Pg_daemon = new Pgreet::DaemonUtils($Pg_default_config, $Pg_error);

DATABASE UTILITY METHODS

The object methods for manipulating Berkeley DB databases and related activities included in Pgreet::DaemonUtils are described below:

GetDateCode()

This is a utility method that computes the number of days since January 1, 1997 to provide some metric for determining how long an ecard has been in the ecard database. The DateCode is included in the information when a card is created. So subtracting the cards DateCode from today's DateCode provides the number of days the card has been in the database. This method is a simple function and returns the DateCode. A simple call is below:

# Compute number of days since 1997 to "age" ecards
$DateCode = $Pg_daemon->GetDateCode();
backup_db_files()

This method is a convenient tool to create copies of any number of files with the additional extension .bak. It is used to create backup files of the database files before manipulating them. It takes any number of file arguments as seen in the sample call below:

# Back up any number of database files
$Pg_daemon->backup_db_files($db_file-1, $db_file-2, $db_file-3,
                            $db_file-4 ...
                           );
copy_db_files()

This method copies files from one location path to another. It requires the source path and destination path as the first two arguments and then any number of filenames as the remaining arguments. A sample call is below:

# Copy any number of database files from one location to another
$Pg_daemon->copy_db_files($src_path, $dst_path,
                          $db_file-1, $db_file-2, $db_file-3,
                          $db_file-4 ...
                          );
copy_db_records()

This method uses the internal Berkeley DB routines (rather than File::Copy) to copy the database records of a Berkeley DB file from one path to a new file at another path. This process compacts the database in the copy file. It takes a single Berkeley DB file as its first argument and then needs the source and destination path as arguments 2 and 3. A sample call is below:

# Copy the database records (using Berkeley DB) from one path to another
$Pg_daemon->copy_db_records($db_file, $src_path, $dst_path);
purge_old_cards()

This method is specific to the task of removing old ecards who have been in the database for longer than the adminstrator would like. It requires 5 arguments: the path to the database files, the datelimit (in days) that a card should be kept in the database, and the three database files: $card_name_file, $name_passwd_file, and $card_data_file. This method uses the Berkeley DB routines to remove old records "in place," without making a copy of the database file. Since over time an ecards site should reach some "equilibrium" with new cards being added at roughly the rate that they expire, this should be a reasonable solution. A sample call is below:

# Purge database of ecard records older than $DateLimit
$Pg_daemon->purge_old_cards($path, $DateLimit, $card_name_file,
                            $name_passwd_file, $card_data_file
                            );
backup_db_purge_old()

This method is simply a combination of backup_db_files and purge_old_cards. It first makes a backup copy of every database file with backup_db_files and then it performs the purging of old ecards with purge_old_cards. The arguments are identical with purge_old_cards as can be seen in the sample call below.

# Backup and purge old records in one step.
$Pg_daemon->backup_db_purge_old($path, $DateLimit, $card_name_file,
                                $name_passwd_file, $card_data_file
                               );

This method exists mainly to standardize calling schemes between the application daemon and command line utilties.

COPYRIGHT

Copyright (c) 2004 Edouard Lagache

This software is released under the GNU General Public License, Version 2. For more information, see the COPYING file included with this software or visit: http://www.gnu.org/copyleft/gpl.html

BUGS

No known bugs at this time.

AUTHOR

Edouard Lagache <pgreetdev@canebas.org>

VERSION

0.9.7

SEE ALSO

syslog, Pgreet, Pgreet::Config, Pgreet::Error, Log::Dispatch, Log::Dispatch::File, Log::Dispatch::Syslog, CGI::Carp