/*
 * $Id: tracing.txt,v 1.2 2002/06/06 06:24:04 ckedem 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>
 *   Documentación en Inglés
 *
 * Copyright 2001 Alejandro de Gárate <alex_degarate@hotmail.com>
 *   Traducción al Español
 *
 * Vea doc/license.txt por los términos de la licencia.
 *
 */


INTRODUCCION AL SEGUIMIENTO DE LA EJECUCIÓN (rastrear)
======================================================

Este archivo explica como habilitar el seguimiento en Harbour.


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

Harbour implementa el seguimiento al agregar llamadas a la siguiente
macro en código 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 compilación y tiempo de ejecución.


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

En tiempo de compilación, 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 explícitamente establece HB_TR_LEVEL ó este es
establecido por el compilador, sus efectos son como sigue: cualquier
llamada en el código con un nivel mayor que HB_TR_LEVEL son borradas
del código; estas llamadas simplemente desaparecen, y no hay efecto en
la perfomance del código después de eso.


TIEMPO DE EJECUCIÓN
===================

En tiempo de ejecución, 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    Descripción
compilación    ejecución
----------------------------------------------------------------------
HB_TR_INFO     HB_TR_ERROR    Todas las llamadas con niveles HB_DEBUG
                              son eliminadas del código, 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 código, 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 ejecución no
                              tiene ningún efecto, porque el código 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 información,
en tiempo de ejecución, 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 función de seguimiento para el nivel INFO
serán hechas de todas formas, así que habrá un pérdida de perfomance.


USO
===

Cuando Harbour es compilado / ejecutado con algún nivel de seguimiento
y, entonces usado para compilar una aplicación regular de Harbour, la
aplicación producirá MONTONES de información 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 efectúa el seguimiento, va a stderr por
defecto. Ud. puede controlar esto en tiempo de ejecución al establecer
la variable de entorno HB_TR_OUTPUT al nombre del archivo donde Ud.
podría querer que la salida de seguimiento sea dirigida. Si hay algún
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 adición 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 también posible habilitar y deshabilitar el seguimiento en tiempo
de ejecución y averiguar y establecer el nivel de seguimiento. Desde
código C:

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

    hb_tracestate( estado );

  Por lo tanto, para sólo 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 debería estar en el
  rango [0,5], de otra manera, el estado actual permanece sin cambios):

    hb_tracelevel( nivel );


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

    nivel_actual = hb_tracelevel(-1);


Hay funciones para ser llamadas desde código Clipper:
(en realidad desde Harbour)

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

