Win32::EventLog::Carp - for carping in the Windows NT Event Log
This document describes version 1.41 of Win32::EventLog::Carp, released 2007-05-19.
Carp Win32::EventLog
These should be standard modules on Win32 systems.
The module will use Win32::EventLog::Message to register itself as a source, if that module is installed.
Win32::EventLog::Message
use Win32::EventLog::Carp; croak "We're outta here!"; use Win32::EventLog::Carp qw(cluck); cluck "This is how we got here!";
Win32::EventLog::Carp traps warnings and fatal errors in Perl and reports these errors in the Windows NT Event Log. This is useful for scripts which run as services or through the scheduler, and for CGI/ISAPI scripts.
Win32::EventLog::Carp
The interface is similar to Carp: the carp, croak and confess functions are exported (with cluck being optional). You need only change references of "Carp" to "Win32::EventLog::Carp" to begin using this module.
carp
croak
confess
cluck
One notable exception is the addition of the click function:
click
Win32::EventLog::Carp::click "Hello!\n";
This outouts a message to STDERR with a short stack trace and allows scripts to post a simple "I have started" or "I am doing XYZ now" message to the log. To avoid the stack trace, end the message with a newline (which is what happens with the Carp module).
Carp
See the documentation to the Carp module for an explanation of these routines. The only difference is that instead of sending their output to STDERR, the message is also logged in the Application Log.
Similar to cluck, except that it prints to STDERR directly, rather than going through Carp.
If the Win32::EventLog::Message module is available, register the source with the Windows NT event log (this only works if the user has the proper permissions). This removes the 'description not found' warning in when looking at the event in the event log viewer.
Some modules which trap the __WARN__ and __DIE__ signals are not very friendly, and will cancel out existing traps. The solution is to use this module after using other modules:
__WARN__
__DIE__
use CGI::Carp; use Win32::EventLog::Carp
or
BEGIN { $SIG{__WARN__} = \&my_handler; } use Win32::EventLog::Carp
It is assumed that the previous handler will properly warn or die as appropriate. This module will instead report these events to the NT event log.
warn
die
By default, this module will no longer log errors in the event log when something dies in an eval. If you would like to enable this, specify the LogEvals option:
LogEvals
use Win32::EventLog::Carp { LogEvals => 1 };
You can also change the value from within your program:
$Win32::EventLog::Carp::LogEvals = 1;
If the Win32::EventLog::Message module is installed on the system, and if the script is run with the appropriate (Administrator) permissions, then Perl program will attempt register itself as an event source. Which means that
carp "Hello";
will produce something like
Hello at script.pl line 10
rather than
The description for Event ID ( 0 ) in Source ( script.pl ) could not be found. It contains the following insertion string(s): Hello at script.pl line 10.
You can specify a different event source. The following
use Win32::EventLog::Carp qw(cluck carp croak click confess), { Source => 'MyProject' };
will list the source as "MyProject" rather than the filename.
You can specify a log other than the Application Log to report events to:
use Win32::EventLog::Carp 1.40 { Register => 'System' };
Events can only be posted to one log. (For example, you cannot have some events go to the Application Log while others go to the Security Log.)
Once you have registered a source to an event log, it may not be possible to register it to a different log.
This feature should still be considered experimental.
As with Carp, you can force a stack trace by specifying the verbose option:
verbose
perl -MCarp=verbose script.pl
Windows 95/98/ME do not support the event log, so this module will not work on those operating systems. If you are writing scripts which will be used on both NT-based and non-NT-based operating systems, use the following workaround:
require Win32; if (Win32::IsWinNT) { require Win32::EventLog::Carp; import Win32::EventLog::Carp 1.31; } else { require Carp; import Carp; }
This will import the standard Carp namespace for both types of machines, although the click function will not be available to Windows 95/98/ME scripts.
See http://rt.cpan.org/NoAuth/Bugs.html?Dist=Win32-EventLog-Carp for an up-to-date list of known issues and bugs.
We use the basename of the script as the event source, rather than the full pathname. This allows us to register the source name (since we cannot have slashes in registered event log source names).
The downside is that we have to view the event text to see which script it is (for common script names in a web site, for instance). In such cases, define a custom source name related to the application.
In some server configurations using IIS (Windows Server 2003), you may need to set security policy to grant permissions to write to the event log(s).
See Microsoft KnowledgeBase Article 323076 at http://support.microsoft.com/default.aspx?scid=kb;en-us;323076.
When using Test::Exception functions such as dies_ok, the source will be listed as the "Test::Exception" module rather than the script that is running the tests.
dies_ok
Test::Warn functions will block warnings from being posted to the event log altogether.
Carp Win32::EventLog Win32::EventLog::Message
Win32::EventLog::Message can be found at http://www.roth.net/perl/packages/
A PowerPoint presentation about this module can be found at http://stonybrook.pm.org/
CGI::Carp Log::Dispatch::Win32EventLog Tk::Carp Win32::GUI::Carp Wx::Perl::Carp
David Landgren <dland at cpan.org> (current maintainer)
Robert Rothenberg <rrwo at cpan.org>
Feedback is always welcome. Please use the CPAN Request Tracker at http://rt.cpan.org to submit bug reports.
Copyright (c) 2000-2004, Robert Rothenberg. Copyright (c) 2006, David Landgren. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Win32::EventLog::Carp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::EventLog::Carp
CPAN shell
perl -MCPAN -e shell install Win32::EventLog::Carp
For more information on module installation, please visit the detailed CPAN module installation guide.