/*
 * $Id: tracing.txt,v 1.4 2004/02/29 21:50:20 lculik Exp $
 */
/*  $DOC$
 *  $FUNCNAME$
 *      Xharbour Tracing 
 *  $CATEGORY$
 *      Xharbour extension
 *  $ONELINER$
 *      This doc has info on how to do low level tracing on xharbour app 
 *  $DESCRIPTION$
 *      INTRODUCTION
 *      
 *      This file explains how to enable tracing in Xharbour.
 *      
 *      XHARBOUR TRACING EXTENSION

 *      First be aware that, if you are temporarily debugging
 *      or tracing values in C code, you can bypass
 *      the rest of this discussion by just using the TraceLog() function.
 *      It's defined in rtl\trace.c, and is not dependent on the various
 *      settings that HB_TRACE uses.
 *      
 *         void TraceLog( const char * sFile, const char * sTraceMsg, ... )
 *      
 *       First parameter:  NULL to default to "trace.log", or a file name.
 *       Second parameter: a format string, followed by variable args for it.
 *      
 *      ADDITIONAL TOOL

 *      Once the tracing decribed below is turned on, you can call this
 *      in a PRG to trace PRG-level function calls:
 *      
 *          __TRACEPRGCALLS( <lOnOff> ) --> <lOldValue>
 *      
 *        It turns on|off tracing of PRG-level function and method calls.
 *        The symbol name is written just before it's called.
 *        This is very useful when debugging GPFs as it
 *        will trace all PRG-level calls up until the crash.
 *        Uses HB_TRACE so traces are in line with any C-level traces.
 *      
 *      TRACING
 *      
 *      Xharbour implements tracing by adding calls to the following macro in
 *      the C code:
 *      
 *      HB_TRACE(level, ("printf-style parameters", arg1, arg2));
 *      
 *      The level specified for the HB_TRACE call affects Xharbour in two ways:
 *      compilation time and run time.
 *      
 *      
 *      COMPILATION TIME
 *      
 *      At compilation time, the macro checks whether the preprocessor
 *      constant HB_TR_LEVEL is set to any of the following values:
 *      
 *        #define HB_TR_ALWAYS     0
 *        #define HB_TR_FATAL      1
 *        #define HB_TR_ERROR      2
 *        #define HB_TR_WARNING    3
 *        #define HB_TR_INFO       4
 *        #define HB_TR_DEBUG      5
 *      
 *        #define HB_TR_LEVEL_ALWAYS     0
 *        #define HB_TR_LEVEL_FATAL      1
 *        #define HB_TR_LEVEL_ERROR      2
 *        #define HB_TR_LEVEL_WARNING    3
 *        #define HB_TR_LEVEL_INFO       4
 *        #define HB_TR_LEVEL_DEBUG      5
 *      
 *      If it is not set to any of these, the macro is set to the value of
 *      HB_TR_DEFAULT, which is currently set (in hbtrace.h) to HB_TR_WARNING.
 *      
 *      Whether the user explicitly sets HB_TR_LEVEL or it is set by the
 *      compiler, its effect is as follows: any calls in the code with a level
 *      higher than HB_TR_LEVEL are obliterated from the code; these calls
 *      simply disappear, and there is no effect in the code performance
 *      thereafter.
 *      
 *      
 *      RUN TIME
 *      
 *      At run time, the user can set the environment variable HB_TR_LEVEL to
 *      one of
 *      
 *        HB_TR_ALWAYS
 *        HB_TR_FATAL
 *        HB_TR_ERROR
 *        HB_TR_WARNING
 *        HB_TR_INFO
 *        HB_TR_DEBUG
 *      
 *      with the following effect: any calls to HB_TRACE that were left by the
 *      compiler and which have a level lower or equal to HB_TR_LEVEL will
 *      print its arguments on stderr.
 *      
 *      
 *      EXAMPLES
 *      
 *      HB_TR_LEVEL      HB_TR_LEVEL    Description
 *      compilation      run-time
 *      -----------      -----------    ----------------------------------------
 *      HB_TR_INFO       HB_TR_ERROR    All calls with levels HB_DEBUG are
 *          or                          erased from the code, so they have no
 *      HB_TR_LEVEL_INFO                performance effect; only calls with
 *                                      levels HB_TR_ERROR, HB_TR_FATAL and
 *                                      HB_TR_ALWAYS are printed.
 *      
 *      HB_TR_WARNING    HB_TR_INFO     All calls with levels HB_INFO and
 *          or                          HB_DEBUG are erased from the code, so
 *      HB_TR_LEVEL_WARNING             they have no performance effect; only
 *                                      calls with levels HB_TR_WARNING,
 *                                      HB_TR_ERROR, HB_TR_FATAL and
 *                                      HB_TR_ALWAYS are printed. Notice how
 *                                      setting HB_TR_INFO at run-time has no
 *                                      effect, since the code was compiled with
 *                                      a lower tracing level.
 *      
 *      For example, I compile Xharbour on WinNT with gcc (MINGW32), so I
 *      usually set the C_USR environment variable like this:
 *      
 *      export C_USR='-DHARBOUR_USE_WIN_GTAPI -DHB_TR_LEVEL=HB_TR_INFO'
 *      
 *      or for other OS (eg: DOS, WIN9x)
 *      
 *      SET C_USR=-DHARBOUR_USR_WIN_GTAPI -DHB_TR_LEVEL_INFO
 *      
 *      and make sure I have all the tracing for the INFO, WARNING, ERROR,
 *      FATAL and ALWAYS levels. If I get too much information, at run-time I
 *      can set an environment variable like this:
 *      
 *      export HB_TR_LEVEL=HB_TR_WARNING
 *      
 *      or for other OS (eg: DOS, WIN9x)
 *      
 *      SET HB_TR_LEVEL=HB_TR_WARNING
 *      
 *      and get rid of all the tracing for the INFO level. In this case, all
 *      the calls to the tracing function for the INFO level will be done
 *      anyway, so there will be a performance hit.
 *      
 *      
 *      USAGE
 *      
 *      When Xharbour is compiled/run with some level of tracing and then used
 *      to  compile a regular Xharbour application, the app will output LOTS of
 *      tracing information to stderr.  If you are using a sensible command
 *      shell (such as bash) you can redirect stderr to a file like this:
 *      
 *      my_app 2>trace.txt
 *      
 *      
 *      REDIRECTION
 *      
 *      The output generated while tracing goes to stderr by default. You can
 *      control this at run-time by setting the environment variable
 *      HB_TR_OUTPUT to the name of a file where you would like the tracing
 *      output to be directed. If there is any problem opening the file for
 *      writing, the output reverts to stderr.
 *      
 *      When it happens an error and the controller of errors of Xharbour cannot
 *      intercept it (eg: GPF), it can happen that part of information of tracing
 *      it is not written. This problem is avoided setting the environment
 *      variable HB_TR_FLUSH to 1 (one). This makes that every time that one
 *      record is sent to write, don't remain in the buffer, but rather it is
 *      writen in the file before continuing with the execution.
 *      This set can produce an important reduction of speed of execution.
 *      
 *      TRACING THE PREPROCESSOR AND COMPILER
 *      
 *      Usually, you will not want tracing enabled in the preprocessor and
 *      compiler; otherwise, you will see the trace output while compiling
 *      Xharbour itself.  If you REALLY want to enable tracing in the
 *      preprocessor and/or compiler, you must define, in addition to
 *      HB_TR_LEVEL as described above, the following variable, and then
 *      recompile the preprocessor/compiler:
 *      
 *        HB_TRACE_UTILS
 *      
 *      The value is of no importance.
 *      
 *      TRACING AND RUNTIME
 *      
 *      It is also possible to enable and disable tracing at run-time, and to
 *      query and set the trace level. From C code:
 *      
 *      * To query the current tracing state, and optionally change the
 *        current state to a given value (which should be in the range [0,1],
 *        otherwise the current state remains unchanged):
 *      
 *        hb_tracestate(state);
 *      
 *        Therefore, to just query the current state, you can safely call
 *      
 *        current_state = hb_tracestate(-1);
 *      
 *        To turn tracing completely off:
 *      
 *        hb_tracestate(0);
 *      
 *        To turn tracing back on:
 *      
 *        hb_tracestate(1);
 *      
 *      * To query the current tracing level, and optionally change the
 *        current level to a given value (which should be in the range [0,5],
 *        otherwise the current level remains unchanged):
 *      
 *        hb_tracelevel(level);
 *      
 *        Therefore, to just query the current level, you can safely call
 *      
 *        current_level = hb_tracelevel(-1);
 *      
 *       
 *      There are wrapper functions callable from Clipper code:
 *      
 *      current_state := HB_TRACESTATE( [new_state] )
 *      current_level := HB_TRACELEVEL( [new_level] )
 *  $END$
 */
