repadm Replication Agent administrator
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]
Command | Description |
|---|---|
| Changes current replication file filter where -x specifies the filter file name, and it is persisted in |
| 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 |
| 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 ( |
| Reads exception log from last entry |
| 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: |
| 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 |
| |
| Stops replication on the named file and resynchronize it. |
| Stops replication on the named file, cleans up previous failed resync attempts, and resynchronizes it. |
| Cleans resync resources |
| Checks resync state |
| Changes the specified configuration option at runtime |
| Sets the server role: primary or secondary |
| When used with |
| Stops the Replication Agent |
| Stops the replication agent after it applies all changes to the target server, -n can be used with this option |
Option | Description |
|---|---|
| FairCom server name |
| User name |
| User password |
| Pause |
| When used with the |
| Output a timestamp with a header. |
| A text file name with a list of source file names. |
| The working directory for the dump information. The default is the server data path. |
| XML file name with a list of file filter changes |
| Resync action identification |
| Stops the keeping of transaction logs for replication on the source server. |
Note
This utility can only connect to the Replication Agent process, replagent. NSUP_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 USERID ADMIN ; 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.
Data | Description |
|---|---|
| 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. |
repadm output showing the time valueThe 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.
Note
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.
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.
repadm command-line usageThe 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
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.
Status code | Description |
|---|---|
More status codes may be added in the future. | |
1 | Error checking agent status |
2 | Agent is operational |
3 | Agent is paused |
4 | 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.
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
Note
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.