Hardware::UPS::Perl::Driver::Megatec - package of methods for dealing with an

    use Hardware::UPS::Perl::Connection;
    use Hardware::UPS::Perl::Driver::Megatec;
    use Hardware::UPS::Perl::Logging;

    $logger     = Hardware::UPS::Perl::Logging->new();

    $connection = Hardware::UPS::Perl::Connection->new({
        Connection  =>  'serial',
        Options     =>  {
                            SerialPort  => '/dev/ttyS0',
                        },
        Logger      =>  $logger,
    });

    $ups  = Hardware::UPS::Perl::Driver::Megatec->new({
        Connection  =>  $connection,
        Logger      =>  $logger,
    });

    $ups->readUPSInfo();
    $ups->printUPSInfo();

    $ups->readStatus();
    $ups->printStatus();

    undef $ups;                        # disconnects

    http://www.cc-c.de/german/linux/linux_usv.php

    http://www.networkupstools.org

package Hardware::UPS::Perl::Driver::Megatec;

#==============================================================================
# package description:
#==============================================================================
# This package supplies a set of methods dealing with an UPS using the
# Megatec protocol. This might serve as a template for other UPS drivers. For
# a detailed description see the pod documentation included at the end of this
# file.
#
# List of public methods:
# -----------------------
#   new                     - initializing an UPS object
#   setDebugLevel           - setting the debug level
#   getDebugLevel           - getting the debug level
#   setLogger               - setting the current logger
#   getLogger               - getting the current logger
#   getErrorMessage         - getting the error message
#   connect                 - connecting to UPS
#   connected               - connection status to UPS
#   disconnect              - disconnecting from UPS
#   sendCommand             - sending a command to the UPS
#   flush                   - flushing any buffered input
#   readUPSInfo             - reading the UPS info
#   getManufacturer         - getting the manufacturer of the UPS
#   getModel                - getting the UPS model
#   getVersion              - getting the UPS firmware version
#   printUPSInfo            - printing the informations about the UPS
#   readRatingInfo          - reading the UPS rating info
#   getRatingVoltage        - getting the rating voltage
#   getRatingCurrent        - getting the rating current
#   getRatingBatteryVoltage - getting the rating battery voltage
#   getRatingFrequency      - getting the rating frequency
#   readStatus              - reading the UPS status
#   getInputVoltage         - getting the input voltage
#   getInputFaultVoltage    - getting the input fault voltage
#   getOutputVoltage        - getting the output voltage
#   getUPSLoad              - getting the UPS load
#   getInputFrequency       - getting the input frequency
#   getBatteryVoltage       - getting the battery voltage
#   getUPSTemperature       - getting the UPS temperature
#   getPowerStatus          - getting the power status
#   getBatteryStatus        - getting the battery status
#   getBypassStatus         - getting the bypass status
#   getFailedStatus         - getting the failed status
#   getStandbyStatus        - getting the standby status
#   getTestStatus           - getting the test status
#   getShutdownStatus       - getting the shutdown status
#   getBeeperStatus         - getting the beeper status
#   resetMinMax             - resetting minima and maxima
#   printMinMax             - getting minima and maxima
#   printData               - printing comparison between firmware and status
#   printStatus             - printing status flags
#   toggleBeeper            - toggles the beeper state
#   testUPS                 - testing the UPS
#   testUPSBatteryLow       - testing the UPS until battery low occurs
#   testUPSPeriod           - testing the UPS for a period of time in minutes
#   cancelTest              - cancel testing of the UPS
#   shutdownUPS             - shutdown of the UPS
#   shutdownRestore         - shutdown and restore of the UPS
#   cancelShutdown          - cancel shutdown of the UPS
#
#==============================================================================

#==============================================================================
# Copyright:
#==============================================================================
# Copyright (c) 2007 Christian Reile, <Christian.Reile@t-online.de>. All
# rights reserved. This program is free software; you can redistribute it
# and/or modify it under the same terms as Perl itself.
#==============================================================================

#==============================================================================
# Entries for Revision Control:
#==============================================================================
# Revision        : $Revision: 1.13 $
# Author          : $Author: creile $
# Last Modified On: $Date: 2007/04/17 19:43:42 $
# Status          : $State: Exp $
#------------------------------------------------------------------------------
# Modifications   :
#------------------------------------------------------------------------------
#
#   $Log: Megatec.pm,v $
#   Revision 1.13  2007/04/17 19:43:42  creile
#   documentation bugfixes.
#
#   Revision 1.12  2007/04/14 09:38:14  creile
#   documentation update.
#
#   Revision 1.11  2007/04/07 15:21:40  creile
#   Megatec protocol completed (test, shutdown and
#   shutdown/restore of UPS);
#   adaptations to "best practices" style;
#   update of documentation.
#
#   Revision 1.10  2007/03/13 17:15:14  creile
#   usage of Perl pragma constant for most of the package
#   variables;
#   options as anonymous hashes;
#   format directives revised;
#   reconnect fixed.
#
#   Revision 1.9  2007/03/03 21:26:10  creile
#   "return undef" replaced by "return";
#   adaptations to new Constants.pm;
#   formatted output of UPS information, status and data revised
#   using new logging method write();
#   method getMinMax() replaced by printMinMax().
#
#   Revision 1.8  2007/02/25 17:06:26  creile
#   connection as option now;
#   option handling redesigned.
#
#   Revision 1.7  2007/02/05 20:58:43  creile
#   initialization of logger in method() added;
#   pod documentation revised.
#
#   Revision 1.6  2007/02/04 18:57:51  creile
#   bug fix of pod documentation.
#
#   Revision 1.5  2007/02/04 14:11:03  creile
#   package renamed to Hardware::UPS::Perl::Driver::Megatec;
#   output of methods printData(), printStatus() and printUPSInfo()
#   revised;
#   logging support added;
#   update of documentation.
#
#   Revision 1.4  2007/01/28 21:08:24  creile
#   call of method flush() removed from method sendCommand() to avoid deep recursion error;
#   flush() is called now, if sendCommand() was unsuccessful.
#
#   Revision 1.3  2007/01/28 05:32:12  creile
#   renamed to Hardware::UPS::Perl::Megatec;
#   Exporter package removed;
#   network support added;
#   new methods setHost(), getHost(), setTCPPort(), getTCPPort()
#   added;
#   unnecessary comments removed;
#   update of pod documentation.
#
#   Revision 1.2  2007/01/21 15:04:06  creile
#   some beautifications.
#
#   Revision 1.1  2007/01/20 08:11:12  creile
#   initial revision
#
#
#==============================================================================

