KrTrace

Description

#include "krtrace.hpp"

This class handles uncatched exceptions. Whenever an uncatched exception occurres, the following is done:

1.Optionally, the exception data is writen to some location

2.Optionally, the user is informed that an error has occurred

3.The program is terminated

This class uses and enhances the functionality of ITrace.

Derivation

KrTrace inherits from IBase.

Constructors

You cannot construct objects of this class. Instead, make use of its enumerations and of its static member functions.

Overload 1

private: 
KrProfile (); 

Public Functions

Exception handling

tellUser

Use this function to determine how detailed (if at all) the user should be informed about a program crash by a message box.

public:

static void tellUser (userInfo aInfo); 

TraceTo

Use this function to determine whether trace and exception information should be logged, and if yes, to which destination.

Overload 1

public: 
static void traceTo (traceTarget aTarget); 

Overload 1 traces to the destination aTarget.

Overload 2

public: 
static void traceTo (const IString & s); 

Overload 2 traces to a file. Its filename is given by s.

Overload 3

public: 
static void traceTo (); 

Overload 3 traces to the file progname.log in the current directory, where progname is the name of the exe-file of the program (without the .exe suffix).

Note: Overload 3 requires that the IBM open class library has been correctly initialized using IApplication::current().setArgs().

Exception throwing

_throw

You should not call this function directly, but use one of the macros instead.

Overload 1

public:
static void _throw (const IException & ex,  const char* fileName,
                   const char* functionName, unsigned long lineNumber);

Overload 2

public:
static void _throw (const IException & ex, const char* fileName,
                   const char* functionName, unsigned long lineNumber,
                   const IString & group);

Enumerations

traceTarget

public: enum traceTarget {stdout, stderr, file, queue, none};

This enumeration is used to identify the logging destination when calling traceTo. These are the meanings of their members:

stdout     Write all log information to stdout

stderr     Write all log information to stderr

file       Write all log information to a file. If a file
           name has already been set using traceTo, that name
           is used. If no file name has been set so far,
           traceTo is called without arguments to determine a
           filename. In this case, please note the remarks to
           traceTo.

queue      Write all log information to the queue
           \\QUEUES\\PRINT32.

none       Do not perform any logging. This is the default
           until traceTo is called.

userInfo

public: enum userInfo {noMsg, simple, logFile, full};

Use this enumeration with tellUser to tell the system whether the user of your application should recieve information about crashes. The meanings of their members are:

noMsg      Do not give the user any message and just exit
           from the program. This is the default until
           tellUser is called. This is also what the IBM open
           class library does if Kroi's Classes are not used.

simple     Just tell the user that an error was encountered
           and that the program cannot continue.

logFile    Like "simple", but tell the user also the location
           of the log file (if any exists).

full       Like "logFile", but also pop up full information
           about the exception which caused the crash.

Macros

For use with the KrTrace class, the following macros are defined:

KRTHROW(exc) KRNAMEDTHROW(exc,name)

KRTHROW works exactly like ITHROW, but accepts also temporaries as arguments (if you try this with ITHROW, all position information will be lost).

KRNAMEDTHROW works like KRTHROW, but expects another parameter name, which should be an IString object and contains the name of the group this exception belongs to. Use this to identify the module the exception was thrown from.