Skip to main content


Replication Agent administrator utility


The Replication Agent administrator utility, repadm, is used to control and retrieve statistics from the Replication Agent process.

The Replication Agent administrator utility, repadm, is used to control and retrieve statistics from the Replication Agent process.

repadm -c <command> [-s svn] [-u uid] [-p upw] [-a agentid] [-i int [cnt]] [-h frq] 
				[-f flst] [-w wrkDir] [-x fflt] [-r resyncID] [-threadid threadid]
Table 1. Commands




Changes current replication file filter where -x specifies the filter file name, and it is persisted in REPLFFCHGDT.FCS


Demotes the server to a secondary server


Controls exception logging. This is for V11.5 and later.


Enables exception logging


Disables exception logging


Enables function timing and using the getfncstats command will turn it on if it is off


Disables function timing


Retrieves replication IDs that are currently registered in the Replication Agent. This is for V11.5 and later.


Retrieves current file filter list


Reads and displays function call times to help troubleshoot a misbehaving replication setup. Figures generated are cumulative from highest to lowest call time. This is for V11.5 and later.


Browses the replication exception log (REPLOGDT.FCS)


Reads exception log from last entry


Displays the oldest uncommitted transaction information.


Retrieves list of files for a given resync


Retrieves the server's role


Retrieves the server's sync mode


Views current replication state


Views replication statistics


Retrieves the replication thread names


Retrieves transaction commit state (with -s target_server)


Checks if an agent is active: "y: active" , "p: paused", "n: inactive"repadm also returns a corresponding return code: 1, 2, or 3 respectively.


Lists the registered replication agents (with -s source_server)


 Lists the registered replication agent file filters (with -s source_server)


 Lists all current replication filters


Pauses the Replication Agent


Promotes the server to the primary server


Purges all entries from replication exception log


Removes a replication file filter change by its name, -x specifies the filter file name


Removes a synchronous replication agent


Resets function statistics


Resets replication statistics


resync <filename>

Stops replication on the named file and resynchronize it. <filename> can be a single file or a text file listing multiple files. This is for V11.5 and later.

resyncclean <filename>

 Stops replication on the named file, cleans up previous failed resync attempts, and resynchronizes it. <filename> can be a single file or a text file listing multiple files. This is for V11.5 and later.


Cleans resync resources


Checks resync state


 Changes the specified configuration option at runtime

setserverrole <role>

 Sets the server role: primary or secondary


When used with shutdown or syncshutdown option, the replication agent enables write access to the target server


Stops the Replication Agent


Stops the replication agent after it applies all changes to the target server, -n can be used with this option

Table 2. Options



-s svn 

FairCom server name

-u uid

User name

-p upw

User password

-i int [cnt] 

Pause int seconds for optional cnt times.


When used with the getfuncstats command, this option will cause the figures generated to be the difference between the previous and current time interval instead of cumulative. This is for V11.5 and later.


Output a timestamp with a header.

-f flst

A text file name with a list of source file names.

-w wrkDir

 The working directory for the dump information. The default is the server data path.

-x fflt

 XML file name with a list of file filter changes

-r resyncID

Resync action identification


Stops the keeping of transaction logs for replication on the source server.


This utility can only connect to the Replication Agent process, replagentNSUP_ERR (454) is reported when connecting to a standard FairCom DB database engine with this utility.

This utility supports the use of an encrypted password file. Encrypted password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:

; User Id
; User Password
PASSWD <pass>

Use the -1 option to specify the name of the encrypted file. Use the -a option to specify the name of the encrypted file.

In V11.6 and later, the getstate option includes a time column, which can be used to determine the latency with ctreplagent (the name of the FairCom replication agent process).

repadm -c getstate -s FAIRAGENT 

The time column shows how up-to-date replication is relative to the source server's current time. On each transaction commit, the source server calculates how many seconds have passed between the time at which the transaction commit entry was written to the transaction log and it sent that value to the replication agent. The replication agent stores this value in memory and makes it available to the repadm utility.

