Skip to main content

Replication agent extension tutorial

Tutorial for extending the replication agent to log replication events

This tutorial describes how to run an example that demonstrates one possible use of the user-defined extensions for replication by providing detailed logging of the replication subsystem.

To exercise replication to monitor its behavior, compile ctrepluser.c with #define REPLUSER_LOGGING uncommented. This enables 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 using the #define REPLUSER_LOGGING logic discussed in replication logging.

Note

This is only one simple use of the callback extension. By reviewing the code in ctrepluser.c, you will be able to explore many alternate uses for this technology.

In the tutorial, we execute some scripts to build the data on the source and target servers. With data on both servers, we insert and delete data in the table we built. We connect to the source and watch the Replication Agent replicating data to the target server.

Figure 1. The Replication Agent replicates data to the target server
The Replication Agent replicates data to the target server


This tutorial demonstrates how an end user can run the replication agent extension tutorial shipped with FairCom DB, FairCom Edge , and FairCom RTG.The source and build files can be found in <faircom>\drivers\ctree.callbacks\replication\ of your replication bundle.

We use the unmanaged replication agent. To set up a simple replication agent environment, we start with the FairCom DB package, but the steps can be easily adapted to FairCom Edge or FairCom RTG packages. The basic footprint is the same between the three products.

This tutorial requires a good knowledge of C language. The replication agent extension is a DLL written in C language that implements specific functions that the replication agent will call when certain events happen during the replication. The specification of the replication agent extension API, together with a simple tutorial, can be found in the User-Defined Extensions for Replication .

This tutorial runs both servers on the same machine. In a production environment, the servers would normally run on different machines. Run this tutorial on one machine with the Windows operating system. If desired, it should be very easy to migrate the steps to a UNIX system. We include platform-specific notes where applicable.

Setup a simple replication environment

Follow the steps to Setup the replicate environment.

Build a replication agent extension DLL

To take advantage of the replication agent extension, we need to provide a C-written DLL that defines a set of functions to be resolved by the replication agent. In order to build a sample DLL, your FairCom bundle provides a simple build system. On Windows, you need a recent version of Visual Studio (2015 or newer). On Linux, the basic build system is required (GCC 4 or newer).

Always remember that any custom implementation of the replication agent extension DLL is loaded directly by the server through the replication agent threads, so any mistake made in the replication agent extension DLL may lead to an unexpected server crash.

Follow these steps to build the replication agent extension sample DLL.

  1. Make sure you have access to the build tools from your favorite terminal processor. On Windows, you normally need to load the Visual Studio Environment.

  2. CD to <faircom>\drivers\ctree.callbacks\replication\

  3. (Optional) Enable replication agent extension DLL logging. This step is not required, but it immediately logs entries into the ctreplagent.log file, making it easier to see the activity flow of the replication agent extension DLL.

    To enable logging, uncomment #define REPLUSER_LOGGING in <faircom>\drivers\ctree.callbacks\replication\src\ctrepluser.c.

  4. Run BuildCallback.bat (If on UNIX run make.)

    After compilation, the required DLL is saved in <faircom>\drivers\ctree.callbacks\replication\

  5. Copy <faircom>\drivers\ctree.callbacks\replication\bin\ctrepluser.dll into the secondary server binary directory <faircom>\secondary\server\

    It is now time to start the secondary server.

Create activity on data using SQL and observe the replication agent extension messages

This final step uses SQL to create and manipulate data to be replicated by the replication agent configured with the secondary server. The replication agent extension DLL logs its messages into ctreplagent.log.

  1. Use ISQL to connect to the default ctreeSQL database.

    ISQL can be found in the <faircom>\tools\ directory.

    >isql -u admin -ADMIN ctreeSQL

  2. Create a table:

    ISQL> CREATE TABLE custmast (cm_custnumb CHAR(4), cm_custzipc CHAR(9), cm_custstat CHAR(2), cm_custrtng CHAR(1), cm_custname VARCHAR(47), cm_custaddr VARCHAR(47), cm_custcity VARCHAR(47));

  3. Commit data:

    ISQL> COMMIT

  4. Insert some records:

    ISQL> INSERT INTO custmast VALUES ('1000','92867','CA','1','Bryan Williams','2999 Regency','Orange');
