Configurations

API for Initializing, configuring, and shutdown the logging facility. More...

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

Functions
int __stdcall	SFLOG_INITW (LPCWSTR szAppName, LPCWSTR szLogDir, DWORD dwBackupFiles, size_t ulMaxFileSize, unsigned int *pClientToken)
	Initialize the logging system and accepts a unicode filename and path.
int __stdcall	SFLOG_INITA (LPCSTR szAppName, LPCSTR szLogDir, DWORD dwBackupFiles, size_t ulMaxFileSize, unsigned int *pClientToken)
	Initialize the logging system for SDK using ascii strings for the logging base filename and directory.
int __stdcall	SFLOG_SHUTDOWN (unsigned int uClientToken)
	write all the cache logs to the file and closed the log file.
int __stdcall	SFLOG_GETLEVEL (unsigned int *nLevel)
	query and retrieve the current logging level in the logging subsystem
int __stdcall	SFLOG_SETLEVEL (unsigned int uClientToken, unsigned int nLevel)
	sets the current logging level in the logging subsystem

Detailed Description

The NumXL SDK logging subsystem definie a logging level to determine whether a message is written to the log file or not. The numeric integer value of the logging level is represented by the value of one of those macros.

Macro Definition Documentation

SFLOG_INIT

#define SFLOG_INIT   SFLOG_INITW

See also

SFLOG_INITW, SFLOG_INITA

Function Documentation

SFLOG_GETLEVEL()

int __stdcall SFLOG_GETLEVEL

(

unsigned int *

nLevel

)

retieve the current logging level (or threshold) in the logging system.

Parameters

[out]

nLevel

(Required) a pointer to variable that the currently-selected logging level (e.g. debug, info, trace). For a full list, see Logging Levels

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success
NDK_FAILED	failed
NDK_INVALID_ARG	failed (see remarks)

Remarks

1. if the nLevel is NULL, the function will fail and retun NDK_INVALID_ARG error code.
2. Upon success, the function will save the current logging level in the variable (pointed to by nLevel).

Requirements

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

See also

• SFLOG_SETLEVEL

SFLOG_INITA()

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

Initialize the logging system for SDK using ascii strings for the logging base filename and directory.

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]	pClientToken	An integer token used during the logging shutdown

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success
NDK_SKIP_INIT	success with warning (see remarks)
NDK_DATAPATH_INVALID	failed (see remarks)
NDK_FAILED	failed

Remarks

1. The argument szBaseName value must be a vaild base logging filename, so it can't include the following characters: backslash (\), slash(/), colon(:), astrick(*), question mark(?), double-quote("), left-angle(<), right-angle(>), or vertical pipeline(|).
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.
6. If the path in szLogDir does not exists or invalid, the function will fail and return NDK_DATAPATH_INVALID error code.
7. 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.

Requirements

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

See also

• SFLOG_SHUTDOWN
• SFLOG_INIT

<

Examples

log_ascii.cpp.

SFLOG_INITW()

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

Initializes the logging facility of the NumXL SDK using Unicode strings for the logging base filename and directory.

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]	pClientToken	an integer token used during the logging shutdown

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success
NDK_SKIP_INIT	success with warning (see remarks)
NDK_DATAPATH_INVALID	failed (see remarks)
NDK_FAILED	failed

Remarks

1. This is often the first API call that an application makes and is a prerequisite for other logging APIs.
2. The argument szBaseName value must be a vaild base logging filename, so it can't include the following characters: backslash (\), slash(/), colon(:), astrick(*), question mark(?), double-quote("), left-angle(<), right-angle(>), or vertical pipeline(|).
3. The first call to this function initializes the logging system, and all subsequent calls to SFLOG_INIT are ignored (returns NDK_SKIP_INIT).
4. 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.
5. 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.
6. To reset the logging system, call the SFLOG_SHUTDOWN first, then call the SFLOG_INIT.
7. If the path in szLogDir does not exists or invalid, the function will fail and return NDK_DATAPATH_INVALID error code.
8. 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.

A sample code

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

Requirements

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

See also

• SFLOG_SHUTDOWN
• SFLOG_INITA
• SFLOG_INIT

Examples

log_init.cpp, and log_wchar.cpp.

SFLOG_SETLEVEL()

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

set the new logging level in the SDK

Parameters

[in]	uClientToken	(Required) Is the logging system token id (acquired during initialization).
[in]	nLevel	(Required) Is the new logging level (e.g. debug, info, trace). For a full list, see Logging Levels

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success
NDK_INVALID_ARG	failed (see remarks)
NDK_FAILED	failed

Remarks

1. If the value of nLevel is out of range (i.e., nLevel < SFLOG_ALL or nLevel > SFLOG_OFF), the function will fail and return NDK_INVALID_ARG error code.
2. If the value of the uClientToken argument is invalid, the function will fail and return NDK_INVALID_ARG error code.

Requirements

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

See also

• SFLOG_GETLEVEL

SFLOG_SHUTDOWN()

int __stdcall SFLOG_SHUTDOWN

(

unsigned int

uClientToken

)

Shutdown and release resources allocated by logging system

Parameters

[in]

uClientToken

(Required) Is the logging system token id (acquired during initialization).

Returns

status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.

Return values

NDK_SUCCESS	success
NDK_UNINITIALIZED	failed (see remarks)
NDK_INVALID_TOKEN	failed (see remarks)
NDK_FAILED	failed

Remarks

1. if the value of uClientToken is invalid, the function will fail and return NDK_INVALID_TOKEN error code.
2. If the logging system was not initialized earlier (i.e., via call to SFLOG_INIT or its variants), the function will fail and return NDK_UNINITIALIZED error code.

Examples

std::wstring szAppName = L"testapp";
std::wstring szLogDir =L"C:\\temp";
DWORD dwBackupFiles=7;
size_t ulMaxFileSize= (1024 * 1024); 
 
unsigned int uClientToken=0;
int nRetCode = SFLOG_INITW(szAppName.c_str(),szLogDir.c_str(), dwBackupFiles, ulMaxFileSize, &uClientToken);
if(nRetCode == NDK_SUCCESS){
SFLOG_SHUTDOWN(uClientToken);
}

Requirements

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

See also

• SFLOG_INITA
• SFLOG_INITW
• SFLOG_INIT

Examples

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