Table 3. Columns of data that state information outputs




Connection status to source server (y | n).


Connection status to target server (y | n).


Current transaction log number.


Current transaction log position.


The environment being processed (local | master | self).


Function sequence number.


Number of seconds between the time the transaction commit entry was written to the transaction log and that value to the replication agent. This is for V11.6 and later.


Function by name processed.

Example 1. repadm output showing the time value

The first row is showing that the replication agent is 6 seconds behind. The second row shows 7 seconds behind, and the last 2 rows show that it's current and caught up.

s t   lognum     logpos   state    seqno time func

y y       48   30101431  target  1630145    6 ADDREC

y y       49   12735790  source  1698005    7 ctReplGetNextChange

y y       49   12735790  source  1698009    0 ctReplGetNextChange

y y       49   12735790  source  1698009    0 ctReplGetNextChange

The replication exception log (REPLOGDT.FCS) is a FairCom file that contains a record for each error the Replication Agent has logged. This file can be imported into a SQL database for easier examination. V11.6 and later no longer require exclusive access to a table for import and this can be done while REPLLOGDT.FCS is online.

The repadm utility now supports an option, -settargetserverwritable, that can be used with the shutdown or syncshutdown commands. This option causes the Replication Agent to connect to the target server and set it writable (READONLY_SERVER NO). This is done at the end of shutting down the Replication Agent.


The call to shut down returns to the repadm utility before this is done, since it is done by the main Replication Agent thread rather than the server thread that initiates the shutdown of the Replication Agent.

Example 2. Replication Agent shutdown command
repadm -c syncshutdown -settargetserverwritable -s FAIRAGENT

The repadm utility now supports an option to indicate if the Replication Agent is operational. Operational means the agent threads are running and are connected to the source and target server as appropriate. This simple point-in-time check is able to detect when Replication Agent threads have exited due to an error and when Replication Agent threads are not connected to their servers. It cannot detect a situation where Replication Agent threads are alive but are in a hung state.

Example 3. repadm command-line usage

The utility outputs a value of y if the agent is operational, p if the agent is paused, and n if the agent is not operational.

repadm -c isactive -s AGENTSERVERNAME

Example 4. Function call usage

ctReplAgentOp() with mode of ctRAOPcheckifactive.

NINT rc;

TEXT stateBuffer[2];

VRLEN bufsize = 2;

rc = ctReplAgentOp(ctRAOPcheckifactive, NULL, 0, stateBuffer, &bufsiz);

When the repadm utility's isactive command is used, the utility now sets the return code to indicate the agent's status as of the last check made by the utility.

Table 4. Status codes

Status code


More status codes may be added in the future.


Error checking agent status


Agent is operational


Agent is paused


Agent is not operational

The repadm utility can be used to reset the Replication Agent statistics (counts of passed/failed operations). Use the option repadm -c resetstats.

This is in addition to the existing support for resetting Replication Agent function statistics (repadm -c resetfuncstats).

By default, when the Replication Agent fails to apply a replicated operation to the target server, it writes an entry to the replication exception log for every operation in the transaction where the failure occurred. This makes it possible to see what operations were not applied due to the failure. But this can generate a lot of log entries and may make it difficult to see the failed operations.

To address these issues, we added a Replication Agent configuration option to instruct the agent to only record exception log records for those operations that failed. To use this feature, add the following option to the Replication Agent configuration file, ctreplagent.cfg.

exception_logging errors_only

The repadm utility now supports an option to cause the Replication Agent to finish applying all changes it has read from the source server's transaction logs and then shut down.

The repadm utility's -n option can also be used with this option.

Example 5. Output
C:\> repadm -c syncshutdown -s AGENTSERVERNAME

Requesting replication agent to shut down with the specified options.

Successfully shut down the replication agent. Log copy position=<6,309897979> Last commit position=<6,309888349> Log read position=<6,309897979> Transaction ID=808025


If the Replication Agent was not able to connect to the target server before it is shut down, it reports zeros for the log positions and transaction ID.