#==============================================================================
# module preamble:
#==============================================================================

use strict;

BEGIN {

    use vars qw($VERSION @ISA);

    $VERSION = sprintf( "%d.%02d", q$Revision: 1.13 $ =~ /(\d+)\.(\d+)/ );

    @ISA     = qw();

}

#==============================================================================
# end of module preamble
#==============================================================================

#==============================================================================
# packages required:
#------------------------------------------------------------------------------
#
#   Hardware::UPS::Perl::Connection - importing Hardware::UPS::Perl connection
#   Hardware::UPS::Perl::Constants  - importing Hardware::UPS::Perl constants
#   Hardware::UPS::Perl::Logging    - importing Hardware::UPS::Perl methods
#                                     dealing with logfiles
#   Hardware::UPS::Perl::Utils      - importing Hardware::UPS::Perl utility
#                                     functions for packages
#
#==============================================================================

use Hardware::UPS::Perl::Connection;
use Hardware::UPS::Perl::Constants qw(
    UPSSCRIPT
);
use Hardware::UPS::Perl::Logging;
use Hardware::UPS::Perl::Utils qw(
    error
);

#==============================================================================
# defining user invisible package constants and variables:
#------------------------------------------------------------------------------
# 
#   F_CMD_REPLY_SIZE                - the reply length for the F command
#   I_CMD_REPLY_SIZE                - the reply length for the I command
#   M_CMD_REPLY_SIZE                - the reply length for the M command
#   Q1_CMD_REPLY_SIZE               - the reply length for the Q1 command
#
#   INPUT_VOLTAGE_MINIMUM_INIT      - the initial minimum input voltage
#   INPUT_VOLTAGE_MAXIMUM_INIT      - the initial maximum input voltage 
#   INPUT_FREQUENCY_MINIMUM_INIT    - the initial minimum input frequency 
#   INPUT_FREQUENCY_MAXIMUM_INIT    - the initial maximum input frequency 
#
#   $PRINT_UPS_INFO                 - the string declaring the format of
#                                     writing the UPS info to the log file
#   $PRINT_DATA                     - the string declaring the format of
#                                     writing the UPS data to the log file
#   $PRINT_STATUS                   - the string declaring the format of
#                                     writing the UPS status to the log file
# 
#==============================================================================

use constant F_CMD_REPLY_SIZE               =>   21;
use constant I_CMD_REPLY_SIZE               =>   38;
use constant M_CMD_REPLY_SIZE               =>    1;
use constant Q1_CMD_REPLY_SIZE              =>   46;

use constant INPUT_VOLTAGE_MINIMUM_INIT     =>  240; 
use constant INPUT_VOLTAGE_MAXIMUM_INIT     =>  210; 
use constant INPUT_FREQUENCY_MINIMUM_INIT   =>   55; 
use constant INPUT_FREQUENCY_MAXIMUM_INIT   =>   45; 

my $PRINT_UPS_INFO               = <<EOF;
format PRINT_UPS_INFO =
=============================================
 UPS Information:
---------------------------------------------
    - UPS Manufacturer: @<<<<<<<<<<<<<<<<
\$manufacturer
    - UPS Model       : @<<<<<<<<<<<
\$model
    - UPS Version     : @<<<<<<<<<<<
\$version
=============================================
.
EOF

my $PRINT_DATA                   = <<EOF;
format PRINT_DATA =
=============================================
 UPS Data at date @<<<<<<<<<<<<<<<<<<<<<<<<
\$date
=============================================
+---------------------+---------------------+
| Nominal:            | Current:            |
+---------------------+---------------------+
|                     | Vin  =@###.# V      |
\$inputVoltage
+---------------------+---------------------+
| Vref =@###.# V      | Vout =@###.# V      |
\$ratingVoltage, \$outputVoltage
+---------------------+---------------------+
| IMax =@###.# A      | Load =@##### %      |
\$ratingCurrent, \$upsLoad
+---------------------+---------------------+
| Batt =@###.# V      | Batt =@###.# V      |
\$ratingBatteryVoltage, \$batteryVoltage
+---------------------+---------------------+
| Freq =@###.# Hz     | Freq =@###.# Hz     |
\$ratingFrequency, \$inputFrequency
+---------------------+---------------------+
|                     | Temp =@###.# °C     |
\$upsTemperature
+---------------------+---------------------+
=============================================
.
EOF

my $PRINT_STATUS                 = <<EOF;
format PRINT_STATUS =
=============================================
 UPS Status at date @<<<<<<<<<<<<<<<<<<<<<<<<
