The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Win32-EventLog-Carp-1.42
River stage zero No dependents
++
/ Win32::EventLog::Carp

NAME

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

BERSION

This document describes version 1.41 of Win32::EventLog::Carp, released 2007-05-19.

REQUIREMENTS

  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.

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

FUNCTIONS

carp
cluck
confess
croak

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.

click

Similar to cluck, except that it prints to STDERR directly, rather than going through Carp.

register_source

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.

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

You can also change the value from within your program:

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

Logging to Security or System Logs

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.

Forcing a Stack Trace

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

  perl -MCarp=verbose script.pl

Windows 95/98/ME

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.

KNOWN ISSUES

See http://rt.cpan.org/NoAuth/Bugs.html?Dist=Win32-EventLog-Carp for an up-to-date list of known issues and bugs.

Basename of Event Source

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.

IIS and Windows Server 2003

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.

Test::Exception and Test::Warn

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.

Test::Warn functions will block warnings from being posted to the event log altogether.

SEE ALSO

  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

AUTHOR

David Landgren <dland at cpan.org> (current maintainer)

Robert Rothenberg <rrwo at cpan.org>

Suggestions and Bug Reporting

Feedback is always welcome. Please use the CPAN Request Tracker at http://rt.cpan.org to submit bug reports.

LICENSE

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.