package RDA::Log;

# $Id: Log.pm,v 1.29 2009/02/03 15:49:58 mschenke Exp $
# ARCS: $Header: /u02/webapps/workbench/cvs/RDA_4/src/scripting/lib/RDA/Log.pm,v 1.29 2009/02/03 15:49:58 mschenke Exp $
#
# Change History
# 20090203  MSC  Introduce file modes.

=head1 NAME

RDA::Log - Class Used for Objects to Manage the Event Log

=head1 SYNOPSIS

require RDA::Log;

=head1 DESCRIPTION

The objects of the C<RDA::Log> class are used to manage the event log.

The following methods are available:

=cut

use strict;

BEGIN
{ use Exporter;
  use File::Spec;
  use IO::File;
}

# Define the global public variables
use vars qw($VERSION);
$VERSION = sprintf("%d.%02d", q$Revision: 1.29 $ =~ /(\d+)\.(\d+)/);

# Define the global private variables

# Report the module version number
sub Version
{ $VERSION;
}

=head2 S<$h = RDA::Log-E<gt>new($agt)>

The object constructor. It takes the agent reference as an argument.

C<RDA::Log> is represented by a blessed hash reference. The following
special keys are used:

=over 12

=item S<    B<'_afl'> > Autoflush indicator

=item S<    B<'_agt'> > Reference to the agent object

=item S<    B<'_beg'> > Start time

=item S<    B<'_mod'> > File mode hash

=item S<    B<'_nam'> > Setup file name

=item S<    B<'_ofh'> > Output file handle

=item S<    B<'_pth'> > Log file path

=item S<    B<'_ver'> > Software version

=back

Internal keys are prefixed by an underscore.

It also tries to open the event log file and to add a start event (type 'b').

=cut

sub new
{ my $slf = shift;
  my $cls = ref($slf) || $slf;
  my $agt = shift;
  my $pth;

  # Create the render object
  $slf = bless {}, $cls;

  # Get some setup information
  $slf->{'_agt'} = $agt;
  $slf->{'_beg'} = time;
  $slf->{'_mod'} = $agt->get_info('mod');
  $slf->{'_nam'} = $agt->get_info('nam');
  $slf->{'_ver'} = $agt->get_info('ver');

  # Return the object reference
  $slf;
}

=head2 S<$h-E<gt>end>

This method logs an end event (type 'e') including the execution duration,
and then closes the event log.

=cut

sub end
{ my ($slf) = @_;

  if (exists($slf->{'_ofh'}))
  { # Log the end record
    my $tim = time;
    $slf->_log($tim, 'e', $slf->{'_agt'}->get_setting('RDA_VERSION'),
      $tim - $slf->{'_beg'}, $slf->{'_agt'}->get_setting('RPT_GROUP', 'RDA'));

    # Close the event log file
    close($slf->{'_ofh'});
    delete($slf->{'_ofh'});
  }
}

=head2 S<$h-E<gt>init($dir[,$flg])>

This method initialises the log file in the specified directory. When the flag
is set, it also creates the report directory.

=cut

sub init
{ my ($slf, $dir, $flg) = @_;

  unless (exists($slf->{'_ofh'}))
  { my $pth;

    # Create the report directory when needed.
    if ($flg && $dir)
    { die "RDA-00200: Cannot create the report directory $dir:\n $!\n"
        unless -d $dir || mkdir($dir, 0750);
    }

    # Open the event log file and add the start event
    $slf->_init($dir) if $dir && -d $dir;
  }
}

sub _init
{ my ($slf, $dir) = @_;
  my ($agt, $ofh, $pth);

  # Open the event log file and add the start event
  $agt = $slf->{'_agt'};
  $ofh = IO::File->new;
  $pth = File::Spec->catfile($dir,
    $agt->get_setting('RDA_CASE') ? 'RDA.log' : 'rda.log');
  if ($ofh->open($pth, $slf->{'_mod'}->{'>>'}, 0640))
  { $ofh->autoflush(1)
      if ($slf->{'_afl'} = $agt->get_setting('RDA_FLUSH', 1));
    $slf->{'_ofh'} = $ofh;
    $slf->{'_pth'} = $pth;
    $slf->_log($slf->{'_beg'}, 'b', $slf->{'_ver'});
  }
}

=head2 S<$h-E<gt>log($typ[,$arg...])>

This method logs an event. It prefixes log records with a timestamp (GMT) and
the setup name. Fields are separated by a C<|> character.

=cut

sub log
{ my $slf = shift;
  my $typ = shift;

  $slf->_log(time, $typ, @_) if exists($slf->{'_ofh'}) && $typ;
}

sub _log
{ my $slf = shift;
  my @tbl = gmtime(shift);

  print {$slf->{'_ofh'}} join('|',
    sprintf("%04d%02d%02d_%02d%02d%02d",
      1900 + $tbl[5], 1 + $tbl[4], $tbl[3], $tbl[2], $tbl[1], $tbl[0]),
    $slf->{'_nam'},
    @_,
    "\n");
}

=head2 S<$h-E<gt>logfile>

This method returns the file handle that is associated with the event log.
Othewise, it returns C<undef> when not possible.

=cut

sub logfile
{ my $slf = shift;

  exists($slf->{'_ofh'}) ? $slf->{'_ofh'} : undef;
}

=head2 S<$h-E<gt>resume>

This method reopens the log file and restarts the event logging.

=cut

sub resume
{ my $slf = shift;
  my $ofh;

  if (exists($slf->{'_pth'}) && !exists($slf->{'_ofh'}))
  { $ofh = IO::File->new;
    if ($ofh->open($slf->{'_pth'}, $slf->{'_mod'}->{'>>'}, 0640))
    { $ofh->autoflush(1) if $slf->{'afl'};
      $slf->{'_ofh'} = $ofh;
    }
  }
}

=head2 S<$h-E<gt>suspend>

This method suspends event logging and closes the log file.

=cut

sub suspend
{ my $slf = shift;

  if (exists($slf->{'_ofh'}))
  { close($slf->{'_ofh'});
    delete($slf->{'_ofh'});
  }
}

1;

__END__

=head1 SEE ALSO

L<RDA::Agent|RDA::Agent>, L<RDA::Block|RDA::Block>,
L<RDA::Daemon|RDA::Daemon>, L<RDA::Discover|RDA::Discover>,
L<RDA::Extra|RDA::Extra>, L<RDA::Filter|RDA::Filter>,
L<RDA::Lock|RDA::Lock>, L<RDA::Module|RDA::Module>,
L<RDA::Output|RDA::Output>, L<RDA::Pod|RDA::Pod>,
L<RDA::Profile|RDA::Profile>, L<RDA::Remote|RDA::Remote>,
L<RDA::Render|RDA::Render>, L<RDA::Setting|RDA::Setting>,
L<RDA::Upgrade|RDA::Upgrade>, L<RDA::Value|RDA::Value>,
L<RDA::Web|RDA::Web>

=head1 COPYRIGHT NOTICE

Copyright (c) 2002-2009, Oracle. All rights reserved.

=head1 TRADEMARK NOTICE

Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle
Corporation and/or its affiliates. Other names may be trademarks of their
respective owners.

=cut