|
|
|
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 chapter 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.
|
|
|
Before this tutorial can be run, you need to have installed Memphis and at least two instances of the FairCom Server (i.e., FairCom DB, FairCom Edge, or FairCom RTG). See Quick Start in the Replication Manager guide. Follow the Example Test Configuration section to get everything configured on one server.
Next, you will need to set up one-way replication from the source to the target server. See Setting Up Replication - An Overview in the Replication Manager guide Quick Start.
Now you are ready to run this tutorial.
|
|
|
To register an external library (Windows DLL or Linux SO) to be used by the Replication Agent, add the option extension_library to ctreplagent.cfg, optionally including the directory name in which it is located if necessary:
extension_library ctrepluser.dll
As a suggestion, you can add the setting after unique_id, which will result in the ctreplagent.cfg file appearing as shown below:
This configuration will take effect upon the initialization of the Replication Agent.
You must have ctrepluser.dll present. This example assumes it is in the same path as ctreplagent.cfg.
|
|
|
To build a Replication Agent extension library, you will need to use the FairCom DB Professional package.
Create a client-side multi-threaded DLL or shared library makefile or project file by running mtmake with the repldll command-line option as shown below:
c:\FairCom_path>mtmake repldll
The makefile or project file will contain rules to compile the source file ctree/samples/special/utils/ctrepluser.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 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.
|
|
|
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 allows you to test the ability to open files from external library callback functions.
REPLUSER_SKIP_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 as described in the next section.
