c-treeACE V11.0 Update Guide

Asynchronous Record Update Notifications

Many c-tree applications store documents and other non-trivial data types. c-tree allows nearly any type of data to be stored, including text, XML, JSON, PDFs, word processing documents, and email. Frequently, these types of data require alternate indexing algorithms compared to how standard data types are indexed with basic b-tree algorithms. What is needed is a method to hand off these types of record updates to alternative handling.

In V11 and later, a set of Record Update Notification callback functions allows applications to externally process records as they are added or updated within a c-tree database.

These callback functions are called when records in the file are modified (added, updated, and deleted) and are asynchronously processed and persisted. Contrast this with the c-treeACE notification feature which is a memory-based queue. While standard notification can trigger callback handling, this is done in a synchronous manner which can impact up-front application performance. The record update notification callback also handles change events, however, its intent is to allow user-defined actions to occur when a record in a particular table is modified, in a deferred asynchronous manner. With this deferred handling, update events are deferred for background processing while maintaining application responsiveness.

Implementing Record Update Notifications

Function prototypes to handle record updates are located in the following c-tree source module:

ctree\source\ctrucbdll.c

To create a functional shared library, build the module using the c-treeACE build utility mtmake and choose the c-treeACE CTUSER model option. ctuser.dll (or libctuser.so) is generated and this module is then copied into your server's binary folder location.

The callback feature defines three functions:

1. File open callback function called when a connection opens a file,
2. File close callback called when a connection closes or deletes a file, and
3. Record update callback called when an ISAM-level record add, update, or delete operation is performed on a file.

The ctRecordUpdateCallbackControl() function, described below, is used to add and delete callback function definitions. A file can have more than one callback function definition. Each callback function definition is identified by its name, which is a case-sensitive ASCII string.

Each callback definition consists of the following attributes:

• Callback physical .DLL name
• Callback logical identifier name
• Callback function names for file open, file close, and record update
• Parameter string (optional)
• Callback time: this is the time when the record update callback is called. Supported options are:
  1. called during a record update
  2. called when a transaction commits (available only for a transaction-controlled file; for a non-transaction-controlled file, this option causes the callback to be called during a record update)
  3. written to transaction log or a memory queue and processed by a background thread after a transaction commits or the operation completes
  4. written to transaction log or a memory queue and no further action taken: the application is responsible for processing any queued entries

Restrictions

1. c-treeACE allows a callback function definition to be added when the data file is open in shared mode. In standalone mode, adding a callback function requires the data file to be open in exclusive mode.
2. A callback function definition can only be deleted when the data file is open in exclusive mode.

Management API Function

• ctRecordUpdateCallbackControl() - Callback definition management API

See also:

• Update Callback Specifications
• Option to specify external library name in platform-independent format

In This Section Update Callback Specifications