Home

Table of Contents

• • confirgurations
  • Log levels and Thresholds
  • Writing log messages
  • Requirements

The SFLOG module provides the logging system functionality to NumXL SDK, and can be used as well by your application. The logging subsystem is implemented after the common "log4j" library, and support similar configuration and functionality. The logging message contains the following:

• Timestamp
• Source File
• Line number
• Function name
• Severity
• Message

confirgurations

Upon calling the initialization API (i.e., SFLOG_INIT(.)), the calling application passes the configuration parameters as arguments:

• Basename of the log file.
• Filepath for the logfile on your systems (e.g., c:\temp)
• Log file rotation policies: Maximum filesize, compression and maximum number of files

#include <windows.h>
#include <iostream>
#include <SFLOG.h>
 
int main(){
  int nRet= NDK_FAILED; 
 
  string szAppName="myapp";     // Log file base filename (i.e., myapp.log, myapp_2.log, etc.)
  string szPath = "C:\\temp";   // Full directory path where the log files are created
  DWORD dwBackupFiles=7;        // Maximum number of log files to keep at any given file.
  size_t  ulMaxFileSize=10240,  // Maximum filesize (in bytes), after which, a new file is created
  unsigned int uClientToken=-1; // A unique integer token used to shutdown the logging s
 
  nRet = SFLOG_INITA(szAppName.c_str(), szPath.c_str(), dwBackupFiles,ulMaxFileSize, &uClientToken);  
  if(nRet < NDK_SUCCESS){
    std::cerr << "Initializing the logging facility failed, exit" << std::endl;
    exit(-1);
  }
 
  .....
 
  
  // Close the log file and shutdown the logging
  nRet = SFLOG_SHUTDOWN(uClientToken);
 
  exit(0;)
}

Note

1. The logging system has two initialization API variants:
   • SFLOG_INITA(.) for single-byte ASCII arguments.
   • SFLOG_INITW(.) for wide character (Unicode) arguments.
2. The helper macro (SFLOG_INIT) expands during compilation to eitehr API variant based on your project Unicode settings.
3. The SFLOG implements a size-based rotation for log files, so when the current log file exceed given limit, the logging system closes the file, rename it, and open a new one file for writing.
4. The number of log (current + older) files reached a given limit, the logging system will delete the oldest file when it open a new file.

Log levels and Thresholds

Upon initialization, the SFLOG set the logging level or threshold to SFLOG_ERROR (or 5), by default. Thus, only log messages with severity of error or higher will be written to the log file.

To inquire about the current log level, client application should call SFLOG_GETLEVEL(), and to change the log level from its current level, client application must call SFLOG_SETLEVEL() function.

int nLevel= -1;
 
...
int nRet = SFLOG_GETLEVEL(&nLevel);
if( nRet < NDK_SUCCESS){
  std::cerr << "Failed to query the current logging level, exit" << std::endl;
  exit(-1);
}
 
// Set the logging threshold to Critical or fatal
nRet = SFLOG_SETLEVEL(SFLOG_FATAL);

Note

SFLOG includes macros that capture all supported logging levels, as detailed in the following table:

Macro	Level	Description
SFLOG_ALL	0	Enable all logging messages (info, debug, trace, warning and error).
SFLOG_TRACE	1	Enable trace level logging: trace, debug, info, warning, error and fatal error messages.
SFLOG_DEBUG	2	Enable debug level logging: debug, info, warning, error and fatal error messages.
SFLOG_INFO	3	Enable information level logging: info, warning, error, and fatal error messages.
SFLOG_WARN	4	Enable warning level logging: warning, error and fatal error messages.
SFLOG_ERROR	5	Enable error level logging: error and fatal error messages.
SFLOG_FATAL	6	Enable fatal or critical level logging.
SFLOG_OFF	7	Disable all logging messages.

Writing log messages

The client application writes to the log file by calling the SFLOG_LOGMSGA(.) for ASCII text, or SFLOG_LOGMSGW(.) for wide-charcter unicode messages. Using either variant of those two functions, the client application must provide the folllowing details:

1. source filename
2. Line number
3. severity level
4. Function name
5. Error message

Just like we have for SFLOG_INIT, the SFLOG includes a helper macro SFLOG_LOGMSG that expands during compile-time to proper variant of the function based on your project's charater-set size.

Furthermore, the SFLOG system includes a set of helper macros (e.g., SFLOG_MSG_INFO, SFLOG_MSG_ERROR) to simply the logging greatly, by passing the compiler preprocessors (e.g., FILE, LINE) to many of the arguments. There is two variants of he macros: single-character (ASCII) message and wide-character (Unicode) messages.

Note

Having the flexibility to write ASCII/Unicode messages to the logfile frees the developer from converting string from one character-set to another, especcially, when the log messages may originat in different libraries.

Requirements

The SFLOG library is a standalone module from the rest of the NumXL SDK.

Target Platform	Windows
Header	SFLOG.h (include Windows.h)
Library	SFLOG.lib
DLL	SFLOG.dll

See also

• Log Levels
• SFLOG_INITA
• SFLOG_INITW
• SFLOG_SHUTDOWN
• SFLOG_SETLEVEL
• SFLOG_GETLEVEL
• SFLOG_LOGMSGA
• SFLOG_LOGMSGW