ZOOM ZOOM

Physicist's Augmented Exception Code
The physicist's code (like a physicist's ErrorLogger code) would appear in a 'module' or 'package'. The framework would call the module to do some calculations and throw an exception if an error occurs.

User Interface

This section contains the bare minimum that is required to construct a user's augmented exception and throw it. It is the frameworker's job to set up the exception for throwing.
The physicists module must have: 

  #include "Exceptions/ZMthrow.h"
You would also include your frameworker's custom handler.

Because the exception handler must compare the exception name and facility of different classes of augmented exceptions, these strings must be different. Otherwise the hierarchy will not work properly. (see Hierarchy Based on Name and Facility for a more specific reason). Therefore, there are static functions that can be called for any augmented exception: 

    //assuming 'overQuota' is your augmented exception class
    //that your frameworker has set up
  overQuota::setName("Exception Name");
  overQuota::setFacility("Facility Name");
Note: these two functions change only the specific class' values and not its subclasses' names or facilities. The subclasses' values should be changed separately. Also, only one of these must be different in order for the hierarchy to work.

A static setHandler(HandlerClassName( )) function should be called in the same manner to designate your custom handler. Unlike the previous two functions the subclass' handlers could change. This is because the handler for a ZMexDerivedAug is LogViaParent( ) by default which means that the exception will use whatever handler its parent class uses.

To actually throw an exception, create an augmented exception object by using your frameworker's typedef (in this example 'overQuota') and passing the constructor one of your extra objects. Then, use ZMthrow to throw it. The suggested way to throw an exception is: 

  point extra(23, 12);  //creates my extra object- a point's coordinates
  ZMthrow(overQuota(extra));

Augmented Exception Log Outputs

The logged messages will look like: 

%ERLOG-i ErrorObj Name:
         x-coord = 23  y-coord = 12
         Facility Name-I-Exception Name [#1]
           Mon Jul 26 10:38:38 1999
           -- ZMthrow was issued at line 58
           of file "basic.cc"
           ... Exception ignored
         26-Jul-1999 10:38:38
This message contains a regular (i.e. non-augmented) exception log which is shown in green. Take a look at a breakdown of a similar exception log.
Here is a partial breakdown of the rest: This is just what would be output if you ran the code above with the example handler from the augmented exception framework webpage. There are other formatting options that come along with the ErrorLogger package that can add more information to your log such as the module name, subroutine name, run/event numbers, etc. It is the frameworker's responsibility to add many of these options.

Default Settings

ZMexAugmented ZMexDerivedAug
Exception Name "ZMexAugmented" "ZMexDerivedAug"
Exception Facility Same as the facility of its regular(i.e. non-Augmented) exception base class
Exception Severity ZMexERROR ZMexERROR
Exception Handler ZMexThrowErrors( ) ZMexHandleViaParent( )
Exception Logger ZMexLogAlways( ) ZMexLogViaParent( )
ErrorObj Name The exception name
ErrorObj Severity ELerror
ErrorLog Properties No Name; No Subroutine;

Further Options

  • Setting Exception Severities and Constructing your own ErrorObj - Augmented exceptions are logged using an ErrorObj. By default augmented exceptions create their own ErrorObj's and then delete them when the exception is deleted. By passing the constructor of an augmented exception a second argument, the user can specify either:
    1.) the name of the ErrorObj or
    2.) the ErrorObj itself
    If the user chooses option 2 then the user is responsible for deleting the ErrorObj if necessary. Option 2 is useful because you can add more information to an ErrorObj easily with operator<<. An optional third argument specifies the exception's severity.
    1. overQuota(extra, "ErrorObj Name", ZMexNORMAL);

    2. ErrorObj errobj(ELerror,"ErrorObj Name");
      errobj << "\nThis message will show up in my log";
      overQuota(extra, errobj, ZMexINFO);
    Note: The ErrorObj timestamp may differ from the timestamp in the exception log if option 2 is used because ErrorObj's gather that information when they are constructed. The Frameworker is able to remove the ErrorObj timestamp with a simple function call.
    Another catch when you use your own ErrorObj is the severity of the ErrorObj may not be the same as the severity of your exception which would happen in the case above. The failsafe way to avoid this is to use option 1 along with the following idea.
  • Accessing an Exception's ErrorObj and Adding Messages to it - To compensate for the catch identified above another feature can be used instead. Once an augmented exception is created the user can access it's ErrorObj and add more comments: 
      overQuota xepshun(extra);
  ErrorObj& errobj = xepshun.getErrorObj();
  errobj << "\nWhatever you want to add.";
    This ensures that the severity of the ErrorObj is the same as the severity of the augmented exception.
  • Setting an ErrorLog - To set a specific ErrorLog you can use: 
      #include "ErrorLogger/ErrorLog.h"
  //...
  ErrorLog errlog("ErrorLog Name");
  overQuota::setErrorLogger(errlog);
  • Setting an Exception Logger - To set a specific exception logger you can use: 
      #include "Exceptions/ZMexLogger.h"
  //...
  overQuota::setLogger(ZMexLoggerName());
    Check out the list of available loggers.
    Warning: A log will output nothing if an augmented exception and all its ancestors up to the ZMexception class (the base class of all exceptions) use ZMexLogViaParent().

    • BACK TO THE AUGMENTED EXCEPTION MAIN PAGE
    FPCLTF Home Page- Fermilab at Work- Fermilab Home

    Last modified: Feb 22 2001