\$date
---------------------------------------------
    - Net:@<<<<V/@<<<Hz=@<<<<<<
\$inputVoltage, \$inputFrequency, \$powerStatus
    - Battery:@<<<V=@<<<
\$batteryVoltage, \$batteryStatus
    - Bypass=@<<<<<<
\$bypassStatus
    - UPS=@*, @*
\$failedStatus, \$standbyStatus
    - Test=@<<<<<<
\$testStatus
    - Shutdown=@<<<<<<
\$shutdownStatus
    - Beeper=@<<<
\$beeperStatus
=============================================
.
EOF

#==============================================================================
# public methods:
#==============================================================================

sub new {

    # public method to construct an UPS object
    #
    # parameters: $class   (input) - class
    #             $options (input) - anonymous hash; options
    #
    # The following option keys are recognized:
    #
    #   Connection  ($) - the connection; a Hardware::UPS::Perl::Conection
    #                     object;
    #   Logger      ($) - Hardware::UPS::Perl::Logging object; the logger to
    #                     use; optional

    # input as hidden local variables
    my $class   = shift;
    my $options = @_ ? shift : {};

    # hidden local variables
    my $self    = {};       # referent to be blessed
    my $option;             # an option
    my $optionRefType;      # the reference type of the option input
    my $logger;             # the logger object
    my $connection;         # the connection object

    # blessing UPS object
    bless $self, $class;

    # checking options
    $optionRefType = ref($options);
    if ($optionRefType ne 'HASH') {
        error("not a hash reference -- <$optionRefType>");
    }

    # the logger; if we don't have one, we have to create our own with output
    # on STDERR
    $logger = delete $options->{Logger};

    if (!defined $logger) {
        $logger = Hardware::UPS::Perl::Logging->new()
            or return;
    }

    # the connection
    $connection = delete $options->{Connection};

    # checking for misspelled options
    foreach $option (keys %{$options}) {
        error("option unknown -- $option");
    }

    # initializing
    $self->{ ups    }->{ manufacturer        } = q{};
    $self->{ ups    }->{ model               } = q{};
    $self->{ ups    }->{ version             } = q{};

    $self->{ rating }->{ voltage             } = 0;
    $self->{ rating }->{ current             } = 0;
    $self->{ rating }->{ battery_voltage     } = 0;
    $self->{ rating }->{ frequency           } = 0;

    $self->{ status }->{ input_voltage       } = 0;
    $self->{ status }->{ input_voltage_fault } = 0;
    $self->{ status }->{ output_voltage      } = 0;
    $self->{ status }->{ ups_load            } = 0;
    $self->{ status }->{ input_frequency     } = 0;
    $self->{ status }->{ battery_voltage     } = 0;
    $self->{ status }->{ ups_temperature     } = 0;
    $self->{ status }->{ power               } = 0;    # Bit7: Utility Fail (Immediate)
    $self->{ status }->{ battery_low         } = 0;    # Bit6: Battery Low
    $self->{ status }->{ bypass              } = 0;    # Bit5: Bypass/Boost or Buck Active
    $self->{ status }->{ failed              } = 0;    # Bit4: UPS Failed
    $self->{ status }->{ standby             } = 0;    # Bit3: UPS Type is Standby (0 is On_line)
    $self->{ status }->{ test                } = 0;    # Bit2: Test in progress
    $self->{ status }->{ shutdown            } = 0;    # Bit1: Shutdown active
    $self->{ status }->{ beeper              } = 0;    # Bit0: Beeper on

    $self->{ errorMessage                    } = q{};

    # the logger
    $self->setLogger($logger);

    # the connection
    $self->setConnection($connection);

    # initializing minima and maxima
    $self->resetMinMax();

    # initializing debug level 
    $self->setDebugLevel(0);

    # returning blessed UPS object
    return $self;

} # end of public method "new"

sub setDebugLevel {

    # public method to set the debug level, the higher, the better
    #
    # parameters: $self       (input) - referent to an UPS object
    #             $debugLevel (input) - the debug level

    # input as hidden local variables
    my $self       = shift;

    @_ == 1 or error("usage: setDebugLevel(debugLevel)");
    my $debugLevel = shift;

    # getting old debug level
    my $oldDebugLevel = $self->getDebugLevel();

    # setting debug level
    $self->{debugLevel} = $debugLevel;

    # promoting it to connection
    my $connection = $self->getConnection();
    if (defined $connection) {
        $connection->getConnectionHandle()->setDebugLevel($debugLevel);
        $self->{connection} = $connection;
    }

    # returning old debug level
    return $oldDebugLevel;

} # end of public method "setDebugLevel"

sub getDebugLevel {

    # public method to get the current debug level
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting debug level
    if (exists $self->{debugLevel}) {
        return $self->{debugLevel};
    }
    else {
        return;
    }

} # end of public method "getDebugLevel"

sub setConnection {

    # public method to set the connection
    #
    # parameters: $self       (input) - referent to an UPS object
    #             $connection (input) - the connection object

    # input as hidden local variables
    my $self       = shift;

    1 == @_ or error("usage: setConnection(CONNECTION)");
    my $connection = shift;

    if (defined $connection) {
        my $connectionRefType = ref($connection);
        if ($connectionRefType ne 'Hardware::UPS::Perl::Connection') {
            error("no connection -- <$connectionRefType>");
        }
    }

    # getting old connection
    my $oldConnection = $self->getConnection();

    # setting connection
    $self->{connection} = $connection;

    # returning old connection
    return $oldConnection;

} # end of public method "setConnection"