ISQL> INSERT INTO custmast VALUES ('1001','61434','CT','1','Michael Jordan','13 Main','Harford');
ISQL> INSERT INTO custmast VALUES ('1002','73677','GA','1','Joshua Brown','4356 Cambridge','Atlanta');
ISQL> INSERT INTO custmast VALUES ('1003','10034','MO','1','Keyon Dooling','19771 Park Avenue','Columbia');
ISQL> COMMIT;

  5. Delete all the records:

    ISQL> DELETE FROM CUSTMAST;
ISQL> COMMIT;

  6. Quit ISQL:

    ISQL> quit;

Check the results in ctrepluser.log in the secondary server binary directory <faircom>\secondary\server\ctrepluser.log. The following is sample content of the activity shown in ctrepluser.log.

Mon Feb 10 11:51:23 2025: INF: OnStartTransaction: logser=0; logpos=0; tranno=0; timestamp=0
Mon Feb 10 11:51:23 2025: INF: OnCREIFIL: logser=1; logpos=4742504; fileid=785; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 11:51:23 2025: INF: AfterCREIFIL: logser=1; logpos=4742504; fileid=785; filnam=./ctreeSQL.dbs/admin_custmast.dat; datno=7
Mon Feb 10 11:51:23 2025: INF: OnSETDEFBLK: logser=1; logpos=4743032; fileid=785; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 11:51:23 2025: INF: OnSETDEFBLK: logser=1; logpos=4745410; fileid=785; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 11:51:23 2025: INF: OnAddResource: logser=1; logpos=4747107; tranno=705; fileid=785; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 11:51:23 2025: INF: OnCommitTransaction: logser=0; logpos=0; tranno=0; timestamp=0
Mon Feb 10 11:51:23 2025: INF: OnCloseFile: logser=0; logpos=0; fileid=785; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:46:57 2025: INF: OnStartTransaction: logser=0; logpos=0; tranno=0; timestamp=0
Mon Feb 10 14:46:57 2025: INF: OnOpenFile: logser=1; logpos=4767055; fileid=807; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:46:57 2025: INF: AfterOpenFile: logser=1; logpos=4767055; fileid=807; filnam=./ctreeSQL.dbs/admin_custmast.dat; datno=7
Mon Feb 10 14:46:57 2025: INF: OnAddRecord: logser=1; logpos=4767055; tranno=738; fileid=807; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:46:57 2025: INF: OnAddRecord: logser=1; logpos=4767467; tranno=738; fileid=807; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:46:57 2025: INF: OnAddRecord: logser=1; logpos=4767875; tranno=738; fileid=807; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:46:57 2025: INF: OnAddRecord: logser=1; logpos=4768288; tranno=738; fileid=807; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:46:57 2025: INF: OnCommitTransaction: logser=0; logpos=0; tranno=0; timestamp=0
Mon Feb 10 14:46:58 2025: INF: OnCloseFile: logser=0; logpos=0; fileid=807; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:47:32 2025: INF: OnStartTransaction: logser=0; logpos=0; tranno=0; timestamp=0
Mon Feb 10 14:47:32 2025: INF: OnOpenFile: logser=1; logpos=4769476; fileid=810; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:47:32 2025: INF: AfterOpenFile: logser=1; logpos=4769476; fileid=810; filnam=./ctreeSQL.dbs/admin_custmast.dat; datno=7
Mon Feb 10 14:47:32 2025: INF: OnDeleteRecord: logser=1; logpos=4769476; tranno=744; fileid=810; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:47:32 2025: INF: OnDeleteRecord: logser=1; logpos=4769746; tranno=744; fileid=810; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:47:32 2025: INF: OnDeleteRecord: logser=1; logpos=4770012; tranno=744; fileid=810; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:47:32 2025: INF: OnDeleteRecord: logser=1; logpos=4770283; tranno=744; fileid=810; filnam=./ctreeSQL.dbs/admin_custmast.dat
Mon Feb 10 14:47:32 2025: INF: OnCommitTransaction: logser=0; logpos=0; tranno=0; timestamp=0
Mon Feb 10 14:47:36 2025: INF: OnCloseFile: logser=0; logpos=0; fileid=810; filnam=./ctreeSQL.dbs/admin_custmast.dat
…

How to run replication agent with extensions

replication agentextensionsreplication extensiontutorial