ftl.h File Reference

Start and stop FTL
Log levels. More...

Macros
#define	TIB_COMPATIBILITY_VERSION   (2)
	Compiled compatibility version. More...

Functions
TIB_API void	tib_Close (tibEx e)
	Cleanup FTL. More...
TIB_API void	tib_Open (tibEx e, tibint32_t compatible_version)
	Initialize FTL. More...
TIB_API const char *	tib_Version (void)
	Release string identifying the linked FTL library. More...

Log Level Constants
tib_SetLogLevel supports these constants as log level values.
#define	TIB_LOG_LEVEL_DEBUG   "debug"
	Debug – output trace entries for all events (debug, verbose, information, warning and severe events). More...
#define	TIB_LOG_LEVEL_INFO   "info"
	Info – output trace entries for information, warning and severe events. More...
#define	TIB_LOG_LEVEL_OFF   "off"
	Off – disable all tracing. More...
#define	TIB_LOG_LEVEL_SEVERE   "severe"
	Severe – output trace entries only for severe events. More...
#define	TIB_LOG_LEVEL_VERBOSE   "verbose"
	Verbose – output trace entries verbose, information, warning and severe events. More...
#define	TIB_LOG_LEVEL_WARN   "warn"
	Warn – output trace entries for warning and severe events. More...
TIB_API void	tib_SetLogCallback (tibEx e, tibLogCallback logCallback, tibProperties properties, void *closure)
	Register a global log callback. More...
TIB_API void	tib_SetLogFiles (tibEx e, const char *filePrefix, tibint64_t maxFileSize, tibint32_t maxFiles, tibProperties properties)
	Arrange rotating log files. More...
TIB_API void	tib_SetLogLevel (tibEx e, const char *level)
	Set the global log trace level for low-level FTL internal calls. More...

Detailed Description

Start and stop FTL
Log levels.

This file defines calls that start and stop FTL, and configure logging.

Macro Definition Documentation

TIB_COMPATIBILITY_VERSION

#define TIB_COMPATIBILITY_VERSION   (2)

Compiled compatibility version.

Your program must compile and link the same compatibility version of the FTL library. tib_Open checks this correspondence, and fails if they do not match. This constant defines the compiled compatibility version (which is independent of the software release version).

TIB_LOG_LEVEL_DEBUG

#define TIB_LOG_LEVEL_DEBUG   "debug"

Debug – output trace entries for all events (debug, verbose, information, warning and severe events).

TIB_LOG_LEVEL_INFO

#define TIB_LOG_LEVEL_INFO   "info"

Info – output trace entries for information, warning and severe events.

TIB_LOG_LEVEL_OFF

#define TIB_LOG_LEVEL_OFF   "off"

Off – disable all tracing.

TIB_LOG_LEVEL_SEVERE

#define TIB_LOG_LEVEL_SEVERE   "severe"

Severe – output trace entries only for severe events.

TIB_LOG_LEVEL_VERBOSE

#define TIB_LOG_LEVEL_VERBOSE   "verbose"

Verbose – output trace entries verbose, information, warning and severe events.

TIB_LOG_LEVEL_WARN

#define TIB_LOG_LEVEL_WARN   "warn"

Warn – output trace entries for warning and severe events.

Function Documentation

tib_Close()

TIB_API void tib_Close

(

tibEx

e

)

Cleanup FTL.

This call closes (that is, terminates) FTL within your program, and reclaims related resources that tib_Open allocated and initialized.

Calls to tib_Close decrement the FTL reference counter, but actually close (that is, terminate) FTL only when the counter reaches zero.

In each program, the number of calls to tib_Open() and tib_Close() must match.

Programs must not call tib_Close within a callback.

Programs must close realm objects before closing FTL.

Parameters

e	The exception object captures information about failures.

Returns

void

tib_Open()

TIB_API void tib_Open	(	tibEx	e,
		tibint32_t	compatible_version
	)

Initialize FTL.

This call opens (that is, initializes) FTL within your program, including threads and global data structures.

The first time a program calls it, this call initializes FTL. If the program (or a third-party package) calls it again, it increments a reference counter, but does not reinitialize FTL. Calls to tib_Close decrement the FTL reference counter, but actually close (that is, terminate) FTL only when the counter reaches zero.

In each program, the number of calls to tib_Open() and tib_Close() must match.

Parameters

e	The exception object captures information about failures.
compatible_version	The program must supply the constant TIB_COMPATIBILITY_VERSION.

Returns

void

tib_SetLogCallback()

TIB_API void tib_SetLogCallback	(	tibEx	e,
		tibLogCallback	logCallback,
		tibProperties	properties,
		void *	closure
	)

Register a global log callback.

If you register a log callback (at most one), then FTL directs all log statements to that callback.

Parameters

e	The exception object captures information about failures.
logCallback	FTL invokes this callback to process all log statements.
properties	Reserved for future use. To ensure forward compatibility, programmers must supply NULL.
closure	FTL supplies this closure object to the callback with each log statement.

Returns

void

tib_SetLogFiles()

TIB_API void tib_SetLogFiles	(	tibEx	e,
		const char *	filePrefix,
		tibint64_t	maxFileSize,
		tibint32_t	maxFiles,
		tibProperties	properties
	)

Arrange rotating log files.

The filename extension .0 indicates the current log file. Rotation shifts each file by incrementing its numeric extension. If the number of files would exceed the maximum, rotation deletes the oldest file.

Parameters

e	The exception object captures information about failures.
filePrefix	All log files begin with this filename prefix.
maxFileSize	FTL rotates the log files when the current log file exceeds this limit (in bytes). This value must be greater than 102400 (100 kilobytes).
maxFiles	FTL limits the number of log files to this maximum.
properties	Reserved for future use. To ensure forward compatibility, programmers must supply NULL.

Returns

void

tib_SetLogLevel()

TIB_API void tib_SetLogLevel	(	tibEx	e,
		const char *	level
	)

Set the global log trace level for low-level FTL internal calls.

Set one log level for all logging elements, e.g., tib_SetLogLevel(tibEx e, TIB_LOG_LEVEL_WARN)

Or, set log levels per element tag, e.g., tib_SetLogLevel(tibEx e, "transports:warn;api:debug")

Valid levels:

• TIB_LOG_LEVEL_OFF
• TIB_LOG_LEVEL_SEVERE
• TIB_LOG_LEVEL_WARN
• TIB_LOG_LEVEL_INFO
• TIB_LOG_LEVEL_VERBOSE
• TIB_LOG_LEVEL_DEBUG

Valid element tags:

• all - applies to all elements.
• application - logging for the application, e.g., API calls, message formats, and content matchers.
• transports - logging for transports, including peer connections, subscriber interest, message sends, protocols.
• msg - logging related to messages. For debug, print a representation of each inbound/outbound message.
• api - logging related to API calls.

For more information, see the topic Log Levels in the book TIBCO FTL Development.

Parameters

e	The exception object captures information about failures.
level	The call sets the level to this value.

Returns

void

tib_Version()

TIB_API const char * tib_Version

(

void

)

Release string identifying the linked FTL library.

Programs can use this string to output the FTL version in a start banner or in debug output.

Returns

The release string that identifies the FTL library