sub getConnection {

    # public method to get the current connection
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting connection
    if (exists $self->{connection}) {
        return $self->{connection};
    }
    else {
        return;
    }

} # end of public method "getConnection"

sub setLogger {

    # public method to set the logger
    #
    # parameters: $self   (input) - referent to an UPS object
    #             $logger (input) - the logging object

    # input as hidden local variables
    my $self   = shift;

    1 == @_ or error("usage: setLogger(LOGGER)");
    my $logger = shift;

    if (defined $logger) {
        my $loggerRefType = ref($logger);
        if ($loggerRefType ne 'Hardware::UPS::Perl::Logging') {
            error("no logger -- <$loggerRefType>");
        }
    }

    # getting old logger
    my $oldLogger = $self->getLogger();

    # setting logger
    $self->{logger} = $logger;

    # returning old logger
    return $oldLogger;

} # end of public method "setLogger"

sub getLogger {

    # public method to get the current logger
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting debug level
    if (exists $self->{logger} ) {
        return $self->{logger};
    }
    else {
        return;
    }

} # end of public method "getLogger"

sub getErrorMessage {

    # public method to get the current error message
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting debug level
    if (exists $self->{errorMessage}) {
        return $self->{errorMessage};
    }
    else {
        return;
    }

} # end of public method "getErrorMessage"

sub connect {

    # public method to connect to an UPS agent or the serial port an UPS
    # resides
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # checking connection type
    my $connection = $self->getConnection();
    if (defined $connection and !$connection->connect(@_)) {
        $self->{errorMessage}
            = "connection failed -- ".$connection->getErrorMessage();
        return 0;
    }
    else {
        $self->{errorMessage} = "connection unavailable";
        return 0;
    }

    # flushing any buffered input
    $self->flush();

    return 1;

} # end of public method "connect"

sub connected {

    # public method to test the connection status
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # checking for connection
    my $connection = $self->getConnection();
    if (defined $connection) {
        return $connection->connected();
    }
    else {
        return 0;
    }

} # end of public method "connected"

sub disconnect {

    # public method to disconnect from an UPS agent or the serial
    # port a local UPS resides
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # deleting connection if connected
    if ($self->connected()) {

        # deleting connection
        $self->{connection}->disconnect();

        return 1;

    } else {

        # error: UPS was not connected
        $self->{errorMessage} = "not connected to UPS";

        return 0;
    }

} # end of public method "disconnect"

sub sendCommand {

    # public method to send a command to the UPS and getting its response
    #
    # parameters: $self         (input) - referent to an UPS object
    #             $command      (input) - command sent to UPS
    #             $response     (input) - response from UPS (anonymous reference)
    #             $responseSize (input) - size of response from UPS

    # input as hidden local variable
    my $self         = shift;
    my $command      = shift;
    my $response     = shift;
    my $responseSize = shift;

    # hidden local variables
    my $connection;         # the connection

    # getting connection
    $connection = $self->getConnection();
    if (! defined $connection) {
        $self->{errorMessage} = "no connection available";
        return 0;
    }

    # send message to UPS
    if (!$connection->sendCommand($command, $response, $responseSize)) {
        $self->{errorMessage} = $connection->getErrorMessage();
        return 0
    }

    # checking for command being successfull
    # If the UPS receives any command that it could not handle, the UPS should
    # echo the received command back to the computer. The host should check if
    # the command sent to UPS been echo or not.
    if ($command eq $$response) {
        $self->{errorMessage} = "command $command unknown to UPS";
        return 0;
    }
    else {
        if ($$response or ($responseSize == 0)) {
            return 1;
        }
        else {
            $self->{errorMessage} = "no response to command $command";
            return 0;
        }
    }

} # end of public method "sendCommand"

sub flush {

    # public method to flush any buffered input at the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # flushing UPS communication
    return $self->sendCommand(q{M}, \$response, M_CMD_REPLY_SIZE);

} # end of public method "flush"

