#$Id: //depot/prod/DOT/dev/test/nate/lib/TCD/Err.pm#1 $

#
# Copyright (c) 2011 NetApp, Inc., All Rights Reserved.
#   Any use, modification, or distribution is prohibited
#   without prior written consent from NetApp, Inc.
#

package TCD::Err;

use strict;

###############################################################################
# Method:    errmsg
# Objective: Return the errmsg component from the object.
# Details:   See POD documentation at the end of this file.
#
# This method was copied from Error.pm
###############################################################################
sub errmsg {
    my $self = shift;
    unless (ref($self->{errmsg}) eq 'ARRAY') {
        return ('NO ERROR MESSAGE');
    }
    return (wantarray()) ? @{$self->{errmsg}} : join("\n", @{$self->{errmsg}});
}

###############################################################################
# Method:    error
# Objective: Return error status of the err object.
# Details:   See POD documentation at the end of this file.
#
# This method was copied from Error.pm
###############################################################################
sub error { shift->{error}; }

###############################################################################
# Method:    _clear_err
# Objective: Clear error components in the object.
# Details:   See POD documentation at the end of this file.
#
# This method was copied from Error.pm
###############################################################################
sub _clear_err {
    my $self = shift;
    $self->{error}  = 0;
    $self->{errmsg} = '';
    1;
}

###############################################################################
# Method:    _set_err
# Objective: Set error components in the object based on input errmsg.
# Details:   See POD documentation at the end of this file.
#
# This method was copied from Error.pm
###############################################################################
sub _set_err {
    my ($self, @tmp_errmsg) = @_;
    my (@errmsg, $parent_obj, $array_index);

    $self->{error} = 1;
    $array_index   = 0;

    # if there is no setting for disable caller string, then set it to 0
    if (not defined($self->{error_disable_caller_string})) {
        $self->{error_disable_caller_string} = 0;
    }

    if (not defined($self->{error_stack_style})) {
        $self->{error_stack_style} = 'normal';
    }

    foreach my $msg (@tmp_errmsg) {
        # only prepend with the first message in the array
        # indent the remaining messages in the array
        if ($array_index == 0 && $self->{error_disable_caller_string} == 0) {
            # prepend parent caller and line number of the error
            # - ERROR: San::ControllerCluster::Filer10M::Aggregate:: \
            #   create_vol_obj:104 - failed to instantiate volume object
            push @errmsg, 'ERROR: ' . _parent_caller() . '():' . _parent_lineno() . ' - ' . $msg;
        }
        else {
            # indent and append messsage.
            push @errmsg, ' ' . $msg;
        }
        $array_index++;
    }

    # if there is currently an error on the object, then dont overwrite it,
    # append to it so that an object can keep invoking set err to build an error stack
    if (defined($self->{errmsg})                      &&
        ref($self->{errmsg}) eq 'ARRAY'               &&
        scalar(@{$self->{errmsg}})                    &&
        defined($self->{error_dont_overwrite_errors}) &&
        $self->{error_dont_overwrite_errors} == 1) {
        # take the current errmsg array, and merge it with the error that is being pushed on
        my @err_array = @{$self->{errmsg}};
        if ($self->{error_stack_style} eq "reverse") {
            push(@err_array, @errmsg);
        }
        else {
            unshift(@err_array, @errmsg);
        }
        @errmsg = @err_array;
    }

    $self->{errmsg} = \@errmsg;

    return 1;
}

# format for the caller:
#  0         1          2      3            4
# ($package, $filename, $line, $subroutine, $hasargs,
#  5          6          7            8       9         10
# $wantarray, $evaltext, $is_require, $hints, $bitmask, $hinthash) = caller($i);
# $i is the caller depth
# _parent_caller returns the subroutine of caller of depth 2
sub _parent_caller { (caller(2))[3] }

# _parent_lineno returns the line number of caller of depth 1.
# this will return the line number within the above subroutine
sub _parent_lineno { (caller(1))[2] }


1;

__END__

=pod

=head1 Package Name

Err.pm

=head1 Description

Err.pm provides an API interface for performing basic error handling.  Use @ISA to
inherit these methods into another package. Use the private methods
_clear_err() and _set_err($error_msg) in your package to remove or set error messages.

=over 4

=item Examples

use vars qw( @EXPORT @ISA);

@ISA = qw(TCD::Err);

=back

=head1 Public Methods

=head2 B<errmsg()>

This method allows you to get the text of the error message if an error
occurred on the previous method call.

=over 4

=item Inputs

None

=item Outputs

Returns the text of the last error message set.  If no error message is
set, an empty string will be returned.

=item Examples

 # Check for errors.
 if ($myObj->error) {
    $errmsg = $myObj->errmsg;
    print "An error occurred: $errmsg\n";
 }

=back

=head2 B<error()>

This method allows you to determine if any errors occured in the
previous method call.  Note that the error flag is reset at the
beginning of each method, so it should be checked after B<every>
major method call.  If you do not check for errors, your calling
program may fail at some point and you will not know why.

=over 4

=item Inputs

None.

=item Outputs

Returns 1 if an error occured in the previous call, 0 otherwise.

=item Examples

 # Determine if error occurred...
 if ($myObj->error) {
    print "Error encountered in previous method call\n";
 }

=back

=head1 AUTHOR/MAINTAINER

=over

=item NATE Development (dl-nate-dev@netapp.com)

=back

 $Id: //depot/prod/DOT/dev/test/nate/lib/TCD/Err.pm#1 $
 Last revised $Date: 2016/04/12 $ by $Author: madhavs $

=cut