/*
 * $Id: tracing.txt,v 1.1 2002/01/22 22:02:24 lculik Exp $
 */

/*
 * Las siguientes partes son derechos adquiridos de sus autores individuales.
 * www - http://www.harbour-project.org
 *
 * Copyright 2001 Gonzalo A. Diethelm  <Gonzalo.Diethelm@jda.cl>
 *   Documentacin en Ingls
 *
 * Copyright 2001 Alejandro de Grate <alex_degarate@hotmail.com>
 *   Traduccin al Espaol
 *
 * Vea doc/license.txt por los trminos de la licencia.
 *
 */
 
 
INTRODUCCION AL SEGUIMIENTO DE LA EJECUCIN (rastrear)
======================================================

Este archivo explica como habilitar el seguimiento en Harbour.


SEGUIMIENTO
===========

Harbour implementa el seguimiento al agregar llamadas a la siguiente 
macro en cdigo C:

    HB_TRACE(level, ("parametros estilo printf", arg1, arg2));

El nivel epecificado por la llamada a HB_TRACE afecta a Harbour en 
dos formas: tiempo de compilacin y tiempo de ejecucin.


TIEMPO DE COMPILACION
=====================

En tiempo de compilacin, la macro chequea cuando la constante del 
preprocesador HB_TR_LEVEL es establecida a alguno de los siguientes 
valores:

  #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

Si no es establecida a alguna de estas, la macro es seteada al valor
HB_TR_DEFAULT, la cual est actualmente establecida (en hbtrace.h) a 
HB_TR_WARNING.

Cuando el usuario explcitamente establece HB_TR_LEVEL  este es 
establecido por el compilador, sus efectos son como sigue: cualquier 
llamada en el cdigo con un nivel mayor que HB_TR_LEVEL son borradas 
del cdigo; estas llamadas simplemente desaparecen, y no hay efecto en 
la perfomance del cdigo despus de eso.


TIEMPO DE EJECUCIN
===================

En tiempo de ejecucin, el usuario puede establecer la variable de 
entorno HB_TR_LEVEL a una de:

  HB_TR_ALWAYS
  HB_TR_FATAL
  HB_TR_ERROR
  HB_TR_WARNING
  HB_TR_INFO
  HB_TR_DEBUG

con el siguiente efecto: cualquiera de las llamadas a HB_TRACE que 
fueron dejadas por el compilador y que tenga un nivel inferior  igual 
a HB_TR_LEVEL imprimir sus argumentos a la salida stderr (pantalla).


EJEMPLOS
========

HB_TR_LEVEL    HB_TR_LEVEL    Descripcin
compilacin    ejecucin 
----------------------------------------------------------------------
HB_TR_INFO     HB_TR_ERROR    Todas las llamadas con niveles HB_DEBUG 
                              son eliminadas del cdigo, as ellas no 
                              tienen efecto en la perfomance; solamente 
                              llamadas con niveles de HB_TR_ERROR, 
                              HB_TR_FATAL y HB_TR_ALWAYS son impresas.

HB_TR_WARNING  HB_TR_INFO     Todas las llamadaa con niveles HB_INFO y
                              HB_DEBUG son eliminadas del cdigo, as 
                              ellas no tienen efecto en la perfomance; 
                              solamente llamadas con niveles de 
			      HB_TR_ERROR, HB_TR_FATAL y HB_TR_ALWAYS 
                              son impresas. Note como estableciendo 
                              HB_TR_INFO en tiempo de ejecucin no 
                              tiene ningn efecto, porque el cdigo fu 
                              compilado con un menor nivel de rastreo.

Por ejemplo, Yo compilo Harbour en WinNT con gcc (MINGW32), as 
usualmente establezco la variable de entorno C_USR a algo as:

  export C_USR="-DHARBOUR_USE_WIN_GTAPI -DHB_TR_LEVEL=HB_TR_INFO"

y me aseguro que tengo todo el seguimiento para los niveles INFO, 
WARNING, ERROR, FATAL y ALWAYS. Si obtengo demasiada informacin, 
en tiempo de ejecucin, yo puedo cambiar la variable de entorno a:

  export HB_TR_LEVEL=HB_TR_WARNING

y mantener alejado todo el seguimiento del nivel INFO. En este caso 
todas las llamadas a la funcin de seguimiento para el nivel INFO 
sern hechas de todas formas, as que habr un prdida de perfomance.


USO
===

Cuando Harbour es compilado / ejecutado con algn nivel de seguimiento 
y, entonces usado para compilar una aplicacin regular de Harbour, la 
aplicacin producir MONTONES de informacin a la salida stderr.
Si Ud. est usando un sensible shell de comando (como ser bash) Ud. 
puede redirigir la salida stderr a un archivo como en:
 
  mi_aplic >rastro.txt


REDIRECCION
===========

La salida generada mientras se efecta el seguimiento, va a stderr por 
defecto. Ud. puede controlar esto en tiempo de ejecucin al establecer 
la variable de entorno HB_TR_OUTPUT al nombre del archivo donde Ud. 
podra querer que la salida de seguimiento sea dirigida. Si hay algn 
problema abriendo el archivo para escritura, la salida se revierte a 
stderr.


RASTREANDO EL PREPROCESADOR Y EL COMPILADOR
===========================================

Usualmente, Ud, no desear habilitar el seguimiento en el preprocesador 
y en el compilador; de otra menera Ud. ver la salida de seguimiento 
mientras compila a Harbour mismo. Si Ud. REALMENTE quiere habilitar el 
seguimiento en el pre-procesador y/o el compilador, Ud. debe definir 
en adicin a como se describe arriba, la siguiente variable, y entonces 
recompilar el preprocesador / compilador:

  HB_TRACE_UTILS

El valor no tiene ninguna importancia.


SEGUIMIENTO Y EJECUCION
=======================

Es tambin posible habilitar y deshabilitar el seguimiento en tiempo 
de ejecucin y averiguar y establecer el nivel de seguimiento. Desde 
cdigo C:

* Para averiguar el estado actual de seguimiento, y opcionalmente 
  cambiar el estado actual a un valor dado (el cual debera estar 
  en el rango [0,1], de otra manera, el estado actual permanece sin 
  cambios):

    hb_tracestate( estado );

  Por lo tanto, para slo averiguar el estado actual, Ud. puede llamar 
  en forma segura:

    estado_actual = hb_tracestate(-1);


  Para desactivar completamente el seguimiento:

    hb_tracestate(0);


  Para activar el seguimiento:

    hb_tracestate(1);


* Para averiguar el nivel actual de seguimiento, y opcionalemente 
  cambiar el nivel actual a un valor dado (cual debera estar en el 
  rango [0,5], de otra manera, el estado actual permanece sin cambios):  

    hb_tracelevel( nivel );


  Por lo tanto, para slo averiguar el nivel actual, Ud. puede llamar 
  en forma segura:

    nivel_actual = hb_tracelevel(-1);




Hay funciones para ser llamadas desde cdigo Clipper:
(en realidad desde Harbour)

  current_state := HB_TRACESTATE( [new_state] )
  current_level := HB_TRACELEVEL( [new_level] )








