ZOOM Exceptions -- Basic User Features

ZOOM ZOOM

ZOOM Exceptions and the C++ Exception Mechanism

When will ZOOM exceptions throw a C++ exception?

When a ZOOM facility detects an exceptional situation, where a library package would ordinarily throw an exception, it instead calls ZMthrow supplying an instance of a ZMexception object.

When ZMthrow is invoked, a custom handler established by the user or framework writer may be invoked. In any event, ultimately the ZOOM exception will either:

As in any C++ application, if a C++ exception is thrown and is not caught by the user or framework code, the program will abort.


try and catch

The user may imbed any calls to ZOOM routines in a try block. That way, if some ZOOM exception ultimately leads to a C++ exception being thrown, the user can catch the exception and deal with it without necessarily aborting the job.

The try block and catch code may appear locally, in the user routine invoking the ZOOM library call. More typically, it might be set up at a higher level, so that the overall job is isolated from potential problems in routines coded by individual users.

Since information about the exception is available via methods of the ZMexception object, the recommended style in a catch is to catch a reference to that object, as illustrated:

// Part of a framework that will let users set up Ntuple columns
for (userPtr u=user1; u<=lastUser; u++) {
try {
u->setupColumns();
} catch (ZMxHepColumn& x) {
// do whatever, utilizing methods of x if necessary
u->declareFlawed();
}
} // end of loop over users
C++ allows more than one catch to be connected to a given block. And the catch can, of course, specify a ZMexception which is higher in the hierarchy that the particular one thrown. For instance, all exceptions thrown by methods in the HepTuple package are ultimately derived from ZMxHepTuple -- so all such exceptions may be caught by catching that single type of exception object.


Exception Logs

An exception log is a way to get information from the exception into either a file or a stream like stderr. ZOOM exceptions write information into the log, whether they were ignored, handled and then ignored, thrown and later caught, or thrown and not caught so that the job aborted.

However, the exception handler may choose not to log exceptions beyond the n-th instance of a given exeption type. For example, the default handlers that ignore or throw an exception will log only:

The next such exception past whatever limit is established will result in a warning that further such exceptions will not be logged.

(It is also possible to set up a log so as to filter out exceptions below some level of severity, for example, to not include warning messages.)

In general, the framework of a major program sets up a log, determining where the information will go and so forth. Ordinary users need know nothing about this when coding; they should be aware of the choice made for where the excpetion messages will be logged in case they want to look at them.

A user can explicitly insert a message into the log, unrelated to ZOOM exceptions. To do this, the user must know the instance of a ZMlogger object that the framework set up to log ZOOM exceptions. By default, this will be ZMlog. The message is passed as an argument to the log() method of that logger.

See ZMlogger.h for further details on the log() method.


Information About an Exception

The user program, having caught an exception object, can use public methods of this instance of the ZMexception class to extract (at runtime) and possibly act upon information about the exception. Some basic methods are: A more detailed explanation about extracting exception information is available.

Checking for ZMexceptions

A way is provided to check on whether any ZOOM exception has been issued (even if it may have been handled and/or ignored) in a given interval. This involves an object analogous to the Unix errno variable, called how to use ZMerrno is available, but the basics for finding out about the existence of an exception are:

  1. Include <ZMerrno.h> for the declaration of ZMerrno.
  2. Invoke ZMerrno.clear() to put the system into the "no exception lately.
  3. Later, when you wish to check whether anything anomolous may have occured, do
      ZMexception * x = ZMerrno.read();
    If x is non-zero, some ZOOM exception of severity ZMsevError or higher (that is, warnings are not noted) has been ZMthrown since the last invocation of ZMerrno.clear().
  4. If you find a non-zero x, you can extract exception information about the ZOOM exception.
  5. Unlike the Unix errno, ZMerrno is set up as a buffer of the last N ZOOM exceptions. More advanced features allow inspection of earlier exceptions.

    ZOOM Exceptions Page - ZOOM Home Page - Fermilab at Work - Fermilab Home


    Mark Fischler
    and
    Philippe Canal
    Last modified: August 13, 1997