Skip to main content

Replication extensions tutorial

The FairCom Replication Agent is an advanced feature allowing high availability and disaster recovery setups across distributed server environments. As replication transfers data from server to server, it is possible to intercept this operation for advanced data transformations. These transformations can include conflict detection and resolution, data transformation, filtering and redirecting data updates, and even replicating to third-party databases. This capability is provided by Replication user-defined extensions, an extensive set of callbacks within the Replication Agent process. More than two dozen events can trigger custom callback actions.

The Replication Agent supports loading a user-defined external library (an extension to Replication Agent) that can perform customized actions when processing replication operations. The library contains callbacks — functions that are called when certain predefined events occur. A list of events callbacks can be attached to can be found in replication events — for example, if you wanted to log each time a record was inserted into a table, you could write a routine that does the desired logging and call it from the rxOnAddRecord() callback function. This would be a replication extension. The Replication Agent would invoke that callback function and run your code each time a record was inserted into a table.

There are dozens of different callback hooks available (replication events), and this gives the user a very powerful way to customize the behavior of the c-tree database engine.

Your replication extension takes the form of a Windows DLL file or a Linux SO file. It is attached to the c-tree server at runtime, so it is not necessary to recompile the c-tree server to use replication extensions.

c-tree ships with the source code of an example replication extension which you can compile yourself and attach to the c-tree server, and modify, as you desire. This makes it easy to get started using replication extensions.

Note

To use this feature, you will need FairCom DB Professional and a development environment that supports writing and compiling C code into a DLL or shared library.

This section describes the use of callbacks to extend the FairCom Replication Agent (the replication extension feature introduced in V11.5). If you are using FairCom's newer replication solution (based on the central Replication database introduced in V12), contact FairCom.

Tutorial requirements

Before this tutorial can be run:

  • Install Memphis (see Quick Startin the Replication Manager guide).

  • Install at least two instances of the FairCom server, FairCom DB

    FairCom DB, FairCom Edge, or FairCom RTG, (see Quick Startin the Replication Manager guide).

  • Set up one-way replication from the source to the target serve (see Setting Up Replication - An Overview in the Replication Manager guide Quick Start).

Configure the Replication Agent to use a user-defined extension library

To register an external library (Windows DLL or Linux SO) to be used by the Replication Agent:

  1. Add the option extension_library to ctreplagent.cfg:

    Note

    Optionally include the directory name in which it is located if necessary.

    extension_library ctrepluser.dll

  2. Optionally, add the setting after unique_id, which will result in the ctreplagent.cfg file appearing as shown:

    ;The unique ID of the Replication Agent for multi server replications unique_id REPLAGENT1

;callback replication
extension_library ctrepluser.dll

    Important

    You must have ctrepluser.dll present. This example assumes it is in the same path as ctreplagent.cfg.

    Note

    This configuration will take effect upon the initialization of the Replication Agent.

Build a user-defined extension library

  1. To build a Replication Agent extension library, use the FairCom DB Professional package.

  2. Create a client-side multi-threaded DLL or shared library makefile or project file by running mtmake with the repldll command line option:

    c:\FairCom_path>mtmake repldll

    For Windows, make the following choices in mtmake (other versions or platforms may differ slightly):

    2 (vs2019)
    2 (command line)
    1 (client, not server)
    1 (client side library, not stand alone)
    3 (mulitthreaded)
    3,6 (IP & shared memory)
    1 (DLL)
    2 (samples)

    Note

    • The makefile or project file will contain rules to compile the source file build_sdk/source/Xtras/ctree.samples/special/utils/ctreepluser.c, which contains your user-defined callback functions, and will link that module into a DLL named ctrepluser.dll or a shared library named libctrepluser.so (or other naming convention depending on the operating system).

    • The library will be built inside the project folder you specified with mtmake:

      Windows: build_sdk/build/<yourFolder>/bin/Debug/ctrepluser.dll

      Linux: build_sdk/build/<yourFolder>/obj/Debug/libctrepluser.so

    • The external library must provide a function named rxOnStartAgent() for the Start agent event. All other callbacks are optional (they do not need to exist in your external library).

Replication logging using callbacks

When compiling ctrepluser.c, you can uncomment #define REPLUSER_LOGGING if you want to enable example code that calls a function to log a message to the file ctrepluser.log each time one of the callback functions is called. The sample code also tracks the number of calls made to each callback function.

  • REPLUSER_OPEN_EXAMPLE 

    This example allows you to test the ability to open files from external library callback functions.

  • REPLUSER_SKIP_EXAMPLE 

    This example demonstrates the ability to skip operations.

Examine this code to understand the examples. Enable the desired #defines and compile the library to try the tutorial.