c-treeDB API for C++ - Developers Guide

Working with Callbacks

c-treeDB represents a high-level, easy to use API on top of the popular FairCom DB ISAM and FairCom Low-Level APIs. c-treeDB is intended as the new standard for FairCom DB programming. When compared to ISAM and low-level APIs, c-treeDB introduced a more formal definition for the structure of data and index files, new concepts such as ROWID and NULL field support, and more specifically a formal definition for each field type supported.

Existing applications’ data and index files, i.e. data created prior to the publication of the c-treeDB API, may have implemented certain field types in ways that may be incompatible with c-treeDB. Field types such as CT_DATE, CT_TIME and CT_TIMES are probably the most common examples of existing data that may be incompatible with c-treeDB.

The c-treeDB Callback feature was implemented to provide developers a means to intercept certain c-treeDB operations and add custom code to manipulate record buffer layouts or change field data on the fly such that the record and field data are compatible with c-treeDB.

To enable a given callback, perform the following:

1. Write your callback functions. Every callback function must have the callback function type. There is no need to implement every single callback type. Implement only the callback functions that are necessary for your logic.
2. Set your callbacks with the ctdbSetCallback() function. For example if you have implemented CTDB_ON_LOGON and CTDB_ON_LOGOUT callback functions, you call the ctdbSetCallback() function once for each callback to the session handle with the appropriate callback type.

You remove a callback from a c-treeDB handle by calling the ctdbClearCallback() function. After removed, a callback for a particular handle will not be called again. You can remove all callbacks from a particular session, database, table or record handle by calling the ctdbClearAllCallback() function.

In This Section Callback Function Type Callback Return Codes Callback Handle Parameters Callback Types Working with Callbacks