Skip to main content

Replication events

Types of replication events

The Replication Agent calls the corresponding callback function in the external library when the events listed in this section occur.

Table 1. Replication Agent state change events

Event

Description

Start agent

The Replication Agent is starting.

Connected to source

The Replication Agent successfully connected to the source server.

Connected to target

The Replication Agent successfully connected to the target server.

Lost connection to source

The Replication Agent has lost its connection to the source server.

Lost connection to target

The Replication Agent has lost its connection to the target server.

Disconnecting from source

The Replication Agent is disconnecting from the source server.

Disconnecting from target

The Replication Agent is disconnecting from the target server.

Terminating agent

The Replication Agent is terminating due to an unhandled error.

Pause agent

The Replication Agent has been requested to pause its operation.

Resume agent

The Replication Agent has been requested to resume its operation.

Stop agent

The Replication Agent is shutting down.



Table 2. File events

Event

Description

Open file

The Replication Agent is opening a replicated file on the target server.

After file open

The Replication Agent has successfully opened a replicated file on target server.

Close file

The Replication Agent is closing a replicated file on the target server.

Alter schema

The Replication Agent performs an alter schema operation on the target server's replicated file.



Table 3. Transaction events

Event

Description

Start transaction

The Replication Agent is starting a transaction on the target server.

Commit transaction

The Replication Agent is committing a transaction on the target server.

Abort transaction

The Replication Agent is aborting a transaction on the target server.

User-defined log entry

The Replication Agent is processing a user-defined log entry operation.

Checkpoint

The Replication Agent is processing a checkpoint log entry.



Table 4. Data events

Event

Description



Table 5. Exception events

Event

Description



Replication Agent state change event details

Start agent

The Replication Agent is starting. The external library must provide a function named rxOnStartAgent() for the start agent event to handle any extension library initialization that may be needed.

VOID rxOnStartAgent(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxVEROP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues startup.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Connected to source

The Replication Agent successfully connected to the source server.

VOID rxOnSourceConnected(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Connected to target

The Replication Agent successfully connected to the target server.

VOID rxOnTargetConnected(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Lost connection to source

The Replication Agent has lost its connection to the source server.

VOID rxOnSourceLostConnection(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Lost connection to target

The Replication Agent has lost its connection to the target server.

VOID rxOnTargetLostConnection(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Disconnecting from source

The Replication Agent is disconnecting from the source server.

VOID rxOnSourceDisconnected(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field:

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Disconnecting from target

The Replication Agent is disconnecting from the target server.

VOID rxOnTargetDisconnected(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Terminating agent

The Replication Agent is terminating due to an unhandled error.

VOID rxOnTerminateAgent(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Pause agent

The Replication Agent has been requested to pause its operation.

VOID rxOnPauseAgent(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent pauses its operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Resume agent

The Replication Agent has been requested to resume its operation.

VOID rxOnResumeAgent(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent pauses its operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Stop agent

The Replication Agent is shutting down.

VOID rxOnStopAgent(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN 

      The Replication Agent shuts down.

Synchronous server shutdown

The Replication Agent is shutting down from a synchronous replication state.

VOID rxOnSyncShutdown (prxEVENT prxevent);
Parameters:

  • Input parameters: rxEVENT (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    The replication state as of the shutdown is passed to this function in the prxevent->ev.shutdownInfo structure; prxevent->unqid holds the agent unique ID, and state info is also in the JSON file recovery_<agentid>.json.

File event details

Open file

The Replication Agent is opening a replicated file on the target server.

VOID rxOnOpenFile(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxFILOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent opens the file on the target server.

    • RXA_SKIP

      The Replication Agent does not open this file on the target server.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

After open file

The Replication Agent has successfully opened a replicated file on the target server.

VOID rxAfterOpenFile(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxFILOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Close file

The Replication Agent is closing a replicated file on the target server.

VOID rxOnCloseFile(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxFILOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent closes the file on the target server.

    • RXA_SKIP

      The Replication Agent skips closing the file.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

After create IFIL

The Replication Agent has successfully replicated a create file using an IFIL on the target server.

VOID rxAfterCREIFIL(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxFILOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent continues normal operation.

    • RXA_SKIP

      Returning this action for this event has no effect on the Replication Agent (same as RXA_DEFAULT).

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

After schema

The Replication Agent performs an alter schema operation on the target server's replicated file.

VOID rxOnAlterSchema(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxFILOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent performs the alter schema operation on the target data file.

    • RXA_SKIP

      The Replication Agent skips the alter schema operation.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Resync file

The Replication Agent is resyncing a replicated file with the target server.

VOID rxOnResyncFile(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxFILOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent performs the resync file operation on the target data file.

    • RXA_SKIP

      The Replication Agent skips the resync file operation.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Transaction event details

Start transaction

The Replication Agent is starting a transaction on the target server.

VOID rxOnStartTransaction(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxTRNOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent starts a transaction on the target server.

    • RXA_SKIP

      The Replication Agent does not start a transaction on the target server.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Commit transaction

The Replication Agent is committing a transaction on the target server.

VOID rxOnCommitTransaction(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxTRNOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent commits the transaction on the target server.

    • RXA_SKIP

      The Replication Agent does not commit the transaction on the target server.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Abort transaction

The Replication Agent is aborting a transaction on the target server.

VOID rxOnAbortTransaction(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxTRNOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent aborts the transaction on the target server.

    • RXA_SKIP

      The Replication Agent does not abort the transaction on the target server.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

User-defined log entry

The Replication Agent is processing a user-defined log entry operation.

VOID rxOnUserTransaction(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxTRNOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent processes the user-defined log entry.

    • RXA_SKIP

      The Replication Agent ignores the user-defined log entry.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Checkpoint

The Replication Agent is processing a checkpoint log entry.

VOID rxOnCheckpoint(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxTRNOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent processes the checkpoint entry.

    • RXA_SKIP

      The Replication Agent ignores the checkpoint entry.

      Note

      Be aware that if you skip the Replication Agent's processing of checkpoint entries, you must manually inform the source server of the Replication Agent's current minimum transaction log requirement.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Data event details

Add record

The Replication Agent is adding a record to a replicated file on the target server.

VOID rxOnAddRecord(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxDATOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent adds the specified record to the target file.

    • RXA_SKIP

      The Replication Agent ignores the add record entry.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Update record

The Replication Agent is updating a record in a replicated file on the target server.

VOID rxOnUpdateRecord(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxDATOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent updates the specified record in the target file.

    • RXA_SKIP

      The Replication Agent ignores the update record entry.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Delete record

The Replication Agent is deleting a record from a replicated file on the target server.

VOID rxOnDeleteRecord(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxDATOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent deletes the specified record from the target file.

    • RXA_SKIP

      The Replication Agent ignores the delete record entry.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Deferred key

The Replication Agent is processing a deferred key log entry.

VOID rxOnDeferredKey(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxDATOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent processes the deferred key entry.

    • RXA_SKIP

      The Replication Agent ignores the deferred key entry.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.

Exception event details

Exception

An action performed by the Replication Agent has failed.

VOID rxOnException(prxEVENT prxagentev);
Parameters:

  • Input parameters: rxEVENT with rxEXCOP (see Callback function input parameters)

  • Output parameters: rxEVENT action field

    • RXA_DEFAULT

      The Replication Agent handles the specified exception using its normal exception handling procedure.

    • RXA_SKIP

      The Replication Agent ignores the exception.

    • RXA_SHUTDOWN

      The Replication Agent shuts down.