NAME

Win32::EventLog::Carp - for carping in the Windows NT Event Log

REQUIREMENTS

Carp
Win32::EventLog

The module will use Win32::EventLog::Message to register itself as a source, if that module is installed.

SYNOPSIS

use Win32::EventLog::Carp;
croak "We're outta here!";

use Win32::EventLog::Carp qw(cluck);
cluck "This is how we got here!";

DESCRIPTION

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).

All messages are posted the the Application Log we well as to STDERR.

Using Win32::EventLog::Carp with CGI::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.

Logging failed evals

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
	};

Event Source Registration

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.

Redefining Event Sources

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. Future versions of the module may allow you to post events in the System or Security logs.

This feature should be considered experimental.

Caveat: the effect of multiple modules using Win32::EventLog::Carp with sources set and which call each other may have funny interactions. This has not been thoroughly tested.

Forcing a Stack Trace

As with Carp, you can force a stack trace by specifying the verbose option:

perl -MCarp=verbose script.pl

KNOWN ISSUES

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).

SEE ALSO

Carp
CGI::Carp
Win32::EventLog
Win32::EventLog::Message

Win32::EventLog::Message can be found at http://www.roth.net/perl/packages/

AUTHOR

Robert Rothenberg <rrwo@cpan.org>

LICENSE

Copyright (c) 2000-2001 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.