Package DE_EPAGES::Core::API::Error
This module provides exception-like error handling. Error messages are formatted using a template which is defined by the ErrorDefinition function in the module that threw an error. The template may contain placeholders for additional information, such as file name, SQL statement or other information that may be useful for tracking an error. These parameters are passed to the Error function.
Example |
use DE_EPAGES::Core::API::Error qw( Error ExistsError GetError ); # How to define error codes and message templates sub ErrorDefinition { return { MissingParameter => 'Missing parameter #Parameter', ValueTooLong => 'Value length #Length is larger than #MaxLength' }} # How to throw errors sub MyFunction { my ( $Name, $Value ) = @_; Error('MissingParameter', { Parameter => 'Name' } ) unless defined $Name; Error('ValueTooLong', { Length => length $Value, MaxLength => 25 } ) if length $Value > 25; ... } # How to handle errors $SIG{__DIE__} = \&DE_EPAGES::Core::API::Error::DieHandler; eval { MyFunction(); }; print GetError->message if ExistsError; |
@EXPORT_OK |
Functions
- CleanupOnError
- DieHandler
- Error
- ExistsError
- GetError
- ResetError
- RunScript
- VarsOnError
- addReEntry
- addVars
- callers
- code
- file
- guid
- innerLongMessage
- line
- longMessage
- message
- new
- package
- reEntries
- shortMessage
- subname
- vars
CleanupOnError
Executes the function $Sub if an error occured in the previous 'eval' block. Afterwards re-throws the original error. Creates a warning if $Sub throws an error.
Syntax |
CleanupOnError( $Sub ); |
Example |
eval { ... }; CleanupOnError( sub { my ($Error) = @_; ... }); |
Input |
|
DieHandler
Set this function as handler for the __DIE__ signal. It converts a native "die" into an error object.
Syntax |
DieHandler( $Message ) |
Example |
$SIG{__DIE__} = \&DE_EPAGES::Core::API::Error::DieHandler; |
Input |
|
Error
Call this function to raise an error. In case of a 'die' error, the function DieHandler will generate the error object automatically. The Error function may also be called to escalate an error, in this case the function gets the error object as its only parameter.
Syntax |
Error( $Code, $hVars ); # report a new error Error( $Code, $hVars, $InnerError ); # report a new error and encapsulate a previous error Error( $Error ); # escalating an unhandled error |
Example |
Error( 'MissingParameter', { Param => 'CatalogID' } ) unless $CatalogID; Error( 'Timeout' ); Error( $Error ) unless $Error->code eq 'Timeout'; |
Input |
|
ExistsError
Returns true if an error occured inside an 'eval' block. Uses $@ to check for an existing error.
Syntax |
$ExistsError = ExistsError() |
Example |
eval { ... }; if( ExistsError ) { ... } |
Return |
|
GetError
Returns the Error object if an error occured in the previous 'eval' block. Returns 'undef' if no error occured.
Syntax |
$Error = GetError() |
Example |
print GetError->message if ExistsError; |
Return |
|
ResetError
Resets the global error state. When this function was called, then GetError will return 'undef'. Note that it is normally not necessary to use this function because $@ is automatically reset by the 'eval' function.
Syntax |
ResetError() |
RunScript
Runs the main function in the context of the Error module and enables detailed error information.
Syntax |
RunScript( Sub => $Sub, Debug => $Debug ); |
Example |
RunScript( Sub => \&Main ) |
Input |
|
VarsOnError
If an error occured in the previous 'eval' block, the variables of the parameter will be added to the error variables. The error will be raised again.
Syntax |
VarsOnError($hVars) |
Example |
eval { doanything($file) }; VarsOnError({'file'=>$file}); |
Input |
|
addReEntry
Adds a stack to error re-entries. Rememebers the point which calls Error(GetError()).
Syntax |
$Error->addReEntry($Stack); |
Example |
$Error->addReEntry(GetCallerStack()); |
Input |
|
addVars
Copies all keys and values from the $hVars hash to the parameter hash. Overrides any existing parameter values.
Syntax |
$Error->addVars( $hVars ); |
Example |
$Error->addVars( { 'FileName' => $FileName } ); |
Input |
|
callers
Returns the stack trace as an array ref of caller array references. The caller index 1 contains the file/line where the error was actually raised. See DE_EPAGES::Core::API::PerlTools::GetCallerStack for the meaning of the caller stack entries.
Syntax |
$aaCallers = $Error->callers; |
Example |
print "Error in file: " . GetError->callers->[1][CALLER_FILENAME]; print GetCallerString(GetError->callers, 1); |
Return |
|
code
Returns the error code that was passed to Error or new.
Syntax |
$Code = $Error->code; |
Input |
|
file
Returns the file name of error.
Syntax |
$filename = $Error->file |
Return |
|
guid
Returns the unique error id.
Syntax |
$Code = $Error->guid; |
Input |
|
innerLongMessage
Returns the full message of the inner error including stack trace.
Syntax |
$LongMessage = $Error->innerLongMessage; |
Return |
|
line
Returns the line number of error.
Syntax |
$lineno = $Error->line |
Return |
|
longMessage
Returns the message including file name, line number, stack trace and all parameter values.
Syntax |
$Message = $Error->longMessage |
Return |
|
message
Returns the message including file name and line number in the same format as Perl would print a "die" error. The message will include the file name and line number that raised the error.
Syntax |
$Message = $Error->message |
Example |
print GetError->message if ExistsError; |
Return |
|
new
Creates a new error object. Normally you don't use this constructor directly. Rather you will use Error and GetError.
Syntax |
$Error = DE_EPAGES::Core::API::Error->new( Code => $Code, Vars => $hVars, Message => $Message, InnerLongMessage => $Message, ); |
Example |
$Error = DE_EPAGES::Core::API::Error->new( Code => 'DiskFull' ); |
Input |
|
Return |
|
package
Returns the package name of error.
Syntax |
$packagename = $Error->package |
Return |
|
reEntries
Returns the stack traces of error re-entries. That means the points which can't handle the error an set it again with Error(GetError()). Each caller entry has the format of:
{ FileName => $FileName, Line => $LineNo, SubName => $SubName, Package => $PackageName }The caller index 1 contains the file/line where the error was actually raised.
Syntax |
$aCallers = $Error->reEntries; |
Return |
|
shortMessage
Returns the message without file name and line number. If the error was thrown by the Error function, the message is retrieved from the "ErrorDefinition" function in the module that threw the error. Any placeholders are replaced by variables in the parameter $hVars that were passed to Error.
Syntax |
$Message = $Error->shortMessage |
Return |
|
subname
Returns the function name of error (ignores eval calls in stack).
Syntax |
$subname = $Error->subname |
Return |
|
vars
Returns the parameter hash that was passed to Error or new.
Syntax |
$hVars = $Error->vars; |
Return |
|