KrTrace

Description

#include "krtrace.hpp"

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

1. Optionally, the exception data is written 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 receive 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 Kroni'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.