TIBCO FTL®

Macros | Functions
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