|
Win32::EventLog::Carp - for carping in the Windows NT Event Log |
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.
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.
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.
One notable exception is the addition of the click function:
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 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.
cluck, except that it prints to STDERR directly, rather
than going through Carp.
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:
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.
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:
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:
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 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.
When using the Test::Exception manpage functions such as dies_ok, the source
will be listed as the ``Test::Exception'' module rather than the script
that is running the tests.
the Test::Warn manpage 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.
|
Win32::EventLog::Carp - for carping in the Windows NT Event Log |