NAME

OTC_Tracer - Class for tracing execution path through a function.

SYNOPSIS


#include <OTC/debug/tracer.hh>

class OTC_Tracer
{
  public:
    OTC_Tracer(
      char const* thePrototype,
      char const* theFile,
      u_int theLine,
      int theEnable=0
    );
    OTC_Tracer(char const* thePrototype);
    ~OTC_Tracer();
    inline ostream& operator()() const;
    inline char const* prototype() const;
    inline static OTC_Boolean globalTrace();
    inline static void enableGlobalTrace();
    inline static void disableGlobalTrace();
    inline static int level();
    inline static void setLevel(int theLevel);
    inline static OTC_Boolean traceIndent();
    inline static void enableTraceIndent();
    inline static void disableTraceIndent();
    inline static OTC_Tracer const* last();
    inline OTC_Tracer const* prev() const;
    friend ostream& otclib_tracer();
    inline static ostream* stream();
    inline static void setStream(ostream* theStream);
};

CLASS TYPE

Concrete

DESCRIPTION

Used to trace execution path through a function, by printing out messages when an instance of the class is created, and automatically, when the class is destroyed on function exit. An example of how the class is used. This would produce the following output. To encourage you to leave debugging statements in your code, a number of macros have been provided, that achieve the above result, but that can be conditionally compiled into your code, only when required. These are the OTCLIB_DOTRACE and OTCLIB_TRACER macros and are used in the following manner. It is not necessary to use the OTCLIB_DOTRACE macro in a block to be able to use the OTCLIB_TRACER macro. The OTCLIB_TRACER can be used in a block by itself. To compile the debugging statements into your code, the preprocessor symbol OTCLIB_TRACE must be defined, ie., -DOTCLIB_TRACE must be supplied as an argument to the compiler. The argument to the OTCLIB_TRACER macro represents a debug level. If the debug level set in the OTC_Tracer class is greater than the value of the argument, and the argument is positive, the line will be run. When the OTCLIB_DOTRACE macro is used, the information generated when the OTC_Tracer class is created and destroyed is at level 1. Instead of the OTCLIB_DOTRACE macro, the OTCLIB_MARKBLOCK macro can be used. This macro takes two arguments. The first argument is a trace level. The second argument is the string which will be passed to the construtor of the OTC_Tracer class. The OTCLIB_DOTRACE macro has the same affect as the OTCLIB_MARKBLOCK macro, using 1 as the first argument. A level of 0 indicates that the information should always be displayed. Higher values should be used for successive levels of verbosity. The initial debug level use to to determine what is displayed will be taken from the environment variable OTCLIB_TRACELEVEL or will be set to 0 if this isn't defined or the value in the variable was negative, ie., by default, no trace output is displayed. If you use this feature a lot, ie., you are a code developer, you may wish to permanently set this environment variable to 1 or higher. By default, the output from the OTC_Tracer class is sent to stderr via the clog stream. You can divert the trace output to a file by setting the environment variable OTCLIB_TRACEFILE to be the name of the file. If the file cannot be opened, the output will still be sent to stderr. You can also divert the trace output to a particular file descriptor. If you wish to do this, the environment variable OTCLIB_TRACEFD should be set to the number of the file descriptor. This can be used to divert the trace output through a process that filters or highlights information. Note that if both OTCLIB_TRACEFD and OTCLIB_TRACEFILE are defined, use of the file descriptor will take precedence; output will not be sent to both places. If you are using the OTCLIB_TRACER and OTCLIB_DOTRACE macros, you can enable the generation of additional trace information containing file and line information. This is enabled by setting the environment variable OTCLIB_TRACEINFO. The additional information is output, just before the @enter line for a function. The format of the additional information will be:

CONSTRUCTION

OTC_Tracer(
  char const* thePrototype,
  char const* theFile,
  u_int theLine,
  int theEnable=0
);
OTC_Tracer(char const* thePrototype);

DESTRUCTION

~OTC_Tracer();

STREAM ACCESS

inline ostream& operator()() const;

FUNCTION NAME

inline char const* prototype() const;

GLOBAL TRACE

Enabling of a global trace can be done by setting the environment variable OTCLIB_GLOBALTRACE as well as through the following functions.
inline static OTC_Boolean globalTrace();
inline static void enableGlobalTrace();
inline static void disableGlobalTrace();

TRACE LEVEL

A global trace will override the effect of these settings and will result in everything being displayed.
inline static int level();
inline static void setLevel(int theLevel);

TRACE INDENT

Trace indenting is by default turned on. You can turn identing off by setting the environment variable OTCLIB_NOTRACEINDENT.
inline static OTC_Boolean traceIndent();
inline static void enableTraceIndent();
inline static void disableTraceIndent();

STACK TRACE

inline static OTC_Tracer const* last();
inline OTC_Tracer const* prev() const;

STAND ALONE TRACE

friend ostream& otclib_tracer();

STREAMS

inline static ostream* stream();
inline static void setStream(ostream* theStream);

SEE ALSO

ostream

LIBRARY

OTC

AUTHOR(S)

Graham Dumpleton

COPYRIGHT

Copyright 1991 1992 1993 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED