SFLOG

Initialization/Shutdown APIs
int __stdcall	SFLOG_INITW (LPCWSTR szAppName, LPCWSTR szLogDir, DWORD dwBackupFiles, size_t ulMaxFileSize, unsigned int *uClientToken)
int __stdcall	SFLOG_INITA (LPCSTR szAppName, LPCSTR szLogDir, DWORD dwBackupFiles, size_t ulMaxFileSize, unsigned int *uClientToken)
int __stdcall	SFLOG_SHUTDOWN (unsigned int uClientToken)
#define	SFLOG_INIT   SFLOG_INITW

Logging Functions
int __stdcall	SFLOG_LOGMSGW (int nLevel, LPCSTR szFilename, LPCSTR szFuncName, LPCSTR szFuncSig, int nLineNo, LPCWSTR szMsg)
int __stdcall	SFLOG_LOGMSGA (int nLevel, LPCSTR szFilename, LPCSTR szFuncName, LPCSTR szFuncSig, int nLineNo, LPCSTR szMsg)
int __stdcall	SFLOG_GETLEVEL (unsigned int *nLevel)
int __stdcall	SFLOG_SETLEVEL (unsigned int uClientToken, unsigned int nLevel)
#define	SFLOG_LOGMSG   SFLOG_LOGMSGA

NumXL Logging APIs

Functions

SFLOG_GETLEVEL()

int __stdcall SFLOG_GETLEVEL

(

unsigned int *

nLevel

)

An alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant.

Return values

NDK_SUCCESS	If the function succeeds
NDK_FAILED	If the function fails, the return value is negative

See also

SFLOG_SETLEVEL

Bug

None

Parameters

[out]

nLevel

current logging level

SFLOG_INITA()

int __stdcall SFLOG_INITA	(	LPCSTR	szAppName,
		LPCSTR	szLogDir,
		DWORD	dwBackupFiles,
		size_t	ulMaxFileSize,
		unsigned int *	uClientToken )

Initialize the logging system for SDK. This is often the first API call that an application makes and is a prerequisite for other logging APIs.

Returns

status code of the function call

Return values

NDK_SUCCESS	If the function succeeds
NDK_FAILED	If the function fails, the return value is negative
NDK_SKIP_INIT	If the function has been called earlier, and the logging system is already initialized
NDK_DATAPATH_INVALID	If the szLogDir is invalid path or does not exist.

Note

The SFLOG.h header defines SFLOG_INIT as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant.

Remarks

1. The value of the application name argument (i.e. szAppName) is used as the logging file basename.
2. The first call to this function initializes the logging system, and all subsequent calls to SFLOG_INIT are ignored (returns NDK_SKIP_INIT).
3. If the value of szLogDir argument is missing (empty or NULL), the function will use the default temp directory in the current user's profile.
4. For multiple concurrent running processes (e.g. custom application, NumXL Add-in, etc.), the logging system will open/create a separate log file (with a unique suffix) for each process.
5. To reset the logging system, call the SFLOG_SHUTDOWN first, then call the SFLOG_INIT.

Requirements

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

See also

SFLOG_SHUTDOWN

Bug

None

Parameters

[in]	szAppName	Required. Is the application name (user-defined), but must match the configuration base filename
[in]	szLogDir	Optional. Is the full (absolute) path of the log file directory. If missing (i.e. NULL), SFLOG_Init uses the default temp directory in the current user's profile
[in]	dwBackupFiles	Required. Is the number of backup log files to keep, before we overwite the oldest one
[in]	ulMaxFileSize	Required. Is the maximym file size, before a rolling a new file starts (in bytes)
[out]	uClientToken	an integer token used during the logging shutdown

Examples

log_ascii.cpp.

SFLOG_INITW()

int __stdcall SFLOG_INITW	(	LPCWSTR	szAppName,
		LPCWSTR	szLogDir,
		DWORD	dwBackupFiles,
		size_t	ulMaxFileSize,
		unsigned int *	uClientToken )

Initialize the logging system for SDK. This is often the first API call that an application makes and is a prerequisite for other logging APIs.

  unsigned int uClientToken=0;
  int nRetCode = SFLOG_INITW(L"testapp",L"C:\\temp", 7, (3*1024*1024),&uClientToken);
  if(nRetCode == NDK_SUCCESS)
  {

Returns

status code of the function call

Return values

NDK_SUCCESS	If the function succeeds
NDK_FAILED	If the function fails, the return value is negative
NDK_SKIP_INIT	If the function has been called earlier, and the logging system is already initialized

Note

The SFLOG.h header defines SFLOG_INIT as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant.

Remarks

1. The value of the application name argument (i.e. szAppName) is used as the logging file basename.
2. The first call to this function initializes the logging system, and all subsequent calls to SFLOG_INIT are ignored (returns NDK_SKIP_INIT).
3. If the value of szLogDir argument is missing (empty or NULL), the function will use the default temp directory in the current user's profile.
4. For multiple concurrent running processes (e.g. custom application, NumXL Add-in, etc.), the logging system will open/create a separate log file (with a unique suffix) for each process.
5. To reset the logging system, call the SFLOG_SHUTDOWN first, then call the SFLOG_INIT.

Requirements

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

Bug

None

See also

SFLOG_SHUTDOWN, SFLOG_INITA

Parameters

[in]	szAppName	Required. Is the application name (user-defined), but must match the configuration base filename
[in]	szLogDir	Optional. is the full (absolute) path of the log file directory. If missing (i.e. NULL), SFLOG_Init uses the default temp directory in the current user's profile
[in]	dwBackupFiles	Required. is the number of backup log files to keep, before we overwrite the oldest one
[in]	ulMaxFileSize	Required. is the maximym file size, before a rolling a new file starts (in bytes)
[out]	uClientToken	an integer token used during the logging shutdown

Examples

log_init.cpp, and log_wchar.cpp.

SFLOG_LOGMSGA()

int __stdcall SFLOG_LOGMSGA	(	int	nLevel,
		LPCSTR	szFilename,
		LPCSTR	szFuncName,
		LPCSTR	szFuncSig,
		int	nLineNo,
		LPCSTR	szMsg )

Log a narrow-character (i.e., ASCII) message.

Return values

NDK_SUCCESS	If the function succeeds
NDK_FAILED	If the function fails, the return value is negative

Note

The SFLOG.h header defines SFLOG_LOGMSG as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant.

Remarks

1. C/C++ compiler has a set of standard predefined preprocessors that can be used when calling this function:
   • __FILE__ : This macro expands to the name of the current input file
   • __LINE__ : This macro expands to the current input line number, in the form of a decimal integer constant
2. Microsoft C/C++ compiler offers additional predefined macros that we can use when calling this function:
   • __FUNCTION__ : This macro expands to the the undecorated name of the enclosing function as a string literal
   • __FUNCSIG__ : This macro expands to the the signature of the enclosing function as a string literal.
3. For convenience, you may wish to define few macros to automate the logging further. For example:
   • SFLOG_MSG_DEBUG
   • SFLOG_MSG_INFO
   • SFLOG_MSG_WARN
   • SFLOG_MSG_ERROR
   • SFLOG_MSG_FATAL

Requirements

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

See also

SFLOG_LogMsg()

Bug

None

Parameters

[in]	nLevel	logging level (i.e. debug, info, trace, error, etc.)
[in]	szFilename	the source filename that triggers this logging message
[in]	szFuncName	the function name from which this log is triggered from
[in]	szFuncSig	the function sugnature (i.e. mangled name)
[in]	nLineNo	Line number in the source file
[in]	szMsg	message

Examples

log_ascii.cpp.

SFLOG_LOGMSGW()

int __stdcall SFLOG_LOGMSGW	(	int	nLevel,
		LPCSTR	szFilename,
		LPCSTR	szFuncName,
		LPCSTR	szFuncSig,
		int	nLineNo,
		LPCWSTR	szMsg )

Log a wide-character (i.e., wchar_t*) message.

Return values

NDK_SUCCESS	If the function succeeds
NDK_FAILED	If the function fails, the return value is negative
NDK_UNINITIALIZED	if the logging system has not been initialized successfully yet.

Note

The SFLOG.h header defines SFLOG_LOGMSG as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant.

Remarks

1. C/C++ compiler has a set of standard predefined preprocessors that can be used when calling this function:
   • __FILE__ : This macro expands to the name of the current input file
   • __LINE__ : This macro expands to the current input line number, in the form of a decimal integer constant
2. Microsoft C/C++ compiler offers additional predefined macros that we can use when calling this function:
   • __FUNCTION__ : This macro expands to the the undecorated name of the enclosing function as a string literal
   • __FUNCSIG__ : This macro expands to the the signature of the enclosing function as a string literal.
3. For convenience, you may wish to define few macros to automate the logging further. For example:
   • SFLOG_MSG_DEBUG_W
   • SFLOG_MSG_INFO_W
   • SFLOG_MSG_WARN_W
   • SFLOG_MSG_ERROR_W
   • SFLOG_MSG_FATAL_W

Requirements

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

See also

SFLOG_INIT, SFLOG_LOGMSG, SFLOG_LOGMSGA

Bug

None

Parameters

[in]	nLevel	logging level (i.e. debug, info, trace, error, etc.)
[in]	szFilename	the source filename that triggers this logging message
[in]	szFuncName	the function name from which this log is triggered from
[in]	szFuncSig	the function sugnature (i.e. mangled name)
[in]	nLineNo	Line number in the source file
[in]	szMsg	message

Examples

log_wchar.cpp.

SFLOG_SETLEVEL()

int __stdcall SFLOG_SETLEVEL	(	unsigned int	uClientToken,
		unsigned int	nLevel )

set the new logging level in the SDK

Return values

NDK_SUCCESS	If the function succeeds
NDK_FAILED	If the function fails, the return value is negative

See also

SFLOG_GETLEVEL

Bug

None

Parameters

[in]	uClientToken	an integer token returned during the logging initialization
[in]	nLevel	new logging level

SFLOG_SHUTDOWN()

int __stdcall SFLOG_SHUTDOWN

(

unsigned int

uClientToken

)

Shutdown and release resources allocated by logging system.

Returns

status code of the function call

Return values

NDK_SUCCESS	If the function succeeds
NDK_FAILED	If the function fails, the return value is negative
NDK_UNINITIALIZED	If the logging system has not been successfuly initialized earlier.
NDK_INVALID_TOKEN	If the value of the input argument - uClientToken - is invalid.

Requirements

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

See also

SFLOG_INITA, SFLOG_INITW

Bug

None

[in] logging system token id (acquired during initialization)

Examples

log_ascii.cpp, log_init.cpp, and log_wchar.cpp.