repadm
Replication Agent administrator utility
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>] [-threadid <threadID>]
Command | Description | ||||||
|---|---|---|---|---|---|---|---|
| Use the replication agent manager that is currently running on the server named | ||||||
| Use the replication agent manager that is currently running on the server named | ||||||
| Use the filter definition in the file | ||||||
| Take all required actions to demote the server named | ||||||
| Use the replication agent manager that is currently running on the server named | ||||||
| Controls exception logging. This is for V11.5 and later. | ||||||
| Enables exception logging for the replication agent specified by the unique ID | ||||||
| Disables exception logging for the replication agent specified by the unique ID | ||||||
| Enables function timing for the replication agent specified by the unique ID | ||||||
| Disables function timing for the replication agent specified by the unique ID | ||||||
| Use the replication agent manager that is currently running on the server named | ||||||
| Lists the replication agent IDs for the server named | ||||||
| Gets the current number of records in the exception log for the replication agent specified by the unique ID
| ||||||
| Retrieves the current file filter list for the replication agent specified by the unique ID | ||||||
| Retrieves the function statistics for the replication agent specified by the unique ID | ||||||
| Reads the replication exception log entries that are stored on the server named
| ||||||
| Reads the replication exception log entries that are stored on the server named
| ||||||
| Gets information about the oldest uncommitted transaction for the replication agent specified by the unique ID | ||||||
| Returns the current parallel replication state of the replication agent specified by the unique ID | ||||||
| Retrieves the list of files for the replication resync operation specified by the resync ID | ||||||
| Returns the current role of the server named | ||||||
| Returns the current sync mode of the server named | ||||||
| Returns the current replication state for the replication agent specified by the unique ID | ||||||
| Returns the replication statistics for the replication agent specified by the unique ID | ||||||
| Lists the names of the threads of the replication agent specified by the unique ID | ||||||
| Returns the transaction commit state of the replication agent specified by the unique ID | ||||||
| Checks if the replication agent specified by the unique ID | ||||||
| Lists the replication agents that are registered with the server named | ||||||
| Lists the replication agent file filters that are registered with the server named | ||||||
| Lists all current replication filters | ||||||
| Pauses the Replication Agent specified by the unique ID | ||||||
| Uses the replication agent manager that is currently running on the server named | ||||||
| Takes all required actions to promote the server named | ||||||
| Purges all entries from the replication exception log on the server named | ||||||
| Uses the replication agent manager that is currently running on the server named | ||||||
| Removes the state information for a managed replication agent from the source and target servers. | ||||||
| Uses the replication agent manager that is currently running on the server named | ||||||
| Removes the file filter that is listed in the XML filter file named | ||||||
| Removes the synchronous replication agent specified by the unique ID | ||||||
| Resets function statistics for the replication agent specified by the unique ID | ||||||
| Resets replication statistics for the replication agent specified by the unique ID | ||||||
| Resumes the replication agent specified by the unique ID | ||||||
| Resynchronizes the list of source files for the replication agent specified by the unique ID | ||||||
| Cleans up the resync resources for the resync operation specified by the resync ID | ||||||
| Checks the state of the resync operation specified by the resync ID | ||||||
| Changes the configuration option | ||||||
| Sets the role of the server named
| ||||||
| When used with | ||||||
| Displays the current replication latency for the replication agent specified by the unique ID | ||||||
| Stops the Replication Agent specified by the unique ID
| ||||||
| Uses the replication agent manager that is currently running on the server named | ||||||
| Stops the replication agent manager that is currently running on the server named | ||||||
| Signals to the replication agent specified by the unique ID
|
Option | Description |
|---|---|
| Operate on the replication agent specified by the unique ID <agentID>. |
| Display delta statistic values instead of cumulative values. |
| A text file containing the names of files to resync. |
| Print a description header every <frq> outputs. |
| Pause |
| User password. |
| Replication resync ID. |
| Server name. |
| Output timestamp with header. |
| User name. |
| Working directory name for replication resync. |
| A file containing a replication XML file filter. |
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.
repadm Replication agent administrator options commands and descriptions
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.