sub readUPSInfo {

    # public method to read the UPS info about the manufacturer, model and
    # firmware version
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # getting UPS rating info
    if ($self->sendCommand(q{I}, \$response, I_CMD_REPLY_SIZE)) {

        $response =~ /\#(...............) (..........) (..........)/;

        $self->{ ups }->{ manufacturer } = $1;
        $self->{ ups }->{ model        } = $2;
        $self->{ ups }->{ version      } = $3;

        return 1;

    }
    else {

        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "readUPSInfo"

sub getManufacturer {

    # public method to get the UPS manufacturer
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting the UPS manufacturer
    if (exists $self->{ ups }->{ manufacturer }) {
        return $self->{ ups }->{ manufacturer };
    }
    else {
        return;
    }

} # end of public method "getManufacturer"

sub getModel {

    # public method to get the UPS model
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting UPS model
    if (exists $self->{ ups }->{ model }) {
        return $self->{ ups }->{ model };
    }
    else {
        return;
    }

} # end of public method "getModel"

sub getVersion {

    # public method to get the UPS firmware version
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting UPS firmware version
    if (exists $self->{ ups }->{ version }) {
        return $self->{ ups }->{ version };
    }
    else {
        return;
    }

} # end of public method "getVersion"

sub printUPSInfo {

    # public method to print the UPS informations (manufacturer, model and
    # firmware version) to logger
    #
    # parameters: $self (input) - referent to an UPS object
    #             $type (input) - output type

    # input as hidden local variables
    my $self = shift;
    my $type = @_ ? shift : "none";

    # hidden local variables
    my $manufacturer;       # the manufacturer
    my $model;              # the model
    my $version;            # the firmware version

    my $logger;             # the logger
    my $return;             # the logger's return value

    # getting status flags
    $manufacturer
        = $self->{ ups }->{ manufacturer } ? $self->{ ups }->{ manufacturer }
        :                                    "unknown"
        ;
    $model
        = $self->{ ups }->{ model        } ? $self->{ ups }->{ model        }
        :                                    "unknown"
        ;
    $version
        = $self->{ ups }->{ version      } ? $self->{ ups }->{ version      }
        :                                    "unknown"
        ;

    # printing UPS information
    $logger = $self->getLogger();
    $return = $logger->write({
        Format      =>  $PRINT_UPS_INFO,
        Type        =>  $type,
        Arguments   =>  {
                            manufacturer    => $manufacturer,
                            model           => $model,
                            version         => $version,
                        },
    });

    if (!$return) {
        $self->{errorMessage} = $logger->getErrorMessage();
    }

    return $return

} # end of public method "printUPSInfo"

sub readRatingInfo {

    # public method to read the UPS rating info (firmware data)
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # getting UPS rating info
    if ($self->sendCommand(q{F}, \$response, F_CMD_REPLY_SIZE)) {

        $response =~ /\#(.....) ..(.) (.....) (....)/;

        $self->{ rating }->{ voltage         } = $1;
        $self->{ rating }->{ current         } = $2;
        $self->{ rating }->{ battery_voltage } = $3;
        $self->{ rating }->{ frequency       } = $4;

        return 1;

    } else {

        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "readRatingInfo"

sub getRatingVoltage {

    # public method to get the rating voltage of the UPS (firmware)
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting rating voltage
    if (exists $self->{ rating }->{ voltage }) {
        return $self->{ rating }->{ voltage };
    }
    else {
        return;
    }

} # end of public method "getRatingVoltage"

sub getRatingCurrent {

    # public method to get the rating current of the UPS (firmware)
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting rating voltage
    if (exists $self->{ rating }->{ current }) {
        return $self->{ rating }->{ current };
    }
    else {
        return;
    }

} # end of public method "getRatingCurrent"

sub getRatingBatteryVoltage {

    # public method to get the rating battery voltage of the UPS (firmware)
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting rating battery voltage
    if (exists $self->{ rating }->{ battery_voltage }) {
        return $self->{ rating }->{ battery_voltage };
    }
    else {
        return;
    }

} # end of public method "getRatingBatteryVoltage"

sub getRatingFrequency {

    # public method to get the rating frequency of the UPS (firmware)
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting rating frequency
    if (exists $self->{ rating }->{ frequency }) {
        return $self->{ rating }->{ frequency };
    }
    else {
        return;
    }

} # end of public method "getRatingFrequency"

sub readStatus {

    # public method to read the current UPS status
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # getting UPS status
    if ($self->sendCommand(q{Q1}, \$response, Q1_CMD_REPLY_SIZE)) {
    
        $response =~ /\((.....) (.....) (.....) (...) (....) (....) (....) (.)(.)(.)(.)(.)(.)(.)(.)/;

        $self->{ status }->{ input_voltage       } = $1;
        $self->{ status }->{ input_voltage_fault } = $2;
        $self->{ status }->{ output_voltage      } = $3;
        $self->{ status }->{ ups_load            } = $4;
        $self->{ status }->{ input_frequency     } = $5;
        $self->{ status }->{ battery_voltage     } = $6;
        $self->{ status }->{ ups_temperature     } = $7;
        $self->{ status }->{ power               } = $8;     # Bit7: Utility Fail (Immediate)
        $self->{ status }->{ battery_low         } = $9;     # Bit6: Battery Low
        $self->{ status }->{ bypass              } = $10;    # Bit5: Bypass/Boost or Buck Active
        $self->{ status }->{ failed              } = $11;    # Bit4: UPS Failed
        $self->{ status }->{ standby             } = $12;    # Bit3: UPS Type is Standby (0 is On_line)
        $self->{ status }->{ test                } = $13;    # Bit2: Test in progress
        $self->{ status }->{ shutdown            } = $14;    # Bit1: Shutdown active
        $self->{ status }->{ beeper              } = $15;    # Bit0: Beeper on

        # setting minima and maxima
        if ($self->{ status }->{ input_voltage_maximum } < $1) {
            $self->{ status }->{ input_voltage_maximum } = $1;
        }
        if ($self->{ status }->{ input_voltage_minimum } > $1) {
            $self->{ status }->{ input_voltage_minimum } = $1;
        }

        if ($self->{ status }->{ frequency_maximum     } < $5) {
            $self->{ status }->{ frequency_maximum     } = $5;
        }
        if ($self->{ status }->{ frequency_minimum     } > $5) {
            $self->{ status }->{ frequency_minimum     } = $5;
        }

        return 1;

    }
    else {

        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "readStatus"

sub getInputVoltage {

    # public method to get the current input voltage of the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting the input voltage
    if (exists $self->{ status }->{ input_voltage }) {
        return $self->{ status }->{ input_voltage };
    }
    else {
        return;
    }

} # end of public method "getInputVoltage"

sub getInputFaultVoltage {

    # public method to get the current input fault voltage of the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting the input fault voltage
    if (exists $self->{ status }->{ input_voltage_fault }) {
        return $self->{ status }->{ input_voltage_fault };
    }
    else {
        return;
    }

} # end of public method "getInputFaultVoltage"

sub getOutputVoltage {

    # public method to get the current power status of the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting output voltage
    if (exists $self->{ status }->{ output_voltage }) {
        return $self->{ status }->{ output_voltage };
    }
    else {
        return;
    }

} # end of public method "getOutputVoltage"

sub getUPSLoad {

    # public method to get the current UPS load
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting UPS load
    if (exists $self->{ status }->{ ups_load }) {
        return $self->{ status }->{ ups_load };
    }
    else {
        return;
    }

} # end of public method "getUPSLoad"

sub getInputFrequency {

    # public method to get the current input frequency of the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting the input frequency
    if (exists $self->{ status }->{ input_frequency }) {
        return $self->{ status }->{ input_frequency };
    }
    else {
        return;
    }

} # end of public method "getInputFrequency"

sub getBatteryVoltage {

    # public method to get the current battery voltage
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting the current battery voltage
    if (exists $self->{ status }->{ battery_voltage } ) {
        return $self->{ status }->{ battery_voltage };
    }
    else {
        return;
    }

} # end of public method "getBatteryVoltage"

sub getUPSTemperature {

    # public method to get the current UPS temperature
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting the UPS temperature
    if (exists $self->{ status }->{ ups_temperature } ) {
        return $self->{ status }->{ ups_temperature };
    }
    else {
        return;
    }

} # end of public method "getUPSTemperature"

sub getPowerStatus {

    # public method to get the current power status of the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting power status
    if (exists $self->{ status }->{ power }) {
        return $self->{ status }->{ power };
    }
    else {
        return;
    }

} # end of public method "getPowerStatus"

sub getBatteryStatus {

    # public method to get the current battery status of the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting battery status
    if (exists $self->{ status }->{ battery_low } ) {
        return $self->{ status }->{ battery_low };
    }
    else {
        return;
    }

} # end of public method "getBatteryStatus"

sub getBypassStatus {

    # public method to get the current bypass status of the UPS, i.e. whether
    # bypass/boost or buck is active
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting bypass status
    if (exists $self->{ status }->{ bypass } ) {
        return $self->{ status }->{ bypass };
    }
    else {
        return;
    }

} # end of public method "getBypassStatus"

sub getFailedStatus {

    # public method to get the current failed status of the UPS, i.e. UPS
    # failed
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting failed status
    if (exists $self->{ status }->{ failed } ) {
        return $self->{ status }->{ failed };
    }
    else {
        return;
    }

} # end of public method "getFailedStatus"

sub getStandbyStatus {

    # public method to get the current standby status of the UPS, i.e. whether
    # the UPS is standby (1) or online (0)
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting standby status
    if (exists $self->{ status }->{ standby }) {
        return $self->{ status }->{ standby };
    }
    else {
        return;
    }

} # end of public method "getStandbyStatus"

sub getTestStatus {

    # public method to get the current test status of the UPS, i.e. whether
    # a test of the UPS is in progress
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting test status
    if (exists $self->{ status }->{ test }) {
        return $self->{ status }->{ test };
    }
    else {
        return;
    }

} # end of public method "getTestStatus"

sub getShutdownStatus {

    # public method to get the current shutdown status of the UPS, i.e.
    # whether a shutdown is active or not
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting shutdown status
    if (exists $self->{ status }->{ shutdown }) {
        return $self->{ status }->{ shutdown };
    }
    else {
        return;
    }

} # end of public method "getShutdownStatus"

sub getBeeperStatus {

    # public method to get the current beeper status of the UPS, i.e. whether
    # the beeper is on or not
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # getting beeper status
    if (exists $self->{ status }->{ beeper }) {
        return $self->{ status }->{ beeper };
    }
    else {
        return;
    }

} # end of public method "getBeeperStatus"

sub resetMinMax {

    # public method to reset the minima and maxima of the input voltage
    # and frequency
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # resetting minima and maxima
    $self->{ status }->{ input_voltage_minimum } = INPUT_VOLTAGE_MINIMUM_INIT;
    $self->{ status }->{ input_voltage_maximum } = INPUT_VOLTAGE_MAXIMUM_INIT;

    $self->{ status }->{ frequency_minimum     } = INPUT_FREQUENCY_MINIMUM_INIT;
    $self->{ status }->{ frequency_maximum     } = INPUT_FREQUENCY_MAXIMUM_INIT;

    return;

} # end of public method "resetMinMax"

sub printMinMax {

    # public method to print the minima and maxima of the input voltage
    # and frequency
    #
    # parameters: $self  (input) - referent to an UPS object
    #             $level (input) - the logging level

    # input as hidden local variable
    my $self  = shift;
    my $level = @_ ? shift : "syslog";

    # hidden local variables
    my $message;            # message
    my %levelTable;         # the level table
    my $logger;             # the logger
    my $return;             # the logger's return value

    # getting the logger
    $logger = $self->getLogger();

    # printing minima and maxima
    $message  = "Line max=".$self->{ status }->{ input_voltage_maximum };
    $message .= "V/"       .$self->{ status }->{ frequency_maximum     };
    $message .= "Hz - min=".$self->{ status }->{ input_voltage_minimum };
    $message .= "V/"       .$self->{ status }->{ frequency_minimum     };
    $message .= "Hz"; 

    %levelTable = (
        debug   =>  sub { return $logger->debug ($message); },
        info    =>  sub { return $logger->info  ($message); },
        error   =>  sub { return $logger->error ($message); },
        fatal   =>  sub { return $logger->fatal ($message); },
        syslog  =>  sub { return $logger->syslog($message); },
    );

    if (exists $levelTable{$level}) {
            $return = $levelTable{$level}->();
    }
    else {
        error("unknown printing level -- $level");
    }

    if (!$return) {
        $self->{errorMessage} = $logger->getErrorMessage();
    }
                            
    return $return;

} # end of public method "printMinMax"

sub printData {

    # public method to print the comparison between the rating info (firmware
    # data) and the current data of the UPS to a logger
    #
    # parameters: $self (input) - referent to an UPS object
    #             $type (input) - output type

    # input as hidden local variables
    my $self = shift;
    my $type = @_ ? shift : "none";

    # hidden local variables
    my $logger;             # the logger
    my $return;             # the logger's return value

    # printing UPS data
    $logger = $self->getLogger();
    $return = $logger->write({
        Format      =>  $PRINT_DATA,
        Type        =>  $type,
        Arguments   =>
            {
                date                    => scalar localtime,
                inputVoltage            => $self->{ status }->{ input_voltage   },
                ratingVoltage           => $self->{ rating }->{ voltage         },
                outputVoltage           => $self->{ status }->{ output_voltage  },
                ratingCurrent           => $self->{ rating }->{ current         },
                upsLoad                 => $self->{ status }->{ ups_load        },
                ratingBatteryVoltage    => $self->{ rating }->{ battery_voltage },
                batteryVoltage          => $self->{ status }->{ battery_voltage },
                ratingFrequency         => $self->{ rating }->{ frequency       },
                inputFrequency          => $self->{ status }->{ input_frequency },
                upsTemperature          => $self->{ status }->{ ups_temperature },
            },
    });

    if (!$return) {
        $self->{errorMessage} = $logger->getErrorMessage();
    }

    return $return

} # end of public method "printData"

sub printStatus {

    # public method to print the status flags in a human readable format to
    # a logger
    #
    # parameters: $self (input) - referent to an UPS object
    #             $type (input) - output type

    # input as hidden local variables
    my $self = shift;
    my $type = @_ ? shift : "none";

    # hidden local variables
    my $powerStatus;                # the power status (FAILED/OK)
    my $batteryStatus;              # the battery status (LOW/OK)
    my $bypassStatus;               # the bypass status (ON/OFF)
    my $failedStatus;               # the failed status (FAILED/OK)
    my $standbyStatus;              # the standby status (Online/OFF)
    my $testStatus;                 # the test status (ON/OFF)
    my $shutdownStatus;             # the shutdown status (ON/OFF)
    my $beeperStatus;               # the beeper status (ON/OFF)

    my $logger;                     # the logger
    my $return;                     # the logger's return value

    # getting status flags
    $powerStatus    = $self->{ status }->{ power       } ? "FAILED" : "OK";
    $batteryStatus  = $self->{ status }->{ battery_low } ? "LOW"    : "OK";
    $bypassStatus   = $self->{ status }->{ bypass      } ? "ON"     : "OFF";
    $failedStatus   = $self->{ status }->{ failed      } ? "FAILED" : "OK";
    $standbyStatus  = $self->{ status }->{ standby     } ? "ONLINE" : "OFF";
    $testStatus     = $self->{ status }->{ test        } ? "ON"     : "OFF";
    $shutdownStatus = $self->{ status }->{ shutdown    } ? "ON"     : "OFF";
    $beeperStatus   = $self->{ status }->{ beeper      } ? "ON"     : "OFF";

    # printing UPS status
    $logger = $self->getLogger();

    $return = $logger->write({
        Format      =>  $PRINT_STATUS,
        Type        =>  $type,
        Arguments   =>  {
                            date            => scalar localtime,
                            inputVoltage    => $self->{ status }->{ input_voltage   },
                            inputFrequency  => $self->{ status }->{ input_frequency },
                            powerStatus     => $powerStatus,
                            batteryVoltage  => $self->{ status }->{ battery_voltage },
                            batteryStatus   => $batteryStatus,
                            bypassStatus    => $bypassStatus,
                            failedStatus    => $failedStatus,
                            standbyStatus   => $standbyStatus,
                            testStatus      => $testStatus,
                            shutdownStatus  => $shutdownStatus,
                            beeperStatus    => $beeperStatus,
                        },
    });

    if (!$return) {
        $self->{errorMessage} = $logger->getErrorMessage();
    }

    return $return

} # end of public method "printStatus"

sub toggleBeeper {

    # public method to toggle the beeper state from ON to OFF and vice versa
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # toggle beeper
    if ($self->sendCommand(q{Q}, \$response, 0)) {

        # success
        $self->flush();
        return 1;

    }
    else {

        # error, so clearing UPS buffer
        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "toggleBeeper"

sub testUPS {

    # public method to test the UPS for 10 seconds
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # test UPS
    if ($self->sendCommand(q{T}, \$response, 0)) {

        # success
        $self->flush();
        return 1;

    }
    else {

        # error, so clearing UPS buffer
        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "testUPS"

sub testUPSBatteryLow {

    # public method to test the UPS until the battery low occurs
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # test UPS
    if ($self->sendCommand(q{TL}, \$response, 0)) {

        # success
        $self->flush();
        return 1;

    }
    else {

        # error, so clearing UPS buffer
        $self->flush();
        
        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "testUPSBatteryLow"

sub testUPSPeriod {

    # public method to test the UPS for a certain period of time in minutes
    #
    # parameters: $self   (input) - referent to an UPS object
    #             $period (input) - the period of time to test the UPS in
    #                               minutes

    # input as hidden local variables
    my $self   = shift;
    my $period = @_ ? shift : undef;

    # hidden local variables
    my $response = q{};     # response from the UPS
    my $command;            # command to the UPS

    # checking period
    if (defined $period) {

        # period is not a number
        if ($period !~ m{\A \d+ \z}xms) {
            $self->{errorMessage}
                = "invalid period to test the UPS -- $period";
            return 0;
        }

        # period is out of range
        if (0 >= $period or $period > 99) {
            $self->{errorMessage}
                = "period to test the UPS out of range -- $period";
            return 0;
        }

        # the command
        $command = q{T} . sprintf( "%02d" , $period );

    }
    else {

        # period is undefined
        $self->{errorMessage} = "period to test the UPS undefined";
        return 0;

    }

    # testing UPS
    if ($self->sendCommand($command, \$response, 0)) {

        # success
        $self->flush();
        return 1;

    }
    else {

        # error, so clearing UPS buffer
        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "testUPSPeriod"

sub cancelTest {

    # public method to cancel a running test of the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # test UPS
    if ($self->sendCommand(q{CT}, \$response, 0)) {

        # success
        $self->flush();
        return 1;

    } else {

        # error, so clearing UPS buffer
        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "cancelTest"

sub shutdownUPS {

    # public method to shutdown the UPS in a certain period of time in minutes
    #
    # parameters: $self (input) - referent to an UPS object
    #             $time (input) - the time left in minutes, until the UPS will
    #                             be shutdown

    # input as hidden local variables
    my $self = shift;
    my $time = @_ ? shift : undef;

    # hidden local variables
    my $response = q{};     # response from the UPS
    my $command;            # command to the UPS

    # checking time
    if (defined $time) {

        # time is not a number
        if ($time !~ m{\A \d?\.?\d+ \z}xms ) {
            $self->{errorMessage}
                = "invalid time left to shutdown the UPS -- $time";
            return 0;
        }

        # time is out of range
        if (0 >= $time or $time > 10) {
            $self->{errorMessage}
                = "time left to shutdown the UPS out of range -- $time";
            return 0;
        }

        # the command
        if ($time < 1) {
            $command = q{S} . sprintf( "%.2f" , $time );
        }
        else {
            $command = q{S} . sprintf( "%02d" , $time );
        }

    } else {

        $self->{errorMessage} = "time left to shutdown the UPS undefined";
        return 0;

    }

    # shutdown of UPS
    if ($self->sendCommand($command, \$response, 0)) {

        # success
        $self->flush();
        return 1;

    }
    else {

        # error, so clearing UPS buffer
        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "shutdownUPS"

sub shutdownRestore {

    # public method to shutdown the UPS after a certain period of time in
    # minutes and turn it on again after another period of time in minutes
    #
    # parameters: $self           (input) - referent to an UPS object
    #             $shutdownPeriod (input) - the period of time in minutes,
    #                                       until the UPS will be shutdown
    #             $restorePeriod  (input) - the period of time in minutes,
    #                                       until the UPS will be restored
    #                                       again

    # input as hidden local variables
    my $self           = shift;
    my $shutdownPeriod = @_ ? shift : undef;
    my $restorePeriod  = @_ ? shift : undef;

    # hidden local variables
    my $response = q{};     # response from the UPS
    my $command;            # command to the UPS

    # checking shutdown period
    if (defined $shutdownPeriod) {

        # shutdown period is not a decimal number
        if ($shutdownPeriod !~ m{\A \d?\.?\d+ \z}xms ) {
            $self->{errorMessage}
                = "invalid time left to shutdown the UPS -- $shutdownPeriod";
            return 0;
        }

        # shutdown period is out of range
        if (0 >= $shutdownPeriod or $shutdownPeriod > 10) {
            $self->{errorMessage}
                = "time left to shutdown the UPS out of range -- $shutdownPeriod";
            return 0;
        }

        # the command
        if ($shutdownPeriod < 1) {
            $command = q{S} . sprintf( "%.2f" , $shutdownPeriod );
        }
        else {
            $command = q{S} . sprintf( "%02d" , $shutdownPeriod );
        }

    }
    else {

        $self->{errorMessage} = "shutdown period of the UPS undefined";
        return 0;

    }

    # checking restore period
    if (defined $restorePeriod) {

        # restore period is not a decimal number
        if ($restorePeriod !~ m{\A \d?\.?\d+ \z}xms ) {
            $self->{errorMessage}
                = "invalid restore period of the UPS -- $restorePeriod";
            return 0;
        }

        # restore period is out of range
        if (0 >= $restorePeriod or $restorePeriod > 9999) {
            $self->{errorMessage}
                = "restore period of the UPS out of range -- $restorePeriod";
            return 0;
        }

        # the command
        $command .= q{R} . sprintf( "%04d" , $restorePeriod );

    }
    else {

        $self->{errorMessage} = "restore period of the UPS undefined";
        return 0;

    }

    # shutting down UPS and restoring it again
    if ($self->sendCommand($command, \$response, 0)) {

        # success
        $self->flush();
        return 1;

    } else {

        # error, so clearing UPS buffer
        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "shutdownRestore"

sub cancelShutdown {

    # public method to cancel a running shutdown of the UPS
    #
    # parameters: $self (input) - referent to an UPS object

    # input as hidden local variable
    my $self = shift;

    # hidden local variables
    my $response = q{};     # response from the UPS

    # test UPS
    if ($self->sendCommand(q{C}, \$response, 0)) {

        # success
        $self->flush();
        return 1;

    } else {

        # error, so clearing UPS buffer
        $self->flush();

        if (2 < $self->getDebugLevel()) {
            my $logger = $self->getLogger();
            if (defined $logger) {
                $logger->debug($self->getErrorMessage())
            }
        }

        return 0;

    }

} # end of public method "cancelShutdown"

#==============================================================================
# package return:
#==============================================================================
1;

__END__

#==============================================================================
# embedded pod documentation:
#==============================================================================