FairCom DB API for C

ctdbSetCallback

Establishes a callback function.

Declaration

CTDBRET ctdbSetCallback(CTHANDLE Handle, CTDB_CALLBACK_TYPE

CallBackType,ctdbCallbackFunction CallBackFunc);

Description

ctdbSetCallback() establishes a new callback function to receive calls for a given callback type. Handle can be any valid FairCom DB API session, database, table or record handle. CallBackType is one of the following callback types from the table below. CallBackFunc is an address to a callback function.

Callback Symbolic Constant	Explanation
CTDB_ON_SESSION_LOGON	Called after a successful session logon.
CTDB_ON_SESSION_LOGOUT	Called before a session logout.
CTDB_ON_DATABASE_CONNECT	Called after a successful database connect.
CTDB_ON_DATABASE_DISCONNECT	Called a database disconnect.
CTDB_ON_TABLE_OPEN	Called after c-tree ISAM table open, but before any other table callbacks. This callback can be used to indicate that the table is open and ready for operations.
CTDB_ON_TABLE_CLOSE	Called before the table is closed.
CTDB_ON_TABLE_GET_DODA	Called after the table open code loads the DODA. This callback can be used to change the contents of the DODA before the FairCom DB API field handles are created based on the DODA information and the index and index segment handles are created based on the IFIL information.
CTDB_ON_TABLE_GET_SCHEMA	Called after the table open code load the schema information. This callback can be used to modify the contents of the schema information before the FairCom DB API field handles are created based on the DODA information and the index and index segment handles are created based on the IFIL information.
CTDB_ON_TABLE_GET_EXT_INFO	Called during the table open operation to allow the customization of FairCom DB API’s extended field information.
CTDB_ON_TABLE_GET_RECLEN	Called during the table open operation to allow the customization of the length of the fixed portion of the record.
CTDB_ON_TABLE_ALTER	Called during a FairCom DB API alter table operation to allow the indication if alter table operations are allowed or not for a particular table.
CTDB_ON_TABLE_REBUILD	Called during an alter table full rebuild loop to indicate a percentage progress of the rebuild process.
CTDB_ON_RECORD_INIT	Called to indicate that a record handle is about to become active or an alter table was performed and the record need to be re-initialized.
CTDB_ON_RECORD_RESET	Called to indicate that the record handle is about to become inactive. The record handle is being released or the table is closing.
CTDB_ON_RECORD_BEFORE_READ	Called before a record read operation.
CTDB_ON_RECORD_AFTER_READ	Called after a record read operation.
CTDB_ON_RECORD_BEFORE_BUILD_KEY	Called before c-tree Plus BuildKey function is called.
CTDB_ON_RECORD_AFTER_BUILD_KEY	Called after c-tree Plus BuildKey function is called.
CTDB_ON_RECORD_BEFORE_WRITE	Called before a record write or record update.
CTDB_ON_RECORD_AFTER_WRITE	Called after a record write or record update.

You need to register your callback functions before they are invoked by FairCom DB API. A callback function is registered by calling the ctdbSetCallback() function and passing the appropriate FairCom DB API handle, the callback function type and the address of a function to receive the callback calls.

You can register any of the defined callback functions using the session handle and every time a database, table or record handle is allocated, they will automatically inherit their callbacks from the session handle. Conversely if you register callbacks using a database handle, every time a table or a record handle is allocated they will automatically inherit their callbacks from the database handle. Record handles will also inherit any callbacks registered with the table handle.

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

Example

/* allocate a new session handle */

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTREE);

/* set table open callback */

if (ctdbSetCallback(hSession, CTDB_ON_TABLE_OPEN, OnTableOpen) != CTDBRET_OK)

printf("ctdbSetCallback failed\n");