Skip to main content

repadm

Replication Agent administrator utility

Abstract

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

Command

Description

addagent <configFileName>

Adds a replication agent using the settings provided in a configuration file named <configFileName>

cancelaction <agentID> [<requestID>]

Cancels the action having request ID <requestID> for the replication agent having unique ID <agentID>

changefilter 

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

demoteserver

Demotes the server to a secondary server

deployfilegroups <agentID> <configFileName>

Deploys the file groups in the configuration file <configFileName> to the replication agent having unique ID <agentID>

exceptionlog

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

exceptionlog=on

Enables exception logging

exceptionlog=off

Disables exception logging

fnctim=on

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

fnctim=off

Disables function timing

getactionstatus <agentID> [<requestID>]

Gets the status of the action having request ID <requestID> for the replication agent having unique ID <agentID>

getagentids

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

getexceptionlogcount

Gets the current number of records in the exception log for a specified replication agent

getfilter

Retrieves current file filter list

getfuncstats

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.

getlog

Browses the replication exception log (REPLOGDT.FCS)

getlogtail

Reads exception log from last entry

getoldestuncommittedtran

Displays the oldest uncommitted transaction information.

getparallelstate

Shows the current parallel replication state of a replication agent

getresyncfiles

Retrieves list of files for a given resync

getserverrole

Retrieves the server's role

getsyncmode

Retrieves the server's sync mode

getstate

Views current replication state

getstats

Views replication statistics

getthreadnames

Retrieves the replication thread names

gettranstate

Retrieves transaction commit state (with -s target_server)

isactive

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

listagents

Lists the registered replication agents (with -s source_server)

listagentfilters

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

listfilter

 Lists all current replication filters

pause

Pauses the Replication Agent

pollactionstatus <agentID> [<requestID>]

Monitors the status of the action having request ID <requestID> for the replication agent having unique ID <agentID>

promoteserver

Promotes the server to the primary server

purgelog

Purges all entries from replication exception log

removeagent <agentID>

Removes the replication agent having unique ID <agentID>

removeagentstate

Removes the state information for a managed replication agent from the source and target servers

removefilegroups <agentID> <filegroups>

Removes the specified file groups from the replication agent having unique ID <agentID>

removefilter

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

removesyncagent

Removes a synchronous replication agent

resetfuncstats

Resets function statistics

resetstats

Resets replication statistics

resume

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

Cleans resync resources

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.

resyncstate

Checks resync state

setconfig:<option>

 Changes the specified configuration option at runtime

setserverrole <role>

 Sets the server role: primary or secondary

settargetserverwritable

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

showlatency

Displays the current replication latency

shutdown

Stops the Replication Agent

startagent <agentID>

Starts the replication agent having unique ID <agentID>

stopagentmanager

Stops the replication agent manager

syncshutdown

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



Table 2. Options

Option

Description

-a agentID

Operate on the replication agent having unique ID <agentID>.

-d

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.

-f flst

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

-h frq

Print a description header every <frq> outputs.

-i int [cnt] 

Pause int seconds for optional cnt times.

-n

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

-p upw

User password

-r resyncID

Resync action identification

-s svn 

FairCom server name

-t

Output a timestamp with a header.

-u uid

User name

-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



Note

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
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.

Table 3. Columns of data that state information outputs

Data

Description

s

Connection status to source server (y | n).

t

Connection status to target server (y | n).

lognum

Current transaction log number.

logpos

Current transaction log position.

state

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

seqno

Function sequence number.

time

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.

func

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.

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.

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

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.

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

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.