*********************************************
  XAM Logger README
*********************************************

The XAM Logger is C++ logging framework for the XAM library.
It provides thread safe logging of XAM Library operations without
spawning any additional threads. 

Because this logging framework is built on the XAM_POSIX layer, 
it is portable to all platforms supported by the compatibility 
interface. 

This framework is extensible. LogFormatter objects may be created 
to support XAM library logging to files, streams, other logging 
frameworks, etc., without requiring changes to the core XAM library 
logging code.

This logging mechanism may be configured via (in order of priority):

   1. Predefined XAM Object fields
   2. XAM Library Configuration file
   3. Environment variables

  
How to log to the active XAM Logger from within the XAM Library:
===============================================================

  1. Include the "XAM_Logger.h" file.  
  2. See the "XAM_LogTypes.h" file for level and component options:
     - Determine the level of your log event 
       (e.g. LOGLEVEL_ERROR, LOGLEVEL_DEBUG)   
     - Determine the component of your log event 
       (e.g. component_api_enter)
  3. Utilize the provided macros as a performance consideration 
     for when logging is disabled for the given component or level.

  Examples:
     
   XAM_LOG(component_api_enter, "XAM_Connect");
   XAM_LOG_DEBUG(component_xam_debug, "This is a debug message");
   XAM_LOG_DEBUG_P2(component_xam_debug, "This is a debug message: %s", vMsg);

Configuration Instructions
==========================
 
 Log Field Controls:
 ------------------

   The following XAM Object property fields determine the runtime 
   verbosity/debug level of logging by the XAM Library:

     xam_int  ".xam.log.level"      (read/write)      
     xam_int  ".xam.log.verbosity"  (read/write)      

   A value of "0" for either of these fields indicates "no logging" 
   or "no debugging".

   To enable logging, set the value of ".xam.log.level" > 0.
   To enable debug logging, set ".xam.log.verbosity" > 0.

   Full Debugging Example:

     xam_status vLogLvlStatus = XAM_SetInt(XAM_LIBRARY_HANDLE, XAM_LOG_LEVEL, 5); 
     xam_status vDbgLvlStatus = XAM_SetInt(XAM_LIBRARY_HANDLE, XAM_LOG_VERBOSITY, 5); 

   By default, log output will be written to the "xam.log" file 
   in the working directory.


 Log Verbosity Levels:
 --------------------

    .xam.log.level:
    ------------------------------------------------
       0   OFF     - All logging disabled
       1   FATAL   - Fatal Errors only
       2   ERROR   - Errors
       3   WARN    - Errors, Warnings
       4   INFO    - Errors, Warnings, Log, Debug
       5   ALL     - Errors, Warnings, Log, Debug, Debug+

    .xam.log.verbosity: 
    ------------------------------------------------
       0   No debug output 
           Only fatal errors and warnings will be logged.

       1   Minimal XAM_API debugging (default)
           (components: none, logger, api_enter, api_exit)

       2   Verbose XAM_API debugging
           (components: none, logger, api_enter, api_params, api_exit)

       3   Verbose XAM_API and VIM_API debugging
           (components: none, logger, api_enter, api_params, api_exit, 
            vim_enter, vim_exit)

       4   Verbose XAM_API and verbose VIM_API debugging 
           (components: none, logger, api_enter, api_params, api_exit, 
            vim_enter, vim_params, vim_exit, lib)

       5   Verbose XAM_API and VIM_API debugging, extra debug msgs 
           (components: none, logger, api_enter, api_params, api_exit, 
            vim_enter, vim_params, vim_exit, lib, xam_debug)

    Where the log components are defined as follows:

       logger       - Log headers, log configuration changes, etc. 
       api_enter    - Entry into the XAM API methods
       api_params   - XAM API parameters (in and out)
       api_exit     - Exit from the XAM API methods
       vim_enter    - Entry into the VIM API methods
       vim_params   - VIM API parameters (in and out)
       vim_exit     - Exit from the VIM API methods
       lib          - Library loading/unloading
       xam_debug    - Internal log events for debugging the XAM Library implementation
       none         - Messages under this component will always be logged

 Advanced Log Field Controls:
 ---------------------------

  xam_string  ".xam.log.path"   (read/write)      
   - Specify a log file path other than "xam.log". 

  xam_boolean ".xam.log.append"  (read/write)      
   - Append to the existing log file (true) or overwrite (false, default).

  xam_int     ".xam.log.max.size"  (read/write)
   - The max size in KB the log is allowed to grow (default 1 GB).

  xam_int     ".xam.log.max.rollovers"  (read/write)      
   - The maximum number of "rollover" files to retain (default 1)

  xam_string  ".xam.log.message.filter"  (read/write)
   - A string containing a token required for log message output
      (e.g. "XAM" would include only log messages containing the 
       "XAM" string)

  xam_string  ".xam.log.component.filter"  (read/write)
   - A string containing a component token required for log output
      (e.g. "api_enter" would include only log events whose component 
       name contains this string)


 Environment Variable Controls:
 -----------------------------

    The following env var controls may be used to initialize the 
    value of the above XAM Object fields on construction:

      XAM_LOG_LEVEL
      XAM_LOG_VERBOSITY
      XAM_LOG_PATH
      XAM_LOG_APPEND
      XAM_LOG_MAXSIZE
      XAM_LOG_MAXROLLOVERS
      XAM_LOG_MSG_FILTER
      XAM_LOG_COMP_FILTER


 How to configure logging via config file:
 ----------------------------------------

    The XAM Library configuration file may be used to configure 
    logging on application startup.

    Example Configuration: 

     # Logging Controls
     xam_int..xam.log.level=5
     xam_int..xam.log.verbosity=5
     .xam.log.path=C:\Logs\MyXAM.log
     xam_boolean..xam.log.append=true
     xam_int..xam.log.config.path.pollInterval=5
     xam_int..xam.log.max.size=-1
     xam_int..xam.log.max.overflows=1




 

